API docs v1
GET /v1/brands/{brand_id}/content-briefs/{brief_id}

Retrieve a content brief

scope read:content cost 3 RU

Fetch a single content brief by id, including its generated assets (article HTML, images, meta), the structured outline_json, and the research_output. Cross-brand requests return 404 not_found.

Path parameters

Query parameters

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Responses

Returned a content brief application/json
Type: ContentBrief
  • brand_id string required

    Owning brand id (UUID).

  • created_at string required

    When the brief was created.

    format: `date-time`

  • id string required

    Content brief id (UUID).

  • status enum required

    Brief lifecycle state. One of draft, processing, needs_review, published, failed.

  • assets array of ContentAsset

    Generated assets (article HTML, images, meta).

  • content_context object

    The format's own fields (the ones a content opportunity pre-fills, e.g. listTheme and listSize for ranked_list), plus sources: {"urls": [...], "only_mine": false}, up to 10 pages or PDFs the article reads before writing and cites, each reported in quality_report.enforcement.sources as used, not_used or source_unreadable (only_mine: true turns web search off and unwraps any other outside link), sourcePrompts: ids of the report prompts the article answers, and length: {"mode": "auto"|"short"|"standard"|"long"} or {"mode": "exact", "words": 300-5000} (omitted: the brand's default_length), and blockedWords: up to 100 phrases of up to 100 characters this article must not use on top of the brand's banned_phrases, and knowledge: {"mode": "auto"} (the knowledge base chunks closest to the topic, the default), {"mode": "pick", "ids": [...]} (only those knowledge base items) or {"mode": "off"}. This article only: language (a language name, over the brand's), tone (up to 200 characters, over the brand's), audience (who it is written for, up to 200 characters) and tools ({tool: on|off|auto} over the brand's AI tools, see content preferences). Other keys are ignored; the brand's banned phrases stay in its preferences.

    Show fields

    Empty object (no properties).

  • content_type string (nullable) nullable

    Content format id (e.g. blog_post, ranked_list).

  • error_message string (nullable) nullable

    User-facing failure reason when status is failed.

  • generated_at string (nullable) nullable

    When content was last generated, if ever.

    format: `date-time`

  • generation_settings object | array of any

    What the last run wrote with and where each value came from: language, tone, length, audience, banned_phrases, knowledge and sources as {value, origin}, and tools as {value: {tool: mode}, origin: {tool: origin}}; origin is article (this brief's content_context), brand (the brand's content preferences) or system. A regeneration keeps the brand values it records unless asked for today's. Null before the first run.

  • mode enum

    create writes a new article; optimize improves the page at source_url (content-optimizations).

    default: `create`

  • object string

    Always content_brief.

    default: `content_brief`

  • opportunity_id string (nullable) nullable

    The content opportunity this article answers, when it was created from one.

  • optimize_level enum (nullable) nullable

    How far an optimize brief goes; null for create.

  • outline_json object | array of any

    Structured article outline produced during generation.

  • planned_publish_at string (nullable) nullable

    The day the article sits on in the content calendar until it is published or a publish is queued; null when it has none. Set it with PATCH /v1/brands/{brand_id}/content-briefs/{brief_id}.

    format: `date-time`

  • publications array of ContentPublication

    Every place the article was published, with its live URL. Empty until it is published.

  • quality_report object | array of any

    Rule-based checks run on the finished article: {score, axes[], checks[], notes[], words, language, link_check}, where score is the percentage of weighted checks that passed. link_check is the source check run after writing: checked (how many external links were fetched), removed[] (links unwrapped because the page is gone: url, reason, status), warnings[] (links kept but worth a look, each {url, reason}: moved_to_root when a deep link now lands on the site's home page, with the final_url it landed on, unverified when the research never read the page) and unverified_claims[] ({sentence, numbers[], urls[], reason}, reason being not_on_source when the cited page does not carry the figures, source_removed when every cited link was removed, source_unreadable when no cited page could be read). Advisory only; it never blocks publishing.

  • research_output string (nullable) nullable

    Research notes gathered during generation.

  • review_due_at string (nullable) nullable

    When the article's fastest-ageing fact (a price, a plan tier) is worth re-checking.

    format: `date-time`

  • serp_research object | array of any

    What Google ranked for the target keyword when the article was researched: pages (rank, url, domain, title, words, published_at, reachable), people_also_ask, features, table_stakes (subtopics most top pages cover), differentiators, median_words and intent (Google's main intent for the keyword: informational, commercial, transactional or navigational, null when unknown). Null when the results page was unavailable.

  • source_url string (nullable) nullable

    The brand's own page an optimize brief improves.

  • target_keywords array of string

    Target keywords for the brief.

  • title string (nullable) nullable

    Brief title, set on creation or filled in from the article.

  • topic string (nullable) nullable

    Topic or target keyword the content is written around.

  • updated_at string (nullable) nullable

    When the brief was last updated.

    format: `date-time`

Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}