> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/tools/concepts.md).

# Concepts

Review Ava’s ideas before anything is made.

### concept\_list

List a campaign's concepts (the creative ideas Ava drafted), newest first, optionally for one plan run or status: hook, status, output kind and creative\_id once approved. A concept\_id is also a brief id, so draft\_get shows its full script; then approve with concept\_approve or reject with concept\_reject.

* **Permission:** Read campaigns (`campaigns:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/concept_list`

#### Input

| Field          | Type    | Required | Description                                                                                                                                         |
| -------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`  | string  | Yes      | Campaign id from campaign\_list or campaign\_create.                                                                                                |
| `week_start`   | string  |          | All runs in this Monday-Sunday Studio week; omit period\_start.                                                                                     |
| `period_start` | string  |          | Only concepts from this plan run (YYYY-MM-DD). Omit for all runs.                                                                                   |
| `status`       | string  |          | Only concepts with this status, e.g. draft for the ones awaiting review. One of `draft`, `approved`, `producing`, `produced`, `rejected`, `failed`. |
| `limit`        | integer |          | Max results (1-100, default 50). Value 1 to 100.                                                                                                    |

#### Output

| Field                               | Type             | Description                                                                                                                                                                                                                                                                                                           |
| ----------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`                       | string           |                                                                                                                                                                                                                                                                                                                       |
| `concepts`                          | array of objects |                                                                                                                                                                                                                                                                                                                       |
| `concepts[].display_code`           | string           | Studio's AVA-C### label for this reusable concept within the displayed week.                                                                                                                                                                                                                                          |
| `concepts[].root_concept_id`        | string           |                                                                                                                                                                                                                                                                                                                       |
| `concepts[].version_number`         | integer          | Value at least 1.                                                                                                                                                                                                                                                                                                     |
| `concepts[].version_count`          | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                     |
| `concepts[].concept_id`             | string           | Concept id. It is also a brief id: draft\_get, draft\_spec and draft\_prompts accept it as brief\_id.                                                                                                                                                                                                                 |
| `concepts[].campaign_id`            | string           |                                                                                                                                                                                                                                                                                                                       |
| `concepts[].period_start`           | string           | Plan run day it belongs to (YYYY-MM-DD); absent for concepts drafted outside a plan run, e.g. with draft\_briefs.                                                                                                                                                                                                     |
| `concepts[].title`                  | string           |                                                                                                                                                                                                                                                                                                                       |
| `concepts[].hook`                   | string           |                                                                                                                                                                                                                                                                                                                       |
| `concepts[].concept`                | string           | One-paragraph creative concept.                                                                                                                                                                                                                                                                                       |
| `concepts[].output_kind`            | string           | One of `video`, `static_image`, `carousel`.                                                                                                                                                                                                                                                                           |
| `concepts[].status`                 | string           | draft = drafted, waiting for approve or reject; approved = in the production queue, not produced yet (creative\_produce); producing; produced = media ready (creative\_get); rejected; failed = drafting or production failed (see error). One of `draft`, `approved`, `producing`, `produced`, `rejected`, `failed`. |
| `concepts[].strength`               | string           | Ava's own read of how strong the idea is. One of `High`, `Medium`, `Low`.                                                                                                                                                                                                                                             |
| `concepts[].credit_range`           | array of values  | Estimated media credits to produce it (creative\_produce charges these at Studio prices). 2 to 2 items.                                                                                                                                                                                                               |
| `concepts[].estimated_duration_sec` | number           | Estimated video length; absent for images.                                                                                                                                                                                                                                                                            |
| `concepts[].preview_image_url`      | string           | Concept still, when Studio has made one.                                                                                                                                                                                                                                                                              |
| `concepts[].creative_id`            | string           | The concept's creative once approved; pass to creative\_get.                                                                                                                                                                                                                                                          |
| `concepts[].rejection_reason`       | string           |                                                                                                                                                                                                                                                                                                                       |
| `concepts[].error`                  | string           | Short reason, when status is failed.                                                                                                                                                                                                                                                                                  |
| `concepts[].studio_url`             | string           | Ava Studio link to the concept.                                                                                                                                                                                                                                                                                       |
| `concepts[].created_at`             | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                    |
| `concepts[].updated_at`             | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                    |
| `concepts[].next_steps`             | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                             |
| `next_steps`                        | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                             |

### concept\_approve

Approve 1-20 draft concepts into the campaign's production queue; if one fails, none are approved, and approving starts no production. Concepts that need an actor picked first come back in needs\_cast with a Studio link while the rest are approved; produce approved ones with creative\_produce.

* **Permission:** Manage campaigns (`campaigns:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/concept_approve`

#### Input

| Field             | Type             | Required | Description                                                                            |
| ----------------- | ---------------- | -------- | -------------------------------------------------------------------------------------- |
| `campaign_id`     | string           | Yes      | Campaign id from campaign\_list or campaign\_create.                                   |
| `concept_ids`     | array of strings | Yes      | 1-20 concept ids from concept\_list, all from this campaign. 1 to 20 items.            |
| `idempotency_key` | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters. |

#### Output

| Field                      | Type             | Description                                                                                               |
| -------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `campaign_id`              | string           |                                                                                                           |
| `approved`                 | array of objects | Concepts now in the production queue, including ones that already were.                                   |
| `approved[].concept_id`    | string           |                                                                                                           |
| `approved[].creative_id`   | string           | Pass to creative\_get; produce it with creative\_produce { concept\_id }.                                 |
| `needs_cast`               | array of objects | Concepts left unapproved because they need an actor chosen in Studio first; the rest were still approved. |
| `needs_cast[].concept_id`  | string           |                                                                                                           |
| `needs_cast[].faceless_ok` | boolean          | True when the concept also works without a person on screen.                                              |
| `needs_cast[].studio_url`  | string           | Where the user picks the actor in Ava Studio.                                                             |
| `next_steps`               | array of strings | Short hints naming the next tool to call.                                                                 |

### concept\_reject

Reject a draft concept, with an optional reason Ava uses as feedback when she drafts later concepts. Only concepts with status draft can be rejected (anything else is invalid\_input); returns the updated concept.

* **Permission:** Manage campaigns (`campaigns:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/concept_reject`

#### Input

| Field             | Type   | Required | Description                                                                                        |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `campaign_id`     | string | Yes      | Campaign id from campaign\_list or campaign\_create.                                               |
| `concept_id`      | string | Yes      | Concept id from concept\_list or plan\_get.                                                        |
| `reason`          | string |          | Why, in a sentence, e.g. too salesy, wrong audience. Up to 500 characters. At most 500 characters. |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.             |

#### Output

| Field                    | Type             | Description                                                                                                                                                                                                                                                                                                           |
| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display_code`           | string           | Studio's AVA-C### label for this reusable concept within the displayed week.                                                                                                                                                                                                                                          |
| `root_concept_id`        | string           |                                                                                                                                                                                                                                                                                                                       |
| `version_number`         | integer          | Value at least 1.                                                                                                                                                                                                                                                                                                     |
| `version_count`          | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                     |
| `concept_id`             | string           | Concept id. It is also a brief id: draft\_get, draft\_spec and draft\_prompts accept it as brief\_id.                                                                                                                                                                                                                 |
| `campaign_id`            | string           |                                                                                                                                                                                                                                                                                                                       |
| `period_start`           | string           | Plan run day it belongs to (YYYY-MM-DD); absent for concepts drafted outside a plan run, e.g. with draft\_briefs.                                                                                                                                                                                                     |
| `title`                  | string           |                                                                                                                                                                                                                                                                                                                       |
| `hook`                   | string           |                                                                                                                                                                                                                                                                                                                       |
| `concept`                | string           | One-paragraph creative concept.                                                                                                                                                                                                                                                                                       |
| `output_kind`            | string           | One of `video`, `static_image`, `carousel`.                                                                                                                                                                                                                                                                           |
| `status`                 | string           | draft = drafted, waiting for approve or reject; approved = in the production queue, not produced yet (creative\_produce); producing; produced = media ready (creative\_get); rejected; failed = drafting or production failed (see error). One of `draft`, `approved`, `producing`, `produced`, `rejected`, `failed`. |
| `strength`               | string           | Ava's own read of how strong the idea is. One of `High`, `Medium`, `Low`.                                                                                                                                                                                                                                             |
| `credit_range`           | array of values  | Estimated media credits to produce it (creative\_produce charges these at Studio prices). 2 to 2 items.                                                                                                                                                                                                               |
| `estimated_duration_sec` | number           | Estimated video length; absent for images.                                                                                                                                                                                                                                                                            |
| `preview_image_url`      | string           | Concept still, when Studio has made one.                                                                                                                                                                                                                                                                              |
| `creative_id`            | string           | The concept's creative once approved; pass to creative\_get.                                                                                                                                                                                                                                                          |
| `rejection_reason`       | string           |                                                                                                                                                                                                                                                                                                                       |
| `error`                  | string           | Short reason, when status is failed.                                                                                                                                                                                                                                                                                  |
| `studio_url`             | string           | Ava Studio link to the concept.                                                                                                                                                                                                                                                                                       |
| `created_at`             | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                    |
| `updated_at`             | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                    |
| `next_steps`             | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                             |

### concepts\_draft\_more

Draft 1-5 more concepts with the current campaign goal, reusing the existing run's research or the chosen source\_id; use plan\_run with refresh:true for fresh research and recommendations after a goal change. Costs 10 credits per concept drafted; it never produces media, so on a campaign whose mode is produce it fails with invalid\_input. Returns a job\_id; poll jobs\_get, the result lists only the new concepts.

* **Permission:** Manage campaigns (`campaigns:write`)
* **Price:** 10 credits per concept
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/concepts_draft_more`

#### Input

| Field             | Type    | Required | Description                                                                                                                |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`     | string  | Yes      | Campaign id from campaign\_list or campaign\_create.                                                                       |
| `period_start`    | string  |          | Saved run from plan\_list or campaign\_evidence; omit for the current week.                                                |
| `source_id`       | string  |          | Draft from an exact saved organic signal or owned Meta winner from campaign\_evidence; use count:1. No media is generated. |
| `count`           | integer | Yes      | How many concepts to draft (1-5). Value 1 to 5.                                                                            |
| `idempotency_key` | string  |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                     |

### concept\_draft\_get

Read a campaign concept's editable draft, scripts and submitted versions with project ids; before\_version pages older history. May initialize Studio's draft bookkeeping without starting production. For changes call concept\_draft\_update action:start\_editing, then save with the returned draft\_id/revision; submitted versions remain immutable.

* **Permission:** Read campaigns (`campaigns:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/concept_draft_get`

#### Input

| Field            | Type    | Required | Description                                          |
| ---------------- | ------- | -------- | ---------------------------------------------------- |
| `campaign_id`    | string  | Yes      | Campaign id from campaign\_list or campaign\_create. |
| `concept_id`     | string  | Yes      | Concept id from concept\_list or plan\_get.          |
| `before_version` | integer |          | Value at least 1.                                    |

#### Output

| Field                                     | Type             | Description                                                                                                                                                                     |
| ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`                             | string           |                                                                                                                                                                                 |
| `root_concept_id`                         | string           |                                                                                                                                                                                 |
| `display_code`                            | string           |                                                                                                                                                                                 |
| `draft_id`                                | string           |                                                                                                                                                                                 |
| `revision`                                | integer          | Value at least 0.                                                                                                                                                               |
| `requires_fork`                           | boolean          |                                                                                                                                                                                 |
| `version_number`                          | integer          | Value at least 1.                                                                                                                                                               |
| `version_count`                           | integer          | Value at least 0.                                                                                                                                                               |
| `draft`                                   | object           |                                                                                                                                                                                 |
| `draft.brief_id`                          | string           |                                                                                                                                                                                 |
| `draft.campaign_id`                       | string           |                                                                                                                                                                                 |
| `draft.brand_id`                          | string           |                                                                                                                                                                                 |
| `draft.title`                             | string           |                                                                                                                                                                                 |
| `draft.status`                            | string           | Draft lifecycle. candidate = drafted, awaiting review in Studio. One of `candidate`, `queued`, `planning`, `planned`, `generating`, `review`, `approved`, `failed`, `rejected`. |
| `draft.output_kind`                       | string           | One of `video`, `static_image`, `carousel`.                                                                                                                                     |
| `draft.platform`                          | string           | One of `tiktok`, `reels`, `shorts`, `meta`.                                                                                                                                     |
| `draft.concept`                           | string           | One-paragraph creative concept.                                                                                                                                                 |
| `draft.hook`                              | string           |                                                                                                                                                                                 |
| `draft.body`                              | string           |                                                                                                                                                                                 |
| `draft.cta`                               | string           |                                                                                                                                                                                 |
| `draft.script`                            | array of objects |                                                                                                                                                                                 |
| `draft.script[].id`                       | string           | Section tag, e.g. Hook, Body\_1, Cta.                                                                                                                                           |
| `draft.script[].label`                    | string           |                                                                                                                                                                                 |
| `draft.script[].channel`                  | string           | One of `spoken`, `voiceover`, `caption`.                                                                                                                                        |
| `draft.script[].role`                     | string           |                                                                                                                                                                                 |
| `draft.script[].text`                     | string           |                                                                                                                                                                                 |
| `draft.storyboard`                        | array of objects |                                                                                                                                                                                 |
| `draft.storyboard[].role`                 | string           | One of `hook`, `build`, `proof`, `cta`.                                                                                                                                         |
| `draft.storyboard[].beat`                 | string           | On-screen action / story beat (not a model prompt).                                                                                                                             |
| `draft.slides`                            | array of objects | Carousel briefs (output\_kind carousel): the slides in order.                                                                                                                   |
| `draft.slides[].index`                    | integer          | 1-based slide order. Value at least 1.                                                                                                                                          |
| `draft.slides[].role`                     | string           | hook, body or cta.                                                                                                                                                              |
| `draft.slides[].headline`                 | string           | Main on-slide text (empty on a text-free slide).                                                                                                                                |
| `draft.slides[].body`                     | string           | Supporting on-slide line under the headline.                                                                                                                                    |
| `draft.slides[].visual_description`       | string           | The image itself: scene, subject, framing. No text.                                                                                                                             |
| `draft.static_ad`                         | object           | Static briefs (output\_kind static\_image): the one image ad.                                                                                                                   |
| `draft.static_ad.headline`                | string           |                                                                                                                                                                                 |
| `draft.static_ad.body`                    | string           |                                                                                                                                                                                 |
| `draft.static_ad.cta`                     | string           |                                                                                                                                                                                 |
| `draft.static_ad.visual_description`      | string           | The image itself: scene, subject, framing. No text.                                                                                                                             |
| `draft.static_ad.aspect_ratio`            | string           | One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                            |
| `draft.caption`                           | string           | Post caption for a carousel or static, hashtags included.                                                                                                                       |
| `draft.variables`                         | object           |                                                                                                                                                                                 |
| `draft.variables.angle`                   | object           |                                                                                                                                                                                 |
| `draft.variables.hook`                    | object           |                                                                                                                                                                                 |
| `draft.variables.format`                  | object           |                                                                                                                                                                                 |
| `draft.variables.cast`                    | object           |                                                                                                                                                                                 |
| `draft.variables.cta`                     | object           |                                                                                                                                                                                 |
| `draft.rationale`                         | object           |                                                                                                                                                                                 |
| `draft.rationale.test_hypothesis`         | string           | The audience response this creative is designed to test.                                                                                                                        |
| `draft.rationale.audience`                | object           |                                                                                                                                                                                 |
| `draft.rationale.why_now`                 | string           |                                                                                                                                                                                 |
| `draft.rationale.evidence`                | object           |                                                                                                                                                                                 |
| `draft.rationale.predicted_strength`      | object           |                                                                                                                                                                                 |
| `draft.basis`                             | string           | One of `pattern`, `competitor`, `trend`, `first`.                                                                                                                               |
| `draft.strength`                          | string           | One of `High`, `Medium`, `Low`.                                                                                                                                                 |
| `draft.source`                            | object           |                                                                                                                                                                                 |
| `draft.source.kind`                       | string           | One of `ugc_recreate`, `competitor_recreate`, `original`.                                                                                                                       |
| `draft.source.url`                        | string           | Original platform URL of the reference video/ad.                                                                                                                                |
| `draft.source.video_id`                   | string           |                                                                                                                                                                                 |
| `draft.source.competitor_brand`           | string           |                                                                                                                                                                                 |
| `draft.source.format`                     | string           | draft\_clone: the source's format (e.g. talking\_head), kept in the brief.                                                                                                      |
| `draft.source.beats`                      | array of objects | draft\_clone: the source's beats, in order, that the brief follows.                                                                                                             |
| `draft.source.duration_sec`               | number           | draft\_clone: source video length in seconds.                                                                                                                                   |
| `draft.estimated_duration_sec`            | number           |                                                                                                                                                                                 |
| `draft.credit_range`                      | array of values  | Estimated credits to produce the video later in Studio. 2 to 2 items.                                                                                                           |
| `draft.preview_image_url`                 | string           |                                                                                                                                                                                 |
| `draft.rejection_reason`                  | string           |                                                                                                                                                                                 |
| `draft.origin`                            | object           |                                                                                                                                                                                 |
| `draft.origin.via`                        | string           | "api" for briefs created through this API.                                                                                                                                      |
| `draft.origin.client`                     | string           |                                                                                                                                                                                 |
| `draft.studio_url`                        | string           |                                                                                                                                                                                 |
| `draft.created_at`                        | string           | ISO-8601 timestamp                                                                                                                                                              |
| `draft.updated_at`                        | string           | ISO-8601 timestamp                                                                                                                                                              |
| `draft.evidence`                          | array of objects | What the brief cites, primary reference first: market videos (source corpus), your own Meta ads (source my\_ad) and, for draft\_clone, the cloned video (source clone\_source). |
| `draft.next_steps`                        | array of strings | Short hints naming the next tool to call.                                                                                                                                       |
| `submitted_concept_id`                    | string           | With action:submit, the immutable queued version; pass it to creative\_produce after spending approval.                                                                         |
| `creative_id`                             | string           |                                                                                                                                                                                 |
| `versions`                                | array of objects |                                                                                                                                                                                 |
| `versions[].concept_id`                   | string           |                                                                                                                                                                                 |
| `versions[].version_number`               | integer          | Value at least 1.                                                                                                                                                               |
| `versions[].status`                       | string           |                                                                                                                                                                                 |
| `versions[].creative_id`                  | string           |                                                                                                                                                                                 |
| `versions[].project_id`                   | string           |                                                                                                                                                                                 |
| `versions[].draft`                        | object           |                                                                                                                                                                                 |
| `versions[].draft.brief_id`               | string           |                                                                                                                                                                                 |
| `versions[].draft.campaign_id`            | string           |                                                                                                                                                                                 |
| `versions[].draft.brand_id`               | string           |                                                                                                                                                                                 |
| `versions[].draft.title`                  | string           |                                                                                                                                                                                 |
| `versions[].draft.status`                 | string           | Draft lifecycle. candidate = drafted, awaiting review in Studio. One of `candidate`, `queued`, `planning`, `planned`, `generating`, `review`, `approved`, `failed`, `rejected`. |
| `versions[].draft.output_kind`            | string           | One of `video`, `static_image`, `carousel`.                                                                                                                                     |
| `versions[].draft.platform`               | string           | One of `tiktok`, `reels`, `shorts`, `meta`.                                                                                                                                     |
| `versions[].draft.concept`                | string           | One-paragraph creative concept.                                                                                                                                                 |
| `versions[].draft.hook`                   | string           |                                                                                                                                                                                 |
| `versions[].draft.body`                   | string           |                                                                                                                                                                                 |
| `versions[].draft.cta`                    | string           |                                                                                                                                                                                 |
| `versions[].draft.script`                 | array of objects |                                                                                                                                                                                 |
| `versions[].draft.storyboard`             | array of objects |                                                                                                                                                                                 |
| `versions[].draft.slides`                 | array of objects | Carousel briefs (output\_kind carousel): the slides in order.                                                                                                                   |
| `versions[].draft.static_ad`              | object           | Static briefs (output\_kind static\_image): the one image ad.                                                                                                                   |
| `versions[].draft.caption`                | string           | Post caption for a carousel or static, hashtags included.                                                                                                                       |
| `versions[].draft.variables`              | object           |                                                                                                                                                                                 |
| `versions[].draft.rationale`              | object           |                                                                                                                                                                                 |
| `versions[].draft.basis`                  | string           | One of `pattern`, `competitor`, `trend`, `first`.                                                                                                                               |
| `versions[].draft.strength`               | string           | One of `High`, `Medium`, `Low`.                                                                                                                                                 |
| `versions[].draft.source`                 | object           |                                                                                                                                                                                 |
| `versions[].draft.estimated_duration_sec` | number           |                                                                                                                                                                                 |
| `versions[].draft.credit_range`           | array of values  | Estimated credits to produce the video later in Studio. 2 to 2 items.                                                                                                           |
| `versions[].draft.preview_image_url`      | string           |                                                                                                                                                                                 |
| `versions[].draft.rejection_reason`       | string           |                                                                                                                                                                                 |
| `versions[].draft.origin`                 | object           |                                                                                                                                                                                 |
| `versions[].draft.studio_url`             | string           |                                                                                                                                                                                 |
| `versions[].draft.created_at`             | string           | ISO-8601 timestamp                                                                                                                                                              |
| `versions[].draft.updated_at`             | string           | ISO-8601 timestamp                                                                                                                                                              |
| `versions[].draft.evidence`               | array of objects | What the brief cites, primary reference first: market videos (source corpus), your own Meta ads (source my\_ad) and, for draft\_clone, the cloned video (source clone\_source). |
| `versions[].draft.next_steps`             | array of strings | Short hints naming the next tool to call.                                                                                                                                       |
| `next_cursor`                             | integer          | Value at least 1.                                                                                                                                                               |
| `next_steps`                              | array of strings | Short hints naming the next tool to call.                                                                                                                                       |

### concept\_draft\_update

Edit campaign scripts, their order, carousel copy or storyboard direction using Studio's version workflow; saving generates no media and costs no credits. Read concept\_draft\_get, call action:start\_editing, then action:save with returned draft\_id/revision and patch, then action:submit to queue a version for separate approved production. Existing projects stay intact; slides\_update/timeline\_update edit existing on-screen text and layout.

* **Permission:** Manage campaigns (`campaigns:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/concept_draft_update`

#### Input

| Field                           | Type             | Required | Description                                                                                                                                                                           |
| ------------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`                   | string           | Yes      | Campaign id from campaign\_list or campaign\_create.                                                                                                                                  |
| `concept_id`                    | string           | Yes      | Concept id from concept\_list or plan\_get.                                                                                                                                           |
| `draft_id`                      | string           | Yes      |                                                                                                                                                                                       |
| `revision`                      | integer          | Yes      | Value at least 0.                                                                                                                                                                     |
| `action`                        | string           | Yes      | One of `start_editing`, `save`, `submit`.                                                                                                                                             |
| `patch`                         | object           |          |                                                                                                                                                                                       |
| `patch.concept`                 | string           |          | At most 10000 characters.                                                                                                                                                             |
| `patch.hook`                    | string           |          | At most 2000 characters.                                                                                                                                                              |
| `patch.body`                    | string or null   |          |                                                                                                                                                                                       |
| `patch.cta`                     | string or null   |          |                                                                                                                                                                                       |
| `patch.script`                  | array of objects |          | Complete script in the requested order; keep each section id. Speech changes apply to this draft and require approved production to change the generated audio/video. 1 to 100 items. |
| `patch.script[].id`             | string           | Yes      | 1 to 128 characters.                                                                                                                                                                  |
| `patch.script[].label`          | string           |          | At most 200 characters.                                                                                                                                                               |
| `patch.script[].channel`        | string           |          | One of `spoken`, `voiceover`, `caption`.                                                                                                                                              |
| `patch.script[].role`           | string           |          | At most 100 characters.                                                                                                                                                               |
| `patch.script[].text`           | string           | Yes      | 1 to 10000 characters.                                                                                                                                                                |
| `patch.storyboard`              | array of objects |          | Visual direction: lighting, setting and performance, with each beat's role. Existing produced media is preserved. 1 to 100 items.                                                     |
| `patch.storyboard[].role`       | string           | Yes      | One of `hook`, `build`, `proof`, `cta`.                                                                                                                                               |
| `patch.storyboard[].beat`       | string           | Yes      | 1 to 5000 characters.                                                                                                                                                                 |
| `patch.carousel_slides`         | array of objects |          | 1 to 50 items.                                                                                                                                                                        |
| `patch.carousel_slides[].index` | integer          | Yes      | Value at least 0.                                                                                                                                                                     |
| `patch.carousel_slides[].text`  | string           | Yes      | At most 10000 characters.                                                                                                                                                             |
| `idempotency_key`               | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                |

#### Output

| Field                                     | Type             | Description                                                                                                                                                                     |
| ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`                             | string           |                                                                                                                                                                                 |
| `root_concept_id`                         | string           |                                                                                                                                                                                 |
| `display_code`                            | string           |                                                                                                                                                                                 |
| `draft_id`                                | string           |                                                                                                                                                                                 |
| `revision`                                | integer          | Value at least 0.                                                                                                                                                               |
| `requires_fork`                           | boolean          |                                                                                                                                                                                 |
| `version_number`                          | integer          | Value at least 1.                                                                                                                                                               |
| `version_count`                           | integer          | Value at least 0.                                                                                                                                                               |
| `draft`                                   | object           |                                                                                                                                                                                 |
| `draft.brief_id`                          | string           |                                                                                                                                                                                 |
| `draft.campaign_id`                       | string           |                                                                                                                                                                                 |
| `draft.brand_id`                          | string           |                                                                                                                                                                                 |
| `draft.title`                             | string           |                                                                                                                                                                                 |
| `draft.status`                            | string           | Draft lifecycle. candidate = drafted, awaiting review in Studio. One of `candidate`, `queued`, `planning`, `planned`, `generating`, `review`, `approved`, `failed`, `rejected`. |
| `draft.output_kind`                       | string           | One of `video`, `static_image`, `carousel`.                                                                                                                                     |
| `draft.platform`                          | string           | One of `tiktok`, `reels`, `shorts`, `meta`.                                                                                                                                     |
| `draft.concept`                           | string           | One-paragraph creative concept.                                                                                                                                                 |
| `draft.hook`                              | string           |                                                                                                                                                                                 |
| `draft.body`                              | string           |                                                                                                                                                                                 |
| `draft.cta`                               | string           |                                                                                                                                                                                 |
| `draft.script`                            | array of objects |                                                                                                                                                                                 |
| `draft.script[].id`                       | string           | Section tag, e.g. Hook, Body\_1, Cta.                                                                                                                                           |
| `draft.script[].label`                    | string           |                                                                                                                                                                                 |
| `draft.script[].channel`                  | string           | One of `spoken`, `voiceover`, `caption`.                                                                                                                                        |
| `draft.script[].role`                     | string           |                                                                                                                                                                                 |
| `draft.script[].text`                     | string           |                                                                                                                                                                                 |
| `draft.storyboard`                        | array of objects |                                                                                                                                                                                 |
| `draft.storyboard[].role`                 | string           | One of `hook`, `build`, `proof`, `cta`.                                                                                                                                         |
| `draft.storyboard[].beat`                 | string           | On-screen action / story beat (not a model prompt).                                                                                                                             |
| `draft.slides`                            | array of objects | Carousel briefs (output\_kind carousel): the slides in order.                                                                                                                   |
| `draft.slides[].index`                    | integer          | 1-based slide order. Value at least 1.                                                                                                                                          |
| `draft.slides[].role`                     | string           | hook, body or cta.                                                                                                                                                              |
| `draft.slides[].headline`                 | string           | Main on-slide text (empty on a text-free slide).                                                                                                                                |
| `draft.slides[].body`                     | string           | Supporting on-slide line under the headline.                                                                                                                                    |
| `draft.slides[].visual_description`       | string           | The image itself: scene, subject, framing. No text.                                                                                                                             |
| `draft.static_ad`                         | object           | Static briefs (output\_kind static\_image): the one image ad.                                                                                                                   |
| `draft.static_ad.headline`                | string           |                                                                                                                                                                                 |
| `draft.static_ad.body`                    | string           |                                                                                                                                                                                 |
| `draft.static_ad.cta`                     | string           |                                                                                                                                                                                 |
| `draft.static_ad.visual_description`      | string           | The image itself: scene, subject, framing. No text.                                                                                                                             |
| `draft.static_ad.aspect_ratio`            | string           | One of `9:16`, `4:5`, `1:1`, `16:9`.                                                                                                                                            |
| `draft.caption`                           | string           | Post caption for a carousel or static, hashtags included.                                                                                                                       |
| `draft.variables`                         | object           |                                                                                                                                                                                 |
| `draft.variables.angle`                   | object           |                                                                                                                                                                                 |
| `draft.variables.hook`                    | object           |                                                                                                                                                                                 |
| `draft.variables.format`                  | object           |                                                                                                                                                                                 |
| `draft.variables.cast`                    | object           |                                                                                                                                                                                 |
| `draft.variables.cta`                     | object           |                                                                                                                                                                                 |
| `draft.rationale`                         | object           |                                                                                                                                                                                 |
| `draft.rationale.test_hypothesis`         | string           | The audience response this creative is designed to test.                                                                                                                        |
| `draft.rationale.audience`                | object           |                                                                                                                                                                                 |
| `draft.rationale.why_now`                 | string           |                                                                                                                                                                                 |
| `draft.rationale.evidence`                | object           |                                                                                                                                                                                 |
| `draft.rationale.predicted_strength`      | object           |                                                                                                                                                                                 |
| `draft.basis`                             | string           | One of `pattern`, `competitor`, `trend`, `first`.                                                                                                                               |
| `draft.strength`                          | string           | One of `High`, `Medium`, `Low`.                                                                                                                                                 |
| `draft.source`                            | object           |                                                                                                                                                                                 |
| `draft.source.kind`                       | string           | One of `ugc_recreate`, `competitor_recreate`, `original`.                                                                                                                       |
| `draft.source.url`                        | string           | Original platform URL of the reference video/ad.                                                                                                                                |
| `draft.source.video_id`                   | string           |                                                                                                                                                                                 |
| `draft.source.competitor_brand`           | string           |                                                                                                                                                                                 |
| `draft.source.format`                     | string           | draft\_clone: the source's format (e.g. talking\_head), kept in the brief.                                                                                                      |
| `draft.source.beats`                      | array of objects | draft\_clone: the source's beats, in order, that the brief follows.                                                                                                             |
| `draft.source.duration_sec`               | number           | draft\_clone: source video length in seconds.                                                                                                                                   |
| `draft.estimated_duration_sec`            | number           |                                                                                                                                                                                 |
| `draft.credit_range`                      | array of values  | Estimated credits to produce the video later in Studio. 2 to 2 items.                                                                                                           |
| `draft.preview_image_url`                 | string           |                                                                                                                                                                                 |
| `draft.rejection_reason`                  | string           |                                                                                                                                                                                 |
| `draft.origin`                            | object           |                                                                                                                                                                                 |
| `draft.origin.via`                        | string           | "api" for briefs created through this API.                                                                                                                                      |
| `draft.origin.client`                     | string           |                                                                                                                                                                                 |
| `draft.studio_url`                        | string           |                                                                                                                                                                                 |
| `draft.created_at`                        | string           | ISO-8601 timestamp                                                                                                                                                              |
| `draft.updated_at`                        | string           | ISO-8601 timestamp                                                                                                                                                              |
| `draft.evidence`                          | array of objects | What the brief cites, primary reference first: market videos (source corpus), your own Meta ads (source my\_ad) and, for draft\_clone, the cloned video (source clone\_source). |
| `draft.next_steps`                        | array of strings | Short hints naming the next tool to call.                                                                                                                                       |
| `submitted_concept_id`                    | string           | With action:submit, the immutable queued version; pass it to creative\_produce after spending approval.                                                                         |
| `creative_id`                             | string           |                                                                                                                                                                                 |
| `versions`                                | array of objects |                                                                                                                                                                                 |
| `versions[].concept_id`                   | string           |                                                                                                                                                                                 |
| `versions[].version_number`               | integer          | Value at least 1.                                                                                                                                                               |
| `versions[].status`                       | string           |                                                                                                                                                                                 |
| `versions[].creative_id`                  | string           |                                                                                                                                                                                 |
| `versions[].project_id`                   | string           |                                                                                                                                                                                 |
| `versions[].draft`                        | object           |                                                                                                                                                                                 |
| `versions[].draft.brief_id`               | string           |                                                                                                                                                                                 |
| `versions[].draft.campaign_id`            | string           |                                                                                                                                                                                 |
| `versions[].draft.brand_id`               | string           |                                                                                                                                                                                 |
| `versions[].draft.title`                  | string           |                                                                                                                                                                                 |
| `versions[].draft.status`                 | string           | Draft lifecycle. candidate = drafted, awaiting review in Studio. One of `candidate`, `queued`, `planning`, `planned`, `generating`, `review`, `approved`, `failed`, `rejected`. |
| `versions[].draft.output_kind`            | string           | One of `video`, `static_image`, `carousel`.                                                                                                                                     |
| `versions[].draft.platform`               | string           | One of `tiktok`, `reels`, `shorts`, `meta`.                                                                                                                                     |
| `versions[].draft.concept`                | string           | One-paragraph creative concept.                                                                                                                                                 |
| `versions[].draft.hook`                   | string           |                                                                                                                                                                                 |
| `versions[].draft.body`                   | string           |                                                                                                                                                                                 |
| `versions[].draft.cta`                    | string           |                                                                                                                                                                                 |
| `versions[].draft.script`                 | array of objects |                                                                                                                                                                                 |
| `versions[].draft.storyboard`             | array of objects |                                                                                                                                                                                 |
| `versions[].draft.slides`                 | array of objects | Carousel briefs (output\_kind carousel): the slides in order.                                                                                                                   |
| `versions[].draft.static_ad`              | object           | Static briefs (output\_kind static\_image): the one image ad.                                                                                                                   |
| `versions[].draft.caption`                | string           | Post caption for a carousel or static, hashtags included.                                                                                                                       |
| `versions[].draft.variables`              | object           |                                                                                                                                                                                 |
| `versions[].draft.rationale`              | object           |                                                                                                                                                                                 |
| `versions[].draft.basis`                  | string           | One of `pattern`, `competitor`, `trend`, `first`.                                                                                                                               |
| `versions[].draft.strength`               | string           | One of `High`, `Medium`, `Low`.                                                                                                                                                 |
| `versions[].draft.source`                 | object           |                                                                                                                                                                                 |
| `versions[].draft.estimated_duration_sec` | number           |                                                                                                                                                                                 |
| `versions[].draft.credit_range`           | array of values  | Estimated credits to produce the video later in Studio. 2 to 2 items.                                                                                                           |
| `versions[].draft.preview_image_url`      | string           |                                                                                                                                                                                 |
| `versions[].draft.rejection_reason`       | string           |                                                                                                                                                                                 |
| `versions[].draft.origin`                 | object           |                                                                                                                                                                                 |
| `versions[].draft.studio_url`             | string           |                                                                                                                                                                                 |
| `versions[].draft.created_at`             | string           | ISO-8601 timestamp                                                                                                                                                              |
| `versions[].draft.updated_at`             | string           | ISO-8601 timestamp                                                                                                                                                              |
| `versions[].draft.evidence`               | array of objects | What the brief cites, primary reference first: market videos (source corpus), your own Meta ads (source my\_ad) and, for draft\_clone, the cloned video (source clone\_source). |
| `versions[].draft.next_steps`             | array of strings | Short hints naming the next tool to call.                                                                                                                                       |
| `next_cursor`                             | integer          | Value at least 1.                                                                                                                                                               |
| `next_steps`                              | array of strings | Short hints naming the next tool to call.                                                                                                                                       |
