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. The AI pipeline runs synchronously and can take a while, so allow a long timeout. Provide a topic or at least one target_keywords entry. Costs credits, charged to the account this API key belongs to. Returns the generated brief.

Path parameters

Header parameters

Request body

application/json required
Type:ContentBriefCreate
  • content_contextobject

    Free-form context folded into the generation prompt.

    Show fields

    Empty object (no properties).

  • content_typeenum (nullable)nullable

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

  • target_keywordsarray of string

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

    max items: 20

  • titlestring (nullable)nullable

    Optional title; the generator fills one in when omitted.

  • topicstring (nullable)nullable

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

Responses

Created a content briefapplication/json
Type:ContentBrief
  • brand_idstringrequired

    Owning brand id (UUID).

  • created_atstringrequired

    When the brief was created.

    format: `date-time`

  • idstringrequired

    Content brief id (UUID).

  • statusenumrequired

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

  • assetsarray of ContentAsset

    Generated assets (article HTML, images, meta).

  • content_contextobject

    Free-form context folded into the generation prompt.

    Show fields

    Empty object (no properties).

  • content_typestring (nullable)nullable

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

  • error_messagestring (nullable)nullable

    User-facing failure reason when status is failed.

  • generated_atstring (nullable)nullable

    When content was last generated, if ever.

    format: `date-time`

  • objectstring

    Always content_brief.

    default: `content_brief`

  • outline_jsonobject | array of any

    Structured article outline produced during generation.

  • research_outputstring (nullable)nullable

    Research notes gathered during generation.

  • target_keywordsarray of string

    Target keywords for the brief.

  • titlestring (nullable)nullable

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

  • topicstring (nullable)nullable

    Topic or target keyword the content is written around.

  • updated_atstring (nullable)nullable

    When the brief was last updated.

    format: `date-time`

Request validation failedapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 credentialsapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 operationapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 resourceapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 foundapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 conflictapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 schemaapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 exceededapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 occurredapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 retryapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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"
}