POST /v1/brands/{brand_id}/content-briefs/generations

Generate an article asynchronously

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

Create a content brief and run the AI pipeline in the background. Returns immediately with a brief_id and a job_id.

Prefer this over POST /v1/brands/{brand_id}/content-briefs for anything unattended. Generation chains research, outline, writing and images and routinely runs for minutes. The synchronous endpoint holds the connection open for all of it and will time out on a slow article while the pipeline keeps running and still charges you.

Workflow:

POST /v1/brands/{brand_id}/content-briefs/generations: returns { brief_id, job_id }.
GET /v1/jobs/{job_id}: poll until status is completed. step reports the pipeline phase (research, outline, writer, editor, images).
GET /v1/brands/{brand_id}/content-briefs/{brief_id}: read the finished article.
POST /v1/brands/{brand_id}/content-briefs/{brief_id}/publish: push it to WordPress.

Pricing: the same credits as the synchronous endpoint, debited when the worker picks the job up. Your balance is checked before the job is queued, so an underfunded account gets 402 here rather than a job that fails later. A failed generation is refunded automatically.

Subject to the LLM-tier rate limit, which is stricter than the global /v1 burst cap.

Path parameters

brand_idstring required
Brand UUID.

Query parameters

dry_runboolean 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-Keystring optional

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

Content generation job dispatched.application/json

Type:ContentBriefDispatched

brand_idstringrequired
Brand the article is being written for.
brief_idstringrequired
The brief that was created. It is in processing until generation finishes.
job_idstringrequired
Poll GET /v1/jobs/{job_id} for progress. Equal to brief_id, since one article is one job.
objectstring
Always content_brief.generation.dispatched.

default: `content_brief.generation.dispatched`

Example response

{
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "brief_id": "8c2d4f1e-5a3b-4c7d-9e1f-2a3b4c5d6e7f",
  "job_id": "8c2d4f1e-5a3b-4c7d-9e1f-2a3b4c5d6e7f",
  "object": "content_brief.generation.dispatched"
}

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

Request example

curl --request POST \
  --url 'https://api.rankprompt.com/v1/brands/your_brand_id_here/content-briefs/generations?dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <UNIQUE_KEY>' \
  --data '{}'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/content-briefs/generations?dry_run=false';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Idempotency-Key': '<UNIQUE_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/brands/your_brand_id_here/content-briefs/generations"

querystring = {"dry_run":"false"}

payload = {}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())