# POST /v1/content/:containerId/regenerate (/docs/api/reference/content/regenerate-content)



<Endpoint method="POST" path="/v1/content/:containerId/regenerate" scope="content:write" phase="1">
  Runs the generation pipeline again for an existing container. The container
  id stays the same; the media and caption get replaced.
</Endpoint>

Use regenerate when a container is almost right but you want a new take — different visuals, tighter caption. The container's id, approval state, and scheduled-post links are preserved. Old media assets are superseded but not deleted (previous versions remain accessible via their asset ids until storage lifecycle rules clean them up).

## What happens to the old content [#what-happens-to-the-old-content]

* **Media assets:** new assets are written; `GET /v1/content/:containerId` returns only the current set in `assets`.
* **Caption:** replaced entirely.
* **Approval status:** reset to `pending` if the project's approval policy requires review. Previously approved? You'll need to approve again.
* **Scheduled posts:** untouched. If they were queued against the old caption, they'll publish the old caption. Cancel and re-schedule if the caption change matters.

## Path parameters [#path-parameters]

<Parameters
  rows="[
  { name: 'containerId', type: 'string (uuid)', required: true, description: 'The container to regenerate.' },
]"
/>

## Body [#body]

<Parameters
  title="Body (all optional)"
  rows="[
  { name: 'brief', type: 'object', description: 'Overrides for the original brief. Anything you omit keeps its previous value.' },
  { name: 'brief.topic', type: 'string', description: 'New subject or premise.' },
  { name: 'brief.angle', type: 'string', description: 'New point of view.' },
  { name: 'brief.cta', type: 'string', description: 'New closing call-to-action.' },
  { name: 'brief.valuePropositions', type: 'string[]', description: 'Replace the benefit array.' },
  { name: 'references', type: 'object', description: 'Updated structured references. `{ sourcePostIds?: string[], assetIds?: string[] }`' },
  { name: 'preserveAssets', type: 'boolean', default: 'false', description: 'If true, the workflow keeps existing assets and regenerates only the caption.' },
]"
/>

## Request [#request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```sh title="terminal"
    curl -X POST https://api.layers.com/v1/content/{containerId}/regenerate \
      -H "X-Api-Key: $LAYERS_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: 8d2f1a3e-0b4c-4a11-9f7e-33c0a2c1bd55" \
      -d '{ "brief": { "topic": "Thirty days, one run at a time." } }'
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="regenerate-content.ts"
    const res = await fetch(
      `https://api.layers.com/v1/content/${containerId}/regenerate`,
      {
        method: 'POST',
        headers: {
          'X-Api-Key': process.env.LAYERS_API_KEY!,
          'Content-Type': 'application/json',
          'Idempotency-Key': crypto.randomUUID(),
        },
        body: JSON.stringify({
          brief: { cta: 'Start today — link in bio.' },
          preserveAssets: false,
        }),
      },
    );
    const { jobId, containerId: id } = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```py title="regenerate_content.py"
    import os, uuid, httpx

    r = httpx.post(
        f"https://api.layers.com/v1/content/{container_id}/regenerate",
        headers={
            "X-Api-Key": os.environ["LAYERS_API_KEY"],
            "Content-Type": "application/json",
            "Idempotency-Key": str(uuid.uuid4()),
        },
        json={"brief": {"cta": "Start today — link in bio."}},
    )
    job = r.json()
    ```
  </Tab>
</Tabs>

## Responses [#responses]

<Response status="202" description="Regeneration job accepted.">
  ```json
  {
    "jobId": "job_01HXZ9G7KMV2QX8Y1S5RJW3B7T",
    "kind": "content_regenerate",
    "status": "running",
    "containerId": "cnt_01HXZ9...",
    "locationUrl": "/v1/jobs/job_01HXZ9G7KMV2QX8Y1S5RJW3B7T"
  }
  ```
</Response>

## Stages [#stages]

Uses the `content_regenerate` job kind. Same stages as generate: `planning` → `generating_visuals` → `assembling` → `finalizing`.

## Errors [#errors]

| Code                 | When                                  |
| -------------------- | ------------------------------------- |
| `VALIDATION_FAILED`  | Bad field in `brief` or `references`. |
| `BILLING_EXHAUSTED`  | Credits insufficient.                 |
| `MODERATION_BLOCKED` | Updated brief failed safety.          |
| `NOT_FOUND`          | Container id not in this org.         |

## See also [#see-also]

* [Generate a new container](/docs/api/reference/content/generate-content)
* [Read container state](/docs/api/reference/content/get-container)
* [Poll the job](/docs/api/reference/jobs/get-job)