> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmora.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Identifiers and accepted values

> Which string fields are fixed choices, which are ids Sigmora returns, and exactly where each id comes from.

## Three kinds of string

The API reference types text, resource ids and some fixed choices as `string`,
but you fill them in differently:

| Kind | What you should send | Example |
| - | - | - |
| Your text | A value you write | `title: "August launch"` |
| Fixed choice | One of the values listed under the field in the API Reference | `mode: "review_first"` |
| Resource id | A value returned by a list, create, or job response | `contentBrandId: "brd_4b81"` |

<Warning>
  Never construct an id from an example. Examples such as `brd_4b81` only show
  the shape; use ids returned for your workspace.
</Warning>

These docs use the same example ids throughout: `prj_9x2a4c` (project),
`brd_4b81` (Brand), `job_4k1b7d` (render job), `job_7e3c2f` (footage-edit job)
and `cnt_8f3e2a71` (asset).

## Where each resource id comes from

| Field | Copy it from | Can you omit it? |
| - | - | - |
| `themeId`, `parentId` | `GET /v1/themes` → `themes[].id` | Yes on filters; no in `/themes/{themeId}` |
| `contentBrandId` | `GET /v1/brands` → `brands[].id` | No in Brand-owned request bodies and filters |
| `projectId` | `POST /v1/projects` → `project.id` | No on capability calls or host sessions |
| `jobId` | An asynchronous capability response → `jobId` | No when polling or planning shorts |
| `assetId` | `GET /v1/assets?projectId=...` → `assets[].id`, or `POST /v1/assets/import` → `asset.id` | Yes where `transcript` can be sent inline instead |
| `runId` | The corresponding discovery or autopilot start response | No on a run-detail action |
| `campaignId` | `GET /v1/campaigns` → `campaigns[].id`, or a create response | No on a campaign-detail action |
| `contentId` | `GET /v1/viral-content` → `items[].id` | No in `/viral-content/{contentId}` |
| `productDocId` | `GET /v1/products` → `products[].id` | No on `/products/{productDocId}` |
| `productId` | `GET /v1/products` → `products[].productId` | Required in an autopilot destination |
| `trendId` | `GET /v1/trends` → `trends[].id` | Yes; omit it to let Sigmora select a trend, or send `topic` |
| `videoId` | `GET /v1/video/catalog/{domain}` → `videos[].id` | Yes when you send your own prose as `story` |

Products have two ids on purpose. `products[].id` addresses the product record
and is the `{productDocId}` path parameter for reads and updates.
`products[].productId` is the short binding id that Brands and autopilot
destinations refer to.

## Theme ids

Theme ids are versioned IAB taxonomy identifiers such as `iab:3.1:391`. The
accepted set is too large and evolves too independently to paste into every
field. The API itself is the list:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl "https://api.sigmora.org/v1/themes?rootOnly=true&limit=100" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"
```

Use `themes[].id` exactly as returned, including the colons and version. Search
by name when you do not know the id:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl "https://api.sigmora.org/v1/themes?q=personal%20finance" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"
```

Send the response's `nextCursor` back as `cursor` to continue. See
[Pagination](/pagination).

## Values that come from the dashboard

A few ids refer to things a person sets up interactively, such as an account
authorization. The API accepts them but does not create them:

| Field | Where it comes from | API-only alternative |
| - | - | - |
| `connectedAccountId` | A social account connected in the dashboard. List connected accounts with `GET /v1/publish/destinations` → `destinations[].id` | None; connecting an account is an interactive authorization step |
| `productTargetId` | A publish target selected in the dashboard | Use an empty `destinations` list to generate without publishing |
| `sourceClipIds` | Source clips uploaded in the dashboard | Omit them to generate a new narrated video |
| `brandBrainId` | A saved Voice profile | Omit it to use the Brand Foundation and Brand context |
| `playbookId` | A saved marketing playbook | Omit it and Sigmora chooses its normal strategy |

The API reference repeats these notes on each field.

## Dates, times, regions, and languages

| Value | Format | Example |
| - | - | - |
| Calendar date | `YYYY-MM-DD` | `2026-08-10` |
| Date and time | ISO 8601 with timezone | `2026-08-15T09:00:00Z` |
| Quiet-hour time | 24-hour `HH:MM`, interpreted in the nearby `timezone` | `22:00` |
| Timezone | IANA timezone | `Africa/Nairobi` |
| Region | Two-letter ISO 3166-1 country code | `KE` |
| Language | BCP 47 language tag | `en`, `sw`, `en-GB` |

## Fixed choices

When a field has a closed set, the API reference lists every accepted value
under it and explains choices whose names are not self-evident — for example
`draft_only`, `review_first` and `full_auto`. A value outside the list answers
`400 invalid_request`.

A string field without a list says in its description whether it is free text,
provider-specific, or best left unset. Voice and model ids are provider-specific:
omit them to use Sigmora's defaults unless you have a value you know is valid.
`GET /v1/video/options` lists the live voices, models and other video choices.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.