API docs v1
PATCH /v1/brands/{brand_id}/content-preferences

Set how this brand's articles are written

scope write:content cost 2 RU idempotent optional

Change what you send and leave the rest. tone and writing_style are free text the writer reads, so write them as you would tell a person: what to sound like, how long the paragraphs are, whether to use tables. banned_phrases are dropped whatever the topic. It applies to the next article, not to ones already written. A field sent as null clears it: language: null writes in the brand's market language again. auto_interlink: true applies the proposed links back to every article of the brand that goes live, on sites that can edit a post; other sites get a task. recheck_source_prompts: true runs each live article's source prompts again 14 and 28 days after it went live, charged like any run; it needs the brand owner on Starter.

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 optional

    Optional. A retry with the same key and body within 24 hours replays the first response.

Request body

application/json required
Type: ContentPreferencesUpdate
  • banned_phrases array of string (nullable) nullable

    Up to 100 phrases, each up to 200 characters.

  • default_length enum (nullable) nullable

    Default article length: auto, short, standard or long.

  • image_style string (nullable) nullable
  • language string (nullable) nullable
  • recheck_source_prompts boolean (nullable) nullable

    Run each live article's source prompts again 14 and 28 days after it went live (Starter, charged).

  • tone string (nullable) nullable
  • tools object (nullable) nullable

    AI tool defaults to set, for example {"google_news": "on", "screenshots": "off"}: the whole map is replaced by what you send.

  • writing_style string (nullable) nullable

Responses

Set how this brand's articles are written application/json
Type: ContentPreferences
  • banned_phrases array of string

    Phrases the article must not use, whatever the topic.

  • default_length enum

    How long articles run unless a brief sets content_context.length. auto follows the median length of the readable top Google results for the keyword (times 1.1); short, standard and long are about 800, 1,500 and 2,500 words. All of them are held inside the content type's bounds.

    default: `auto`

  • image_style string (nullable) nullable

    How generated images should look.

  • language string (nullable) nullable

    Language to write in; the brand's own when null.

  • object string

    default: `content_preferences`

  • recheck_source_prompts boolean

    When true, the prompts each article was written for run again 14 and 28 days after it went live, in the market and on the engines they were measured in, as a one-off report named after the article. Each run is charged like any run. Needs the brand owner on Starter or above.

    default: `false`

  • tone string (nullable) nullable

    How it should sound, in your words.

  • tools object

    The brand's default for each AI tool its articles may use: on, off or auto (the run decides from the format, the site index, the knowledge base and the results page). A tool not listed is auto. A brief overrides any of them in content_context.tools.

    Show fields

    Empty object (no properties).

  • voice_extracted_at string (nullable) nullable

    When the voice was last learned.

  • voice_profile VoiceProfile (nullable) nullable

    The voice learned from the brand's own posts, or null before it is learned. Generation does not read it: copy what fits into writing_style and banned_phrases.

  • writing_style string (nullable) nullable

    Structure and habits: length, lists, tables.

Example response 
{
  "auto_interlink": true,
  "banned_phrases": [
    "game changer",
    "in today's fast-paced world"
  ],
  "default_length": "auto",
  "image_style": "Flat illustration, purple accents",
  "language": "English",
  "object": "content_preferences",
  "recheck_source_prompts": false,
  "tone": "Direct and technical, no hype",
  "writing_style": "Short paragraphs, real numbers, a table when comparing"
}
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"
}
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"
}