API docs v1
POST /v1/brands/{brand_id}/content-briefs

Create a content brief

scope write:content cost 8 RU · 10 credits rate-limit 10/minute · key idempotent required

Create a content brief and generate its content inline, returning the finished article.

The AI pipeline runs synchronously and routinely takes minutes, so allow a long timeout, and prefer POST /v1/brands/{brand_id}/content-briefs/generations for anything unattended, which queues the same work and hands you a job to poll. A client that gives up on this request does not stop the pipeline: it keeps running and still charges.

Provide a topic or at least one target_keywords entry. Costs credits, charged to the brand's owner.

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

Header parameters

  • Idempotency-Key string required

    Required with an API key, else 400 idempotency_key_required: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with dry_run=true.

Request body

application/json required
Type: ContentBriefCreate
  • 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 (see the brief's content_context), and length, knowledge, language, tone, audience and tools (see the brief's content_context). Those keys are checked: an unknown language, a tone or audience over 200 characters, a tool or mode outside the lists, or a source that is not an http(s) address answers 422. Other keys are ignored.

    Show fields

    Empty object (no properties).

  • content_type enum (nullable) nullable

    Content format to generate; inferred from the topic when omitted.

  • opportunity_id string (nullable) nullable

    The id of the content opportunity this article answers.

  • planned_publish_at string (nullable) nullable

    When it should go live. It prefills the CMS schedule; nothing fires from it.

    format: `date-time`

  • source_prompt_ids array of string

    Report prompts this article is written to answer. They are snapshotted now, so the citation uplift can later say which of them came back.

    max items: 50

  • target_keywords array of string

    Target keywords to write around (each up to 200 chars).

    max items: 20

  • title string (nullable) nullable

    Optional title; the generator fills one in when omitted.

  • topic string (nullable) nullable

    Topic or target keyword to write about. Provide this or at least one target_keywords entry.

Responses

Created 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"
}
Not enough credits to complete this operation 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": "insufficient_credits",
    "message": "Not enough credits to complete this operation"
  },
  "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"
}
Request body did not match the expected schema 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": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "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"
}