---
title: "Update a creative brief"
method: PUT
path: "/creative-briefs/{brief_id}"
tags: ["Briefs"]
---

# Update a creative brief

`PUT /creative-briefs/{brief_id}`

Replace this brief's editable content — name, description, angles, USPs, filming recommendations, dos/don'ts, inspiration videos — and its `status`. Set `status: published` to make it shareable (its URL is then available from `GET /creative-briefs/published-url`), or `archived` to retire it.

This is a **replace**: the stored document is rebuilt from the body, so send the whole brief back with your edits, not just changed fields.

Two things happen automatically on save: inspiration videos missing `key_points` get them AI-generated from that video's analysis, and videos missing an `orders` count have it filled from our attribution data. `Idempotency-Key` is optional here (a replace is naturally repeatable); `X-Dry-Run: true` validates without writing.

## Path parameters

- `brief_id` integer, required

## Headers

- `Idempotency-Key` string, nullable
- `X-Dry-Run` string, nullable

## Request body

- CreativeBriefUpdateRequest — Full-document update for one creative brief (the portal's save action). This is a replace, not a patch: the portal's editor always submits the whole document, and the stored `brief_content` blob is rebuilt from these fields. Omitted fields therefore reset to their defaults — send back what `GET /creative-briefs/{brief_id}` returned, with your edits applied. `image_urls` is a plain ordered list here; the portal's index-keyed object with its `"uploaded"` sentinel is an upload-widget artifact, not a contract worth publishing. File uploads are portal-only — pass already-hosted URLs.
  - `brief_name` string, nullable
  - `product_description` string, nullable
  - `when_to_use` string
  - `image_urls` string[]
  - `content_angles` unknown[]
    - unknown
  - `unique_selling_points` unknown[]
    - unknown
  - `filming_recommendations` object
  - `dos_and_donts` object
  - `content_inspiration` unknown[] — Inspiration videos. Entries missing `key_points` get them AI-generated from the video's analysis on save. At most 50 entries.
    - unknown
  - `status` string

## Response `200`

Successful Response

- CreativeBriefWriteResponse
  - `data` object, required
  - `dry_run` boolean

## Other responses

- `400` — Validation error, multi-shop key, or missing/invalid Idempotency-Key.
- `403` — API key lacks `read_write` scope (`WRITE_NOT_PERMITTED`).
- `404` — Brief or product not found in this shop.
- `409` — Idempotency conflict.
- `422` — Validation Error
- `429` — Write-tier rate limit exceeded.

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/578c830ce294/schema)