Developer API
Drive the full content lifecycle programmatically — discover a brand, pick or create a topic, generate, poll, and read the draft. Every call is scoped to the organization that owns your API key.
Authenticate first
Every request carries your organization API key as a Bearer token. Create keys in your dashboard under Settings → API keys.
Authorization: Bearer YOUR_API_KEY
Base URL
JSON REST, path-versioned. Breaking changes ship under a new version prefix.
https://api.roboad.ai/api/public/v1
RoboWrite's Public API is served from api.roboad.ai, the shared RoboAd platform host: RoboAd and RoboWrite are the same platform, and there is no robowrite.ai API hostname to call instead.
Full endpoint reference
Browse every endpoint, schema, and status code in an interactive OpenAPI explorer generated from the published contract.
How the public API fits together
Conventions, authentication, pagination, errors, and the full endpoint narrative — the same source we ship as API.md.
RoboWrite Public API — v1 Integration Guide
Status: v1, live and supported, with versioned breaking changes. The full content lifecycle — discover → create → generate → edit → read — is callable programmatically, with uniform pagination and error conventions, and an Idempotency-Key rule declared per POST route (see Idempotency). Existing integrations can keep their current API and tool versions; compatible additions do not require reinstalling a plugin.
This document is the consumer-facing reference. For exact request/response field shapes, the published OpenAPI schema is the source of truth (it is CI-guarded against drift). This guide explains how the surface fits together.
Overview
The Public API lets you drive content operations end-to-end without the dashboard: manage brands / properties / taxonomy, create briefs and content items, kick off AI generation, and read everything back. Every endpoint is scoped to the organization authorized by your credential.
- Base URL:
https://api.roboad.ai/api/public/v1 - Why that hostname? RoboWrite's Public API is served from api.roboad.ai, the shared RoboAd platform host: RoboAd and RoboWrite are the same platform, and there is no robowrite.ai API hostname to call instead. Point your client at the host above.
- Versioning: path-versioned (
/v1). A breaking change requires a new API path version or a separately named MCP tool version, with the existing contract retained. See Versioning and stability and the Changelog. - Format: JSON request and response bodies.
- Client generation: an OpenAPI specification is published for the surface at
https://www.robowrite.ai/openapi.json(itsserversentry is the API host); we maintain a generated, drift-checked TypeScript client, so you can generate a typed client in any language.
Authentication
Every request requires a Bearer credential: an organization API key, or a delegated OAuth access token from an enabled agent installation.
Authorization: Bearer <YOUR_TOKEN>
Keys are created, listed, and revoked from your dashboard. Each key is bound to a single organization; all reads and writes are automatically scoped to that org — there is no cross-tenant access. A missing or malformed Authorization header returns 401.
For existing pinned agent installations, connect to the supplied MCP endpoint and choose Sign in. Complete browser sign-in/signup, select an organization, and consent to content access. The client manages token storage, refresh and disconnect; never paste tokens into a chat. Current organization membership, subscriptions and quotas still apply. OAuth access includes category and tag list, detail, create, update and delete operations alongside the other agent content operations, and requires the delegated user:org:read and robowrite:content grants. Publishing additionally requires robowrite:publish; organization settings and Programs require an API key. Revoked or unauthorized grants return 401. Temporary identity-provider failures return 503 with Retry-After. API-key integrations continue to work independently.
If account setup is required, the MCP endpoint returns 409 with error: "account_setup_required" and a setup_url. Open that URL to finish organization creation, then reconnect the client and select the organization during consent. Repeating sign-in without completing that step will not grant organization access.
Job history and the documented editorial review and draft-editing operations use the existing delegated content grants. They do not require publishing permission; the selected organization's access and each operation's existing review, quota and version checks still apply.
Optional workspace-explicit access (v2)
Multi-workspace access requires one separately disclosed initial OAuth consent combining discovery and content across every eligible organization you belong to now or join later. Publication permission stays separate. Existing API keys and selected-workspace grants keep their v1 behavior. The hosted capability is off by default until enabled; its absence is not a reason to keep reconnecting.
robowrite:organizations:readpermits listing your memberships and checking your own access.robowrite:content:all_orgs, together with that discovery scope, permits the existing agent content operations in an explicitly named eligible workspace. Publication additionally requiresrobowrite:publish:all_orgsand the connection's separate publication capability and review rules.- Use OAuth access tokens for the exact resource
https://mcp.robowrite.ai/mcp. API keys and browser session tokens do not authorize these v2 routes.
Discover with GET /api/public/v2/organizations (limit 1–100, default 100; offset starts at 0). Its response is {granted_scopes, items, total, limit, offset, has_more}. Then read GET /api/public/v2/organizations/{organization_id}/access and verify the intended target with GET /api/public/v2/organizations/{organization_id}/selection. Discovery separates safe granted workspace scopes from membership cards; workspace_checks separately reports current role support, security eligibility and deletion blocking. Access and selection add operation_readiness for read, edit, generation and publication: each entry reports blocked or request_checks_required, workspace eligibility, missing scopes and remaining request checks. Those checks include account, resource ownership, applicable allowance/service/version checks and separate publication capability, exact-version review and destination policy. They are not evaluated by discovery and are never an authorization or quota promise. Selection is read-only: it changes no shared/browser workspace and starts no content work. Every action checks current access again. Workspaces whose security/enterprise requirements cannot be verified remain unavailable.
Subsequent content calls use that same explicit prefix, for example GET /api/public/v2/organizations/{organization_id}/account. Only the existing agent operation set is projected into v2; it does not expose organization settings, billing administration or Programs. A broad grant cannot use v1 as an implicit fallback: omitted selection returns 409 organization_selection_required. Missing scopes require consent; membership/role/security refusals do not require a reconnect loop.
When this capability is enabled in MCP, use list_organizations, get_organization_access and switch_organization, then pass the returned organization_id explicitly on later content calls. Existing pinned grants may keep omitting it. Switching invalidates the conversation's old workspace brand/object choices; recover the new workspace's content before acting. The setup manual remains RoboWrite MCP installation and usage.
Conventions (apply to every endpoint)
Versioning and stability
Every breaking change requires a new API or tool version. Published request inputs, response guarantees, authentication requirements and operation semantics remain compatible within their existing version. A changed API uses a new path version; a changed MCP operation uses a distinct versioned tool name while retaining the existing tool. Bumping the connector package version does not replace this requirement.
- Compatible additions stay on the current version. New optional request fields and new operations can be added without a client migration. A response field is additive only when existing readers can accept it; widening a closed response enum or weakening a required-field guarantee can break them.
- Old contracts keep working. Introducing a new version does not remove or silently redirect the existing one. Any future retirement needs its own announced migration plan; this change sets no automatic expiry window.
- Changes remain documented. Every observable change is dated in the Changelog. A new version with breaking semantics is labelled Breaking and explains migration. A changelog entry or baseline update cannot authorize a same-version break.
- Compatibility is checked before merge. The published API and MCP input/output contracts are compared with the branch's base contracts as well as the recorded API baseline. Changing the baseline in the same patch cannot erase the previous contract. Schema checks cover wire compatibility. The check also rejects an existing MCP tool that widens its reviewed side-effect class (read, workspace write, external work) or requires a new OAuth scope in its published contract. Other changes in meaning, permissions and side effects also require explicit review and a new version when breaking.
- The OpenAPI schema remains the field reference. It moves with compatible additions; existing clients can keep using their supported version. Read collection envelopes and saved-version identities as documented rather than inferring shapes from examples.
This policy takes effect on 2026-11-11 and protects the contracts published then and compatible additions afterward. Historical changes, including the August 11 versions pagination migration, remain recorded below; they do not authorize future same-version breaks.
Pagination
Paginated v1 content collections and their v2 projections return a uniform envelope:
{ "items": [ ... ], "total": 137, "limit": 50, "offset": 0, "has_more": true, "next_cursor": null }
Control with ?limit= (1–200, default 50) and ?offset=. total is the full filtered count; has_more indicates whether another page exists after this window. Page deterministically off those fields.
next_cursor is present on these content pagination envelopes. It is non-null only when the endpoint supports keyset cursor paging and another page exists. Today that is GET /programs only — see that endpoint for the contract.
GET /brands defaults limit to 100 (the 1–200 bound is the same). Organization discovery at GET /api/public/v2/organizations separately uses a 1–100 bound, default 100, and {granted_scopes, items, total, limit, offset, has_more} without next_cursor. Send an explicit ?limit= within the endpoint's bounds rather than assuming a fixed page size.
Endpoints that return nested resource arrays or aggregates use their documented shape instead of the pagination envelope. Examples: GET /brands/{brand_id}/keywords returns { "brand_id": "…", "clusters": [ … ], "counts": { … } }, GET /topics/{topic_id}/scores returns PublicTopicScore[], and GET /briefs/{brief_id}/sections returns PublicBriefSection[].
Errors
Research allowance exhaustion can return 429 with
PROVIDER_ALLOWANCE_EXHAUSTED (or the legacy DATAFORSEO_BUDGET_EXCEEDED).
These responses have no Retry-After; do not retry them as short rate limits.
A byok_required reason offers your own key only where that provider supports
it; allowance_exhausted does not. A nullable reset time means no scheduled reset.
Synchronous provider work can be refused with 403 and the body
{ "error": "MCP_ACCEPTANCE_SYNC_SPEND_REFUSED", "message": "…", "details": … }.
This body has no detail; branch on error. It is returned when your
organization's paid work may run only as background jobs, and also when the
service cannot verify your organization's state at that moment. Nothing is
charged and no job starts. Use the asynchronous routes (for example item
generation and job polling) instead of retrying the same call in a loop; if it
persists for an organization not in that mode, retry later or contact support.
Research at generation start: POST /content/items/{item_id}/generate checks
that at least one of your organization's selected research providers can run
before charging or creating a job. When none can, it returns 422 with an
object detail
{code: "allowance_exhausted_byok_required", message, details}, where
details.reasons maps each provider to why it cannot run (for example
byok_required: add your own key for that provider; paused: resume it). If
provider availability cannot be read, it returns 503 with a string detail;
retry later. Neither response starts a job or counts against your allowance.
Retrying a failed generation with the same Idempotency-Key returns 409
when the research it would run changed since the first attempt: your keys,
provider settings or limits, or research providers being enabled for your
organization. Provider order alone is not a change. Send a new key.
If the first attempt recorded your research limits and they can't be read
right now, the retry returns 503 instead; retry shortly with the same key.
In-item rewrites (POST /content/{content_item_id}/rewrites) use no research
and are never refused for it. Until research providers are enabled for your
organization, this check does not run and generation behaves as it did.
Every rewrite, refresh and variation (in-item rewrites included) is checked
against its own source list before it is saved: the links under its Sources,
References or Bibliography heading. The check never edits the text, except
that the required regulated-industry disclaimer is appended when your
organization has regulated industries configured. A sentence
with a specific fact (a figure, date, price, rate or named behaviour) that has
no inline link to a listed source, or that links outside that list, holds the
version for review: it is saved, the job completes with an article_partial
warning, and it is not auto-published. When the check cannot run, no version
is saved and the job fails with a source-verification error. To avoid a hold,
cite each specific with an inline link to a source in the text's own Sources
list, or remove the specific. The content-policy checks still apply, as for
articles: a text that contains one of your organization's or the request's
prohibited phrases saves no version and the job fails with a content-policy
error, and regulated-content findings block auto-publish. Each saved version's
citation records come from its own body. ?include=sources lists the URLs
under its Sources list, the ones cited inline first; a body with no Sources
list lists its inline links instead. ?include=assertion_provenance has one
receipt per inline link to a listed source, and its sentence is that
sentence exactly as it appears in markdown_body. A link to a URL that is not
in the Sources list gets no receipt.
Failures return the documented status code with a JSON body carrying a detail:
{ "detail": "Human-readable explanation" }
detail has two shapes, and 422 is where you meet both. Every error the API raises itself — including every 404, 429, 503, the business-rule 422s described in this guide, and almost every 409 — uses the string form above. The one 409 exception is POST /content/items/{item_id}/generate: its detail is an object {code, message, details} (see Idempotency). The research-start 422 on that route uses the same object form (see the research note above). A request that fails schema validation before reaching the handler returns the framework's field-error form instead:
{ "detail": [ { "type": "uuid_parsing", "loc": ["body", "brand_id"], "msg": "Input should be a valid UUID", "input": "not-a-uuid" } ] }
A schema-validation 422 carries detail only. The request body is not echoed. Values under credential-named keys inside detail[].input are replaced with [REDACTED]; loc, type, and msg stay.
Both can come back from the same route with the same 422: send a malformed brand_id and you get the array; send a well-formed body with an Idempotency-Key a route does not accept and you get the string. So branch on the type, not on the status:
const detail = body.detail;
const message = typeof detail === "string"
? detail
: detail.map((e) => `${e.loc.join(".")}: ${e.msg}`).join("; ");
Note for generated clients: most routes publish 422 as the field-error form (the framework default), so a typed client will need the guard above rather than trusting the generated type for the string form. Program approve/decline verbs, POST /programs/{program_id}/facts, and POST /briefs/{brief_id}/approve, which refuse Idempotency-Key, are the exception: they publish both shapes via oneOf, so a generated client can see either branch. Every other status is typed as the string form and matches.
| Code | Meaning |
|---|---|
400 / 422 | Invalid or malformed input |
401 | Missing/invalid API key |
403 | Not permitted for this key or organization — e.g. MCP_ACCEPTANCE_SYNC_SPEND_REFUSED (see above); do not retry unchanged |
404 | Resource not found, or not owned by your org |
409 | Conflict — e.g. the resource is in the wrong state for the operation |
429 | Rate limit exceeded — honor the Retry-After response header when present, then retry. Exception: PROVIDER_ALLOWANCE_EXHAUSTED and DATAFORSEO_BUDGET_EXCEEDED carry no Retry-After and are not short rate limits — do not retry them |
503 | Backend temporarily unavailable — honor the Retry-After response header when present, then retry |
Treat any non-2xx defensively and read detail through the type guard above.
Idempotency
Idempotency-Key is a per-request header. Where a route accepts one, a retry with the same key replays the original response instead of repeating the operation, and the replay carries an Idempotency-Replayed: true response header. The route also echoes the key back in an Idempotency-Key response header, so you can tell "accepted" from "not accepted" without guessing.
There is no blanket rule — the rule is per route, and the scheme covers POST. Every public POST declares one of the three rules below, so a key sent to a POST that does not accept one comes back as a 422 rather than being silently discarded. PATCH and DELETE are outside the scheme: they address one existing resource by id, so a repeat converges on the same state instead of creating or billing a second one. They declare no key, and a key sent to one is ignored — neither honored nor refused — so do not rely on one there. PUT is also outside the scheme and an Idempotency-Key sent to it is ignored. Source-policy replacement instead requires expected_revision; replaying an already committed update with its old revision returns 409.
| Rule | What it means | Routes |
|---|---|---|
| Required | Absent header → 422. Protects charged work and durable setup confirmation from duplicate requests. | POST /brand-setups, POST /brand-setups/{setup_id}/confirm, POST /content/items, POST /content/rewrite, POST /content/{content_item_id}/rewrites, POST /brands/{brand_id}/topics/generate, POST /programs/{program_id}/ideas:generate, POST /programs/{program_id}/plan:generate, POST /programs/{program_id}/pages:generate |
| Optional (creates) | Accepted and honored; absent means no deduplication, so a blind retry writes a second row. | POST /brands/{brand_id}/topics, POST /briefs, POST /properties, POST /categories, POST /tags, POST /pillars, POST /authors, POST /audiences, POST /programs, POST /programs/{program_id}/ideas, POST /programs/{program_id}/plan |
| Optional (generation) | Accepted and honored, but these also deduplicate on their own — a keyless retry does not necessarily start a second run. See the note below. | POST /content/generate, POST /content/items/{item_id}/generate |
| Not accepted | Present header → 422. These use request-derived replay or revision checks, so a client key would conflict with that mechanism. Projection preview is read-only; replaying a committed apply or rollback with its old revision returns 409. | POST /content/{item_id}/publish, POST /content/{content_item_id}/edits, POST /content/{content_item_id}/restores, POST /content/{content_item_id}/checks, POST /brands/{brand_id}/topics/rescore, POST /pillar-strategies, POST /programs/{program_id}/facts, POST /brands/{brand_id}/projection/preview, POST /brands/{brand_id}/projection/apply, POST /brands/{brand_id}/projection/rollback, POST /reviews, POST /reviews/{review_id}/assignments, POST /reviews/{review_id}/decisions, POST /briefs/{brief_id}/approve, every .../approve, .../decline and ...:approve-all verb |
Rules that hold wherever a key is accepted:
- A malformed key (empty, whitespace-only, or over-long) returns
422. - Reusing a key with a different request body returns
409— mint a new key for the new body; the original key stays bound to the first payload. - A concurrent second request under the same key, while the first is still in flight, returns
409— opposite remedy from payload mismatch: keep the same key and retry. - An unreadable idempotency record returns
409— retry without the key.
Do not branch on the detail prose of those three 409s. The condition and
the remedy are stable; the exact sentence is not, and it differs by route family:
| condition | POST /programs… routes | L1 spine routes listed below |
|---|---|---|
| payload mismatch | This Idempotency-Key was already used with a different request payload. | Idempotency-Key reused with a different request payload |
| in flight | A request with this Idempotency-Key is in progress. Retry the same key. | A request with this Idempotency-Key is in progress |
| unreadable record | Idempotency record unreadable; retry without the key. | Idempotency record unreadable; retry without the key |
The left column covers POST /programs, /programs/{program_id}/ideas,
/programs/{program_id}/plan, and the three …:generate program verbs. The
right column is the L1 reservation spine (detail=value) on POST /briefs,
/properties, /categories, /tags, /pillars, /authors, /audiences,
/brands/{brand_id}/topics, /brands/{brand_id}/topics/generate,
/content/items, /content/generate and /content/rewrite. Note the right
column has no trailing full stop, and words payload mismatch differently.
POST /content/items/{item_id}/generate is a third case: it accepts a key and
replays the original job, but a 409 from it is not an idempotency
conflict. It means the item is not generatable (brief_not_approved or
item_not_generatable), or not generatable yet because another generation of
the item is still running (article_run_active), and the body is
{"detail": {"code": "…", "message": "…", "details": …}} — none of the three
sentences above, and not a top-level {code, message, details} object. The
type guard under Errors must treat this detail as an object, not
call .map on it.
On POST /content/items, a durable (L2) payload mismatch after the L1
record is gone uses a third sentence, Idempotency-Key reused with a different payload (no request). Match on status + your key, not on that prose either.
Match on the 409 status plus your own record of the key you sent. A future
release may align this wording, and doing so would not be treated as a breaking
change.
- If our deduplication store is briefly unavailable, an Optional-rule route proceeds without deduplicating rather than failing (your write succeeds; a simultaneous retry could create a second row).
POST /content/rewriteis the exception: it fails closed with503+Retry-Afterrather than risk an undeduplicated billed rewrite. - For
POST /content/itemsthe deduplication is durable: a retry replays the original item even after a long delay or an infrastructure blip, so a billed create is never repeated. The Optional (creates) routes deduplicate for 24 hours; a retry after that creates a new row.
The two generation routes are the exception to the rule above. Their deduplication is keyed on the work, not only on your key, and it is bounded by that work's lifetime rather than by a fixed 24 hours:
POST /content/generatededupes pertopic_idwhether or not you send a key: while a run for that topic is still active you get the originaljob_idback. Once that job is terminal (or has beenrunningwithout progress for a long time), the same request — and the sameIdempotency-Key— starts a fresh, separately charged attempt. Once the topic has a saved draft, the keyless per-topic dedupe only absorbs repeats within about a minute, so reuse your key for retries. See Re-running after failure for the full rule, including parked runs and replay identity.POST /content/items/{item_id}/generatededupes on the item and the key together, and supplies its own key when you omit one — echoed back in theIdempotency-Keyresponse header. That protects a capture-and-resend retry: resend the echoed key and you replay. A blind keyless retry gets a freshly synthesized key instead, so it is not deduplicated by one and does generate again. A previously failed generation is never replayed either — the same key re-dispatches as new, charged work.
The practical consequence: "I sent the same key" does not mean "this can never charge twice", and on POST /content/generate "I sent no key" does not mean "a retry is unprotected". Use a fresh key whenever you intend a new run — and note a same-key retry that changes citation_mode replays the original job rather than applying the new value.
All Required routes publish the requirement. Each marks Idempotency-Key as a required parameter in the schema, so a typed client generated from it will not let you omit one. The three program stage verbs — ideas:generate, plan:generate, pages:generate — used to enforce it inside the handler instead, which published the parameter as optional and let a generated client omit a header the route then rejected; that is fixed. The one consequence to know: because the framework now refuses the absent header, that specific 422 carries the field-error detail described under Errors, not the string form. A malformed key still returns the string form.
Why "not accepted" is a 422 and not a shrug. Those three routes already refuse to do the work twice: publish is exactly-once per item/version/mode and returns the original job_id with was_duplicate_lookup: true; rescore reuses the brand's in-flight job; pillar-strategies returns the matching completed snapshot (and force_refresh: true is the deliberate way to bypass that). Accepting a key you could not act on would tell you a retry was protected by something that was not reading the header at all.
Rate limits
Fixed-window per organization: 120 requests / 60 seconds, counted across every API key in the org and every process you run. Exceeding it returns 429 with a Retry-After response header (whole seconds to wait, 1–60) — honor it before retrying.
Every counted response says where you stand, so you can pace yourself instead of waiting for a 429. Successes, handled errors and the 429 itself carry the IETF RateLimit headers; an unhandled server error (500) does not, because Starlette's outer error middleware sends it before these headers are added. The headers are:
| Header | Example | Meaning |
|---|---|---|
RateLimit-Policy | "org";q=120;w=60 | q requests per w-second window for your organization |
RateLimit | "org";r=57;t=30 | r requests remaining, t seconds until the window resets |
RateLimit-Limit | 120 | Requests allowed per window |
RateLimit-Remaining | 57 | Requests left in the current window |
RateLimit-Reset | 30 | Seconds until the current window resets, measured when the response is sent |
They are absent when a request was not counted: authentication failures, workspace discovery (GET /api/public/v2/organizations and its access / selection reads), the draft-editing operations under /content/{content_item_id}/ (checks, diff, edits, restores, review-card, rewrites, sections), and any request while the limiter is unavailable. The published OpenAPI document declares them on the existing 2xx and 429 responses of counted operations; it adds no status codes. The counted Programs idea and plan PATCH operations publish only 403 / 422 / 501, so they carry the headers at runtime but have no declaration in the spec.
The window is fixed, not sliding. It is a wall-clock bucket, so the counter resets at the boundary rather than rolling off gradually. Two consequences:
Retry-Afteris the time left in the current bucket, so it shrinks as the window ages — a429early in a window costs you most of a minute, one at the end costs a second.- Straddling a boundary lets through up to 240 requests in a ~2-second span (120 at the end of one bucket, 120 at the start of the next) and then locks you out for the rest of that minute. Do not calibrate your client on that burst — it is an artifact of the window shape, not headroom you can rely on.
It fails open. If the counter store is unavailable the limit is not enforced and requests proceed — the limiter is a spend and fairness guardrail, not an availability dependency, so an outage in it must never take the API down with it. The same is true of the daily cap below. Never read a missing 429 as permission to exceed the budget: enforcement can resume on any request.
Daily cap on content-item creates
On top of the per-minute window, POST /content/items carries a separate per-organization daily cap of 1,000 creates. It exists because that route is billable at create time, independently of generation.
- Exceeding it returns
429with{"detail": "Daily content-item create limit exceeded"}. Unlike the per-minute limit, this429carries noRetry-After— the window is the UTC day, so retry after the next UTC midnight rather than by header. - The day is a fixed UTC bucket (not a rolling 24 hours), so the allowance resets at 00:00 UTC.
- Replays and rejected requests do not consume allowance. An
Idempotency-Keyreplay returns the original item for free, and a request that fails validation (404on the brief/property,422on a brand mismatch) gives its slot back. - It fails open. If the counter store is unavailable the cap is not enforced and creates proceed — it is a spend guardrail, not an availability dependency, so never treat its absence as permission.
- No other route is capped this way; generation volume is governed by your plan quota (
GET /account), which returns429on its own when a metered resource is exhausted.
Clients & User-Agent
api.roboad.ai sits behind Cloudflare bot protection. Non-browser clients must send a normal, non-empty User-Agent header. Default library agents such as Python's urllib are blocked at the edge — you will see an HTTP 403 with an empty body (Cloudflare error 1010), before the request reaches the API, so there is no { "detail": … } envelope. Most HTTP clients (httpx, requests, curl) send an acceptable UA by default; if you build raw urllib requests, set one explicitly, e.g. User-Agent: my-app/1.0.
Asynchronous generation
AI generation is asynchronous. Generation endpoints return 202 Accepted with { "job_id": "…", "workflow_id": "…", "status": "…" }. Poll GET /jobs/{job_id} until the status stops polling:
Product context. Generated product context is selected from the run's prompt-eligible active products using authoritative name or alias matches, semantic relevance when available, and a safe lexical fallback. If no product is relevant, generation proceeds without product context rather than inserting unrelated catalog entries.
- In-flight:
queued,running - Terminal:
completed,completed_with_errors,failed,cancelled - Needs review (stop polling):
awaiting_review— see below
The polled job has shape { "job_id": "…", "status": "…", "content_item_id": "…", "content_version_id": "…", "error": "…", "error_type": "…" }:
content_item_idon the202depends on the kickoff path.POST /content/rewritereturns{ "job_id", "content_item_id", "status" }on the202because the source item is created synchronously before dispatch. Other generation paths (POST /content/generate,POST /content/items/{item_id}/generate) return onlyjob_id/workflow_id/statuson the202— readcontent_item_idfrom the polled job once it is populated, typically by the time the job reaches a terminal (orawaiting_review) status.content_version_ididentifies the generated draft version and is populated alongsidecontent_item_id.errorcarries the human-readable failure reason onfailed/completed_with_errors.error_typecarries a machine-readable failure classification alongsideerror, so you can branch automatically instead of parsing the message. Common values:generation_error(the draft pipeline failed — often a transient upstream/model error; safe to retry the topic, ideally with backoff and not in a large concurrent burst),rate_limit_error(back off before retrying),timeout/reconciled_failed(the run exceeded its budget or was reconciled by the stuck-run watchdog — retry, and prefer serializing rather than firing many generations at once),save_error(the draft generated but persistence failed — retry),not_found/validation_error/content_policy_error(permanent for that input — do not blind-retry; fix the request),cms_write_rejected(a CMS publish whose destination CMS refused the write and gave no reason — see the2026-08-29Changelog entry; re-sending the same publish is not the remedy).nullfor non-failed jobs. Treat unrecognized values as retryable-with-backoff. The Failure classifications table below lists every classification the workflow taxonomy defines, including the ones not named here.
Failure classifications (error_type). The table below is the full set of classifications RoboWrite's workflow taxonomy defines. It is a reference, not a closed contract: runs outside that taxonomy write their own values — save_error (the draft generated but persistence failed) and reconciled_failed (the stuck-run watchdog reconciled the run) are two you will meet — so keep treating an unrecognized value as retryable-with-backoff. "Handling" is guidance about the class, not a promise about your specific run.
error_type | What it means | Handling |
|---|---|---|
workflow_error | The run failed and nothing more specific was recorded. | Retry with backoff. |
unknown | No classification was attached to the failure. | Retry with backoff. |
not_found | A record the run needed (item, brief, property) does not exist. | Fix the request; do not blind-retry. |
validation_error | The request, or a stored input the run read, failed validation. | Fix the input; do not blind-retry. |
conflict | The target changed underneath the run. | Re-read the resource, then retry. |
canary_budget_error | An operator-controlled validation run reached an execution limit. | Ask the operator to review the run before retrying. Any retained draft remains unpublished. |
dataforseo_budget_exhausted | The organization's monthly SEO-data (DataForSEO) spend allowance is used up for this UTC month. | Do not blind-retry: cached results still serve, fresh keyword/SERP research resumes after the next UTC month begins or the operator raises the allowance. |
dataforseo_budget_pricing_unknown | A keyword/SERP request shape has no approved price entry, so it was refused before any provider call. | Report the operation to the operator; do not retry the same request. |
dataforseo_budget_unavailable | The spend-admission check could not run (transient). | Retry with backoff; the denied attempt sent no provider request. Earlier work in the same job may already have completed. |
source_verification_error | Supporting pages did not substantiate the article, or verification could not finish within its budget. No content version was created. | Review the source diagnostics, correct unsupported claims or provide accessible evidence, then retry. |
generation_time_budget_exceeded | Article generation reached its ten-minute time budget without an eligible reviewed partial. No content version was created. | Retry later or reduce the brief scope. This does not mean sources contradicted the draft. |
generation_error | The draft pipeline failed — often a transient upstream/model error. | Retry with backoff, not in a large concurrent burst. |
content_policy_error | The topic or input was refused on content policy, or the draft still contained a prohibited phrase after copy repair. No content version is saved when a prohibited phrase remains. | Fix the request or remove the listed phrases; do not blind-retry. |
rate_limit_error | An upstream provider rate-limited the run. | Back off, then retry. |
pillar_agent_failure | The strategy agent behind pillar work failed. | Retry with backoff. |
empty_generation | The model returned nothing usable. | Retry; if it repeats, revise the brief or topic. |
context_error | The run could not assemble the context it needs (brand, brief, or research inputs). | Fill in the missing inputs, then retry. |
persistence_error | Output was produced but storing it failed. | Retry. |
persistence_empty | The write completed but stored no rows. | Retry. |
topic_export_error | Exporting generated topics failed. | Retry. |
selection_error | The run could not resolve which inputs to work on. | Fix the request; do not blind-retry. |
selection_missing | Nothing matched the selection the run was given. | Widen or correct the selection. |
configuration | The workspace or property is misconfigured for this run. | Fix the configuration, then retry. |
credentials | Stored credentials were rejected. | Reconnect the integration, then retry. |
authentication | Authentication against an upstream service failed. | Reconnect the integration, then retry. |
token_decryption | A stored token could not be decrypted. | Reconnect the integration; contact support if it repeats. |
database | A storage-layer call failed. | Retry with backoff. |
cms_connection | The connected CMS could not be reached. | Retry with backoff; check the CMS is up. |
cms_sync | A CMS sync failed. | Retry with backoff. |
cms_write_rejected | The destination CMS answered and refused the write, giving no reason. | Re-sending the same publish is not the remedy — see the 2026-08-29 Changelog entry. |
strapi_api | The connected CMS's API returned an error. | Retry with backoff; the CMS's own log carries the detail. |
network | A network call failed. | Retry with backoff. |
timeout | The run or one of its calls exceeded its budget. | Retry, and prefer serializing over firing many runs at once. |
awaiting_review is a stop-polling outcome. A job with no content_version_id (an article run holding its content kit) has no saved draft yet: read the item's kit with GET /content/items/{item_id}/kit and approve or reject it (see Content kits). Otherwise it is a saved draft from POST /content/generate (topic autopilot): retain content_item_id and content_version_id, fetch the saved draft, then use GET /reviews?content_item_id=… to recover its editorial review. Return the review, item and version identifiers and stop for the human decision. Review reads remain available after the original job ends. GET /jobs/{job_id} carries no review_id: when a job parks, a review is opened for its draft if that draft is nonempty and still the item's latest version, and GET /reviews?content_item_id=… is how you find it. If none is listed for the current version, request review of the current nonempty saved version with POST /reviews. Historical jobs are not backfilled.
Editorial review. POST /reviews with content_version_id requests review of the current nonempty saved draft; repeating that version recovers the same review. Do not send Idempotency-Key on review POSTs — replay is owned by body request_id and a key returns 422. GET /reviews/{review_id} returns the exact version, body_sha256, assigned reviewer, status, is_current, and durable decisions. GET /reviewers lists current organization members. To decide, send POST /reviews/{review_id}/decisions with content_version_id, a UUID request_id, action (approve, reject, or request_revision), and optional feedback. Rejection and revision requests require nonblank feedback. Only an assigned current member or organization admin can decide; an unassigned non-admin cannot. A successful response is the applied decision. Reuse the same request ID and identical input after a lost response; changed input, stale versions, and attempts to replace a decision conflict.
Assignment. Members may claim an unassigned review for themselves. Organization admins may assign or reassign a current organization member. Send POST /reviews/{review_id}/assignments with content_version_id, a UUID request_id, reviewer_id, and the expected_assignment_revision read from the review. Successful assignment increments assignment_revision and appends an assignment receipt. Reuse the same request ID and identical input after a lost response. A stale revision or version returns 409; a removed or inaccessible target member returns 404; unauthorized assignment returns 403. Terminal reviews cannot be reassigned. GET /reviews supports content_item_id, limit (default 50, maximum 200) and offset, returning {items, total}. Review detail includes append-only assignments and decisions.
Versioned edits. Saving Markdown always creates a new immutable version. POST /content/{content_item_id}/edits takes expected_base_version_id of the current version and a UUID request_id. Send markdown_body to replace the whole draft, or a unique target plus replacement for an exact patch. Missing or repeated targets do not write. A stale base returns 409. Do not send Idempotency-Key. POST /content/{content_item_id}/restores copies an earlier version into a new current revision and records restoration lineage. GET /content/{content_item_id}/diff compares two versions. GET /content/{content_item_id}/sections lists parser-derived H2 ids (duplicate headings are distinct; headings in code fences are ignored). POST /content/{content_item_id}/rewrites starts an in-item AI rewrite and requires Idempotency-Key; section rewrites keep every outside-section byte identical unless allow_broader_repair is true; failed verification saves no version; the first AI rewrite of a handwritten-only item uses the content allowance. AI rewrites of items that already have a generated version use the revisions allowance. POST /content/{content_item_id}/checks starts an explicit quality check of the current saved version and does not edit Markdown. Replay that check with the same request_id; do not send Idempotency-Key. GET /content/{content_item_id}/review-card reads the persisted checks and never starts work. Publish returns 409 until hard checks for that exact version exist and pass: missing checks use EDITORIAL_CHECKS_REQUIRED, a body mismatch uses EDITORIAL_CHECKS_STALE, a hard fail uses EDITORIAL_CHECK_FAILED, and a hard unknown uses EDITORIAL_CHECK_UNKNOWN. Soft brand and score warnings do not block. Approval still records when hard checks fail. Manual edits and restores are free and invalidate prior approval until a new review.
Approval authorizes that exact draft for editorial use/export; publication remains a separate explicit operation. Rejection preserves the draft and history. A revision request records feedback and stops; rewriting requires another action and a new version needs a new review. Check is_current before using an approval: a later version or changed body invalidates it. Editorial decisions neither start CMS publication nor resume an expired job. The dashboard inbox's explicitly publish-oriented approval remains a separate operation.
Avoiding awaiting_review entirely (headless integrations). If you have no CMS connected to RoboWrite and intend to collect finished pages over the API, set the target property's publish_policy to draft_only (see Properties below), and send its property_id on POST /content/generate when it is not the property the API would resolve for you (see Choosing the property). Runs for that property then finish as completed instead of parking in the dashboard inbox: the page is downloaded with GET /content/{content_item_id} exactly as above, and POST /content/{item_id}/publish answers 409 because there is no destination to publish to. Content-quality escalations (for example a failed fact-check) still route to the review inbox under either policy — draft_only only removes the CMS-connectivity ones. The full headless path — property setup, topic eligibility, the call sequence, idempotency, batch throughput and what a held draft means — is walked through in Topic generation for headless integrators below.
"Ready for export" is that outcome's name, not a status you will read. Internally a draft_only topic-autopilot run ends in a distinct terminal success called ready_for_export: finished, deliberately never published, and — unlike awaiting_review — carrying no inbox card for anyone to clear. (It is specific to that path; a programmatic-SEO program page never reaches it under either policy.) Over the API it surfaces as plain status: "completed". GET /jobs/{job_id} does not expose a ready_for_export value or a terminal_status field, so do not branch on that string. The observable contract for a draft_only run is: completed, with content_item_id and content_version_id populated and the page downloadable. You may still see ready_for_export in dashboard and support conversations, which is why it is named here.
Expected latency. A full generation run — brief creation, multi-agent article drafting/editing, and self-scoring — typically takes 10–17 minutes end-to-end (wider variance during content-quality repair passes). Treat anything under 25 minutes as normal; set poll ceilings/timeouts to at least 30 minutes before considering a run stalled (a stalled run self-heals or escalates via the reconciler shortly after). Sub-minute completion is not representative and should not be assumed.
How often to poll. Polling shares one budget with everything else you call: 120 requests / 60 seconds for the whole organization (see Rate limits). Pick an interval from the number of things you are polling, not from a fixed habit:
Polling
Njobs everyTseconds costs60 × N ÷ Trequests per minute. Keep that under half the window — leaving the other half for the reads and writes the polling exists to serve — which meansT ≥ Nseconds, and never below 30.
| Jobs in flight | Minimum interval | Polling cost |
|---|---|---|
| 1–30 | 30 s | ≤ 60 req/min |
| 60 | 60 s | 60 req/min |
| 300 | 5 min | 60 req/min |
Because a run takes 10–17 minutes, a 30-second floor already resolves it within ~0.3 % of its duration — polling faster buys nothing and only brings the 429 forward. Earlier versions of this guide suggested 15–30 seconds without qualification; at anything past a couple of dozen concurrent runs that is not achievable alongside the rate limit, and program-scale workloads are well past it.
At program scale, poll the stage — not the pages. A program's pages:generate returns one job_id for the whole stage no matter how many pages it covers. Poll that single job, and read GET /programs/{program_id}/pages on the same cadence to see pages turn ready one at a time. That is two polls per interval for a 1,000-page program; polling each page's content item instead would exhaust the window immediately.
If a poll is rate-limited (429) or the backend is briefly unavailable (503), honor the Retry-After response header before the next poll, and let that response — not your timer — set the next wake-up. Do not retry a 429 whose body carries PROVIDER_ALLOWANCE_EXHAUSTED or DATAFORSEO_BUDGET_EXCEEDED: it is allowance exhaustion, not a short rate limit.
Inline citations (notation). With citation_mode=inline on POST /content/items/{item_id}/generate, cited claims appear in the prose as markdown hyperlinks — [descriptive anchor](https://source…) — plus a numbered ## Sources section at the end of markdown_body. These links are not numeric [n] markers; a numeric marker appears only in the rare case where a link's anchor text had to be replaced. To verify inline body citations programmatically, look for ](http in markdown_body, not [n]. On an ordinary content item, omit citation_mode and you get structured_only (links stripped from the body — verify citations via GET /content/{id}?include=sources). On a program-owned item, omit keeps inline (see the 2026-08-29 Changelog entry). On the v1 pipeline pages:generate always writes inline — see Programs. On the v2 article pipeline (the default for new drafts) citation_mode does not apply: the body follows citation_style or the organization's default_citation_mode, program pages included (see the 2026-11-08 Changelog entry).
On the v1 pipeline (citation_mode=inline), generated ## Sources rows in markdown_body use sanitized inline-HTML <a> anchors with <wbr> soft-break tags in their visible URL labels. On the v2 article pipeline, a bottom_only body's ## Sources rows are plain Markdown autolinks, one per cited source: n. host — <url>; an inline_only body has no list. Treat markdown_body as Markdown that may contain sanitized inline HTML; do not parse Sources rows as plain-text URLs. For stable machine-readable citation data, use GET /content/{id}?include=sources.
Notes:
- A just-finished run may briefly still read
runninguntil its completion callback lands — poll until the status is terminal orawaiting_reviewrather than trusting a single non-terminal read. - Under rare concurrent-submit timing you may receive
202withstatus: "queued"and an emptyworkflow_id. This is normal — the job exists; just poll it. GET /content/{id}?include=scoring,sourcesfields are populated together per version, but scoring is only written once self-scoring completes — a version fetched before its generation run finishes may showsourcespopulated withscoring: nullbriefly. Poll the job to a terminal/awaiting_reviewstatus before treating a missingscoringfield as an error.GET /content/{id}?include=sourcesand?include=assertion_provenanceentries carryorigin:research(found by platform research) orsupplied(only facts you supplied cite that URL; its page was fetched and states the fact).?include=supplied_factslists the facts you supplied with no source URL (claim_id,text,attribution): they carry no link in the body, so they never appear insources. Supplied-fact provenance is recorded on each version when it is written, so later kit edits, added facts or regenerations do not change it. A v1 version readsorigin: researchandsupplied_facts: [].originandsupplied_factsarenull(unknown) only for a v2 version saved before provenance was recorded whose content kit has since changed.urlstays required on every source and receipt.GET /content/{id}?include=assertion_provenancereturns the per-assertion provenance receipt (sentence,sentence_index,url,marker) for each version that generated one. It is captured at generation time from the inline-linked body before rendering, so it stays populated even whencitation_mode=structured_onlystrips the links frommarkdown_body(numeric-marker output) — the machine-readable complement to?include=sources.sentenceis normalized (link syntax reduced to labels, whitespace collapsed) so a consumer can match it to the sentence text of a published body by exact string comparison. On a v2 article version,sentenceis instead the sentence exactly as it appears inmarkdown_body(list and heading markers dropped; inline links kept on aninline_onlybody), so it is a substring of the published body.[]means the version carries no receipt (legacy version, or a body with no inline citations);nullmeans the projection was not requested.- On
GET /content/{content_item_id}, each version'sseo_descriptionandseo_titleresolve with the same precedence: dedicated SEO column, else a string value in the version metadata blob, else the related meta column (meta_description/meta_title). Description: generated (non-imported) drafts commonly store the SEO summary only asmeta_description, soseo_descriptionis populated where it was previously empty. Title: the same fallback applies whenmeta_titleor metadata carries a title (imported/legacy rows). Native generation now writes a generatedseo_title(at most 60 characters) shortly after the draft is saved, unless the version already shows an SEO title.seo_titlemay still be null on older drafts, on a version read before that step finishes, or when the step produced no usable title;versions.items[].titlethen holds the page title. Treat a non-emptyseo_titleas the authoritative SEO title and prefer it over parsing the body.
All timestamps are UTC ISO-8601.
Endpoint reference
Account
| Method | Path | Purpose |
|---|---|---|
| GET | /account | Bootstrap: org bound to the key, brands it can use, monthly quota remaining, overage flags, optional-action capabilities |
Use this after minting a key to discover which organization and brands you can act on and how much monthly allowance remains before writes return 429.
GET /account
{
"organization": { "id": "org_…", "name": "Acme Co" },
"brands": [
{ "id": "…", "name": "Acme", "status": "active" }
],
"quota": {
"plan_code": "growth",
"period_start": "2026-07-01T00:00:00Z",
"period_end": "2026-08-01T00:00:00Z",
"resources": [
{
"resource_type": "content",
"current": 12,
"limit": 100,
"remaining": 88,
"overage_enabled": true,
"is_blocked": false
}
]
},
"capabilities": {
"humanization": { "available": false, "reason": "not_configured" }
}
}
-
organization— the Clerk org the API key is bound to. If the org row is missing, the response is404. -
brands— slim refs (id,name,status) for brands the key can use (the whole org). Capped at 200; useGET /brandsto page further. Full brand/voice detail remains onGET /brands/{brand_id}. -
quota.resources— monthly metered resources relevant to the public surface:content,topics,revisions,briefs,pillar_strategy. Each row has:remaining— included allowance left this period (max(limit - current, 0)). This is not unlimited overage headroom.overage_enabled— plan allows metered spend past the included limit for that resource (today this is typically content on Growth). Whenremainingis0butoverage_enabledistrueandis_blockedisfalse, further creates still succeed and bill overage.is_blocked— further spend of that resource is hard-capped (no remaining included allowance and no overage).
-
capabilities.humanization— whether the organization can run the optional StealthGPT editorial/style rewrite right now:{ "available": boolean, "reason": string | null }.reasonis set exactly whenavailableisfalse:release_disabled— the feature is not available yet for any organization.not_configured— no StealthGPT account is connected (or no key is stored). An org admin connects it in the web app at Settings → Integrations; keys are never accepted through the API or a chat client.paused— an admin paused the integration.
It is derived only from release readiness, the integration being enabled, and a stored key — a connected key can still be refused at run time (for example invalid key or payment setup), and a cached value never authorizes a run. It never includes the key, a key hash, a Vault id or StealthGPT account data. Runs are charged to the organization's own StealthGPT account.
An unknown/missing org for the key returns 404. Auth and rate-limit behavior match every other endpoint (401 / 429).
Organization settings
| Method | Path | Purpose |
|---|---|---|
| GET | /org/settings | Read organization-level generation settings |
| PATCH | /org/settings | Update organization-level generation settings |
regulated_industries controls the org-wide regulated-content policy. Allowed values are finance, healthcare, and legal; an empty array means the policy is off. At least one of regulated_industries, source_verification_failure_mode, prohibited_phrases, or default_property_id is required on PATCH — an empty body returns 422 so clients cannot accidentally clear policy.
prohibited_phrases is the org-default list of phrases article generation must not ship. Omit it to leave the stored list unchanged. Send [] to clear it. null is rejected. Each phrase is at most 200 characters, and the list holds at most 40 phrases. A generation request may add phrases for that run; it cannot remove phrases stored here. An empty org list and an omitted request list leave generation unchanged.
default_property_id is the organization's default publishing property for topic generation (POST /content/generate), or null when none is set. GET returns the stored value. On PATCH, omit it to leave it unchanged, send a property UUID to set it, or send null to clear it. The property must be an active property of your organization: an unknown ID, another organization's property, or an inactive or deleted property returns 422 with a string detail, and the stored default is left as it was. The default only applies to topics on the property's own brand — see Choosing the property.
PATCH /org/settings
{
"regulated_industries": ["finance"],
"default_property_id": "<property-uuid>" // optional — null clears it
}
When enabled, generation prompts and evaluation gates use a stricter educational-tone policy: regulated figures need inline source grounding, prescriptive advice phrasing is repaired or escalated, and unresolved findings block autopublish by routing the job to awaiting_review.
URL brand setup
| Method | Path | Purpose |
|---|---|---|
| POST | /brand-setups | Start website research; requires Idempotency-Key; returns 202 with setup_id and job_id |
| GET | /brand-setups/{setup_id} | Read pending, running, ready, failed or confirmed state and bounded brand/voice suggestions |
| POST | /brand-setups/{setup_id}/confirm | Save the reviewed brand; requires Idempotency-Key; returns a brand |
Start with { "website_url": "https://example.com" }. Poll the setup until ready, review its suggestions with the user, then confirm with {} to accept them or supply the bounded edits declared by OpenAPI. Failed extraction never creates a placeholder brand. Confirmation creates one brand and does not generate content or publish anything.
If research is rerun in the dashboard, an earlier setup reports running while a different research attempt owns the session. Its earlier suggestions cannot be confirmed during that attempt: confirmation returns 409. Poll again before reviewing or confirming.
Repeat the same key and body to recover the original setup or brand; successful replays include Idempotency-Replayed: true. Changed input under a used key returns 409. An existing active setup must be finished before starting another. Unknown or foreign setup IDs return 404. An existing primary brand is preserved; the first brand becomes primary only when none exists.
Create a property using the returned brand_id and publish_policy: "draft_only", generate/select pillars, create a topic and brief, create a content item, then call the item generation route and read its saved Markdown. Topic autopilot is a separate operation and can publish.
Brands
| Method | Path | Purpose |
|---|---|---|
| GET | /brands | List brands |
| GET | /brands/{brand_id} | Get a brand |
| PATCH | /brands/{brand_id} | Update a brand's voice fields (partial) |
| GET | /brands/{brand_id}/source-policy | Read reviewed source rules and their revision |
| PUT | /brands/{brand_id}/source-policy | Replace source rules using the revision you reviewed |
| GET | /brands/{brand_id}/keywords | Keyword inventory for a brand, including market data (search volume, difficulty, CPC). Does not use the standard list envelope — see Pagination below. |
Reviewed sources. GET /brands/{brand_id}/source-policy returns {revision, strict, rules}. Unconfigured brands return revision 0, strict: false, and no rules. PUT takes {expected_revision, strict, rules} and returns the new revision. A stale revision returns 409; reload and review before submitting again. A missing or foreign brand returns 404. An Idempotency-Key header is ignored; expected_revision is the concurrency control.
Each rule records domain, include_subdomains, authority (government, organization, issuer, merchant, or excluded), permitted_claim_types, reviewed entities, review_evidence_url, review_notes, and timezone-aware reviewed_at. Claim types are general_fact, card_rate, card_benefit, and own_terms. Card rates and benefits require issuer authority; merchant sources can substantiate only their own service terms. Own terms, rates, and benefits require a reviewed entity identity. Under strict selection, unknown domains cannot supply evidence; a .org suffix grants no authority. Each generation retains the policy revision loaded at its start.
Candidate sources must be fetched before research findings enter outlining or writing. Missing evidence triggers bounded alternative-source research; insufficient support fails without saving a version. Fetched content still requires passage-backed review of the exact final draft and full brief coverage.
Update brand voice — PATCH /brands/{brand_id}. Partial update of the fields that shape how content is written for the brand. Only these keys are accepted:
PATCH /brands/{brand_id}
{
"description": "string | null", // nullable — send null to clear
"mission_statement": "string | null", // nullable — send null to clear
"tone": "professional", // closed enum (see below); null is rejected
"phrases_to_avoid": ["string", "…"], // send [] to clear; null is rejected
"dos": ["string", "…"], // send [] to clear; null is rejected
"donts": ["string", "…"] // send [] to clear; null is rejected
}
Every field is optional — an omitted key is left unchanged. description and mission_statement are nullable text, so an explicit null clears them. tone and the three arrays reject an explicit null (422): an array is cleared by sending []. Accepted tone values (closed enum): professional, casual, friendly, authoritative, playful, empathetic, technical, conversational. Any other key — including name, industry, is_primary, status, or voice-directive/embedding/regulated-industry fields — is not editable here and returns 422. A missing or cross-org brand_id returns 404; the response echoes the updated brand (including the voice fields). Editing a voice field marks any AI-generated voice directive as stale (it is regenerated on the next content run), and the new voice guidance is applied to subsequent generation. This endpoint is not billable and needs no Idempotency-Key.
Properties
| Method | Path | Purpose |
|---|---|---|
| GET | /properties | List properties |
| GET | /properties/{property_id} | Get a property |
| POST | /properties | Create a property |
| PATCH | /properties/{property_id} | Change publish_policy on an existing property |
Which property topic generation uses. POST /content/generate runs on: (1) the property_id you send; otherwise (2) the organization default_property_id from PATCH /org/settings, when it is still active and belongs to the topic's brand; otherwise (3) the brand's only active property; otherwise it returns 409. The organization default is one value for the whole organization, so in a multi-brand organization it covers only its own brand's topics. For the other brands, send property_id or keep one active property per brand. See Choosing the property under Generation & jobs.
Brand selection. POST /properties requires brand_id, including in single-brand organizations. Missing or null input returns 422; unknown or foreign IDs return 404. Select an owned brand with GET /brands before creating a property.
Primary role. Each brand with active properties has one Primary. The first active property becomes Primary; later creates preserve that selection, even when the requested/default role is primary (the new property is returned as secondary). Choose a different Primary with Make primary in the RoboWrite Properties screen. Deleting the Primary selects the oldest remaining active property; restoring a property does not replace an existing Primary. Reload the property list after changes to see the current roles. The public PATCH remains limited to publish_policy.
Publish policy. Every property carries publish_policy, returned on list/get/create/patch and settable on create or via the scoped patch:
cms_publish(default) — a finished topic-autopilot page (POST /content/generate) is auto-published to the org's connected CMS. If the org has no connected CMS, those runs end inawaiting_reviewand must be resolved from the dashboard;POST /content/{item_id}/publishworks normally once a destination is resolvable. Topic autopilot is the only path that auto-publishes. The program cycle does not readpublish_policy— a programmatic-SEO program page is never published for you under either policy (see Programs (programmatic SEO)), so you callPOST /content/{item_id}/publishfor it yourself.draft_only— RoboWrite publishes nowhere. Generation runs finish ascompletedand you collect the page withGET /content/{content_item_id}.POST /content/{item_id}/publishfor an item on such a property returns409with a policy-specificdetail.
draft_only is a policy, not a fallback: a draft_only property does not start auto-publishing if a CMS is connected later. Send "publish_policy": "draft_only" in the create body; any other value returns 422.
Change it on an existing property — PATCH /properties/{property_id}:
PATCH /properties/{property_id}
{ "publish_policy": "draft_only" }
Body requires publish_policy (cms_publish | draft_only). Explicit null and unknown keys return 422. A missing or foreign property returns 404. Only this field is writable on the public surface; other property fields stay on the session-authed internal API. No Idempotency-Key (PATCH converges). A programmatic-SEO program needs no particular policy — it closes over the API under either one (see Programs (programmatic SEO)).
Existing properties are unaffected. Every property that existed before this field was introduced reads cms_publish, which is exactly what it did before — nothing changed for an organization already publishing to a CMS. REST integrations select draft_only explicitly on create or update. The MCP create_property tool defaults an omitted policy to draft_only; its advertised schema and transmitted body use that default.
POST /properties takes an optional Idempotency-Key; a retry of the same body replays the original property rather than creating a second. (A duplicate url is refused with 409 independently of any key.)
Audiences
| Method | Path | Purpose |
|---|---|---|
| GET | /audiences?brand_id= | List audiences for a brand (PublicPage) |
| GET | /audiences/{audience_id} | Get an audience |
| POST | /audiences | Create an audience |
| PATCH | /audiences/{audience_id} | Update an audience (partial) |
| DELETE | /audiences/{audience_id} | Delete an audience |
Audiences are brand-scoped. GET /audiences requires brand_id. Optional status filters the list. Pagination is the standard envelope (limit 1–200, default 50).
Create. POST /audiences takes brand_id and name. Optional: description, decision_role, sophistication_level, technical_depth, status, goals, pain_points. Unknown keys return 422. A brand_id that is unknown or not owned by the key's org returns 404. Idempotency-Key is optional.
decision_role values: end_user, influencer, decision_maker, economic_buyer, technical_buyer. sophistication_level: novice, intermediate, expert. technical_depth: non_technical, semi_technical, technical, highly_technical.
Each goals item is { "goal": "…", "priority": "…", "timeline": "…" } (goal required). Each pain_points item is { "pain_point": "…", "severity": "…", "current_solution": "…" } (pain_point required).
PATCH. Omitted keys are left unchanged. Explicit null on name or status returns 422. description, decision_role, sophistication_level, technical_depth, goals, and pain_points accept null to clear (send [] to empty an array).
Audience ids returned here are what POST/PATCH /pillars accept on target_audience_ids.
Topics
| Method | Path | Purpose |
|---|---|---|
| GET | /topics | List topics — ?brand_id= is required; omitting it returns 422 |
| GET | /topics/{topic_id} | Get a topic |
| GET | /topics/{topic_id}/content | List content generated from a topic |
| GET | /topics/{topic_id}/scores | Cached opportunity scores for a topic, including market metrics |
| POST | /brands/{brand_id}/topics | Create a topic from your own input |
| POST | /brands/{brand_id}/topics/generate | Generate fresh topics for a brand (async) → 202 + job |
| POST | /brands/{brand_id}/topics/rescore | Re-score a brand's curated topics on demand → 202 + job |
Topic create — pillar anchoring. Every topic must belong to a content pillar (brief generation requires a pillar context). When pillar_id is omitted, the API auto-assigns the best-match active pillar for the brand (semantic match when available, with a deterministic keyword/name-overlap fallback). Returns 400 when the brand has no active pillars, or when a supplied pillar_id is not an active pillar for that brand. A foreign/unknown brand_id still returns 404 (resolved before create).
Topic create — input bounds. premise is optional and capped at 5,000 characters. secondary_keywords is optional, capped at 20 items, and each keyword is capped at 255 characters. Payloads over these limits return 422 (same ingress bounds as brief create — prevents unbounded prompt/token spend).
Generate topics — POST /brands/{brand_id}/topics/generate (the Idempotency-Key header is required). Generates fresh topic-bank ideas for the brand's active pillars asynchronously. Body:
POST /brands/{brand_id}/topics/generate
Idempotency-Key: <opaque-key>
{
"pillar_id": "<uuid> | null", // optional — pin one active pillar; omit to use all of the brand's active pillars
"property_id": "<uuid> | null", // optional — target scoring at a specific property
"requested_count": 50 // optional, 1–500, defaults to 50
}
Returns 202 Accepted with { "job_id": "…", "batch_id": "…", "workflow_id": "…", "status": "…" }. Poll GET /jobs/{job_id} until terminal, then list the generated topics with GET /topics?brand_id=…. A supplied pillar_id that is not an active pillar for the brand, or a brand with no active pillars when pillar_id is omitted, returns 400; a foreign/unknown brand_id or property_id returns 404; over-quota returns 429. This is a spend-charged operation, so a retry with the same key replays the original 202 (Idempotency-Replayed: true) instead of starting a second batch; reusing a key with a different body returns 409. If kickoff fails after a batch was created (transient dispatch), the API returns 503 and freezes the key so a same-key retry does not start a second batch (it may replay the original job_id/batch_id for polling). strategy and seed_keywords are not accepted in v1 (unknown keys return 422). When plan remaining quota is partial, the server may cap requested_count below the requested value without a 429 (429 only when nothing remains).
Create a topic — POST /brands/{brand_id}/topics. Body:
POST /brands/{brand_id}/topics
{
"title": "<string>", // required, 1–500 chars
"primary_keyword": "<string>", // required, 1–200 chars
"pillar_id": "<uuid> | null", // optional — omit to auto-assign the best-match active pillar; an inactive or foreign pillar returns 400
"premise": "<string> | null", // optional, max 5,000 chars
"intent": "informational", // optional search intent
"funnel_stage": "tofu", // optional funnel stage
"suggested_format": "blog_post", // optional, defaults to blog_post
"secondary_keywords": ["<string>", "…"] // optional, ≤20 items, each ≤255 chars
}
Unknown keys are rejected with 422. A supplied pillar_id is validated against the brand's active pillars before insert (see pillar anchoring above).
Briefs
| Method | Path | Purpose |
|---|---|---|
| POST | /briefs | Create a brief |
| GET | /briefs | List briefs |
| GET | /briefs/{brief_id} | Get a brief |
| GET | /briefs/{brief_id}/sections | Get the brief's section breakdown |
| PATCH | /briefs/{brief_id} | Edit a brief (every edit is versioned automatically) |
| POST | /briefs/{brief_id}/approve | Re-approve a brief that a PATCH moved back to draft |
POST /briefs requires brand_id, including in single-brand organizations. Missing or null input returns 422. The brand must belong to the organization; supplied pillar and source_topic_id must belong to that same brand. Unknown/foreign IDs return 404; mismatched brand references are rejected. Optional source_topic_id preserves a saved topic as the origin of this brief. Creation, approval and topic conversion commit together; converted means a brief exists, not that generation succeeded.
POST /briefs takes an optional Idempotency-Key: with one, a retry of the same body replays the original brief (Idempotency-Replayed: true) instead of creating a second; without one, a retried POST creates a second brief. PATCH needs no key (re-applying the same patch lands on the same brief). POST /briefs/{brief_id}/approve does not accept one either — and it is not idempotent: a brief that is already approved returns 422, so retry only after a new edit has moved the brief back to draft.
Exact brief binding for reviewed preparation. A fresh POST /briefs returns
version_id, content_sha256, and content_hash_version: 1 for the approval
snapshot it wrote. A same-key replay returns the original response. Use
GET /briefs/{brief_id} for the latest saved snapshot or when an older receipt
lacks the pair. A detail response without a saved snapshot has null binding
fields. List responses may omit the binding. Copy the opaque SHA-256 value
as returned. It covers the saved snapshot and ordered sections.
POST /content/items and POST /content/items/{item_id}/generate accept
expected_brief_version_id plus expected_brief_content_sha256 together. Omit
both for existing behavior. A partial pair, explicit null, or non-lowercase SHA256 is 422.
A changed/missing snapshot or digest mismatch is 409: the new item or job/outbox
transaction is refused before billing/provider dispatch. The comparison shares
the brief editor's transaction lock. Generation still requires the normal approval
and eligibility gates and produces a draft; this option never publishes or approves.
A saved edit after admission cannot change the immutable snapshot used by that job.
A successful same-key receipt can replay free after later brief edits. Changing or removing the pair under a generation key is a conflict. A failed generation retry is new work and must still match the current snapshot. Item creation uses its existing durable request hash, including the supplied pair; its normal response has no separate creation-snapshot provenance. Old deployments reject these unknown request fields.
Article length limit. target_word_count accepts 100–3500 on POST /briefs and PATCH /briefs/{brief_id}; a larger value returns 422. A brief saved with a larger target before this limit reads back as 3500, and its content is generated at 3500 words. To cover a longer topic, split it into several briefs.
Explicit null on PATCH /briefs/{brief_id}. Omitting a key leaves it unchanged. null clears primary_keyword, target_word_count, audience_details, tone, search_intent, funnel_stage, pillar_id, description, summary, content_goal, notes, and cta. It is rejected with a 422 on title and format, which are published as non-nullable. secondary_keywords, outline, must_cover, must_avoid, source_urls, example_urls, competitor_urls, and attached_document_ids are collections: send [] or null to empty one.
Richer brief fields. Both POST /briefs and PATCH /briefs/{brief_id} accept:
| Field | Type | Notes |
|---|---|---|
outline | string[] | Ordered H2 titles (plain strings, not Markdown), used as the article's headings word for word. Stored as structured brief sections; read back the same way. An item written as an instruction (a semicolon, several sentences, or a sentence like "Explain the fee.") is a 422 outline_item_not_a_heading; put writing directions in must_cover or notes. |
must_cover | string[] | Points the generated draft must address. |
must_avoid | string[] | Points or claims the generated draft must not make. |
source_urls | string[] | Reference URLs the generator may cite as source material. |
example_urls | string[] | Inspiration-only reference URLs. Never treated as verified, citable sources. |
competitor_urls | string[] | Competitor URLs for context. Not fetched or researched by generation. |
notes | string | Free-text guidance folded into the generation prompt. |
cta | string | Desired call to action for the generated draft. |
attached_document_ids | uuid[] | IDs from the document library (GET /documents) pinned to this brief for prompt injection. An ID you cannot access returns 422. |
facts | object[] | Facts the article cites (see Supplied facts below). Needs the v2 article pipeline. |
article_spec | object | What the article must, may or must not contain (see Article spec below). Defaults to {}. |
Supplied facts (facts). POST /briefs and PATCH /briefs/{brief_id} accept facts: up to 20 facts the article cites as supplied claims, each { "text", "source_url"?, "attribution"?, "priority"? }. text is one line of plain text, at most 200 characters, with no Markdown, HTML, links or [[/]]; attribution is at most 120 characters; priority is normal (default) or must_use, and at most 5 facts may be must_use. A source_url must be a public http(s) URL; at generation its page is fetched, and the fact is cited to it only when the page states every figure and name in the fact (otherwise the fact is used without a link). A refused fact is a 422 whose error type names the rule (user_fact_text_markup, user_fact_text_too_long, user_fact_too_many, user_fact_too_many_must_use, user_fact_source_url_invalid, user_fact_duplicate). Your workspace's rules are checked on save too, as on POST …/kit/facts: a source_url your brand's source policy or your research settings block is a 422 with detail.code: "user_fact_source_url_ineligible", and in a workspace with regulated-content settings a fact without a source_url is a 422 with detail.code: "user_fact_source_url_required"; a setting that cannot be read is a 503 (retry). Nothing is saved on a refusal. Generation applies the same rules again, so a fact your settings no longer allow by then (they changed after the save) is left out of the article, and in a regulated workspace so is a fact whose page does not verify. Facts read back on GET /briefs and GET /briefs/{brief_id} with a claim_id, the id the fact carries in the item's content kit. On PATCH, a list replaces the facts and [] or null removes them all; a facts edit re-opens an approved brief like any generation field. Facts need the v2 article pipeline: v2 is the default. If it is switched off, a request that supplies facts returns 409 with detail.code: "article_pipeline_not_v2" and nothing is saved; removing facts is always allowed.
Article spec (article_spec). POST /briefs and PATCH /briefs/{brief_id} accept article_spec, an object that says what the article must, may or must not contain. Every key is optional; omit it (or send {}) for the standard article. elements maps an element (citations, stats, key_takeaways, quotes, faq, comparison_table, steps, toc, relevant_links, products) to required, optional or off; elements you leave out keep their defaults (comparison_table, steps and toc off, the rest optional). Targets: citations (max_sources and min_sources, 1–30 distinct source URLs, max_sources: null = your workspace's citation cap; required_source_urls, at most 10, each also in the brief's source_urls), faq.questions (at most 10 × 200 characters), stats.min_items (1–10), reading_level (level: beginner, practitioner or executive), voice.extra_rules (at most 2 plain lines × 160 characters), length.tolerance_pct (5–50, default 20, applied to target_word_count), products (at most 10 {name, requirement, usage}) and relevant_links (at most 10 {id, url, anchor, usage, requirement}; navigation links, never citations). Citations cannot be off. Steps and comparison tables accept all three modes after activation of KIT_REQUIRED_STEPS_ENABLED. While disabled, optional/required steps receive article_spec_steps_rollout_disabled, and required comparison tables receive article_spec_comparison_table_rollout_disabled (422 before persistence); optional/off comparisons remain allowed. Readers retain stored requirements. How-to templates default to required steps only after activation; while disabled their spec stays empty/off. When active, Kit setup must explicitly map at least the template minimum of outline sections as steps, each supported by admitted research facts. Missing mappings or supporting facts hold the kit without a waiver; edit Kit setup and rebuild, or make steps optional. Steps are written as outline sections rather than as a separate component. A spec that breaks a rule is a 422 whose error loc names the field and whose type names the rule (for example article_spec_citations_off); a required source missing from source_urls (also after a source_urls-only edit) is a 422 with detail.code: "article_spec_required_source_not_in_brief". Nothing is saved on a refusal. On PATCH the spec is replaced whole and null resets it to the standard article; an edit re-opens an approved brief like any generation field. Briefs the platform generates start with your workspace's citation cap and nothing marked required. Generation follows part of the spec now, through the content kit: the kit's FAQ starts with faq.questions, its distinct sources are capped at citations.max_sources, and a required kit element or citation rule the kit cannot provide holds the kit for review (see Article spec findings under Content kits). A reading_level, voice.extra_rules or a required voice also passes the brief's tone, the reading level and must_avoid to the writer, and a required length splits target_word_count across the sections. The other targets are followed in a later release. An empty spec changes nothing.
Each array is capped at 20 items; each must_cover/must_avoid entry and notes share the existing free-text length cap, and each URL entry shares the existing URL length cap. outline, must_cover, must_avoid, source_urls, example_urls, and competitor_urls are read back on GET /briefs/{brief_id} and in list responses.
Editing an approved brief re-opens it for review. PATCH /briefs/{brief_id} on a brief whose status is approved (or ready) moves it back to draft when the patch touches any field that affects generation — that is every field above plus the pre-existing content fields (title, primary_keyword, secondary_keywords, target_word_count, audience_details, tone, format, search_intent, funnel_stage, description, summary, content_goal). The response reflects the new draft status in the same call. Call POST /briefs/{brief_id}/approve to move it back to approved once you are done editing. Re-pointing pillar_id alone does not re-open a brief: the pillar is an organizational link, not a generation input, so an approved brief stays approved when only its pillar changes. A supplied pillar_id must belong to the brief's brand (422 otherwise, same as create). If the brief's status changes while your PATCH is in flight, the request conflicts (409) — retry re-evaluates the edit against the new status.
Content items
An archived empty failed draft drops out of normal content lists and their totals. Read GET /content/{content_item_id} by ID for its failed_draft_archived_at timestamp and latest job. To put it back in inventory, call POST /content/items/{item_id}/restore-archive or the MCP tool restore_archived_failed_draft. Repeating a restore is safe. The 30-day retention policy measures time from failure and subsequent activity. Saved versions, protected edits, active work and downstream references keep an item visible.
| Method | Path | Purpose |
|---|---|---|
| POST | /content/items | Create a content item (Idempotency-Key required). Send "intent":"kit" when creating for a kit. |
| GET | /content/items | List content items in the create/update shape (filters: brief_id, property_id, status) |
| GET | /content | List content items |
| GET | /content/{content_item_id} | Get a content item (add ?include=scoring for quality scores, ?include=sources for cited research sources, ?include=assertion_provenance for the per-assertion provenance receipt, ?include=compliance for regulated-content policy findings, ?include=supplied_facts for the URL-less facts you supplied; combine with a comma) |
| PATCH | /content/items/{item_id} | Update title / status / format / author / slug / published_url |
| DELETE | /content/items/{item_id} | Remove a content item |
For kit creation, the API checks writer readiness before the item consumes a content slot. Generic callers can omit intent. Keep the same body, including the intent, on an idempotent replay. A definitive refusal returns HTTP 409 with kit_write_unavailable. A temporary readiness failure returns HTTP 503 with kit_readiness_unavailable.
Version-bound website links. GET /content/items/{content_item_id}/versions/{version_id}/relevant-links reads the website links approved for one saved generation version: { version_id, links: [{ id, url, anchor, usage, requirement, locale }] }. locale is the indexed page’s locale captured when the editor saved the selection and copied from the pinned brief onto the generation version. A refresh between those steps cannot rewrite it. Older snapshots may have no captured locale. links is [] when the version has none; an unknown version is a 404. The dedicated MCP tool is get_version_relevant_links_v2. This does not widen the published article spec.
versions is a pagination envelope, not an array. On GET /content/{content_item_id} the versions field is a PublicPage (items, total, limit, offset, has_more, next_cursor), newest first, with the standard ?limit= (1–200, default 50) and ?offset= bounds. Read versions.items. Use ?latest_only=true for just the current version or ?version=N to pin one — those two are mutually exclusive (422) and an unknown number is a 404. This replaced a bare array on 2026-08-11; see the Changelog and Versioning and stability.
Published URL. Content item responses (GET /content, GET /content/items, GET /content/{id}, create/PATCH) include published_url — the absolute http(s) URL of the live page when known, otherwise null. CMS-connected orgs usually get this filled automatically after a successful live publish (from the property site URL + a per-profile path template + the item slug). Headless orgs (or any integrator that renders the page themselves) report it back with PATCH /content/items/{item_id}:
PATCH /content/items/{item_id}
{ "published_url": "https://example.com/blog/my-post" }
Rules: value must be an absolute http or https URL (blank string → 422; javascript: / data: → 422). Explicit null clears the field (omit leaves it unchanged). After a clear, the next successful live CMS publish may re-derive it.
Slug cannot be cleared — and can read back null. On PATCH /content/items/{item_id}, slug takes a new value or is omitted; null and "" both return 422. Send a replacement rather than a clear. A value you send is normalised to a URL token — lowercased; Latin letters lose their diacritics (Cómo becomes como, Straße becomes strasse); everything else outside a-z0-9 collapses to - — and made unique within the brand, so the slug you read back may differ from the one you sent. A value with no ASCII letter or digit at all does not become an empty token or a row of hyphens: it takes the same content- plus ten hexadecimal characters that a title in that script gets, described under the 2026-08-30 changelog entry — so PATCHing 如何提高转化率 as a slug is normalised to content-c2eaa9f6b9 rather than stored verbatim. That normalisation is part of the same within-brand uniqueness step described above, so it applies wherever that step does. Read the slug from the response.
On read, slug is published as string | null and an item can still have none. POST /content/items derives a slug from the title at creation. From 2026-08-29 POST /content/rewrite does too — from the title you send, or from the title derived from your Markdown when you omit it — so its source item no longer reads back "slug": null. The two do not derive the same slug, so do not predict one surface's value from the other. They agree on the readable stem, and they differ on three things we have measured: POST /content/items makes the value unique within the property and ignores items you have deleted, while POST /content/rewrite makes it unique within the brand and counts them; once a stem and its -2 … -100 suffixes are all taken the first appends a timestamp and stores it without re-checking, while the second keeps searching and can fail instead; and a title nothing can be derived from at all falls back to content on the first and untitled on the second. POST /content/generate usually assigns one too, but that item can still read back null. The slug is the identity the CMS publish path and the derived published_url above are keyed on, and the automatic derivation described above produces nothing for an item that has no slug — so if you do read null back, PATCH a slug on before you publish that item through a CMS connection, or report its published_url yourself.
Create a content item — POST /content/items (the Idempotency-Key header is required). The item is brief-driven, not topic-driven; its brand is derived from the property. Body:
POST /content/items
Idempotency-Key: <opaque-key>
{
"brief_id": "<uuid>", // required — the brief this item is built from
"property_id": "<uuid>", // required — the publishing target (must belong to the same brand as the brief)
"title": "<string>", // required, 1–500 chars
"format": "blog_post" // optional, defaults to blog_post
}
Unknown keys are rejected with 422 — e.g. sending topic_id or brand_id here is invalid (the brand comes from the property, and topic-based kickoff is POST /content/generate, below). A brief and property whose brands differ returns 422; a missing or foreign brief_id / property_id returns 404.
Because creating a content item can be a billed action, the Idempotency-Key dedupe here is durable: the original item is returned (Idempotency-Replayed: true) on any retry with the same key and body — even hours later or after a transient backend error — so the same key never creates (or bills for) a second item. Reusing the key with a different body returns 409.
This route also carries a per-organization daily cap of 1,000 creates, which answers 429 ({"detail": "Daily content-item create limit exceeded"}, no Retry-After) and resets at 00:00 UTC. Replays and rejected requests do not consume it. See Daily cap on content-item creates.
Find and recover content
Use GET /content and GET /briefs to recover work without retained IDs. Filters combine with AND: brand_id, property_id, status, format, pillar_id, created_from, created_before, q, and keyword. Content also accepts brief_id and the existing content_type selector. GET /pillars accepts brand_id before pagination.
Dates filter creation time: created_from is inclusive and created_before exclusive, using UTC timestamps. Results use newest creation time first with an ID tie-breaker. Follow the standard limit/offset/has_more envelope; total includes the same filters. A brief matches a property through its own property or its current linked content item. Content uses its own pillar when present, otherwise its brief's pillar.
q is a case-insensitive literal substring of a title or content slug. keyword is a trimmed, case-insensitive whole-phrase match against a brief's primary/secondary keywords or a content item's latest saved SEO keywords and linked brief targets. Pending content can therefore match its intended keywords before it has a saved version.
GET /content?brand_id=<uuid>&status=draft&q=content%20briefs&created_from=2026-09-01T00:00:00Z&created_before=2026-10-01T00:00:00Z
Content records include their topic/brief/property/brand references, latest saved version and actual word count, latest job attempt and published URL. Briefs retain target_word_count separately from generated length and include a linked_content preview with its total count. Use GET /content?brief_id=<uuid> to page through all linked items. GET /topics/{topic_id}/content includes the brief-first path through stored source-topic provenance. Historical relationships without reliable IDs remain unknown; matching titles do not establish a link.
Use GET /jobs to recover recent jobs, then GET /jobs/{job_id} for status and errors. Lists accept job_type, status, creation-date bounds, and brand_id, property_id, brief_id, or content_item_id. The response type preserves the stored job type as an open string, including historical types; clients must tolerate names outside the current generation catalog. The optional job_type filter matches that stored name exactly. Elapsed seconds include queue time, ending at the finish timestamp or measured at the response time for unfinished jobs. A latest attempt can fail while an earlier saved version remains usable. The saved version's producing-job reference is separate and remains null when historical evidence cannot establish it.
For MCP clients, these reads are list_content, list_briefs, get_brief, get_content, list_jobs, get_job and get_topic_content. get_content supports the existing version selectors and include=scoring,sources,assertion_provenance,compliance,supplied_facts; read_draft remains the latest-Markdown shortcut. update_brief and approve_brief mirror PATCH /briefs/{brief_id} and POST /briefs/{brief_id}/approve above, including the richer fields and the approve-invalidation behavior. list_documents and get_document mirror GET /documents and GET /documents/{document_id} (see Documents & imported content (read)) for finding IDs to pass as attached_document_ids. Taxonomy MCP names: list_categories, get_category, create_category, update_category, delete_category, list_tags, get_tag, create_tag, update_tag, delete_tag. Lists/creates require brand_id; read the object and verify its brand before updates/deletes. Creates require a stable idempotency_key; updates/deletes forbid it. Deletes require explicit user intent and return a status:204 receipt. Content kit MCP names: get_content_kit, override_kit_component, lock_kit_component, remove_kit_component, add_kit_fact, remove_kit_fact, exclude_kit_source, approve_content_kit, reject_content_kit (see Content kits); they send expected_kit_revision and never an idempotency key. Refresh the client's tool catalog after upgrading.
MCP release diagnostics are separate from the REST /account contract.
initialize.serverInfo.version identifies the connector release.
tools/list._meta["ai.robowrite/connector"] and successful get_account.connector
return version, build_sha (null if unavailable), catalog_hash (SHA-256 of the
effective tool definitions and shipped server instructions), and tool_count. They help investigate a stale or
filtered client catalog; they do not force refresh or grant tool access.
MCP tools declare structured output schemas while preserving existing valid
object results, saved Markdown text and error recovery details. list_reviewers
and list_draft_sections return { "items": [...] }, including for empty lists;
these two list results do not add pagination fields. The REST responses stay
unchanged. Strategy results remain open objects because their REST success
schemas do not currently describe specific fields.
Hosted tools advertise the same delegated scopes at top level and in the legacy security-scheme metadata mirror. Missing or insufficient grants can include an MCP linking challenge; reconnecting does not bypass organization or role access. The developer API-key fallback remains independent of OAuth account linking.
Generation & jobs
| Method | Path | Purpose |
|---|---|---|
| POST | /content/generate | Generate from a topic (autopilot) → 202 + job. Body is { "topic_id": "<uuid>" } plus optional property_id, source_verification_failure_mode and prohibited_phrases |
| POST | /content/items/{item_id}/generate | Generate / rewrite / vary an existing item (supports a direction: draft, rewrite, variation; citation_mode: structured_only / inline; citation_style: bottom_only / inline_only; and kit_mode: auto / hold_for_review) → 202 + job |
| POST | /content/rewrite | Rewrite pasted Markdown to brand voice → 202 + job + content_item_id (Idempotency-Key required) |
| POST | /content/{item_id}/publish | Publish or schedule a live item to the connected CMS → 202 + job_id |
| GET | /jobs | Discover recent jobs by status, type, creation date and linked brand/property/brief/item |
| GET | /jobs/{job_id} | Read job status, errors, timing and content references |
POST /content/generate takes { "topic_id": "<uuid>" } and, optionally, property_id, source_verification_failure_mode and prohibited_phrases. It runs the topic autopilot and does not accept direction or citation_mode — sending either returns 422. The optional recovery-mode override takes precedence over the organization default and stays fixed for that run. prohibited_phrases is unioned with the organization list for that run and does not remove organization phrases. The same optional list is accepted on POST /content/items/{item_id}/generate. Citation and styling options live only on the item path: to control those, create an item (POST /content/items) and call POST /content/items/{item_id}/generate.
POST /content/generate
Idempotency-Key: <opaque-key>
{
"topic_id": "<uuid>", // required
"property_id": "<uuid> | null" // optional — publishing property; must be on the topic's brand
}
Choosing the property. Every run is bound to one publishing property, and that property's publish_policy decides whether the finished page is auto-published or completes as a draft for you to collect (see Properties). Send property_id to choose it. Omit it and the API resolves one, in this order: the organization's default_property_id (set with PATCH /org/settings or in the dashboard) when it is still active and belongs to the topic's brand; otherwise the brand's only active property. When neither applies — the brand has no active property, or several and no matching default — the request returns 409; send property_id, or set the organization default to one of that brand's properties. The organization default is a single value, so a multi-brand organization should send property_id or keep one active property per brand for the brands it does not cover. A property_id that is unknown or not owned by your organization returns 404, and one that belongs to a different brand returns 409. These 409s carry a sentence in detail, not a code; do not branch on its wording. A topic that already has generated content keeps that content's property: a later run writes a new version onto the same content item, so a property_id that differs from that item's property returns 409 — omit property_id, or send the item's own. All of these refusals come before any charge and start no job.
Autopilot eligibility. POST /content/generate only runs for topics whose decision band is autopilot-eligible; ineligible topics return 409. Eligible bands: auto_brief, light_review, plus topics with no decision band yet (decision_band: null). Ineligible: expert_review, reject_or_hold. A topic's band reflects a demand/fit quality gate — freshly-seeded, not-yet-enriched topics (low/zero search volume) often score into the ineligible bands, so a large fraction of a brand-new topic bank may be ineligible until keyword/SEO enrichment runs. Select eligible topics up front with GET /topics?brand_id=… (the response carries decision_band and an eligible_for_autopilot flag) rather than firing blindly into a 409.
eligible_for_autopilot reflects the decision band only. A topic it marks true can still be refused with 409 when its brand's source policy is strict and no reviewed source in that policy matches the topic. The detail of that refusal contains the token no_permitted_sources_for_topic — the one token on this route you can match on. Add a reviewed source for the subject with PUT /brands/{brand_id}/source-policy, or choose a topic about a reviewed issuer or merchant. The refusal comes before any charge and starts no job. The route's other 409s are the property refusals above and the idempotency conflicts under Idempotency. It returns 429 when the plan's content-generation allowance is used up (no Retry-After; check GET /account rather than retrying) and when the per-organization rate limit is exceeded (honor Retry-After).
Topic rescore. POST /brands/{brand_id}/topics/rescore re-evaluates scoring gates (including semantic ICP-relevance when enabled for the brand) and persists new decision bands. Body:
POST /brands/{brand_id}/topics/rescore
{
"property_id": "<uuid>", // required — scoring is property-scoped
"topic_ids": ["<uuid>", "…"], // optional — subset; omit to rescore the whole brand (capped at 200 server-side)
"force_seo_refresh": false // optional — re-fetch keyword/SERP data before scoring
}
Returns 202 Accepted with { "job_id": "…", "status": "queued" } (no workflow_id on this job type). Poll GET /jobs/{job_id} until terminal. For rescore jobs, the polled job includes a result summary: { "total", "rescored", "eligible_before", "eligible_after", "band_counts", "truncated" }. Job types that publish no summary keep result: null — the ideas stage of a program publishes one of its own, see Programs. A foreign or unknown brand_id returns 404. Omitting property_id returns 422. In-flight rescores for the same brand reuse the existing job_id instead of stacking duplicates.
Re-running after failure. A topic's first autopilot kickoff is deduped under autopilot-content:{org}:{topic_id}. If that job finishes in a terminal state (failed, cancelled, completed, etc.) or has been running without progress for an extended period, a later POST /content/generate for the same topic starts a fresh job (new job_id) instead of replaying the old one. In-flight jobs still replay — you get the same job_id/workflow_id and can keep polling. The optional Idempotency-Key follows the same rule: it replays the cached 202 while the linked job is still active or parked in awaiting_review; once that job is terminal or stale-running, the same key dispatches a new charged attempt.
Re-running a topic that already has a draft (including one parked in awaiting_review). Once a run for the topic has saved a draft, a later run writes a new version onto the same content item instead of creating another item. From then on the keyless per-topic dedupe only absorbs repeats within about a minute: after that, a request with no key or a new key starts a fresh, separately charged run — even while the earlier job is still parked and waiting for review. Resending the original Idempotency-Key with the same body replays the parked job's 202 instead; its status may read running, so poll GET /jobs/{job_id} to see awaiting_review. If you only want the parked draft, resolve its review (see Editorial review) rather than re-running the topic.
source_verification_failure_mode starts its own run. A request that sends it — any value, including your organization's current default — never replays a run started without it or with a different value, so a parked run is never resumed by adding it. With no key or a new key it starts a fresh, charged run; only a run started with that same value can be replayed, under the rules above. Under the original key it is a changed body and returns 409.
Replay identity. A replayed run must carry your inputs. When a request would replay an active or parked run (no key or a new key, inside that run's dedupe window) but its prohibited_phrases differ from that run's — any difference, including order, or sending a list the run did not have — it returns 422 with a string detail rather than handing back the old run without your phrases. A property_id that differs from the property the run was started on returns the same 422. Omitting property_id keeps the plain per-topic replay. Under the same Idempotency-Key, any changed body — including a different property_id — returns the key-reuse 409 first.
For generation jobs that saved a draft with completed_with_errors, GET /jobs/{job_id} and MCP get_job return recorded generation_warnings as code/stage pairs. Stages identify research, section coverage, SEO metadata, or completion. The array is empty for clean runs and older records without recognized warnings. A timed-out autopilot review includes review_expired in review_reasons.
Content kit review (kit_mode) and the job's kit fields. On the v2 article pipeline, item generation first researches and builds a content kit (the outline, the claims to cite and the article components), then writes from it. POST /content/items/{item_id}/generate accepts optional kit_mode: auto (default; your organization's brief_auto_approve setting and confidence threshold decide whether a low-confidence kit is held) or hold_for_review (always hold the kit so you can inspect and edit it before the write). The mode is fixed for that job; a different mode under the same Idempotency-Key is a new request, not a replay. hold_for_review needs the v2 article pipeline (409 detail.code: "article_pipeline_not_v2" otherwise, before any charge); auto is accepted everywhere. For an article job, GET /jobs/{job_id} adds kit_status (draft / needs_review / approved), kit_revision (the kit's current revision, for kit writes), kit_confidence (the approval gate's confidence in the kit this job built, 0 to 1; null on the write job an approval starts, which builds no kit, and on jobs that did not record it) and review_reasons (held_for_review, checker_review_hold, review_expired). When a saved draft was held for review (checker_review_hold, on article drafts and on rewrites, refreshes and variations), review_holds lists what to check, in recorded order and at most 50: kind (for example cite_lint, drift_h2_missing or a brief_* rubric kind) and text. For cite_lint, text starts with the source-page reason (fetch_failed: the cited page could not be read; not_on_page: the page does not state a figure or name of the citing sentence; ineligible / not_public: the URL is not an allowed public source; budget_exhausted: too many distinct sources to check) followed by the citing sentence and the URL. review_holds is empty otherwise. A job whose kit was held reads awaiting_review while the kit is still needs_review and that job is still the one an approval would write: read and approve the kit (see Content kits). Once a newer generation of the item replaces it, or once its write finishes, it reads completed even if the item's kit goes back to review (kit_status and kit_revision always describe the item's current kit). Approving starts the write, which you poll on the item's jobs (GET /jobs?content_item_id=…). A held or rejected kit uses no allowance beyond the content item itself (created by POST /content/items): no version is written until a kit is approved.
Rewrite pasted Markdown — POST /content/rewrite (the Idempotency-Key header is required). Submit your own Markdown and get it rewritten to the brand voice. The route creates a source content item (v1 = your paste) and kicks off an async rewrite job that writes v2. Body:
POST /content/rewrite
Idempotency-Key: <opaque-key>
{
"brand_id": "<uuid>", // required — must belong to your org
"property_id": "<uuid>", // required — publishing property (same brand); enables CMS publish target scope
"content": "<markdown>", // required, 1–50,000 chars
"title": "<string> | null", // optional; else derived from the first H1 (or first non-empty line)
"instructions": "<string> | null", // optional rewrite guidance, max 5,000 chars
"pillar_id": "<uuid> | null", // optional pillar override; must belong to brand_id when supplied
"documents": { // optional; defaults to { "mode": "auto", "ids": [] }
"mode": "auto" | "none" | "selected",
"ids": ["<uuid>", "…"] // required non-empty when mode is "selected"
}
}
Returns 202 Accepted with { "job_id": "…", "content_item_id": "…", "status": "running" }. Poll GET /jobs/{job_id} until terminal, then fetch the rewritten draft with GET /content/{content_item_id} — the rewrite lands as version 2 (version_number: 2); v1 is your original paste.
Document-library injection (documents.mode). Controls which of your uploaded knowledge-library documents are blended into the rewrite alongside the brand voice:
auto(default) — use the documents the auto-derived brief attaches.none— brand voice only; no document context.selected— use exactlydocuments.ids. Each id should be an org-owned, ready document; ids that aren't (foreign, unready, or deleted) are silently skipped rather than erroring, and if the selection is too large to fit the rewrite's context budget the overflow is dropped too. An emptyidslist withmode: "selected"is rejected at request time (422).
Idempotency. A retry with the same key and payload replays the stored 202 (Idempotency-Replayed: true) instead of creating (and billing) a second rewrite. Reusing a key with a different payload, or a concurrent in-flight rewrite with the same key, returns 409. If the idempotency backend is unavailable, the route returns 503 with Retry-After rather than proceeding undeduped.
Quota & errors. Each accepted rewrite counts against your org's REVISIONS allowance; over-quota returns 429. A missing, foreign, or cross-org brand_id returns 404. A missing or foreign property_id returns 404; a property_id that belongs to a different brand than brand_id returns 422. A pillar_id that is absent, foreign, or belongs to a different brand returns 404. Validation failures (empty content, missing property_id, oversized fields, documents.mode: "selected" with an empty ids list, unknown keys) return 422. If job infrastructure is temporarily unavailable before the billable row is created, returns 503 with Retry-After.
Latency. The rewrite pipeline analyzes your paste, materializes a brief, and runs the full brand-voice rewrite engine — expect timing similar to other generation jobs (typically 10–17 minutes; allow at least 30 minutes before treating a run as stalled). Poll on the interval from How often to poll above — 30 seconds for a handful of runs, longer as concurrency rises.
Content kits
Public stat components keep the full reward rate, including the spend denominator, and present the supporting source sentence in evidence.span. The cited claim retains its full source span.
Kit reads include an optional allowance_recovery receipt. A counted, empty item returns one content slot in its original billing month after a definitive write refusal at approval or after all three started writes fail. write_state=no_waiting_run means that hold has ended. A fresh generation uses its own allowance. When needs_billing_reconciliation is true, the original month is closed or usage was already reported. The receipt does not promise an invoice credit.
A held autopilot content kit ends the autopilot run for review. Approving it starts one standalone article write for the editor; it does not resume automatic scoring or publishing. Repeated approval reuses the existing write. Organization auto-approval settings are unchanged.
On the v2 article pipeline, each generated item has a content kit: the plan the writer follows. It holds the outline, the claims the article may cite (from research, and the facts you supplied, origin: supplied), and the components (FAQ, stats, quotes, comparison table, key takeaways, sources). A kit in needs_review holds the article until it is approved. Every route needs the v2 article pipeline, which is the default; if it is switched off they return 409 with detail.code: "article_pipeline_not_v2".
| Method | Path | Purpose |
|---|---|---|
| GET | /content/items/{item_id}/kit | Read the kit: status, kit_revision, review findings, outline, claims, components |
| POST | /content/items/{item_id}/kit/components | Add a component, or replace the one with this id, from a typed payload |
| POST | /content/items/{item_id}/kit/components/{component_id}/lock | Lock a component so kit rebuilds keep it as it is |
| DELETE | /content/items/{item_id}/kit/components/{component_id} | Remove a component (rebuilds do not bring it back) |
| POST | /content/items/{item_id}/kit/facts | Add one supplied fact to the kit |
| DELETE | /content/items/{item_id}/kit/facts/{claim_id} | Remove a fact added on the kit |
| POST | /content/items/{item_id}/kit/source-exclusions | Exclude a source domain (and its subdomains) from the kit |
| POST | /content/items/{item_id}/kit/approve | Approve the kit; the article is written from it |
| POST | /content/items/{item_id}/kit/reject | Reject the kit; it stays held and nothing is written |
Revisions. kit_revision changes on every save. Every write sends the revision it read: expected_kit_revision in the body, or the Expected-Kit-Revision header on a DELETE. A stale revision returns 409 detail.code: "kit_revision_stale": read the kit again. An unknown item, an item of another workspace and an item with no kit yet are all 404. A refused write is a 422 with detail.code naming the rule. No route takes an Idempotency-Key: the revision makes a replay a 409.
Components. Send kind and the kind's structured payload, for example key takeaways as {"items": [{"claim_id": "…"}]}: every item is bound to a claim in the kit, and any text you add must state only figures and names that claim states. The payload is rebuilt against the kit's claims, so links and citations always come from the claims. A raw {"markdown": …} payload (component_raw_markdown) and the sources kind (component_kind_not_writable; sources come from the claims, so add a fact instead) are refused, as is a payload a claim does not support (component_unverified, with the claim and the unsupported figures) or one that is not valid for its kind (component_unrenderable). Editing an approved kit moves it back to needs_review.
Facts. POST …/kit/facts takes the same fields and rules as brief facts plus expected_kit_revision. A source_url is fetched now and cited only when its page states every figure and name in the fact. A page that only renders in a browser, or shows a bot check first, is read through a rendering browser, so the request can take up to about 40 seconds. When the fact names something mid-sentence, a capitalised word that only starts a sentence ("The", "Normal", "Choose") need not be on the page; a fact naming nothing else still needs it, and your products and reviewed source names are always checked. A fact with no figure and no known name must appear on the page as written. The same rule applies to brief facts and in regulated workspaces. source_url_cited in the response says whether the URL is cited, and source_check why not: fetch_failed (the page could not be read, even rendered), not_on_page, ineligible_url, unsafe_url, or removed_source (the source was removed or its domain excluded). Each supplied claim records the URL you supplied as supplied_url and its outcome as source_check (null on facts added before 2026-11-19); a later exclusion or removal of that source reads removed_source. An unverified URL is never cited. Optional section_ids (outline ids from the kit's outline) map the fact to sections: it counts as their evidence, and the writer may state it there even in a section otherwise kept general; an id not in the outline is section_not_in_outline. Map supplied facts after excluding research sources, or every section can end up general-only. A duplicate of a fact already on the kit is user_fact_duplicate; a URL your brand's source policy or research settings block is user_fact_source_url_ineligible; in a workspace with regulated-content settings a fact without a verified URL is user_fact_source_url_required. Kit facts (claim_id starting user:k-) survive kit rebuilds. Brief facts (user:b-) live on the brief: edit them with PATCH /briefs/{brief_id}, which re-opens the brief for approval, so a facts change before generation is brief edit → brief approve → generate → kit approve. A kit fact a locked or edited component still cites cannot be removed (fact_bound_by_component) until that component is edited or removed.
Excluding a source domain. POST …/kit/source-exclusions takes {"domain": "example.com", "expected_kit_revision": …}. Send a bare domain, with no scheme, path or wildcard. Every kit source on that domain or one of its subdomains is removed in one change. Its research claims leave the kit, components built from those claims are dropped, and the sources list is rebuilt. The response is the kit plus excluded_source_urls, removed_claim_ids, dropped_component_ids, uncited_fact_claim_ids and general_only_sections. A fact you supplied that cited the domain stays in the kit as an uncited statement (uncited_fact_claim_ids); remove it with DELETE …/kit/facts/{claim_id} if it should go too. In a workspace with regulated-content settings, where a fact needs a source, the exclusion is refused with source_domain_cited_by_facts (details.claim_ids) until you remove those facts. A section left with no cited claim is listed in general_only_sections, and the article keeps it general: no figures, prices, dates or named-product facts. Navigation links in the brief's article_spec.relevant_links are not sources and are unaffected, so a related-reading link to a page on the excluded domain is still placed as a link. The exclusion applies to this kit; regenerating the item can find other pages on the domain, so use your brand's source policy to exclude a domain from research. Refusals are 422: source_domain_invalid, source_domain_not_in_kit, and source_has_locked_components (details.component_ids) when a locked or edited component cites the domain, which you must edit or remove first. An item with a generation still running is 409 article_run_active. Like every kit edit, excluding a domain moves an approved kit back to needs_review. Approving it then starts the write the held run already paid for, from the remaining claims only.
Evidence. Every kit response carries evidence, computed from the current kit: sections (per outline item, claim_count cited claims matched to it, general_only, cited_claim_ids, uncited_claim_ids for supplied facts mapped there without a cited URL, and source_urls), unmapped_claim_count and unmapped_claim_ids (claims not matched to a section, such as facts you supplied without section_ids), unplaceable_claim_ids (facts you supplied, and must-use claims, that no section can state because every section they could appear in is general-only), source_count (distinct cited sources), min_sources (set only when the brief requires citations) and unmet_requirements ({ element, reason, detail }, the article-spec shortfalls described under Article spec findings, for the kit as it is now). review_findings stays the review gate's record of the revision it judged; read evidence after an edit.
Write recovery. Read write_state on GET …/kit (MCP get_content_kit). With owes_write, approve the reviewed revision to start or retry its write without another allowance charge. A held generation allows three started attempts in total. A failed dispatch can be resent on the same attempt. With run_active, follow the item’s jobs. With written, read the saved version. With no_waiting_run, this generation has no write available to approve. A new generation is a separate allowance-checked action.
Approve and reject. POST …/kit/approve stores the approval and starts the write as a new job on the item; write in the response is started (also when that write was already started by an earlier approval) or not_started (the approval is stored either way). Read the kit’s current write_state before retrying. Repeated approval cannot duplicate a successful write. An item whose status cannot generate returns 409 item_not_generatable and stores nothing. An approval made through an agent (OAuth) connection is recorded with decided_by: "agent", an API-key approval with decided_by: "user". POST …/kit/reject keeps the kit held (needs_review) with nothing written: edit and approve it, or regenerate to rebuild it. A rejected or never-approved kit uses no allowance beyond the content item itself.
Article spec findings. When the brief's article_spec marks a kit element (stats, key_takeaways, quotes, faq, comparison_table) or a citation rule (min_sources, required_source_urls) required and the kit cannot provide it, the kit is held (needs_review) and review_findings lists { "element", "reason", "detail" }. Required toc, relevant_links and products are not kit-checked and produce no finding (they follow in a later release). reason is no_admitted_evidence (research found nothing to build it from), build_failed, below_min_items (fewer stats than stats.min_items), below_min_sources (fewer distinct sources than citations.min_sources) or required_source_not_admitted (no claim in the kit cites a required source URL; detail is the URL). If your organization's brief_auto_approve setting approves the kit anyway, the finding stays in review_findings. Approving a held kit waives these findings. Notes that never hold the kit read { "advisory", "element", "component_id" }: off_element_present (a locked component of an element the spec turns off is kept as it is), element_unsupported (the element cannot be built yet, so it is treated as off), stats_min_items_clamped (stats.min_items is above what the content quality allows) and max_sources_raised (the source cap was raised to fit the required source URLs).
Required how-to steps can produce a StepsSufficiencyFinding in review_findings with unsupported_step_ids, mapped_steps and minimum_steps. This hold blocks writer dispatch even with workspace auto-approval, autopilot or a user approval; it cannot be waived.
Pillar strategy (clusters-first engine)
| Method | Path | Purpose |
|---|---|---|
| POST | /pillar-strategies | Generate a clusters-first pillar strategy for a brand |
| GET | /pillar-strategies/{run_id} | Poll a strategy run until completed, failed, cancelled, or still generating |
Request body (POST /pillar-strategies):
{
"brand_id": "<uuid>",
"keyword_segment": { "seeds": ["invoice factoring", "…"] }, // optional — omit for brand-wide cold path
"num_pillars": 5, // optional, clamped to 3–10 (default 5)
"force_refresh": false // optional — bypass idempotency and start a fresh charged run
}
200 vs 202. A matching completed snapshot (same org, brand, request seeds, and num_pillars) returns 200 OK with the full strategy snapshot immediately — no quota charge, no new LLM run. An in-flight run for the same signature returns 202 Accepted with { "status": "generating", "run_id": "…", "poll_url": "/api/public/v1/pillar-strategies/{run_id}" } — also free. Any fresh label/generate pass (including force_refresh: true) returns 202 and charges the org's pillar-strategy allowance once per newly created run.
Polling. GET /pillar-strategies/{run_id} returns:
200+ completed snapshot (clusters,pillars,gaps,warnings) when the run finished. The snapshot's ownstatusis snapshot quality, not run state: it iscompleted, orcompleted_with_errorswhen enrichment was degraded. A degraded snapshot can contain partial results or no usable strategy. Readwarningsand check the returnedclusters/pillarsbefore proceeding to topics or drafts.200+{ "status": "failed", "error": { "detail": "…" } }on failure200+{ "status": "cancelled", "error": { "detail": "…" } }when cancelled200+{ "status": "generating" }while the run is in flight
Research warnings. Warnings keep the { "code": "…", "detail": "…" } shape. Research warnings can accompany existing warnings such as THIN_SEEDS or NO_CLUSTERS; each research code appears at most once per snapshot.
| Code | Meaning |
|---|---|
KEYWORD_RESEARCH_UNCONFIGURED | Keyword research was unavailable for part of this run. |
KEYWORD_RESEARCH_CALL_FAILED | A keyword research request failed. |
KEYWORD_RESEARCH_ZERO_RESULTS | A keyword research request returned no results. |
NO_CLUSTERS means no clusters could be resolved. If the snapshot has no usable pillars, stop the content workflow and inspect its warnings before requesting another generation run. Completed snapshots remain immutable, so older results may contain only the original warnings.
Strategy generation is LLM-backed and typically takes several minutes; treat anything under 15 minutes as normal. Poll on the interval from How often to poll above (30 seconds is the floor).
Errors. An unknown or cross-org brand_id returns 404. An unknown or cross-org run_id returns 404. Over-quota fresh runs return 429.
Programs (programmatic SEO)
Before accepting page generation, a research-only run can return 429 with error_code: PROVIDER_ALLOWANCE_EXHAUSTED and reason: byok_required when the applicable Firecrawl allowance is exhausted. Connect an eligible organization key or supply the missing facts. Runs with supplied inputs, reusable live content on selected pages, or pages needing no research can continue; completed pages alone do not make a research-only run eligible. Inspect each page's blocked_inputs afterward. A disabled provider never silently switches to a platform key or another paid fallback. Temporary research-admission failures return 503.
Programs is parked. Every verb below returns 403 {detail: "Programs is not enabled for this organization."} unless your organization has been allowlisted. That 403 is declared on every Programs operation in the published OpenAPI document too, so a generated client sees it without reading this guide. The paths stay reserved so a later resume does not invent a new surface.
| Method | Path | Purpose |
|---|---|---|
| POST | /programs | Create a program from a brand, property, template family, scope, and a bulk set of seeds |
| GET | /programs | List your programs, newest first |
| GET | /programs/{program_id} | Get one program with its per-stage counts |
A program is how you seed a body of related pages: you supply what the program
covers (its scope), which template family turns that scope into a page
list, and the seeds to research from. Seeds enter here rather than on
POST /brands/{brand_id}/topics/generate, which still rejects strategy and
seed_keywords with a 422.
Create a program — POST /programs. Body:
POST /programs
Idempotency-Key: <opaque-key> // optional
{
"brand_id": "<uuid>", // required
"property_id": "<uuid>", // required — must belong to the same brand
"template_family": "comparison", // required — one of GET /program-templates (comparison | listicle | entity_review)
"scope": {
"entities": ["Card A", "Card B", "Card C"] // required, 1–500 entries; blanks rejected, duplicates collapsed
},
"seeds": [ // optional, up to 500
{ "seed": "best travel card", "client_reference": "CUST-1" },
{ "seed": "cash back card", "client_reference": "CUST-2" }
],
"client_reference": "your-own-id" // optional
}
Returns 201 Created with the program in state draft. Unknown keys are
rejected with 422, including unknown keys inside scope (a typo such
as "entites" is a 422, not a program that covers less than you intended). A
brand_id or property_id that is unknown or not owned by your organization
returns 404, as does a property_id that belongs to a different brand.
The 500-entry bounds are storage bounds, not research bounds. Everything you
submit here is stored and correlated, but one ideas:generate run researches at
most 100 subjects drawn from both lists — see Generate ideas below for
how the budget is split between seeds and scope entities.
Correlating what you submitted with what we generate. client_reference is
your own identifier, opaque to us. Set it on each seed and it is carried onto
every idea and every planned page derived from that seed, so you can match our
rows back to your records without storing our IDs. The program itself takes a
client_reference too.
Seeds are deduplicated per program. Seeds are compared case-insensitively
after trimming, so submitting "best travel card" and " Best Travel Card " in
the same program yields one seed. Re-submitting a seed you already sent adds
nothing. Blank seeds are dropped. The first occurrence wins, so the surviving
client_reference is the one you sent first.
Idempotency. POST /programs accepts an optional Idempotency-Key. With one,
a retry of the same body replays the original 201 (Idempotency-Replayed: true)
instead of creating a second program; reusing a key with a different body returns
409. Without one there is no deduplication and a retry creates a second
program.
Reading a program. GET /programs/{program_id} returns the program plus
per-stage counts:
{
"id": "<uuid>",
"state": "draft",
"template_family": "comparison",
"scope": { "entities": ["Card A", "Card B", "Card C"] },
"client_reference": "your-own-id",
"counts": {
"seeds": 2,
"ideas": { "total": 0, "pending": 0, "approved": 0, "declined": 0 },
"plan_pages": { "total": 0, "pending": 0, "approved": 0, "declined": 0 }
}
}
Scope is strict on write, lenient on read. Create rejects unknown keys
inside scope with 422. On read, unknown keys that a later template
version may have stored are preserved in the scope object (not stripped,
not a 500) so forward-compatible fields round-trip. Clients should ignore keys
they do not understand.
state runs draft → researching → ideas_ready → planning → plan_ready
→ generating → pages_ready, with a single failed state. An unknown
program_id, or one belonging to another organization, returns 404 — never
an empty result.
GET /programs pages with limit (1–200, default 50) and offset, and returns
the standard { items, total, limit, offset, has_more, next_cursor } envelope.
Prefer cursor for multi-page walks. Offset paging can skip or duplicate
rows when programs are created between requests. Pass ?cursor= with the opaque
next_cursor from the previous page; when cursor is set, offset is ignored.
An invalid or malformed cursor returns 422. next_cursor is non-null only
when has_more is true.
Ideas, and approving them
| Method | Path | Purpose |
|---|---|---|
| POST | /programs/{program_id}/ideas:generate | Research the program's seeds and scope and propose ideas |
| GET | /programs/{program_id}/ideas | List the ideas, optionally filtered by approval state |
| POST | /programs/{program_id}/ideas | Add an idea of your own |
| POST | /programs/{program_id}/ideas/{idea_id}/approve | Approve one idea |
| POST | /programs/{program_id}/ideas/{idea_id}/decline | Decline one idea |
| POST | /programs/{program_id}/ideas:approve-all | Approve every high-confidence idea still pending |
| PATCH | /programs/{program_id}/ideas/{idea_id} | Reserved — returns 501 |
Approval is the gate. Every idea starts pending. Only approved ideas
become planned pages. A declined idea is kept — so you can change your mind
and approve it later — but it never advances.
Generate ideas — POST /programs/{program_id}/ideas:generate. This researches
your seeds and your scope entities for keyword ideas and their competition data,
so it bills data providers and an Idempotency-Key header is required
(absent → 422). Retrying with the same key replays the original response
instead of starting a second, separately-charged run; the same key against a
different program is a 409.
POST /programs/{program_id}/ideas:generate
Idempotency-Key: <opaque-key> // required
→ 202 Accepted
{ "job_id": "<uuid>", "status": "queued", "program_state": "researching" }
How many subjects one run researches. A run researches at most 100
subjects — your seeds and your scope entities together — even though
POST /programs accepts up to 500 of each. Every subject is a paid data-provider
read, so the ceiling is a cost control, not a payload limit.
The 100 slots are split so neither side can crowd out the other: seeds and scope entities get 50 each, and whichever side uses fewer than 50 gives the remainder to the other, seeds first. So 500 seeds and 500 entities research 50 of each; 40 seeds and 500 entities research all 40 seeds and 60 entities; a program with seeds and no scope entities researches 100 seeds. Subjects are deduplicated across both sides (compared case-insensitively after trimming), and a scope entity that repeats a seed costs neither side a slot. Subjects past the budget are skipped — they are kept on the program, they are simply not researched, and nothing downstream can produce a page for a subject that was never researched. A single run also writes at most 200 ideas.
Poll GET /jobs/{job_id} until the job reaches a terminal status, then read the
ideas. While the research runs the program sits in researching; a second stage
verb during that window returns 409. A completed ideas job carries a
summary in result:
{
"job_id": "<uuid>",
"status": "completed",
"result": {
"program_id": "<uuid>",
"subjects_researched": 100,
"ideas_proposed": 200,
"ideas_written": 200,
"ideas_by_source_subject": {
"Chase Ultimate Rewards": 5,
"Citi ThankYou Points": 3
},
"related_read_failures": 0,
"metrics_chunk_failures": 0,
"serp_read_failures": 0,
"candidates_without_metrics": 0,
"relevance_judge": {
"status": "applied",
"candidates": 5,
"judged": 5,
"dropped": 3
},
"is_degraded": false
}
}
subjects_researched is the number of subjects this run actually sent to the
data providers — compare it with what you submitted to see whether the budget
skipped anything. ideas_proposed is what the research produced and
ideas_written is what was stored (they differ when a re-run re-proposes an
idea the program already has). ideas_by_source_subject is the per-subject
idea count for this run (keyed by the seed or scope entity that produced each
idea) — use it to see portfolio skew before ideas:approve-all. Multi-subject
runs also balance related-keyword accepts across subjects and drop
single-token / source-subset generics plus near-duplicate sub-clusters, so one
entity cannot dominate the set with paraphrases of one intent.
The five degradation fields report partial DataForSEO / provider outages that
still complete the stage with a non-empty idea set: related_read_failures,
metrics_chunk_failures, and serp_read_failures count failed provider
reads; candidates_without_metrics is how many accepted keywords had no
volume/difficulty payload; is_degraded is true when any of those counters
is positive, or when the relevance check below was attempted and failed
(status failed or partial). Treat is_degraded: true as a soft warning
on the result — the job status remains completed, but the idea set may be
thinner or less scored than a clean run.
relevance_judge reports the automated relevance check on borderline related
keywords: those scored exactly 0.75, which match your program by only one
or two shared words. Before any market data is fetched for them, each is
checked against your template family, scope.entities and seeds; one judged
off-topic (a firm that merely shares a word with a scope entity, say) is not
written, and one judged on-topic keeps relevance_score: 0.75 and arrives
pending as before. Subjects and higher-scoring keywords are never checked.
candidates is how many keywords were eligible, judged how many the check
answered and dropped how many it ruled off-topic. A dropped keyword does not
free a slot for another. status is one of:
applied— every eligible keyword was checked.partial— some were; the rest were written as if no check existed.failed— the check was attempted and did not answer, or it is enabled but could not run as configured; every eligible keyword was written as if no check existed.unavailable— the check is not enabled for this run; every eligible keyword was written as if no check existed. Not counted inis_degraded.not_needed— the run produced no eligible keyword.
The job never fails because of this check. Until the run finishes, result is an empty object;
job types that publish no summary keep result: null.
Read the ideas — GET /programs/{program_id}/ideas. Pages with limit (1–200,
default 50) and offset; add ?state=approved (or pending / declined) to
filter. ?state=approved is exactly the set that will advance.
The response is the standard pagination envelope; one items
entry looks like this:
{
"id": "<uuid>",
"program_id": "<uuid>",
"title": "Best travel card",
"primary_keyword": "best travel card",
"state": "pending",
"client_reference": "CUST-1",
"research": {
"search_volume": 9000,
"keyword_difficulty": 42,
"cpc": 1.5,
"competition_level": "MEDIUM",
"competitor_domains": ["example.com"],
"source_subject": "best travel card",
"source_kind": "related_keyword",
"relevance_score": 0.9
}
}
client_reference is carried forward from the seed the idea came from, so you
can match our ideas back to what you submitted. research is empty for an idea
you added by hand. relevance_score is a 0–1 signal from research: subject
terms score 1.0; related keywords that are too off-brand are dropped before
write, and survivors carry the score so you can filter without reading every
row. On comparison and entity_review, a related keyword whose only link to
a multi-word scope entity or seed is that name's first word is dropped (a firm
called "… Capital …" for Capital One Venture X). On every template family a
related keyword scored 0.75 is also screened by the relevance check described
under the ideas job result (relevance_judge), and one judged off-topic is
not written. On comparison a related
keyword that is itself a comparison ("X vs Y") is dropped too. A "vs" inside one
of your own scope.entities names does not count (VS Code extensions is kept),
except a "vs" that starts or ends the name when the name sits mid-phrase
(best VS Code extensions reads as "best vs …" and is dropped).
Add your own idea — POST /programs/{program_id}/ideas with
{ "title": "...", "primary_keyword": "...", "client_reference": "..." }. Returns
201 with the idea in pending. Ideas are deduplicated within a program on
the primary keyword (falling back to the title), so adding one that already
exists — whether you added it or the research run found it — returns the idea you
already have rather than a second one. An optional Idempotency-Key replays the
original 201.
Approve and decline — POST .../ideas/{idea_id}/approve and .../decline
return 200 with the updated idea. Both are naturally repeatable: restating
an idea's current state is a successful no-op, so a dropped response is safe to
retry. For that reason they do not accept an Idempotency-Key — sending one
returns 422 rather than being quietly ignored.
Approve everything pending — POST /programs/{program_id}/ideas:approve-all
returns the resulting counts:
{ "total": 12, "pending": 2, "approved": 7, "declined": 3 }
It approves only high-confidence ideas that are still pending: subject-
sourced ideas, hand-added ideas, and related keywords whose relevance_score
clears the high-confidence floor. A related keyword carrying no
relevance_score is not high-confidence: an absent or null score is
refused rather than read as passing, so such an idea is left pending for you
to curate. Lower-confidence related keywords stay pending so you can curate
them (or approve them individually). Ideas you
declined stay declined — this convenience verb never reverses a decision you
made deliberately. It does not accept an Idempotency-Key either.
It also skips ideas your template family cannot turn into a page. On a
listicle the page is the facet, and an idea whose idea_key, title or
primary_keyword is exactly one of your scope.entities is one of the things
each list ranks — never a page of its own. Those ideas are left pending
however high their score, because approving them adds nothing to the plan.
On comparison an idea whose title or primary_keyword is already a
comparison ("X vs Y", "X versus Y") is left pending too, and the plan never
pairs it, so no page is titled "A vs B vs C". An idea that is exactly one of
your scope.entities is never treated as a comparison, so VS Code is paired
like any entity; the same edge rule as research applies to longer phrases. On entity_review every subject is
a page, and on a listicle a seed that names no scope entity is a facet and is
still approved. You can still
approve any of them one at a time with POST .../ideas/{idea_id}/approve — this
only changes what the bulk verb picks.
While a stage is running the idea list is frozen. Approving, declining or
adding an idea while the program is in researching or planning returns
409: the stage that consumes the approved set must not have it rewritten
underneath it. Wait for the job to finish, then make your changes.
The freeze is reported ahead of whether the idea exists. Approving or
declining an unknown idea_id on a frozen program returns 409, not
404 — while a stage is running no idea on that program can be mutated, so
the lock is the answer regardless of the id. Once the program is out of
researching / planning, an unknown idea_id returns 404 as usual.
Treat a 409 here as "retry after the job finishes" and only then trust a
404 to mean the idea is genuinely gone.
Editing an idea is not available yet. PATCH /programs/{program_id}/ideas/{idea_id}
is reserved and always returns 501. Decline the idea and add a corrected one
instead.
The plan, and approving it
| Method | Path | Purpose |
|---|---|---|
| POST | /programs/{program_id}/plan:generate | Expand the template over your approved ideas into a page list |
| GET | /programs/{program_id}/plan | List the planned pages, optionally filtered by approval state |
| POST | /programs/{program_id}/plan | Add a page of your own |
| POST | /programs/{program_id}/plan/{page_id}/approve | Approve one page |
| POST | /programs/{program_id}/plan/{page_id}/decline | Decline one page |
| POST | /programs/{program_id}/plan:approve-all | Approve every page still pending |
| PATCH | /programs/{program_id}/plan/{page_id} | Reserved — returns 501 |
The plan is the concrete page list. It is what your template family produces
from the ideas you approved: for a comparison program over a set of cards it is
"Card A vs Card B", "Card A vs Card C", … For entity_review it is one page per
approved idea, and for listicle one page per approved facet. Approval is the
second gate. Every page starts pending; only approved pages are generated.
Generate the plan — POST /programs/{program_id}/plan:generate. An
Idempotency-Key header is required (absent → 422), so a retried
request replays the original response instead of starting a second run.
POST /programs/{program_id}/plan:generate
Idempotency-Key: <opaque-key> // required
→ 202 Accepted
{ "job_id": "<uuid>", "status": "queued", "program_state": "planning" }
Poll GET /jobs/{job_id} until the job reaches a terminal status, then read the
plan. While the expansion runs the program sits in planning; a second stage verb
during that window returns 409. A completed plan job carries a summary in
result:
{
"job_id": "<uuid>",
"status": "completed",
"result": {
"program_id": "<uuid>",
"approved_ideas": 12,
"approved_ideas_unread": 0,
"approved_ideas_not_page_bearing": 0,
"pages_expanded": 48,
"pages_planned": 40,
"pages_skipped_unapproved": 0,
"pages_skipped_existing": 8
}
}
approved_ideas_unread is how many approved ideas this run did not load (the
plan stage paginates the full approved set in windows of 200, up to a hard
safety ceiling of 2000 — non-zero only when that ceiling truncates the drain or
the list ends early); approved_ideas_not_page_bearing is how many of the ideas
it did load this template family never turns into a page of their own (on
listicle, the ones that name a scope entity — they are the ranked shortlist
instead; on comparison, approved ideas that are already "X vs Y"; always 0
on entity_review), so
pages_expanded: 0 with a non-zero count here tells you the approved set holds
no facets rather than that the run failed; pages_planned is what was stored;
pages_skipped_existing is pages left out because matching content already
exists on the property. Until the run finishes, result is an empty object.
Three rules shape what you get:
- Only ideas you approved expand. A
declinedor still-pendingidea never produces a page. Approve at least one idea first — with nothing approved,:generatereturns409. - Re-running is safe. The expansion is deterministic, so a second run adds only pages that are genuinely new. It never duplicates a page you already have, and it never re-creates one you declined.
- Pages you already have are skipped. A planned page whose title matches content that already exists on the program's property is left out, so a program does not plan work you have already done.
- Hard ceilings apply (and are visible). Expansion uses at most 50
approved subjects and materialises at most 500 pages per run. Extra
approved ideas beyond the subject budget are left unplanned; extra expansion
beyond the page budget is truncated. On
listiclethe subject budget counts facets only: in-scope entities are the ranked shortlist every page carries (at most 10, in the order you wrote the scope) rather than pages of their own, so they do not spend it. The resulting plantotalonGET /programs/{program_id}/planis the number that was written — if you expected more pages, check whether either ceiling bit. Templateentities_per_page_max: nullmeans the family does not impose a per-page entity ceiling; it does not mean plan expansion is unbounded.
Read the plan — GET /programs/{program_id}/plan. Pages with limit (1–200,
default 50) and offset; add ?state=approved (or pending / declined) to
filter. ?state=approved is exactly the set that will be generated.
The response is the standard pagination envelope; one items
entry looks like this:
{
"items": [
{
"id": "<uuid>",
"program_id": "<uuid>",
"title": "Card A vs Card B",
"target_keyword": "card a vs card b",
"template_family": "comparison",
"state": "pending",
"client_reference": "CUST-SEED-1",
"content_item_id": null,
"expansion": {
"expansion_unit": "entity_pair",
"entities": ["Card A", "Card B"],
"source_idea_keys": ["card a", "card b"]
}
}
],
"total": 1225,
"limit": 50,
"offset": 0,
"has_more": true
}
client_reference is carried forward from the idea (and the seed) the page came
from. expansion shows why the page is in your plan; for a page you added by hand
it carries only the entities you supplied on create, and is empty if you supplied
none. content_item_id stays null until the page has been generated.
Add your own page — POST /programs/{program_id}/plan with
{ "title": "...", "target_keyword": "...", "client_reference": "...", "entities": ["..."] }.
Returns 201 with the page in pending. Pages are deduplicated within a program
on the title, so adding one that already exists returns the page you already have
rather than a second one. Unlike the automatic expansion, a page you add by hand
is not skipped for matching existing content — you asked for it by name. An
optional Idempotency-Key replays the original 201.
entities is optional and names the things the page is about, recorded as its
expansion.entities. Supply it if your template family gates on facts. A
comparison or entity_review page is written from facts matched against that
list, so a hand-added page without one has nothing to match and reads
generation_state: blocked on every run however many facts you send — see
Supply the facts your pages are written from. Two spellings of one entity
count once (case and surrounding whitespace are ignored, exactly as facts are
matched), blanks are dropped, and at most 50 names of up to 200 characters are
accepted. How many a page may carry is the family's own contract: a count outside
entities_per_page_min/entities_per_page_max from GET /program-templates
returns 422, which is distinct from the 409 you get while the stage
that consumes plan pages is running.
Approve and decline — POST .../plan/{page_id}/approve and .../decline
return 200 with the updated page. Both are naturally repeatable, so they
do not accept an Idempotency-Key — sending one returns 422 rather than
being quietly ignored.
Approve everything pending — POST /programs/{program_id}/plan:approve-all
returns the resulting counts, in the same shape as the idea verb. It approves only
what is still pending; pages you declined stay declined.
While a stage is running the plan is frozen. Approving, declining or adding a
page while the program is in planning or generating returns 409: the
stage that consumes the approved set must not have it rewritten underneath it.
Editing a plan page is not available yet. PATCH /programs/{program_id}/plan/{page_id}
is reserved and always returns 501. Decline the page and add a corrected one
instead.
Supplying facts about your entities
| Method | Path | Purpose |
|---|---|---|
| POST | /programs/{program_id}/facts | Record facts about the program's entities, one per entity and attribute |
| GET | /programs/{program_id}/facts | List the facts recorded for the program, optionally for one entity |
Some template families need structured input before a page can be written: a
comparison page needs an attribute matrix covering every entity it compares,
and an entity_review page needs facts about its entity. Facts are how you
supply them. A fact is one (entity, attribute, value); it belongs to the
program, not to a page, so one fact about Acme Router serves every planned
page that names Acme Router. The next pages:generate run builds each
page's matrix or profile from the facts whose entity matches a name in that
page's expansion.entities (case and whitespace are ignored — " acme ROUTER " matches "Acme Router"). A fact for an entity no page names is
kept but never used.
Supply facts — POST /programs/{program_id}/facts. Body:
POST /programs/{program_id}/facts
{
"facts": [ // 1–500 entries
{
"entity": "Acme Router", // required — a name from a page's expansion.entities
"attribute": "Wi-Fi standard", // required — a product attribute, not a search metric
"value": "Wi-Fi 6E", // required — a fact, not a hedge
"source_url": "https://acme.example/specs", // optional — absolute http(s) only
"source_excerpt": "Supports Wi-Fi 6E." // optional
}
]
}
→ 200 OK
{
"program_id": "<uuid>",
"facts_written": 1,
"entities": ["Acme Router"],
"facts": [
{ "entity": "Acme Router", "attribute": "Wi-Fi standard", "value": "Wi-Fi 6E",
"source_url": "https://acme.example/specs", "source_excerpt": "Supports Wi-Fi 6E.",
"origin": "supplied",
"created_at": "2026-09-04T10:00:00Z", "updated_at": "2026-09-04T10:00:00Z" }
]
}
Returns 200 with the facts as stored — read back from the store, not
your request echoed — so facts is exactly what the next generate run will
use; facts is ordered by entity then attribute, and entities lists each
distinct entity once, in the order your request first named it. source_url
is optional on a fact you supply; the platform's own research always carries
one. origin is supplied for your facts and research for the platform's.
Each (entity, attribute) pair is one fact. Sending the pair again in a
later request replaces the value, so a retry converges on the same rows
and this request does not accept an Idempotency-Key — sending one returns
422 rather than being quietly ignored. Sending the same pair twice in one
request is a 422. A fact you supply is never overwritten by the
platform's research for the same entity and attribute; your value wins.
Refused with 422 (string detail, see Errors) when a
value is a hedge — unknown, n/a, not verified, cannot be verified…
and the like; leave the attribute out instead — or when an attribute is a
search-demand metric (search volume, keyword difficulty, CPC): those are not
attributes of the entities on the page. Refused with 422 in the
field-error form when the body is malformed: a blank field, a source_url
that is not an absolute http(s) URL, a duplicate pair, an unknown key, or
more than 500 entries. Refused with 409 while the program is
generating, because that run is reading the facts — retry once it finishes.
Supplying facts does not change any page by itself. A page that reads
generation_state: blocked stays blocked until the next pages:generate
run re-checks it; a page that already has a content item keeps the brief it
was written from. Supply, then run pages:generate again.
Read the facts back — GET /programs/{program_id}/facts. Pages with
limit (1–200, default 50) and offset in the standard
pagination envelope, ordered by entity then attribute; add
?entity=<name> to see one entity's facts (matched the same way pages are; a
blank name is a 422). Both your facts and the platform's research are
listed; origin says which.
An unknown program_id, or one belonging to another organization, returns
404 — never an empty page.
Generating the pages, and downloading them
| Method | Path | Purpose |
|---|---|---|
| POST | /programs/{program_id}/pages:generate | Write the pages you approved |
| GET | /programs/{program_id}/pages | List every page and how far it has got |
Generate — POST /programs/{program_id}/pages:generate. An
Idempotency-Key header is required (absent → 422): this verb bills, so
a retried request must replay the original response rather than write and charge
for the same articles twice.
On the v2 article pipeline, comparison pages carry a factual research requirement for each named product and comparison attribute. The article must find supporting evidence permitted by your brand's source rules. Missing product-specific evidence holds the content kit for review even when automatic brief approval is enabled; it does not count as a completed comparison. Review the kit before approving the write. Researched values do not become trusted facts you supplied. The same product-specific requirements reach the writer and final checker. An incomplete comparison, or one the checker could not assess, remains a draft for review rather than passing as a complete comparison.
POST /programs/{program_id}/pages:generate
Idempotency-Key: <opaque-key> // required
→ 202 Accepted
{ "job_id": "<uuid>", "status": "queued", "program_state": "generating" }
An accepted generation job remains queued until a worker picks it up; closing
the request does not cancel it. Poll GET /jobs/{job_id} until the job reaches a
terminal status, then read GET /programs/{program_id}/pages. Each page gets its own generation job behind
the scenes, so pages become downloadable one at a time rather than all at once.
A completed generate job carries a summary in result:
{
"job_id": "<uuid>",
"status": "completed",
"result": {
"program_id": "<uuid>",
"approved_pages": 500,
"approved_pages_unread": 0,
"pages_materialized": 480,
"pages_dispatched": 480,
"pages_already_generated": 20,
"pages_refused_unapproved": 0,
"pages_failed": 0,
"pages_quota_exceeded": 0,
"pages_skipped_missing_inputs": 0
}
}
approved_pages_unread is how many never-generated (or soft-deleted) approved
pages sat past this run's dispatch ceiling — re-run pages:generate to drain
them. pages_already_generated counts live pages that already had a content
item (safe no-ops). pages_quota_exceeded counts pages whose per-page
generation dispatch was refused because the monthly content allowance was
exhausted mid-run — distinct from pages_failed (crashes / unavailable).
pages_skipped_missing_inputs counts approved pages the stage declined to
write because a structured input it needs was not available — a comparison
page with no usable attribute matrix (supplied or researched) or an
entity_review page with no supplied facts about its entity (see
Programmatic-SEO templates and Supplying facts about your entities). A
refused page is not a failure and not a charge: it keeps its approved state
and reads generation_state: blocked on GET /programs/{program_id}/pages,
with blocked_inputs naming what is missing, and it is re-checked on the next
run, which writes it once the input is there. Facts reach a page only when it
is written — a page that already has a content item keeps the brief it was
written from. The job reaches completed either way, so compare
pages_dispatched against approved_pages rather than reading a terminal
status as a full yield. Research authorization or configuration failures fail
the generation stage instead of being counted as missing facts. Until the run
finishes, result is an empty object.
- On the v1 pipeline every page this verb writes carries its citations inline.
(On the v2 article pipeline, the default for new drafts, a program page follows
the organization's
default_citation_modelike any other draft; abottom_onlybody still ends with its numbered## Sourceslist.)pages:generatetakes no request body, and every v1 page it writes is generated withcitation_mode=inline: the writer's[anchor](https://source…)links stay inmarkdown_body, and a numbered## Sourcessection is appended whenever the page resolved any citations. A program page is published body-and-nothing-else, so a body that named its sources without linking them had no second surface to recover them from — that is why this path pins inline rather than the item verb's ordinary clean-prose default. A generated page'scontent_item_idis still an ordinary content item forPOST /content/items/{item_id}/generate: an explicit mode you send there wins, and omitting the field on a program-owned item keeps the inline body this verb wrote (see the 2026-08-29 Changelog entry). Ordinary (non-program) items that omit the field still get the clean-prose default. See Inline citations (notation) for the exact notation and?include=sourcesfor the same citations as machine-readable metadata (?include=assertion_provenanceadds the generation-time per-assertion receipt, which survives structured-only rendering). - Only pages you approved are written. A
declinedpage and a page you have not decided on both produce nothing. Approve at least one page first — with nothing approved,:generatereturns409. - Quota is preflighted after startability. If the program is missing, has
no approved pages, or is already in flight / not allowed to enter
generating, you still get404/409even when the org is over quota. Only when the stage is otherwise startable and the monthly content-generation allowance is already exhausted (and overage is not enabled) does:generatereturn429with{"detail": "The monthly allowance for this resource is exhausted."}before the program entersgenerating. CheckGET /accountfor remaining allowance. If allowance runs out mid-run, remaining pages are counted inresult.pages_quota_exceededrather than a generic failure counter. - Re-running is safe. A page that already has a live
content_item_idis never written a second time, so a retry — or a run days later — adds only pages that are genuinely new. A page whose content item you soft-deleted (generation_state=content_deleted) is rematerialised on the next generate run (new brief + content item); the deleted item and its versions stay for audit. - While the stage runs the plan is frozen. Approving, declining or adding a
page while the program is in
generatingreturns409.
Read the pages — GET /programs/{program_id}/pages. Same pagination and
?state= filter as the plan read, plus two fields:
{
"id": "<uuid>",
"program_id": "<uuid>",
"title": "Card A vs Card B",
"template_family": "comparison",
"state": "approved",
"content_item_id": "<uuid>",
"content_status": "draft",
"generation_state": "ready"
}
generation_state is one of:
| Value | Meaning |
|---|---|
not_approved | You have not approved this page, so it will not generate |
awaiting_generation | Approved and queued |
generating | Being written |
ready | Finished — download it |
content_deleted | You deleted this page's content item. The page still names the old content_item_id, but GET /content/{content_item_id} returns 404. Re-running POST …/pages:generate rematerialises a new content item (and clears the dead back-link); the deleted item and its versions stay for audit |
blocked | Approved, but the last generate run declined to write it because a structured input it needs was not available (an attribute matrix covering every compared entity for a comparison page; supplied facts about its entity for an entity_review page). The page keeps its approval and has no content item. Supply facts for the entities the page covers and run POST …/pages:generate again; the next run writes the page, blocks it again, or clears the marker. Stable between runs. listicle pages are never blocked |
Download a finished page — GET /content/{content_item_id}. The
versions field is a PublicPage envelope (items, total, limit,
offset, has_more, next_cursor) — not a bare array. This changed on
2026-08-11 and is breaking against the former full array; see the
Changelog. Page with the standard public bounds (?limit= 1–200,
default 50; ?offset=) — newest first. Read versions.items for the
window, versions.total for the full history count, and versions.has_more
to know whether another page exists. For page-by-page download pass
?latest_only=true to get just the current version, or ?version=N to pin
one. Those two are mutually exclusive (422), and an unknown version
number is a 404.
GET /content/{content_item_id}?latest_only=true
RoboWrite never publishes a program page for you. The program cycle does
not read publish_policy. Both policies produce the same program terminal
states; policy only affects an optional later POST /content/{id}/publish and
topic-autopilot (POST /content/generate). The generate stage starts content
generation and stops there — under either publish policy it never hands a
finished page to your CMS. generation_state=ready means the page is written
and downloadable, not that RoboWrite made it live anywhere.
This is a guarantee about RoboWrite, not about your CMS. It bounds what this product does; it cannot bind your destination. A page can still become live without any call to this API — a scheduler or workflow in your CMS, an automation on the property, or a person in the CMS admin. It has happened: a program run's pages went live and were indexed on a customer property about an hour after creation, while this API still reported them as drafts.
Two consequences worth planning for.
statusandpublished_urlare RoboWrite's own record, not a live read of your CMS —status: "draft"means we did not publish it, not that the URL is dark, so treat your CMS and yoursitemap.xmlas the authority on what is live. And if you find a page you did not mean to ship,POST /content/{item_id}/publishwith"mode": "unpublish"tears the remote document down again.
To publish a page, call POST /content/{item_id}/publish for it. Under the
default cms_publish policy that enqueues the publish to your connected CMS. If
the page's property uses publish_policy=draft_only the same call returns
409 because there is no destination — for those properties the download
above is the intended last step.
The headless shape, end to end. Because the program cycle never consults
publish_policy, a program needs no particular policy — you neither have to
pick one when you create the property nor replace a property you already have.
Each approved page's generation job reaches completed, the page reads
generation_state: "ready", and you download it. Program pages run the plain
content-generation workflow, which has no publish gate: a program page never
reaches awaiting_review, never terminates at ready_for_export (see
Asynchronous generation — that is a topic-autopilot outcome), and
generating one never parks anything in a dashboard inbox for a human to clear.
The policy's only effect on a program is the answer to
POST /content/{item_id}/publish described just above.
Bulk export is not available yet. Download is page-by-page in this release — see Not in v1 yet.
Taxonomy (full CRUD)
| Resource | Paths |
|---|---|
| Pillars | GET/POST /pillars · GET/PATCH/DELETE /pillars/{pillar_id} |
| Audiences | GET/POST /audiences · GET/PATCH/DELETE /audiences/{audience_id} |
| Authors | GET/POST /authors · GET/PATCH/DELETE /authors/{author_id} |
| Categories | GET/POST /categories · GET/PATCH/DELETE /categories/{category_id} |
| Tags | GET/POST /tags · GET/PATCH/DELETE /tags/{tag_id} |
Taxonomy create errors. POST /categories, POST /tags, POST /pillars, and POST /audiences all accept a brand_id in the request body. If that brand_id is unknown or does not belong to the org tied to your API key, the call returns 404 Not Found rather than a 500 — treat it the same as any other not-found resource.
Slug-rename conflicts. PATCH /categories/{id} and PATCH /tags/{id} accept an optional slug field. If the new slug is already in use by another category (or tag) within the same brand, the call returns 409 Conflict. Choose a different slug and retry.
Explicit null on a PATCH. Every PATCH field is optional, and an omitted key is left unchanged. An explicit null clears a field only when that is a real operation; otherwise null is rejected with a 422 — omit the key instead.
| Resource | null clears | null → 422 |
|---|---|---|
| Authors | email, bio, avatar_url | name, slug, status |
| Categories | description, parent_id, icon, color | name, slug, sort_order, status |
| Pillars | description, keywords, target_audience, business_goal, target_audience_ids | name, goal, status |
| Audiences | description, decision_role, sophistication_level, technical_depth, goals, pain_points | name, status |
| Tags | — (both fields are required on the row) | name, slug |
The rejected keys are published as non-nullable in the OpenAPI schema, so a generated client will not offer null for them at all.
goal and status on a pillar reject null even though they look optional on write: both are required and non-nullable on the pillar response, so a stored null could never be read back honestly. status on authors and categories already rejects null. To empty a pillar's keyword list you may send either [] or null.
Idempotency. All five creates (POST /pillars, /authors, /categories, /tags, /audiences) take an optional Idempotency-Key. A retry of the same body under the same key replays the original 201 (Idempotency-Replayed: true); the same key with a different body returns 409. Without a key a retry creates a second row — these resources have no uniqueness constraint beyond the category/tag slug.
Pillar strategy fields. target_audience and business_goal are free-text. target_audience_ids is the list of audience ids from GET /audiences. IDs that are not audiences of the pillar's brand return 422. Omit a key to leave it unchanged; send null or [] to clear target_audience_ids.
Workspace-scoped plugin workflow. The delegated content grant supports audience list, read and create operations, and pillar list, read, create and update operations. With a multi-workspace grant, use the corresponding /api/public/v2/organizations/{organization_id} paths. Automated pillar strategy generation saves its results. For recommendations, discuss candidates and editorial guidance first, then create each selected pillar with its final fields and audience IDs. The plugin requires an idempotency key for each create. You can edit a saved pillar from either workflow using the same pillar ID and use that ID when creating a topic.
Documents & imported content (read)
| Method | Path | Purpose |
|---|---|---|
| GET | /documents | List the document library (filter by category, status, q) |
| GET | /documents/{document_id} | Get document metadata and summary |
| GET | /imported-content | List imported / external content |
| GET | /imported-content/{content_item_id} | Get an imported content item |
Roadmap note. Orgs can now trigger CMS content imports from the app (Settings → CMS); once an import runs, these existing
/imported-contentendpoints simply start returning the imported items — no request or response contract change.
Article templates
| Method | Path | Purpose |
|---|---|---|
| GET | /article-templates | List built-in article presets and organization templates |
| GET | /article-templates/{template_id} | Read a preset by built-in key or organization template UUID |
Article presets are separate from Programs. The built-ins are standard, listicle, how_to, and comparison. Lists return {items, has_more, offset, limit} with built-ins first, then organization copies; limit defaults to 50 (maximum 200). Use include_archived=true to include archived copies; detail reads include them. A missing or foreign UUID returns 404. These read-only endpoints do not apply a preset to a brief or start generation.
Programmatic-SEO templates
| Method | Path | Purpose |
|---|---|---|
| GET | /program-templates | List the template families a program can be built from |
A template family is the page archetype a programmatic-SEO program builds. Three are available, all first-party:
family | What it produces | expansion_unit | entities per page |
|---|---|---|---|
comparison | One page per combination of in-scope entities, lined up against a shared set of attributes | entity_pair | 2 → unbounded |
listicle | One page per facet, ranking a selection of in-scope entities against a stated criterion | entity_facet | 2 → unbounded |
entity_review | One page per in-scope entity, evaluated against a stated rubric and ending in a verdict | single_entity | exactly 1 |
Each entry also carries display_name, summary, and
required_generator_inputs — the structured input kinds a page of that family
is written against (for example a listicle is written against a
facet_definition and a ranking_criterion; a comparison against an
attribute_matrix). They shape the generation prompt for pages of the family.
Two of them are also something you supply: attribute_matrix (comparison)
and entity_profiles (entity_review) are supplied per entity with
POST /programs/{program_id}/facts (see Supplying facts about your
entities); the other kinds shape the prompt only and have no request field.
Those two kinds do one thing more: they gate the write. Before this API
writes a comparison page, it checks that the page has a usable attribute
matrix — at least one attribute with a value for every compared entity — built
from the facts you supplied or the platform researched (a fact you supply
always wins over a researched one for the same entity and attribute); without
one the page is marked blocked rather than written into an empty
comparison table, and counted on the generate job result as
pages_skipped_missing_inputs. Generate-time research uses structured web
search first (schema-shaped {name, value} plus a source URL) and a per-entity
search fallback. The fallback stores a cited snippet excerpt that names both
the entity and the attribute, not a schema-shaped cell; every researched fact
carries an http(s) source URL and is listed on
GET /programs/{program_id}/facts with origin: research. A comparison
page with no usable matrix after supply and research reads
generation_state: blocked. A supplier that built the matrix out of our own
keyword metrics — monthly search volume, keyword difficulty and CPC for the
entity names as search terms — shipped on 2026-08-29 and was withdrawn:
search-demand figures are not attributes of the products on the page, and a
fact whose attribute names one is refused with 422.
The check sits above the write and not above the whole run, so it does not
block recovery: a page whose content item this API already created, but whose
generation job a failed run never started, is re-dispatched by the next
pages:generate rather than blocked. entity_review is gated the same way on
entity_profiles, which only you can supply — the platform does not research
them — so an entity_review page with no supplied facts about its entity
reads blocked until you supply some. listicle declares no gated input and
is never blocked.
What the platform does to the page when the generator finds nothing. These
two mechanisms act on a page the stage has already decided to write, so they sit
behind the gate above: a comparison page does not reach them while that gate
holds, and what follows describes the comparison pages written before
2026-08-29 plus any future page the gate lets through. Both degrade the body
rather than validating anything: the writer is instructed to
cover the comparison in prose and omit the table when it cannot support at least
two attributes, and a table whose every data cell is an admission that we found
nothing (Not established, Unable to verify, N/A) is removed at the end of
generation, before the draft is stored — so a draft can carry a comparison
headline with no table under it.
A table is left alone as soon as one of its value cells carries a real value. Read "value cell" strictly: the first column of each row is the entity label, and a row of real card names beside two hedged cells is still a hedged row — labels are not evidence. A table of nothing but dashes is also kept, on the grounds that in a feature matrix a dash is itself a finding.
Beyond that, the removal works from a fixed vocabulary of hedging phrases, and
phrasings that read as absences but are findings are deliberately kept out of
it — a table whose cells all say Not reported to the credit bureaus, Not disclosed to third parties, No record of a breach, No evidence of adverse effects, Not documented in the public reference, Not verified by the issuer, Not available on the Basic plan, No data caps or Cannot be verified by the issuer survives. That last one is the attribution rule: a
cell that opens with an admission that something could not be checked
(Cannot be verified, Could not be confirmed, Unable to verify, Not verifiable, …) and then says by whom — an issuer, registrar,
manufacturer, vendor, provider, publisher, carrier, lender, bank, agency,
network, operator, insurer, retailer, regulator, airline or company — is read
as a finding about that party's disclosure, while the same opening followed by
us, this page, a source, or nothing (Cannot be verified by us, Unable to confirm by this record, Cannot be verified from public filings, Unable to verify a direct route, bare Cannot be verified) is still a hedge, and so is
a self-reference beside a third party (Cannot be verified by us or the issuer). Read all of that as a vocabulary, not as a judgement about your
subject: it is a list we maintain, not an understanding of what an absence
means in your niche, so a phrasing that happens to open with one of the
remaining hedges is removed even where it was the finding you meant, and an
attribution to a party not on that list is removed too. Ones we know read as
findings and remove the table anyway are No verified … (No verified adverse events) and Not established … (Not established in pediatric patients),
whatever follows them — the attribution rule does not apply to those two; we
have not enumerated the rest. Treat the removal as a floor under diligence theatre
rather than a guarantee about any particular table, and read the list of
required_generator_inputs as a description of the page shape you will get,
not as a promise that the platform checked your data. The platform does check
that a gated input exists before writing a page; it does not verify facts you
supply — they are rendered as supplied.
Reading the numbers. expansion_unit plus entities_per_page_min /
entities_per_page_max is how many pages a given scope will produce, and how
they are keyed. entities_per_page_max: null means the family imposes no
per-page entity ceiling — your program's scope supplies the entity count for
each page. It is not a promise that plan expansion is unbounded: the plan
stage still caps at 50 subjects and 500 pages (see Generate the plan
above).
Not paginated. The response is a plain array. The catalogue is a fixed set,
so there is no limit/offset. If the catalogue cannot be served completely the
call returns 503 rather than a partial list, so a short array is never
something you have to detect yourself.
Nothing here is site-specific. Families describe expansion and generator inputs only — no URL patterns, title templates, or section outlines. Those come from the program you create.
Health
| Method | Path | Purpose |
|---|---|---|
| GET | /ping | Liveness check |
Typical end-to-end workflow
- Discover —
GET /brandsto pick a brand; optionallyGET /brands/{brand_id}/keywordsfor opportunities. - Choose a topic —
POST /brands/{brand_id}/topics(your own input) orGET /topics. - Shape a brief —
POST /briefs(angle, audience, keywords). Refine later withPATCH /briefs/{brief_id}. - Create & generate —
POST /content/items, thenPOST /content/items/{item_id}/generate(orPOST /content/generatefrom a topic, orPOST /content/rewriteto rewrite pasted Markdown). Send anIdempotency-Key. - Poll —
GET /jobs/{job_id}until the status is terminal. - Read & refine —
GET /content/{content_item_id}(?include=scoringfor quality metrics,?include=sourcesfor the research sources cited in each version,?include=assertion_provenancefor the per-assertion provenance receipt,?include=compliancefor regulated-content policy findings);PATCH /content/items/{item_id}to adjust.
Generated body title hygiene. New article-draft versions that run the common
article finalize/export path use versions.items[].title as the page title. When
versions.items[].markdown_body begins with an equivalent ATX H1, generation removes
at most that first duplicate heading; it does not recursively delete a later
H1. A different leading H1 is preserved, and exporter validation cannot rename
the title to that distinct heading or invent a title when finalize produced
none. Imported, older, legacy-DRAFT, rewrite, variation, and refresh versions
may still contain a leading H1. Reads do not normalize stored content.
- Publish — after the draft is ready,
POST /content/{item_id}/publish(see CMS publish below). The item needs either an existing CMS publish target or a human-selected org default destination under Organization settings. If you have no CMS and intend to collect pages over the API instead, skip this step and create the property withpublish_policy: "draft_only"(see Properties).
Cited sources.
?include=sourcesreturns, per version, the research sources actually cited in the generated body assources: [{ marker, source_name, source_url }](ordered by first appearance). It is opt-in and additive: withoutinclude=sources,sourcesisnull; withinclude=sources,sourcesis[]when a version cited nothing or was generated before source capture was available (no backfill). To control whether the published body shows those citations, passcitation_styleon generate for a v2 article draft:bottom_only(prose without links, a numbered## Sourceslist at the end) orinline_only(inline links, no list); omit it to follow the organization'sdefault_citation_mode. On the v1 pipeline the knob iscitation_mode:structured_only(default — clean prose) orinline(keeps inline links + a Sources section). The capturedsourcesmetadata is the same either way.
Request the cited sources for a content item:
GET /content/{content_item_id}?include=sources
{
"id": "…", "title": "…", "status": "draft", "brand_id": "…",
"versions": {
"items": [
{
"id": "…", "version_number": 2, "title": "…", "markdown_body": "…",
"sources": [
{ "marker": 1, "source_name": "Stanford WFH Study", "source_url": "https://stanford.edu/wfh" },
{ "marker": 2, "source_name": "Buffer State of Remote Work", "source_url": "https://buffer.com/state-of-remote-work" }
]
}
],
"total": 1, "limit": 50, "offset": 0, "has_more": false
}
}
Guard on presence, not on null vs [] — treat both as "no sources to show":
const cited = version.sources ?? []; // null = not requested; [] = requested but none/legacy
Combine projections with a comma — ?include=scoring,sources,assertion_provenance,compliance returns scoring, sources, assertion_provenance, and compliance on each version.
Regulated-content compliance.
?include=compliancereturns, per version, the regulated-content policy findings recorded when the org configures regulated industries (finance / healthcare / legal), ascompliance: [{ kind, message, excerpt }].kindis a stable enum —unsourced_figure,advice_tone,off_brand_promotion, ormissing_disclaimer— so you can branch on it rather than parsemessage;excerptis the offending body text for text findings andnullfor structural findings (missing_disclaimer). It is opt-in and additive: withoutinclude=compliance,complianceisnull; withinclude=compliance,complianceis[]for an unregulated org or a clean regulated draft. Findings reflect the shipped body (the generator clearsmissing_disclaimeronce its guaranteed disclaimer footer lands).
Request the compliance findings for a content item:
GET /content/{content_item_id}?include=compliance
{
"id": "…", "title": "…", "status": "draft", "brand_id": "…",
"versions": {
"items": [
{
"id": "…", "version_number": 2, "title": "…", "markdown_body": "…",
"compliance": [
{ "kind": "advice_tone", "message": "Rewrite prescriptive advice tone as educational options and tradeoffs.", "excerpt": "You should move your savings into…" },
{ "kind": "missing_disclaimer", "message": "Add the required finance regulated-content disclaimer…", "excerpt": null }
]
}
],
"total": 1, "limit": 50, "offset": 0, "has_more": false
}
}
Guard on presence, not on null vs [] — treat both as "no findings to show":
const findings = version.compliance ?? []; // null = not requested; [] = requested but none
Generate with inline citations shown in the body:
POST /content/items/{item_id}/generate
Idempotency-Key: <opaque-key>
{ "citation_mode": "inline" }
citation_mode is optional. On an ordinary content item, omit or send null → structured_only (the default clean-prose body). On a program-owned item (one produced by POST /programs/{program_id}/pages:generate), omit defaults to inline so regenerate does not strip the links that stage wrote — see the 2026-08-29 Changelog entry. Non-null values must be structured_only or inline; unsupported strings are rejected with 422. It coexists with direction in the same body. Either way the cited sources are captured and readable via ?include=sources once the job finishes — inline additionally keeps the links in markdown_body and appends a Sources section. On the v2 article pipeline (the default for new drafts) citation_mode does not apply: the body follows citation_style or the organization's default_citation_mode (see the 2026-11-08 Changelog entry).
Idempotency note: a same-key retry replays the original job, so a retry that changes citation_mode under the same Idempotency-Key will not start a new generation with the new value. Use a fresh key when intentionally changing generation options.
CMS publish
POST /content/{item_id}/publish enqueues a publish (or schedule) of a live content item to the org's connected CMS. CMS connections are configured in the dashboard. Publish targets may already exist on the item, or — when the item has none — this endpoint can provision one from the org's human-selected default publish destination (Organization settings). It never invents a CMS collection.
Prerequisites
- The content item exists, belongs to the API-key org, and is not soft-deleted (otherwise
404). - The item's property is not
draft_only. Adraft_onlyproperty means RoboWrite publishes nowhere for it, so this endpoint returns409before touching any destination — collect the page withGET /content/{content_item_id}instead, or switch the property tocms_publish(see Properties). An item with no property is unaffected by this check. - A resolvable CMS destination:
- Exactly one existing publish target on the item → use it.
- No target, but a valid human-selected default destination is set under Organization settings (and matches a valid publish profile) → provision a target for the item and publish to it.
- No target and no valid default →
409(set a default destination under Organization settings, or map the item to a CMS collection in the editor). - More than one target →
409(destination is ambiguous; keep a single active target, then retry). This surface does not accept atarget_idand will not pick a CMS for you.
Body
POST /content/{item_id}/publish
{
"mode": "live", // required: "draft" | "live" | "schedule" | "unpublish"
"schedule_at": "2026-08-01T15:00:00Z" // required only when mode=schedule; must be timezone-aware and in the future
}
draft— push as a CMS draft.live— publish immediately on the remote.schedule— publish atschedule_at(required, future, timezone-aware). Sendingschedule_atwith any other mode is422.unpublish— tear the remote document down again. Use this when a page is live that you did not mean to ship, including one this API never published (see Programs — your CMS can publish without us). After the job reaches a successful terminal for a teardown this API confirmed (the remote document was removed, or it was already gone),GET /content/{item_id}returnspublished_url: null. Ifstatuswaspublished, it becomesdraft. Other statuses are left alone. A no-op (RoboWrite has no remote document recorded) does not change those fields.- Unknown keys (including a client-supplied
triggered_by) are422.
unpublish skips both publish-readiness prerequisites, because they gate creating a remote document and this mode only removes one:
- Prerequisite 2 does not apply:
unpublishworks on adraft_onlyproperty. That policy says RoboWrite publishes nothing there — which is exactly where a page you never meant to publish is most surprising and most worth removing. - Prerequisite 3 does not provision: an item with no publish target returns
409rather than provisioning your default destination, because linking a CMS is the opposite of what the call asked for. If the page is live on a CMS RoboWrite has no target for, remove it in that CMS directly.
Prerequisite 1 (live item → otherwise 404) and the ambiguous-target 409 apply to every mode, unpublish included.
Response — 202 Accepted:
{
"job_id": "<uuid>",
"was_duplicate_lookup": false,
"scheduled_at": null
}
Poll GET /jobs/{job_id} until terminal. Exactly-once: a retry of an already-enqueued publish for the same item/version/mode returns 202 with the original job_id and "was_duplicate_lookup": true — it does not enqueue a second publish and is not a 409. Clients may retry freely.
When mode=schedule, scheduled_at echoes the resolved schedule time. Readiness or schedule validation failures from the publish pipeline return 422 with { "detail": "…" }.
Topic generation for headless integrators
This is the end-to-end recipe for an integrator with no CMS connected: create topics, generate article drafts from them over the API, and collect the finished pages yourself. It assembles behavior documented elsewhere in this guide into one walkthrough. The throughput figures in it are current operating values, not guarantees — they describe today's capacity and will change as the platform is scaled.
1. Point generation at a draft_only property
Every topic-autopilot run (POST /content/generate) is bound to one publishing property, and that property's publish_policy decides what happens to a finished page (see Properties). With no CMS connected, the two policies behave very differently:
cms_publish(the default) — a finished run has nowhere to auto-publish, so it parks inawaiting_reviewand waits for a dashboard decision. That is the opposite of headless.draft_only— RoboWrite publishes nowhere: a clean finished run reportscompleted, you collect the page withGET /content/{content_item_id}, andPOST /content/{item_id}/publishanswers409because there is no destination to publish to.
Create the property with publish_policy: "draft_only" (POST /properties requires brand_id, even in a single-brand organization), or switch an existing property with PATCH /properties/{property_id}.
Then make every run land on it. POST /content/generate resolves the property in this order (see Choosing the property): the property_id you send; otherwise the organization's default_property_id when it is active and on the topic's brand; otherwise the brand's only active property; otherwise 409. Two ways to make that deterministic:
PATCH /org/settings
{ "default_property_id": "<property-uuid>" }
or send the property on every call:
POST /content/generate
Idempotency-Key: <opaque-key>
{
"topic_id": "<uuid>",
"property_id": "<uuid>"
}
The organization default is a single value for the whole organization and covers only topics on its own brand — in a multi-brand or multi-property organization, send property_id explicitly for the brands it does not cover. A topic that already has generated content keeps that content's property: a later run adds a version to the same content item, so a property_id that differs from that item's property returns 409 (omit it, or send the item's own).
2. Choose topics the pipeline will accept
Three gates stand between a topic and a started run, and every one of them answers before any charge:
- Autopilot eligibility.
GET /topics?brand_id=…returns each topic'sdecision_bandand aneligible_for_autopilotflag. Onlyauto_brief,light_review, and not-yet-banded topics run;expert_reviewandreject_or_holdreturn409. Select on the flag instead of firing into refusals — a freshly generated topic bank scores many topics ineligible until keyword enrichment has run. - Strict source policy. If the brand's source policy is strict (
GET /brands/{brand_id}/source-policy), discovery only fetches reviewed hosts. A topic whose title and keywords name no reviewed entity (for example an issuer, card or program listed in the policy's reviewed rules) and no reviewed domain returns409whosedetailcontains the tokenno_permitted_sources_for_topic— the one token on this route you can match on. Name a reviewed subject in the topic, or add a reviewed source for that subject withPUT /brands/{brand_id}/source-policy. (A topic markedeligible_for_autopilot: truecan still hit this: the flag reflects the decision band only.) - Property scope. Covered in step 1 — no resolvable property (or an explicit one on the wrong brand) is a
409.
Create topics that name their reviewed subject directly:
POST /brands/{brand_id}/topics
{
"title": "Chase Freedom card protections", // required, 1–500 chars
"primary_keyword": "chase freedom protections", // required, 1–200 chars
"premise": "…" // optional, max 5,000 chars
}
Every topic anchors to one of the brand's active pillars: omit pillar_id and the API auto-assigns the best match, but a brand with no active pillars returns 400 — create pillars (or generate a pillar strategy) first.
3. The call sequence
Generate — POST /content/generate returns 202 with { "job_id", "workflow_id", "status" }. The Idempotency-Key header is optional on this route (the Optional (generation) rule), and the route also deduplicates on its own per topic — see step 4 before deciding how to use keys.
Poll — GET /jobs/{job_id} until the status is terminal (completed, completed_with_errors, failed, cancelled) or awaiting_review. content_item_id and content_version_id populate on the polled job, typically by the time it reaches one of those statuses. draft_only runs that finish cleanly report completed (the internal outcome name for that finish is ready_for_export — never a status value you will read; see Asynchronous generation).
Read the draft — GET /content/{content_item_id}?include=sources for the saved markdown_body plus the research sources actually cited in that version (?include=scoring,sources also adds the quality scores). Topic-autopilot drafts are generated with inline citations: cited claims appear in the prose as markdown hyperlinks plus a ## Sources section at the end of markdown_body, and include=sources returns the same citations as structured data (citation styling options live on the item path, not the topic path).
Reviews — if the job parked in awaiting_review, a review was opened for the saved draft: find it with GET /reviews?content_item_id=…. The draft is already saved and fetchable at this point — the review decides what happens to it, not whether it exists. Decide with POST /reviews/{review_id}/decisions (approve / reject / request_revision), or edit the draft first (POST /content/{content_item_id}/edits) and review the new version. A parked job does not wait forever: if no decision arrives within the review window (currently about 7 days), the job ends completed_with_errors (review_expired) and the draft stays saved and downloadable.
4. Idempotency and re-runs
The full rules are under Idempotency and Re-running after failure; the parts that matter for a batch integrator:
- While a run for a topic is still active (or parked in
awaiting_review), a repeatPOST /content/generate— with your key or without one — returns the samejob_idinstead of starting a second run. - Once that job is terminal (or has been
runningwithout progress for a long time), the same request starts a fresh, separately charged attempt with a newjob_id. "I sent the same key" does not mean "this cannot charge twice": use a fresh key whenever you mean a new run, and reuse a key only to recover a lost202. - Reusing a key with a different body returns
409; a repeat that would replay a run whoseproperty_idorprohibited_phrasesdiffer from yours returns422— mint a new key for changed inputs. - Once a topic has a saved draft, later runs write a new version onto the same content item (no second item), and the keyless per-topic dedupe only absorbs repeats within about a minute — after that a keyless repeat is a fresh charged run, even while an earlier run is still parked for review. If you only want the parked draft, resolve its review instead of re-running.
5. Batch throughput
Current values, not guarantees — capacity is scaled operationally and these figures move:
- Concurrency: about 4 articles generate at once across the platform's content-generation capacity today. Articles beyond that queue.
- Per-article time: roughly 10–25 minutes of active generation (typically 10–17; treat anything under 25 as normal), consistent with Expected latency.
- A 20-topic batch takes about 1.5–2 hours wall clock (5 waves of ~4 × 10–25 min, plus queue churn). Submitting all 20 at once is fine — they queue, they do not fail.
- A queued run still reads
running. The job status does not distinguish "waiting for a generation slot" from "actively generating": expect later runs in a batch to sit inrunningfor tens of minutes before their article starts moving. That is queue wait, not a stall. Set poll ceilings for batch work above queue wait + run time (for a 20-topic batch, hours — not the 30-minute single-run stall guidance). - Daily spend ceiling. Generation is also bounded by a platform-side daily model-spend ceiling. When it is reached, runs fail (a
failedjob — they do not queue) until the ceiling resets at the next UTC day. It is a platform operating property rather than a quota you can read; it is distinct from your plan's content allowance (which returns429and is readable onGET /account) and from the per-minute rate limit. If a whole batch fails late in a UTC day, this is the first suspect.
6. awaiting_review with removed-sentence and coherence notes
Source verification grounds every claim: sentences it cannot substantiate against a fetched, reviewed source are removed from the draft before it is saved. When the removals are heavy or leave text that no longer reads coherently (a sentence that pointed at a removed one, a truncated span), the run does not fail — it saves the draft and holds it: the job parks in awaiting_review with content_item_id / content_version_id populated, and the dashboard review card names how many unsupported sentences were removed and lists the coherence issues found after removal.
What it means for you: the draft needs an editor pass before publication. It is shorter than its target length (sometimes much shorter), and the seams where sentences were removed can read broken. Over the API:
- read the saved draft and its surviving citations with
GET /content/{content_item_id}?include=sources; - run an explicit quality check with
POST /content/{content_item_id}/checksand read the persisted card withGET /content/{content_item_id}/review-card(check types includeunverified_claimsandmissing_sources); - fix the text with
POST /content/{content_item_id}/edits(orPOST /content/{content_item_id}/rewritesfor an in-item AI rewrite), then resolve the review withPOST /reviews/{review_id}/decisions.
A held draft is a normal outcome, not an error: the run did its job by refusing to ship ungrounded claims. Do not blind-retry the topic expecting a cleaner draft — a re-run is a fresh charged generation that goes through the same verification, and writes a new version onto the same content item.
Not in v1 yet (roadmap)
These are deliberately out of v1 — design accordingly. Everything listed here is absent, not merely undocumented: if you need one of these behaviours today, the workaround beside it is the whole answer.
- Completion webhooks — generation completion is poll-based today (
GET /jobs/{job_id}); there is no callback/push delivery in v1, so design around polling. Push webhooks are planned. - Editing a program idea or a planned page —
PATCH /programs/{program_id}/ideas/{idea_id}andPATCH /programs/{program_id}/plan/{page_id}are reserved paths that always return501. They exist so the URLs are not claimed by something else later; they do nothing today and no request body makes them work. Edit-before-approve is deferred to a future milestone. Workaround: decline the row and add a corrected one (POST .../ideas/POST .../plan), which is why both add-verbs accept your own title and keyword. - Bulk export of program pages — download is page-by-page (
GET /content/{content_item_id}, ideally with?latest_only=true). There is no archive endpoint and no multi-item download. - Direct document file download URLs — document metadata and summaries are available; original-file signed URLs are not yet exposed.
- Public CMS connection / target management — connect a CMS and choose the default publish destination in the dashboard; the API publishes against an existing single target or provisions one from that human-selected default (it does not expose connection setup or collection discovery).
Changelog
Every change an integrator can observe, newest first. Breaking marks a change that can break a client written against the previous shape — see Versioning and stability for the policy these entries implement.
2026-11-22
-
Additive. A supplied kit claim can include
source_check_failurewhen its source could not be fetched. The detail identifies the observed failure and includes the HTTP status when available. Both adding a fact and reopening its kit return the claim. Earlier checks have no recorded detail. -
Behavior: website-link locale is captured on brief save. The versioned link export returns the locale from the pinned brief. Refreshing the website index between the editor’s save and generation no longer changes the exported locale. Older briefs may have no locale recorded.
2026-11-21
- Additive: version-bound website links are readable.
GET /content/items/{content_item_id}/versions/{version_id}/relevant-linksreturns{ version_id, links }for one saved generation version. Each link carries the published fields (id,url,anchor,usage,requirement) pluslocale, the locale the website index carried for that URL when the version was generated. The locale is frozen on the version, so a later website refresh changes future suggestions but never a saved draft.linksis[]when the version has no website-index links; an unknown version or an item you do not own is a 404. The same read is available as the MCP toolget_version_relevant_links_v2. The published article spec is unchanged — this is a dedicated surface, not a field added to the closedRelevantLinkSpec. Migrating: nothing required; existing clients keep their current contract.
The dated record starts at 2026-07-18, when the public OpenAPI schema was first published as a committed artifact. The 2026-07-01 awaiting_review line below is a pre-artifact exception, kept so the review-state rename is not lost; it is not a claim that July 1–17 is itemised.
2026-11-20
- Behavior: a trialing organization has the entry plan's quota. While an organization's subscription is in its trial, every metered and static limit is the lower of the trialed plan's value and the Solo plan's, and metered overage is off.
GET /accountreports the capped amount as each resource's included allowance (quota.resources[].limit) withoverage_enabled: false. A metered resource returns the existing429once usage passes the capped limit by the same grace margin a paying plan gets (an applicable per-organization override still adjusts the threshold), solimitis the included allowance, not the exact refusal point. The plan's own limits apply once the subscription is active. No request or response shape changes. Recorded in AD-0186. Migrating: readGET /accountfor the current quota instead of assuming the plan's published limits during a trial. - Additive:
GET /jobs/{job_id}names the findings that held a saved draft. Newreview_holds(kind,text; at most 50) lists what to check when a draft was saved but held for review, for examplecite_lint/fetch_failed: <url>when a cited page could not be read. A held rewrite, refresh or variation now also reportschecker_review_holdinreview_reasons; before, its poll showed onlycompleted_with_errors. Behavior: when a rewrite, refresh or variation checks its own cited sources and plain HTTP reads no text (a page that renders in the browser, or a bot check in front of it), up to three of those pages are read once more through a rendering browser, as supplied fact URLs already are, so fewer existing official sources are held asfetch_failed. Migrating: nothing required; the new field is additive. - Behavior:
## Sourceslines of a v2 draft are linked labels. A newly generatedbottom_onlyarticle body lists each source as one Markdown link,n. [label](<url>), instead ofn. host — <url>with the URL as visible text. The label is the publisher and page title when research found one (American Express — What is a statement credit?), otherwise the host and a topic read from the URL path; two pages from one publisher get different labels.?include=sourcesreturns the same label as each source'stitle(it was empty for v2 drafts). Numbering, order, destinations andassertion_provenanceare unchanged, as areinline_onlybodies and every draft saved earlier. Migrating: read sources from?include=sourcesrather than parsing the list; a client that does parse it must accept both line forms. - Behavior: brief outline items must be headings.
POST /briefsandPATCH /briefs/{brief_id}now refuse anoutlineitem written as an instruction rather than a heading: one with a semicolon, more than one sentence, or a sentence ending in.that opens with a writing direction ("Show two examples. Link the Delta article."). Each item becomes the article's H2 word for word, so such items were printed as reader-facing headings. The refusal is a422withdetail.code: "outline_item_not_a_heading"anddetail.details.items(index,item,issue:semicolon/multiple_sentences/directive_sentence); nothing is saved. Questions and ordinary titles are unaffected. This in-version refusal is a bug fix recorded in AD-0185. Migrating: move writing directions fromoutlinetomust_coverornotes, and keep each outline item a short topical heading. - Additive: RateLimit response headers. Every counted response other than an unhandled server-error
500now carriesRateLimit-Policy,RateLimit,RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset, including the429, which keepsRetry-After; Starlette's outer error middleware sends an unhandled500before these headers are added. The OpenAPI document declares them on the existing 2xx and 429 responses of counted operations; the counted Programs PATCH operations publish only 403/422/501 and have no declaration. The limit itself is unchanged. See Rate limits. Migrating: nothing required; read the headers to pace requests. - Additive: the OpenAPI document is served at
https://www.robowrite.ai/openapi.json. It is the same document the/api/referencepage renders, so agents and client generators can fetch it directly. Twenty operations that had only a summary (audiences, authors, pillars, categories, tags, organization settings and the pillar-strategy poll, plus their organization-scoped mirrors) now carry a description. Contract documentation only: no path, field, status code or behaviour changed. Migrating: nothing required.
2026-11-19
- Behavior: supplied fact URLs on browser-rendered pages can now verify. When
POST …/kit/facts(and brief facts at generation) reads no text from asource_urlover plain HTTP, because the page renders in the browser or shows a bot check or login wall first, the page is read once more through a rendering browser. More official pages now verify and are cited, and such a request can take up to about 40 seconds. Migrating: nothing required. - Behavior: kit claims now record
supplied_urlandsource_check. Facts you add to a kit (and brief facts at generation) keep the URL you supplied and why it is or is not cited on the claim itself, so a laterGET …/kitshows it. Facts added earlier still read null. Migrating: nothing required. - Additive: map supplied kit facts to sections and see why a fact URL is not cited.
POST /content/items/{item_id}/kit/factsaccepts optionalsection_ids; a mapped fact counts as those sections' evidence and keeps them specific. The response addssource_check. Every kit claim addssection_ids, plussupplied_urlandsource_check, which read as null until a later release records them.evidencesections addcited_claim_ids,uncited_claim_idsandsource_urls;evidenceaddsunmapped_claim_idsandunplaceable_claim_ids. New 422section_not_in_outline. Behavior: when a fact names something mid-sentence, a word capitalised only because it starts a sentence is no longer a name its page must repeat, so more supplied URLs verify. Figures, mid-sentence names, your products and reviewed source names are still required, and a fact that names nothing else still needs its leading name. Migrating: nothing required; every new field is additive. - MCP behavior: connector 0.9.0 adds
section_idstoadd_kit_factand the new fields to kit results. Refresh the client's tool catalog after upgrading. - Additive: exclude a source domain from a content kit, and read the evidence left.
POST /content/items/{item_id}/kit/source-exclusionsremoves every kit source on a domain and its subdomains. Their claims and the components built from them leave the kit, sources are rebuilt, and a section left without cited claims is kept general. Every kit response gainsevidence(sections,unmapped_claim_count,source_count,min_sources,unmet_requirements), computed from the current kit. See Excluding a source domain and Evidence under Content kits. Migrating: nothing required; the new field is additive. - MCP behavior: the connector adds
exclude_kit_sourceunder the existing content grant, and kit tool results carryevidence. Refresh the client's tool catalog after upgrading.
2026-11-18
- Additive: synchronous provider-work
403. A request that would run paid provider work synchronously can return403witherror: "MCP_ACCEPTANCE_SYNC_SPEND_REFUSED"(body{error, message, details}, nodetail) when your organization's paid work may run only as background jobs, or when its state cannot be verified at that moment. Nothing is charged. Request and success response formats are unchanged. Migrating: treat it as non-retryable for the same call; use the asynchronous routes. - Fix: held runs read
awaiting_reviewin every job read.GET /jobsitems and a content item'slatest_attempt(GET /content,GET /topics/{topic_id}/content,GET /content/{content_item_id}) now reportawaiting_reviewfor a finished generation that is holding its content kit for review, matchingGET /jobs/{job_id}. Before, those reads showed the storedcompleted. A run still in progress readsrunningin these lists; pollGET /jobs/{job_id}for its review state. TheGET /jobsstatusfilter,totaland paging still use the stored status, so a held run matchesstatus=completed, notstatus=awaiting_review. No fields changed. Migrating: nothing required; a client that treatedcompletedwithout acontent_version_idas "held" can branch onawaiting_reviewinstead. - Fix: a brief with no tone reads back
tone: null.GET /briefs,GET /briefs/{brief_id}and the brief create/update responses no longer show"professional", which is not an accepted brieftonevalue, for a brief whose tone was never set. A tone you set still reads back as sent. Migrating: nothing required.
2026-11-15
- Optional workspace-explicit OAuth: v2 membership/access/selection and existing agent operations use separate all-eligible-workspace consent and an explicit target. Existing v1 credentials and operation contracts remain supported. MCP exposes three organization tools and an optional target argument only when the capability is enabled; selection never changes shared/browser state or starts work.
2026-11-12
-
Fix: delegated job and editorial access. Valid content grants no longer receive an incorrect
403when listing jobs or using the documented review and in-item editing operations. Existing credentials, scopes, URLs and request/response formats are unchanged; no reconnect or migration is required. -
Behavior: one running generation per content item.
POST /content/items/{item_id}/generate(MCPgenerate_content_item) now returns409withdetail.code: "article_run_active"while another generation of the same item is still pending, queued or running, for example ahold_for_reviewrun still researching its kit. Nothing is charged and no job is created. Before, a second request with a differentIdempotency-Keystarted a parallel run that rebuilt the kit and, under anautokit mode withbrief_auto_approve, could write without the held kit's review. A retry with the sameIdempotency-Keystill replays the original job. A run that ended (completed,failed,cancelled) or whose kit is held (awaiting_review) does not block: regenerating then replaces the held kit as before. Migrating: nothing required; treatarticle_run_activelike the other generate409codes, poll the running job (GET /jobs?content_item_id=…), then review its kit or retry. -
Behavior: the same rule covers every start for the item. The one-running-generation check now runs for every article start of a content item, not only item generate.
POST /content/{content_item_id}/rewrites(MCPrewrite_draft) returns409witherror: "article_run_active"in the usual{error, message, details}body while another generation of that item is pending, queued or running.POST /content/generatereturns its existing topic-ineligible409(stringdetail) when the topic's existing content item has another generation running; a topic with no item yet is unaffected. Nothing is charged and no job is created; a same-key retry still replays. This in-version refusal is a bug fix recorded in AD-0180 (an exception to AD-0178): accepting the parallel run let it bypass a held kit's review. Migrating: nothing required; on that409, poll the running job (GET /jobs?content_item_id=…) and retry once it ends. -
MCP result contracts: declared output schemas preserve valid object, Markdown and error results; reviewer and draft-section lists now return an
itemsobject instead of failing on valid REST arrays. Hosted OAuth descriptors reflect existing delegated scopes, and Bearer authentication failures carry linking metadata. Server instructions keep their existing text and now participate in the catalog hash. REST contracts, token verification and publication rules are unchanged.
2026-11-11
- Compatibility policy: breaking changes require a new API path or MCP tool version, retaining the existing contract. Compatible additions can reach existing installations without a plugin reinstall. Baseline updates and package-version bumps cannot waive same-version compatibility. No request or response shape changes in this policy release.
2026-11-08
- Behavior: rewrites, refreshes and variations are checked against their own sources and never edited by the check. The check replaces the earlier source review that could revise the text before saving. A specific fact without an inline link to the text's own Sources list now holds the saved version for review (job warning
article_partial, no auto-publish) instead of being removed or hedged. A check that cannot run still saves no version. Prohibited phrases and regulated-content policy are enforced as before: a prohibited phrase saves no version (content-policy error), a regulated organization's text gets the required disclaimer appended, and regulated-content findings block auto-publish. No request or response fields changed.?include=sourcesand?include=assertion_provenancefor these versions now come from the saved body itself: its Sources list (inline-cited URLs first) and one receipt per inline link to a listed source, with eachsentenceexactly as it appears inmarkdown_body. A link outside the Sources list gets no receipt. Migrating: nothing required. - Behavior + additive: article citation style. On the v2 article pipeline, a new draft's
markdown_bodyfollows the organization'sdefault_citation_mode:bottom_only(the default) keeps the prose free of links and ends with a numbered## Sourceslist (1. example.com — <https://…>);inline_onlykeeps the inline source links and adds no list. Until now every v2 draft kept its inline links.POST /content/items/{item_id}/generateaccepts optionalcitation_style(bottom_only/inline_only) to override the organization setting for that generation;citation_modedoes not affect v2 drafts. On v2 versions, eachassertion_provenancereceiptsentenceis now the sentence exactly as it appears inmarkdown_body(inline links included oninline_only), so it matches the published body by substring.?include=sourcesis the same for both styles. A draft citing more distinct sources thanmax_citations_per_contentis saved for review rather than published. Migrating: nothing required; sendcitation_style: "inline_only"(or set the organization default) to keep inline links. - Behavior: content kits follow the brief's article spec. A required kit element or citation rule the kit cannot provide holds the kit for review, and
review_findingsonGET /content/items/{item_id}/kitcan carry two new shapes:{ element, reason, detail }and{ advisory, element, component_id }(see Article spec findings under Content kits). The kit also takes the spec's FAQ questions first and its source cap. An emptyarticle_specchanges nothing. Migrating: a client that readsreview_findingsshould accept the two new shapes. - Behavior: the v2 article pipeline is on. New item drafts are generated from a content kit.
facts,kit_mode: hold_for_reviewand the kit routes no longer return409article_pipeline_not_v2; that refusal now appears only if the v2 pipeline is switched off again. Rewrites, refreshes and variations do not use the content-kit pipeline; their source check is the "rewrites, refreshes and variations are checked against their own sources" entry above. Migrating: nothing required.
2026-11-07
- Additive: content kits, supplied facts and kit review. New routes under
/content/items/{item_id}/kitread a generated item's content kit and edit, approve or reject it (see Content kits).POST/PATCH /briefsacceptfactsand brief reads return them;POST /content/items/{item_id}/kit/factsadds a fact to a kit.POST /content/items/{item_id}/generateacceptskit_mode(auto/hold_for_review).GET /jobs/{job_id}addskit_status,kit_revision,kit_confidenceandreview_reasons, and a job whose kit is held readsawaiting_review.GET /content/{content_item_id}sources and provenance receipts addorigin(research/supplied, ornullwhen unknown), and?include=supplied_factslists URL-less supplied facts. These need the v2 article pipeline, which is the default; if it is switched off,facts,kit_mode: hold_for_reviewand the kit routes return409article_pipeline_not_v2. Migrating: nothing required; new fields are optional and existing responses only gain fields. - MCP behavior: the connector adds the content kit tools (
get_content_kit,override_kit_component,lock_kit_component,remove_kit_component,add_kit_fact,remove_kit_fact,approve_content_kit,reject_content_kit) under the existing content grant;create_brief/update_briefcarryfactsandgenerate_content_itemcarrieskit_mode. Refresh the client's tool catalog after upgrading.
2026-11-06
- Behavior: article generation has a ten-minute time budget. Initial queue time is excluded, and automatic retries share the original deadline. When the time budget expires, an eligible partial is retained for review under the existing publication hold. Otherwise, the job returns
generation_time_budget_exceededand creates no content version; unverified drafts are not saved as verified articles. No response fields changed.
2026-11-04
- Behavior: generated drafts carry an
seo_title. After a generation run saves its draft, the SEO metadata step writes a search-result title of at most 60 characters to the version'sseo_title, unless the version already shows one (its ownseo_title, a metadataseo_titleormeta_title).GET /content/{content_item_id}then returns it inversions.items[].seo_title. Drafts saved before this change, and runs whose step produced no usable title, keepseo_titlenull.
2026-11-01
- Additive: research-start
422on item generation.POST /content/items/{item_id}/generatecan return422withdetail: {code: "allowance_exhausted_byok_required", message, details: {reasons: {<provider>: <reason>}}}when none of your organization's selected research providers can run, and a string-detail503when availability cannot be read. Both come before any charge and start no job. A same-Idempotency-Keyretry of a failed generation returns409when the research it would run changed since the first attempt: your keys, provider settings or limits, or research providers being enabled for your organization (provider order alone is not a change), or503when the limits the first attempt recorded can't be checked right now. In-item rewrites use no research and are unaffected. Request bodies are unchanged. Until research providers are enabled for your organization, the check does not run and item generation behaves as it did. Migrating: treat the new422code as "add a key or adjust your research provider settings", not as a retryable error.
2026-10-30
- Additive: program ideas jobs screen borderline related keywords and report it in
result.relevance_judge. A related keyword scored exactly0.75(matched by only one or two shared words) is now checked for relevance against the program's template family,scope.entitiesand seeds before its market data is fetched, on every template family. One judged off-topic (for exampleaqr capital managementagainstCapital One Venture Xon alisticle) is not written; one judged on-topic keepsrelevance_score: 0.75and arrivespendingexactly as before. The completed job'sresultgainsrelevance_judge(status:applied,partial,failed,unavailableornot_needed, pluscandidates,judgedanddroppedcounts). When the check isunavailableor fails, every eligible keyword is written as before, and the job still completes;is_degradedis alsotruewhen the check was attempted and failed (failedorpartial). Until the check is enabled, runs reportstatus: "unavailable"and ideation behaves as it did. Migrating: nothing to change; a new key on aresultobject is additive and no existing key changed meaning. Expect fewer off-topicpendingideas once the check is enabled.
2026-10-29
- Program ideas on
comparisonandentity_reviewdrop first-word-only related keywords — a related keyword whose only link to a multi-word scope entity or seed is that name's first word is no longer written. Oncomparison, related keywords that are already "X vs Y" are no longer written from research, and any "X vs Y" idea (including a seed or a hand-added idea) is skipped byideas:approve-alland never paired byplan:generate; such ideas now count in the plan job'sapproved_ideas_not_page_bearing, which is no longer always0oncomparison. A "vs" inside one of yourscope.entitiesnames does not count unless it starts or ends the name mid-phrase. No shape change. - Additive:
POST /content/generateaccepts an optionalproperty_id. It selects the publishing property for the run; omitting it keeps the existing resolution (organization default on the topic's brand, else the brand's only active property, else409). An unknown or foreignproperty_idreturns404; one on another brand, or one that differs from the property of the topic's existing content item, returns409. The sameIdempotency-Keywith a differentproperty_idreturns409, and a repeat that would replay a run started on another property returns422. See Choosing the property. - Additive:
GETandPATCH /org/settingscarrydefault_property_id.GETreturns the organization's default publishing property (ornull).PATCHsets it, clears it withnull, and leaves it unchanged when the key is omitted. A property that is not an active property of your organization returns422with a stringdetail. Topic generation uses this default whenproperty_idis omitted and the default belongs to the topic's brand. - Behavior: replay-identity
422s onPOST /content/generateuse the stringdetailform. A repeat whoseprohibited_phrasesdiffer from the run it would replay used to return422with an{error, message, details}body; it now returns{"detail": "…"}like the API's other errors. - Docs:
POST /content/generatedeclares its409and429responses in the published schema. The guide now covers the strict-source refusal (no_permitted_sources_for_topic), property resolution, re-running a topic that already has a draft, and replay identity.GET /jobs/{job_id}has never returned areview_id; the guide no longer implies it does.
2026-10-07
GET /accountaddscapabilities.humanization—{ available, reason }for the optional StealthGPT editorial/style rewrite (release_disabled,not_configured,paused). Additive; no humanization endpoint exists yet.
2026-10-01
- Breaking: briefs are limited to 3500 target words.
POST /briefsandPATCH /briefs/{brief_id}now reject atarget_word_countabove3500with422(the publishedmaximumwas10000). Briefs saved above 3500 before this change read back as3500onGET /briefsandGET /briefs/{brief_id}and generate at 3500 words. Migrating: send3500or less; split a longer topic into several briefs.
2026-09-19
- Additive:
GET /content/{content_item_id}/review-card. Reads persisted checks for the current saved version. It does not start a check or a provider call. Do not sendIdempotency-Key. - Behavior:
POST /content/{content_item_id}/checkspersists version-bound checks. Replay with the same bodyrequest_id. Do not sendIdempotency-Key. Publish of that exact version (draft/live/schedule) returns409until the hard checks exist and pass (EDITORIAL_CHECKS_REQUIRED,EDITORIAL_CHECKS_STALE,EDITORIAL_CHECK_FAILED,EDITORIAL_CHECK_UNKNOWN). Soft brand and score warnings do not block. Unpublish and recall do not require a check card. Approval still records when hard checks fail.
2026-09-15
- Additive: richer brief fields.
POST /briefsandPATCH /briefs/{brief_id}acceptoutline(ordered H2 titles),must_cover,must_avoid,source_urls,example_urls,competitor_urls,notes,cta, andattached_document_ids; all are read back onGET /briefsandGET /briefs/{brief_id}.outlineis stored as structured brief sections.example_urlsis inspiration-only and is never treated as a verified, citable source by generation;competitor_urlsis context only and is not fetched or researched. See Briefs for caps and per-field notes. - Additive:
POST /briefs/{brief_id}/approve. Re-approves a brief, moving itsstatusback toapproved. Does not accept anIdempotency-Key. - Behavior: editing an approved brief re-opens it for review.
PATCH /briefs/{brief_id}on anapproved(orready) brief now moves itsstatustodraftin the same response when the patch touches any field that affects generation — every field above plus the pre-existing content fields. Previously the brief stayedapprovedthrough such an edit. Migrating: if you edit an approved brief and still want it approved, callPOST /briefs/{brief_id}/approveafter thePATCH.
2026-09-13
- Breaking: explicit brand required.
POST /propertiesandPOST /briefsnow require a non-nullbrand_id, including for single-brand organizations. Missing or null input returns422. Migrate by selecting an owned brand fromGET /brandsand sending its ID with every create; primary-brand fallback is removed from these public operations. - Additive: searchable inventory and job recovery. Content and brief lists gain brand/property/pillar/format, creation-date, title/slug and keyword filtering plus linked content/version/job summaries.
GET /jobsdiscovers recent work without a retained job ID, and job reads include timing and resource references. Job type names remain open strings so historical jobs stay readable and exactly filterable.GET /pillarsacceptsbrand_id. - Additive: topic provenance. Brief creation accepts
source_topic_id; a successful topic-aware create/approval records the relationship and topic conversion together. Topic-content reads include this path. Existing links are repaired only when stored IDs establish the relationship. - MCP behavior: new inventory/detail/recovery tools expose these reads under the existing content grant.
create_propertynow sendsdraft_onlywhen policy is omitted. The REST publish-policy default remainscms_publish; explicit values remain supported.
2026-09-06
- Additive: URL brand setup. Start research, review suggestions and confirm one brand through
/brand-setups. Both writes require an idempotency key; retries preserve the original result. Existing active setup and primary-brand state are preserved. - Additive: explicit brand selection. At introduction, property and brief creation accepted optional
brand_idwith primary-brand fallback. The 2026-09-13 breaking change now requires explicit selection. Related resources must belong to the same brand. - Additive: delegated agent authentication. Enabled installations can sign in and consent to organization-scoped content access. API keys remain supported. The published OpenAPI document now explicitly declares Bearer authentication.
2026-09-05
-
POST /programs/{program_id}/planacceptsentities, so a page you add by hand can be supplied instead of stayingblocked. A hand-added page carried noexpansion.entities, and on a family that gates on facts (comparison,entity_review) the generate stage derives a page's inputs by matching supplied facts against that list — with no list there was nothing to match, so the page readgeneration_state: blockedon every run however many facts you sent. From this date the create body takes an optionalentitiesarray naming what the page is about; it is stored as the page'sexpansion.entitiesand matched to facts exactly as a planned page's is. Two spellings of one entity count once (case and surrounding whitespace ignored), blanks are dropped, and at most 50 names of up to 200 characters are accepted. How many a page may carry is the template family's own contract: a count outsideentities_per_page_min/entities_per_page_maxfromGET /program-templatesis refused with422{detail: "This template family does not put that many entities on one page. …"}, which is deliberately distinct from the409returned while the stage that consumes plan pages is running. One documented claim narrows:expansionis no longer empty for every hand-added page — it now carries theentitiesyou supplied, and is empty only if you supplied none. Additive otherwise: omit the field and the verb behaves exactly as before. Supplyingentitiesdoes not lift an existingblockedmarker — that marker is the last run's verdict and onlypages:generateclears it. Migrating: if you addcomparisonorentity_reviewpages by hand, sendentitieson create and then supply facts for those names; if you assertexpansion == {}on a hand-added page, that holds only when you supply no entities. -
Every Programs operation now declares its
403in the published OpenAPI document. Programs has been parked behind an organization allowlist since2026-08-30and this guide has said so, butschemas/openapi.public.jsonand the Scalar reference presented all 22 Programs operations as live happy paths with no403declared anywhere, so a generated client or a coding agent that trusts OpenAPI over prose built against a surface that refuses its first call. From this date each Programs operation declares403with the standard error body, and the document description names the parking. This is contract documentation only: no runtime behaviour, path, field or status code changed, and the403itself is unchanged since2026-08-30. Migrating: regenerate your client if you want the403in its typed error union; nothing else to do. -
POST /programs/{program_id}/facts— supply the facts a program's pages are written from, and a page that still lacks a required input readsgeneration_state: blockedinstead of being silently skipped. Two template families gate the write on a structured input: acomparisonpage needs an attribute matrix covering every compared entity, and anentity_reviewpage needs facts about its entity. From this date you supply both as facts — one(entity, attribute, value)per row,source_urloptional — withPOST /programs/{program_id}/facts(returns200with the rows as stored; the(entity, attribute)pair is the identity, so a repeat replaces the value and the verb refuses anIdempotency-Keywith422), and read them back withGET /programs/{program_id}/facts(paged;?entity=narrows to one entity;originissuppliedfor your rows andresearchfor the platform's). A fact you supply always wins over a researched one for the same entity and attribute, and the platform's owncomparisonresearch is now stored as facts too, so it is visible on the read-back. A hedge for avalue(unknown,not verified, …) and a search-demandattribute(search volume, keyword difficulty, CPC) are refused with422; supplying while the program isgeneratingis a409. Pages you approved are no longer skipped in silence: an approved page whose gated input is still unusable whenpages:generatereaches it now readsgeneration_state: blockedonGET /programs/{program_id}/pages— a sixth value — with a newblocked_inputsarray naming the missing kind (attribute_matrixorentity_profiles). It keeps its approval and has no content item, andpages_skipped_missing_inputsstill counts it. Only a generate run changes the marker: supplying facts leaves the pageblockeduntil the nextpages:generate, which writes it, blocks it again, or clears the marker back toawaiting_generation. Facts reach a page only when it is written; a page that already has a content item keeps the brief it was written from.listiclepages are never blocked.entity_reviewprograms now need facts before they generate: until this date anentity_reviewpage was written from its name alone; from this date one with no supplied facts about its entity isblocked, and because the platform does not research entity profiles only you can unblock it. In the OpenAPI document, theTemplateGeneratorInputandPublicProgramTemplate.required_generator_inputsdescriptions and thepages:generateoperation description no longer say these inputs cannot be supplied;PublicProgramPageGenerationStategainsblockedandPublicProgramPagegainsblocked_inputs(both additive). Migrating: readblocked_inputswhengeneration_stateisblocked, supply the named facts and runpages:generateagain; if you poll forreadyonly, addblockedas a stopping state — it is stable between runs;comparisonruns may now write pages research alone could not, and a supplied fact wins over a researched one; if you generateentity_reviewprograms, supply facts for every entity beforepages:generateor expectpages_dispatched: 0and every pageblocked.
2026-09-04
- A comparison table whose cells attribute an unverified value to a third party is no longer deleted at finalize. The finalize pass that removes an all-hedge comparison table (see Programmatic-SEO templates) matched
Cannot be verified,Cannot be confirmed,Could not be verified,Could not be confirmed,Unable to verify,Unable to confirmandNot verifiableas sentence openings whatever followed them, so a page whose table readCannot be verified by the issuerorUnable to confirm by the registrarin every cell lost that table even though each cell is a finding about who declined to confirm the datum — the same shape as theNot verified by the issuerphrasing kept since2026-08-29. From this date a cell that follows one of those openings with by and a third party — issuer, registrar, manufacturer, vendor, provider, publisher, carrier, lender, bank, agency, network, operator, insurer, retailer, regulator, airline or company, in any number — counts as a value, and a table of them survives. What is unchanged: the same openings followed by us, this page, a source, or nothing (Cannot be verified by us,Unable to confirm by this record,Cannot be verified from public filings,Unable to verify a direct route, bareCannot be verified) are still hedges; a self-reference beside a third party (Cannot be verified by us or the issuer) is still a hedge; an attribution to a party not on that list is still removed; andNo verified …/Not established …still remove a table whatever follows them. This is a narrowing of the2026-08-29widening and it applies to every page the finalize pass runs on, not onlycomparison. Tables removed before this date are not restored — this release ships no backfill — and a page generated from today may keep a table, with its comparison headline above it, that would previously have been removed. Migrating: nothing to change; no request, response or job field was added, removed or retyped.
2026-09-03
GET /content/{content_item_id}gains an opt-in per-assertion provenance receipt. Pass?include=assertion_provenanceto returnversions.items[].assertion_provenance: an array of{ sentence, sentence_index, url, marker }captured at generation time from the inline-linked body before rendering. It stays populated whencitation_mode=structured_onlystrips the links frommarkdown_body— the sentence-level complement to?include=sources. Additive: without the include, the field isnull; with it,[]means the version carries no receipt (legacy version, or a body with no inline citations). Combine with other projections via a comma. Migrating: nothing required; existing clients that omit the include keep the previous shape.
2026-09-02
-
GET /jobs/{job_id}'serror_typevalues are now enumerated in this guide. A new Failure classifications table under Asynchronous generation lists every classification RoboWrite's workflow taxonomy defines, with what each one means and how to handle it — previously the guide named only the handful you meet most often. This is documentation only: no endpoint, field, status code or response shape changed,error_typeis still a string rather than a closed enum, values written outside that taxonomy (save_error,reconciled_failed) still occur, and the standing advice to treat an unrecognized value as retryable-with-backoff is unchanged. Migrating: nothing to change; use the table if you branch on the field. -
Breaking — a content-item
slugis now made unique within the BRAND, not within the property. Previously two properties of one brand could each hold the same slug; storage now enforces one live slug per(organization, brand, slug), and the server suffixes (-2,-3, …) against every property of the brand rather than only the target property. A slug you send toPOST /content/itemsorPATCH /content/items/{item_id}may therefore come back suffixed where it previously came back verbatim. Nothing was renamed, retyped, or removed, and no stored slug changed. Migrating: read the slug from the response rather than assuming the value you sent — the same advice as before, now load-bearing in one more case.
2026-08-31
- Superseded on 2026-09-05 for the “still skipped” clause — a
comparisonpage whose matrix is still unusable after research is now markedblocked, and you can supply the matrix yourself withPOST /programs/{program_id}/facts; the research supplier and the counter still hold.pages:generatecan write acomparisonpage when research returns a usable cited attribute matrix. Generate-time enrichment fills shared product-attribute axes with values that carry anhttp(s)source URL: structured web search first, then a per-entity search fallback that stores a cited snippet excerpt naming both the entity and the attribute (not a schema-shaped cell).A page whose research cannot cite at least one axis covering every compared entity is still skipped and counted asKeyword-metrics axes (search volume, difficulty, CPC) stay withdrawn. No endpoint, field, status code or response shape changed. Migrating: if you generatepages_skipped_missing_inputs— that counter still means a skipped page, not a failure.comparisonprograms, a run may now dispatch pages when research succeeds; still readpages_skipped_missing_inputsbefore treating a short yield as a failure.
2026-08-30
-
Breaking — Programs is parked and returns
403unless your organization is allowlisted.POST /programsand every other Programs verb (/programs…,GET /program-templates) now refuse a caller whose organization is not on an operator allowlist, with{"detail": "Programs is not enabled for this organization."}. The surface stays documented; it is no longer open to every API key while the product has no UI and cannot run a 500-page program. Migrating: if you are not on the allowlist, treat403on those paths as expected. Contact support to be enabled. No field or path was added, removed or retyped. -
A title with accents is no longer mangled into the slug, and titles written outside the Latin alphabet no longer share one stem. Every place this API derives a slug from a title —
POST /content/items,POST /content/rewritesince2026-08-29, and the assignmentPOST /content/generatemakes after it creates an item — collapsed everything outsidea-z0-9to a hyphen. Measured throughPOST /content/rewritebefore this change:Cómo mejorar la conversiónwas stored asc-mo-mejorar-la-conversi-n,Café Crème & Naïvetéascaf-cr-me-na-vet, and如何提高转化率,Продвижение сайтаand日本語のタイトル— three different titles — asuntitled,untitled-2anduntitled-3. What changed. A Latin letter now loses its diacritic instead of its place:Cómo mejorar la conversióngivescomo-mejorar-la-conversion,Marketing für Anfängergivesmarketing-fur-anfanger,Søren Østergaardgivessoren-ostergaard,Straßegivesstrasse,Łódźgiveslodz,Æther Œuvre Þórgivesaether-oeuvre-thor. What we do not do, and you should plan around it: we do not transliterate. Chinese, Japanese, Korean, Cyrillic, Arabic, Hebrew, Greek and Thai titles are not romanised — doing that correctly needs per-script tables, and for Chinese and Japanese a dictionary, that this API does not carry, and a wrong romanisation in a URL you have already published is worse than a neutral one. A title that carries no ASCII letter or digit at all now getscontent-plus ten hexadecimal characters derived from the title itself:如何提高转化率gives the stemcontent-c2eaa9f6b9, the same value onPOST /content/itemsandPOST /content/rewrite, before whatever suffix uniqueness adds. That stem is stable — the same title derives the same ten characters, so it does not drift between items or between the two surfaces — and it separates titles that used to share one: ten hexadecimal characters is a digest rather than a serial number, so two different titles can in principle land on the same stem, and when they do the numeric suffix separates them exactly as it does for a title used twice. It is not readable in the language you wrote the title in. Whatever ASCII a mixed title does contain still survives on its own —如何提高转化率 SEOgivesseo. Atitlethat is empty or only whitespace is unaffected — there is nothing in it to derive from — and keeps the fallback token it had:contentonPOST /content/items,untitledon the create RPCs behindPOST /content/rewriteandPOST /content/generate. Nothing in the wire shape moved: the committed OpenAPI document is byte-identical to the one this release replaced, so no endpoint, field or response schema was added, removed or retyped;slugis stillstring | nullon read, andPATCH /content/items/{item_id}still rejectsnulland""with422. Unlike the change on2026-08-29, this one adds no way for a create to fail, but it moves the exhaustion that entry describes in both directions, and which one you get depends on your titles. It becomes harder to reach for a brand whose titles are written outside the Latin alphabet, because the titles that used to pile onto oneuntitledstem no longer do. It becomes easier to reach for a brand whose Latin titles differ only by their diacritics, because folding is a merge:Cañón,Cañon,CânonandCanonproduced four different slugs before today and all four now derive the stemcanon, so they compete forcanon,canon-2,canon-3where previously they did not compete at all. If your titles look like that, expect more numeric suffixes than before, and read the2026-08-29entry for what happens when a stem's suffixes run out. This release ships no backfill — an item created before today keeps the slug it was given, mangled or shared. Migrating: if your titles are Latin, expect a different (and better) slug on items created from today, and re-read any URL you cached from a create response rather than rebuilding it. If your titles are written in a script we do not transliterate, keepPATCHing the slug you want onto each item before you publish it:PATCH /content/items/{item_id}is the one place this API takes a content item's slug from you — no content-item create body carries aslugfield — and it overwrites the derived value. If you have already published items that share theuntitledstem, we will not renumber them for you;PATCHthe ones you care about.
2026-08-29
-
ideas:generatewrites related keywords that name a subject only by the word it starts with — a net widening; read it against your own scope. Every rule above this one needs a subject's whole name, or at least two of its words, so on a scope of brand-plus-product names (Chase Ultimate Rewards,Southwest Rapid Rewards) a keyword such aschase points transfer partnersorsouthwest companion pass promotionscored 0 and was dropped before it became an idea — neitherideas:approve-allnorPOST .../ideas/{idea_id}/approvecould reach it, because there was no row. Both are now written withrelevance_score: 0.75. Under this new rule (other rules could already award 0.75 and are unchanged) a keyword reaches it only when all four of these hold: it carries the first word of one of your subjects (a subject of two words or more); it has at least three content words; it shares no more than that one word with any single subject; and it does not open one of your subjects' words out into a longer one. Worked examples against the scope above that are still dropped:capital one venture x(two words ofCapital One Miles),one way award flights(oneis the second word ofCapital One Miles, not its first),rewards credit card annual fee(rewardsstarts none of those subjects),points transfer partners(no subject's first word in it),chase points(two content words),hedge fundraising for nonprofits(opensfundout into a longer word — measured against aHedge Fundsubject, as isreal estate broker vs agent, which holds two words of aReal Estate Syndicationsubject). What is unchanged: this is the last rule checked, so any keyword that already matched an earlier rule keeps the score that rule gave it;ideas:approve-allstill takes only high-confidence ideas and 0.75 sits below that floor, so nothing this rule writes is auto-approved — these ideas arrivependingand you approve them one at a time withPOST .../ideas/{idea_id}/approve; no request, response or job field was added, removed or retyped; this release ships no backfill. A cost worth knowing: the first-word rule reads your seeds as well as yourscope.entities, and a seed is free text rather than a name — a seed likebest travel credit cardsmakesbesta first word, so a keyword sharing only that word (best mattress 2026) is now writtenpendingtoo. Migrating: expect a largerpendingcount onGET /programs/{program_id}/ideas, and decline what you do not want. -
A CMS publish your CMS refused now reports its own
error_typeinstead ofunknown. When a publish job (POST /content/{item_id}/publish) fails because the destination CMS answered and declined the write without saying why,GET /jobs/{job_id}now returnserror_type: "cms_write_rejected". It previously returned"unknown", which is also what a job that carries no classification at all reports, so a refusal could not be told apart from one. What the value means: the remote was reachable, read the request and refused it, and the wire carried no reason — the discriminating detail is in your CMS's own server log. RoboWrite does not retry this class internally — the publish job fails on its first attempt rather than burning a retry budget; the general "treat an unrecognized value as retryable-with-backoff" guidance under Asynchronous generation still covers values you do not recognise. Migrating: nothing to change unless you branch on the literal"unknown"for a failed publish. No response shape changed and no field was added or removed —error_typeis a string, and the list under Asynchronous generation is examples rather than an enumeration. This is the only failure classification this release re-buckets. -
POST /content/rewritenow gives its source item a slug at creation, so it no longer reads back"slug": null. The intake previously inserted the item with no slug at all; the slug is derived from thetitleyou send, or from the title derived from your Markdown when you omit it. Items created before this date are not backfilled — this release ships no data migration, and neither does the2026-08-30entry above.slugis still published asstring | nullon read, because an item created outside this API can still have none, andPATCH /content/items/{item_id}still rejectsnulland""with422. Three claims in the first version of this entry were wrong; they are corrected here rather than left standing. (1) It described the derivation as "lowercased with non-alphanumerics collapsed to-, and made unique within the brand with a numeric suffix when the same title is used twice". The collapse was accurate; the numeric suffix was not only for repeats. A title with no ASCII letters or digits reduced to nothing and took a shared fallback token, so three different titles in one brand were stored asuntitled,untitled-2anduntitled-3— measured through this endpoint. The2026-08-30entry above replaces that derivation; read it for what a title outside ASCII gets now. (2) It said "No endpoint, field, status code or response shape changed". No endpoint, field or response shape did. But the slug step this entry added can fail — a brand can have used up every candidate this API builds for one title — and that failure is not turned into a4xx: only the not-found and brand/property-scope cases are. The create fails instead of returning its202. Before2026-08-29the intake had no slug step and could not fail for that reason at all. The2026-08-30entry above makes reaching it harder for titles outside the Latin alphabet, which used to pile onto one stem — and easier for Latin titles that differ only by their diacritics, which that entry now merges onto a shared stem. Read it before assuming the risk only went down. (3) Migrating said that if you werePATCHing a slug onto every rewrite item before publishing it, "that step is no longer needed". For a brand whose titles are written in Latin script that now holds. For a brand whose titles carry no ASCII letters or digits it was the wrong way round on the day it shipped, and the2026-08-30entry above says what is true after it. APATCHstill overwrites whatever was derived. -
Superseded again on 2026-09-05 for the “does not apply to them” claim —
entity_reviewis now gated on supplied facts (entity_profiles) and an unusable input marks a pageblockedrather than skipping it;listiclestays ungated. Superseded on 2026-08-31 for the “writes no comparison page” claim — generate-time research can now supply a cited matrix; the skip-when-unusable gate and stranded-page recovery still hold.Two things changed that day. First, the attribute-matrix research added earlier the same day built the page's comparison table out of our own keyword metrics for the entity names as search terms — monthly search volume, keyword difficulty and CPC — and handed them to the writer as the page's verified attributes. Search-demand figures are not attributes of the products being compared, so that supplier was withdrawn rather than relabelled. Until 2026-08-31 nothing supplied attribute values in its place, so an approvedpages:generatewrites nocomparisonpage, and the OpenAPI description that said it always writes one has been corrected.comparisonpage was skipped and counted on the completed job'sresultaspages_skipped_missing_inputs; acomparisonprogram planned and approved as before but its generate run dispatched nothing.Second, a page stranded mid-generation — one whose content item we created before a failed run could start its generation job — is no longer caught by that gate: the gate now sits above the write it was meant to guard, so the next run re-dispatches the stranded page instead of skipping it on every retry. In the OpenAPI document, thelisticleandentity_reviewdeclare noattribute_matrix, so this gate does not apply to them.TemplateGeneratorInputdescription said "a page is still generated when one of them is unavailable … the writer is told to cover the comparison in prose instead of rendering a table it cannot fill", which contradicted this page; it andPublicProgramTemplate.required_generator_inputsnow describe the skip. Thepages:generateoperation description gained the same note. No endpoint, field, status code or response shape changed, and the fiveTemplateGeneratorInputvalues are unchanged. Migrating: if you generatecomparisonprograms, expectpages_dispatched: 0andpages_skipped_missing_inputsequal toapproved_pagesuntil an attribute supplier ships (a run that also re-dispatches a stranded page reports that page underpages_already_generated); the approved pages keep their state and a run that has a matrix for them writes them then. Readpages_skipped_missing_inputsbefore treating a short yield as a failure. Regenerate your client if you surface descriptions to anyone. -
Superseded the same day, for rewrite items, by the
POST /content/rewriteentry at the top of this date.Corrected documentation —That rewrite claim was true for part of 2026-08-29 and is false from the later change: a rewrite item created from that later entry onward stores a title-derived slug. The rest of this correction still holds. A content item'sPOST /content/rewritecreates its source item with no slug.slugcan benull—POST /content/generatecan leavenullif post-create assignment fails, an item created outside this API can have none, and rewrite items created before the later entry were not backfilled.GET /content/{item_id}returns"slug": nullfor those items, and the automaticpublished_urlderivation produces nothing while they have none. No endpoint, field, status code or response shape changed — the four content read schemas (PublicContentItem,PublicContentItemDetail(the create/PATCH response),PublicContentSummary,PublicImportedContentDetail) already publishedslugasstring | null, andPATCH /content/items/{item_id}still rejectsnulland""with422. Only the prose was wrong. ThePATCH /content/items/{item_id}description in the OpenAPI document was reworded to match, so regenerate your client if you surface descriptions to anyone. Migrating: handlenullon generate items and on rewrite items created before this date; do not assume every rewrite item needs aPATCHbefore publish — only those created before the later entry, or any item you read back asnull. -
Superseded the same day by the entry above; read that one for current behaviour.
Additive —The keyword-metrics research this entry describes was withdrawn hours later, so apages:generatemay skip acomparisonpage that still has no usable attribute matrix after research enrichment.comparisonpage is now skipped whatever its entities' metrics say. Kept for the record: for part of 2026-08-29 the stage researched shared attribute axes from keyword metrics for the page's entities between plan and generate, and refused to materialise a comparison page that lacked at least one axis with a verified value for every entity on it. Thepages_skipped_missing_inputscounter that entry introduced is still on the completed job'sresultand still means what it said — a skipped page, not a failure. -
Regenerating a program page without
citation_modekeeps its inline citations.POST /content/items/{item_id}/generateused to fall through tostructured_onlywhenevercitation_modewas omitted — including for content items that came fromPOST /programs/{program_id}/pages:generate, which always writeinline. That silently stripped the markdown links and## Sourcesblock the stage had just produced (the #4680 symptom, reachable by an ordinary regenerate). Omitting the field on a program-owned item now defaults toinline. An explicitstructured_only(orinline) still wins. Ordinary (non-program) items are unchanged: omit still meansstructured_only. Migrating: nothing required if you already sendcitation_modeon regenerate; if you regenerate program pages without it, expect the links to stay. -
Superseded on 2026-09-04 for the attribution example only — a table whose every cell follows one of the epistemic openings below with
byand a third party (Cannot be verified by the issuer) is kept from that date; everything else in this entry still holds. More comparison tables are deleted at finalize than before, and four qualified phrasings stop being deleted. The finalize pass that removes an all-hedge comparison table (see Programmatic-SEO templates) matchedno confirmed,not confirmedandnot verifiedas sentence openings, so acomparisonpage whose table readNo confirmed devaluations,No confirmed blackout dates,Not verified by the issuerorNot confirmed by the registrarin every cell lost that table even though each of those cells is a finding. Those four survive from this date; bareNot verifiedand bareNot confirmedare removed as they were. This release is a net widening — check it against your own tables. A table whose every cell is exactlyInsufficient data,Insufficient evidence,No data,Not applicable,Not documented,Not stated,UndisclosedorUnverifiedshipped before this date and is deleted after it, and so is one whose every cell merely opens withNot established,Not verifiable,Unable to verify,Unable to confirm,Cannot be verified,Cannot be confirmed,Could not be verifiedorCould not be confirmed— a safety matrix readingNot established in pediatric patientsin every cell, and an attribution matrix readingCannot be verified by the issuerin every cell, are worked examples of tables that shipped before and are removed now. The page keeps its comparison headline with no table under it. Migrating: nothing to change — no request, response or job field was added, removed or retyped, and pages generated before this date keep the body they were written with; this release ships no backfill. (TheTemplateGeneratorInputschema description in the OpenAPI document was reworded to say these input kinds are a generation directive rather than a precondition; its five values are unchanged.) -
Superseded on 2026-10-29 for the “always
0oncomparison” claim — approved "X vs Y" ideas now count oncomparison. Additive — the plan job reports how many approved ideas its template family can never page. A completedplan:generatejob'sresultnow carriesapproved_ideas_not_page_bearingalongside the counts it already had. Onlisticleit is the number of approved ideas that name one of yourscope.entities: those are the ranked shortlist every list carries, not pages of their own, so a run that reportsapproved_ideas: 5, pages_expanded: 0andapproved_ideas_not_page_bearing: 5is telling you the approved set holds no facets — previously that was indistinguishable from a failed expansion.AlwaysMigrating: nothing to change; a new key on a0oncomparisonandentity_review, where every approved idea is a page.resultobject is additive, and no existing key changed meaning. -
ideas:approve-allno longer bulk-approveslisticleideas that cannot become pages. On alisticlethe page is the facet; an idea whoseidea_key,titleorprimary_keywordis exactly one of yourscope.entitiesis one of the things each list ranks and never a page of its own.ideas:generateoffers every scope entity back as a subject-sourced idea, and subject-sourced ideas are always high confidence — so this verb approved precisely the ideas the plan stage refuses, and the facets beside them stayedpending. On a program whose research produced no facet above the high-confidence floor that left an approved set that expands to nothing. Those entity ideas are now leftpendingonlisticleprograms, whatever theirrelevance_score. What is unchanged:comparisonandentity_reviewapprove exactly what they did before (every subject is a page there); on alisticle, a seed or related keyword that names no scope entity is a facet and is still approved; declined ideas are still never touched; the response shape is the same counts object. Migrating: if you relied onapprove-allto approve yourlisticlescope entities, approve them individually withPOST .../ideas/{idea_id}/approve— but note they still do not become pages, because a bare entity name is not a facet. Expect a largerpendingcount onlisticleprograms. -
Items whose teardown this API confirmed before 2026-08-28 have stopped advertising the URL they used to live at. The
2026-08-28clarification below — a confirmedunpublishclearspublished_urland movesstatusoffpublished— applies to teardowns from that date onward, because the record it reads is append-only. Items torn down earlier kept the stored URL, soGET /content/{item_id}went on returning a link to a page that was gone, and re-sending"mode": "unpublish"did not repair them: with no remote document left to remove, that call is the no-op described below, which deliberately changes nothing. Those older records have now been corrected in place. Which ones changed: an item whose teardown this API confirmed (the remote document was removed, or it was already gone) and that has not been published live again since now returnspublished_url: null, and if itsstatuswaspublishedit is nowdraft. Which ones did not: a teardown that was only a no-op, an unpublish job that failed, an item published live again after the teardown, and an item already storing no URL — all keep thepublished_urlandstatusthey had. Other statuses are untouched, and an item'spublished_atis unchanged. One side effect worth knowing: a repaired item'supdated_atonGET /content/{item_id}moves to the moment of the repair, so a client that syncs onupdated_atsees those items again with no user edit behind them. Migrating: nothing to change; if you mirrorpublished_url, re-read the items you have unpublished. No response shape changed. As always,published_urlandstatusare RoboWrite's own record rather than a live read of your CMS — see the2026-08-27entry on the program guarantee.
2026-08-28
-
plan:generateon alisticleprogram no longer loses facets to the scope entities you approved. The plan stage's 50-subject budget was counted over every approved idea, and ideas that name a scope entity are ordered first — so those ideas spent the budget even though, onlisticle, only a facet becomes a page. Facets past the cut were dropped: partially once the approved set passed 50 ideas, and entirely once more than 50 of them named scope entities, in which caseGET /programs/{program_id}/planreturnedtotal: 0for a program that had facets to plan. The budget is now counted over the facets alone; in-scope entities are the ranked shortlist (still at most 10 per page, in the order you wrote the scope) and no longer consume it. No response shape changed — the same program simply plans the pages it should have.comparisonandentity_revieware unaffected: their budget already counted exactly the ideas that become pages. Unchanged too: alisticlewhose approved ideas are all bare scope entities still plans zero pages, because a bare entity name is not a facet. -
plan:generateon alisticleprogram still plans the facets you approved after you decline the bare-entity ideas. Declining those ideas used to empty the ranked shortlist (it was drawn from approved ideas that named a scope entity), trip the per-page entity floor, and returntotal: 0— discarding facets you had approved. The ranking now comes fromscope.entities(at most 10, in the order you wrote the scope), including entities you declined as ideas. Only a facet becomes a page; a declined entity is still named as an also-ran on those pages. No response shape changed. Alisticlewhose approved ideas are all bare scope entities still plans zero pages, because a bare entity name is not a facet. -
ideas:generateno longer treats scattered word coverage as a topic match, soideas:approve-allapproves fewer related keywords. A related keyword that merely contained every word of the scope entity that produced it used to score high enough to be auto-approved, even when each of those words belonged to a different, unrelated term. AgainstVenture Capitalthat admittedcapital one venture xandworking capital venture debt; againstPrivate Equity,home equity private lender. The entity's words must now appear together and in order for that high-confidence score. Those three keywords are no longer returned. A keyword that keeps the words in order with a modifier between them —real estate investment syndicationfromReal Estate Syndication,angel investor investing guidefromAngel Investing— is still returned and stayspending. A compound-word lookalike (hedge fundraisingagainstHedge Fund) is dropped: character-prefix is not a mention. Migrating: nothing to change; approve any borderline idea individually if you want it. Clarified, not changed: a related keyword with norelevance_scorewas never auto-approved and still is not —approve-allleaves itpending. -
Clarification — confirmed unpublish clears
published_url. AfterPOST /content/{item_id}/publishwith"mode": "unpublish"reaches a successful terminal for a teardown this API confirmed (the remote document was removed, or it was already gone),GET /content/{item_id}returnspublished_url: null. Ifstatuswaspublished, it becomesdraft. Other statuses are unchanged. A no-op (no remote document recorded) does not change those fields. No response shape changed; this is what the stored record does after the job you already poll. -
Copy — the API calls itself RoboWrite everywhere, and the Overview says why the hostname does not. No endpoint, parameter or response shape changed; two things a client can observe did. (1) In the OpenAPI document, the
PublishPolicyschema description and thePOST /propertiesdescription named the platform brand — the name that belongs to the shared api.roboad.ai host, not to this product — and now say RoboWrite. Theserversdescription is the one surface that still carries the platform name, deliberately: it leads with RoboWrite and then explains whatapi.roboad.aiis, because that is the single sentence where naming the host's owner is what makes the base URL make sense.info.titleisRoboWrite Public API. Regenerate your client if you surface those descriptions to anyone. (2) The two publish409bodies whose text names the product —draft_onlyproperty, andunpublishon an item with no publish target — changed wording for the same reason. Bothdetailstrings are prose: match on the status code and the condition, not on the sentence. The base URL is unchanged.
2026-08-27
-
Program pages now ship their citations inside
markdown_body. From this date, every page written byPOST /programs/{program_id}/pages:generateis generated withcitation_mode=inline. The stage used to dispatch each page with no citation mode at all, so it fell back tostructured_only— the writer's markdown links were stripped out of the body and no reference list was appended, leaving pages that named their sources in prose while linking none of them. What the body looks like now: inline[anchor](https://source…)links are kept, and a numbered## Sourcessection is appended whenever the page resolved any citations (a page that resolved none still gets neither links nor a Sources block). Those rows use sanitized inline-HTML<a>anchors — see Inline citations (notation) for how to read them. Not selectable on this verb:pages:generatetakes no request body, so unlikePOST /content/items/{item_id}/generatethere is no per-call option —citation_modeis not a knob on this path. It is not sealed on the page either: once a page has acontent_item_id, that is an ordinary content item, and regenerating it through the item verb writes the body under whatevercitation_modeyou send there. Sending none used to fall through to that verb'sstructured_onlydefault and strip the links this stage wrote; superseded 2026-08-29 — omittingcitation_modeon a program-owned item now keepsinline(see that entry). An explicitstructured_onlyoverrides that default. Migrating: treat a program page'smarkdown_bodyas Markdown that may contain links and sanitized inline HTML rather than as plain prose, and expect a trailing## Sourcesheading. No response shape changed and no field was added or removed —?include=sourcesstill returns the same machine-readable citation metadata it always did, for pages generated before and after this date. Pages generated earlier keep the body they were written with; there is no backfill. That includes a page whose generation was already in flight when this shipped: a replayed start request keeps the mode it was originally dispatched with. -
Additive —
POST /content/{item_id}/publishaccepts"mode": "unpublish". Tears the remote CMS document down again. Previouslyunpublishwas422on this surface and teardown was dashboard-only, so an integrator who found a live page they did not publish had no API verb to reverse it. It skips both publish-readiness prerequisites, which gate creating a remote document: it is allowed on adraft_onlyproperty, and an item with no publish target returns409instead of provisioning your default destination. The live-item404and the ambiguous-target409still apply. -
Clarification — the program no-auto-publish guarantee is scoped to RoboWrite. "Publishing is never automatic for program pages" bounded what this product does and was read as a promise that the pages could not go live. It cannot bind your CMS: a program run's pages went live and were indexed on a customer property about an hour after creation while this API still reported them as drafts.
statusandpublished_urlare RoboWrite's own record, not a live read of your CMS —status: "draft"means we did not publish it. No response shape changed; the guarantee's wording did.
2026-08-14
-
Additive — audiences and pillar strategy fields.
GET/POST/audiencesandGET/PATCH/DELETE/audiences/{audience_id}manage brand audiences.POST/PATCH/pillarsand pillar reads now accept and returntarget_audience,business_goal, andtarget_audience_ids. IDs must belong to the pillar's brand (422otherwise).POST /audiencestakes an optionalIdempotency-Key. -
Breaking —
PATCH /content/items/{item_id}: an explicitnullonslugnow returns422, andslugis published as non-nullable. An empty string returns422too, andslugnow publishesminLength: 1. Migrating: omit the key to leave the slug unchanged, or send a replacement value — clearing was never something this endpoint could do. Sendingnullpreviously returned200with the slug unchanged: the schema advertisedstring | nulland the operation description saidslug"may be cleared withnull", but the server put the previous slug back before the write (and derived one from the title if the row had none). An empty string took the same path, also returning200having changed nothing. Every item created through this API is property-bound, so those two values are exactly the two that silently did nothing on this surface. A property-less row (import / internal only — this API cannot create one) previously did store a null slug; both surfaces now refuse that write so the contract is one rule. Why it cannot be cleared: the item slug is the identity the CMS publish path and the derivedpublished_urlare keyed on; an item with no slug would publish nothing and derive no URL.published_urlis unaffected and still acceptsnullto clear.
2026-08-13
PATCH /briefs/{brief_id}acceptsnullonsecondary_keywordsagain. Additive — it reverses part of the breaking entry below from the same day, which had madenulla422and left[]as the only way to empty the set.titleandformatare unaffected and still rejectnull. Why:nulland[]are not redundant. A snapshot restore has to be able to put a collection back tonull, and collapsing the two spellings loses that. This also realigns briefs withPATCH /pillars/{pillar_id}, wherekeywordshas always accepted both — the two endpoints now describe collections the same way. If you already switched to[], nothing breaks: both spellings work.POST /authorsandPATCH /authors/{author_id}return422where they used to return500. A whitespace-onlyname, aslugthat is not^[a-z0-9-]+$, or anemailwith no@is now refused at parse with a field error. Each of these already failed — they just failed as an opaque500, by two different routes: a blanknamesurvivedminLength(three spaces is length 3) and collapsed toNULLagainst a non-nullable column, while the others were rejected deeper inside the server in a way that escaped the422handler. No request that previously succeeded is affected.slugalso now publishes itspattern, so a regenerated client can catch it before sending. Leading and trailing whitespace onnameis stripped rather than rejected.- Breaking —
PATCH /briefs/{brief_id}: an explicitnullontitle,format, orsecondary_keywordsnow returns422, and all three are published as non-nullable. The other ten fields (primary_keyword,target_word_count,audience_details,tone,search_intent,funnel_stage,pillar_id,description,summary,content_goal) still acceptnullto clear. Migrating: omit the key to leave the field unchanged; to empty the keyword set send[], which is now the only way to do it. Sendingnullpreviously wrote it straight through — the brief update commits an explicitnullrather than rejecting it — sotitleandformatviolated their NOT NULL columns and returned500with the whole update rolled back, whilesecondary_keywordsstored a SQLNULLthat read back as[], indistinguishable through the API from the[]you get by clearing it properly. Note the deliberate difference fromPATCH /pillars/{pillar_id}, wherekeywordsstill acceptsnull: a pillar's keyword list has no[]clear contract to be redundant with, whereas a brief's does, so the brief keeps one documented way to clear and the pillar keeps two. POST /programs/{program_id}/ideas/{idea_id}/approveand.../decline: an unknownidea_idon a program inresearchingorplanningreturns409, not404. The freeze is reported ahead of whether the idea exists; a404is only trustworthy once the program is out of those states. Matches the already-published freeze rule; previously the handler answered404for this pair.- Breaking —
PATCH /authors/{author_id},PATCH /categories/{category_id},PATCH /tags/{tag_id}: an explicitnullon a key that backs a non-nullable column now returns422. Affected keys:name/slug/statuson authors,name/slug/sort_order/statuson categories,name/slugon tags. Those keys are also published as non-nullable in the OpenAPI schema, so a regenerated client no longer offersT | nullfor them. Migrating: omit the key to leave the field unchanged — that is the only thingnullcould honestly have meant on a column that cannot hold it. Sendingnullpreviously did one of three undocumented things depending on which key you picked:name/slugon a tag or category hit a not-null violation and returned500;sort_orderon a category silently reset the row's ordering to0and returned200;statuson a category andname/slug/statuson an author were silently ignored and returned200. Clearing a genuinely nullable field is unchanged —email/bio/avatar_urlon authors anddescription/parent_id/icon/coloron categories still acceptnull.PATCH /pillars/{pillar_id}is covered by the entry below, which shipped the same day. - Breaking —
PATCH /pillars/{pillar_id}: an explicitnullonname,goal, orstatusnow returns422, and all three are published as non-nullable.descriptionandkeywordsstill acceptnullto clear. Migrating: omit the key to leave the field unchanged; to empty a keyword list send[]ornull. Sendingnullpreviously:namereturned500and did not apply;statusapplied the change and then returned500, after whichGET /pillars/{pillar_id}kept failing until the row was repaired (the default list omitted that pillar);goalreturned200with a defaulted value.goalandstatusrejectnullbecause both are required and non-nullable on the pillar response, so a storednullcould never be read back honestly.
2026-08-11
- Breaking —
GET /content/{content_item_id}:versionsis now aPublicPageenvelope instead of a bare array. Readversions.itemsfor the window,versions.totalfor the full count. Newest first,?limit=1–200 (default 50) and?offset=. The old shape returned every version with its full body in one unbounded response, which had no page bound at all. Migrating:versions[0]→versions.items[0]; a "latest version" scan is better served by?latest_only=true. next_cursoron every pagination envelope. Additive — the field is present everywhere and is non-null only where keyset cursor paging is supported and another page exists. Today that isGET /programsonly;?limit=/?offset=continue to work unchanged everywhere.- Published schema corrected — program approve/decline
422. These routes already returned the string-formdetailwhen anIdempotency-Keywas present, but the schema declared only the framework's field-error form. The published422is nowoneOfboth, matching what the server has always returned. No served behaviour changed; a client generated from the old schema had a type that was simply wrong. PATCH /properties/{property_id}acceptspublish_policy. Additive.
2026-08-10
- Program reads preserve unknown
scopekeys. A program whose storedscopecarries keys beyond the published ones is now returned as-is instead of failing validation. Read and create are separate models: reads allow additional properties,POST /programsstill rejects unknown keys with 422. Practical consequence for a strict client —scopeon a read may contain keys the schema does not name, so do not fail closed on extras. PROGRAM_QUOTA_EXCEEDEDis published as a program error code, raised as a preflight check before a stage verb dispatches work. Additive.
2026-08-09
- Program stage verbs publish
Idempotency-Keyas required.POST /programs/{program_id}/ideas:generate,plan:generate, andpages:generateenforced the header inside the handler while publishing it as optional, so a generated client could omit a header the route then rejected. The schema now marks it required. The one observable difference: an absent key is refused by the framework, so that specific422carries the field-errordetailform rather than the string form. A malformed key still returns the string form.
2026-08-08
- Programs (programmatic SEO) added, over 2026-08-04 → 2026-08-08 — the
/programsresource, its ideas and plan approval gates,draft_onlypublish policy, template families, and per-page generation and download. All additive; no existing endpoint changed shape.
2026-07-19
GET /accountadded — org, brands, quota, and overage in one bootstrap read. Additive.
2026-07-01
awaiting_reviewjob status.GET /jobs/{job_id}can reportawaiting_review— a stop-polling state for a topic generation that produced a draft but was routed to the dashboard review inbox (for example, no connected CMS).content_item_idandcontent_version_idare populated, so the parked draft is fetchable.
Notes
- Internal billing/cost fields are never returned. Keyword and market data (search volume, difficulty, CPC) is included where relevant.
- List endpoints are filterable where noted; filters combine (AND) and compose with pagination.
- Generate against the published OpenAPI schema for exact field shapes — it is the source of truth and is CI-guarded against drift.
Article source verification
Supporting pages are acquired through bounded provider failover. Unavailable, blocked, login-only, or failed pages cannot serve as evidence. An exhausted URL is not fetched again within the same generation; research repair can find another eligible source. Successful acquisition still requires passage-backed claim review.
Generated articles must pass source verification before a successful content
version is returned. Verification cannot be disabled. Rewrites, variations and
refreshes use the source-list check described under in-item rewrites instead:
the check never revises the text, a held version is saved with an
article_partial warning and is not auto-published, and
source_verification_failure_mode does not apply to them. Organization
settings include source_verification_failure_mode for article generation:
repair_then_fail(default): try to substantiate or revise unsupported claims within the available repair limits, then fail if unresolved.fail_fast: verify once and fail when claims are unsupported or unverifiable.
PATCH /api/public/v1/org/settings accepts this field alongside the other
organization settings (regulated_industries, prohibited_phrases and
default_property_id; see Organization settings). Omitted fields remain
unchanged; an empty update or invalid mode is rejected. Existing settings
permissions apply.
POST /api/public/v1/content/generate and item generation accept an optional
source_verification_failure_mode override. The override takes precedence over
the organization default, and the resolved choice stays fixed for that run.
An article source-verification failure creates no successful content version
and does not continue to publishing. For a rewrite, refresh or variation, only
a check that cannot run saves no version. Inspect the job error for actionable diagnostics.
Coverage is checked against the frozen generation brief, including required topics,
outline, intent and transformation instructions. Repairs cannot silently remove
required coverage. Diagnostics distinguish missing coverage, unavailable source
pages, unsupported claims, contradictory evidence and incomplete verification.
An unavailable page alone does not establish that a claim is false or unsupported.
The optional assertion_provenance receipt format remains unchanged.
Source-controlled brand projections
Use this optional workflow when a versioned Git brand contract owns brand copy. Existing brands retain ordinary editing until a projection is applied.
GET /brands/{brand_id}/projection?website_url=...verifies the expected website and returns stored fields, source and revision.POST /brands/{brand_id}/projection/previewcompares a proposed source and fields without writing.POST /brands/{brand_id}/projection/applyapplies the same reviewed request only if its revision remains current; returnsreceipt_id, new revision and field changes.POST /brands/{brand_id}/projection/rollbacktakeswebsite_url,expected_revisionandreceipt_id; restores the previous values and source ownership only if there has been no later brand edit.
Preview/apply bodies contain website_url, expected_revision, source and
fields. Source identifies repository (GitHub HTTPS repository URL), commit
(full 40-character commit), path and sha256 (source bytes). Fields may contain
name, description, tagline, mission_statement, personality_traits and
voice_directive. Omitted fields remain untouched; explicit nulls are rejected.
The source repository/path and owned field set stay fixed until rollback. Treat
source coordinates as immutable: the same repository/commit/path/hash cannot describe
different field values. A new renderer commit may produce an updated projection.
Projected voice text is deterministic source context, not an AI regeneration. Existing tone, writing style, restrictions, credentials, routing and publishing settings are preserved. Ordinary edits that conflict with source ownership and voice regeneration of a source-owned directive return 409. Wrong brand/website identity returns 404. A stale apply or rollback returns 409 without mutation. Store the receipt before performing subsequent work. These operations do not start content generation or publish anything.
If an apply response is lost, GET the projection and verify its source and fields
against the saved plan. rollback_receipt_id recovers the currently usable receipt;
it is null after a subsequent brand edit or rollback. No write retry is required.
Article generation settings
Organization settings expose default_content_quality (quick, standard, or high; default standard), brief_auto_approve (default true), and brief_review_confidence_threshold (0–1; default 0.7). PATCH accepts individual settings; omit to preserve a value. These settings cannot be null. Brief approval behavior is reserved for the forthcoming brief workflow.
Organization settings also expose default_citation_mode (bottom_only or inline_only; default bottom_only) and max_citations_per_content (an integer from 1 to 30; default 8). bottom_only keeps article prose free of links and lists the sources at the end; inline_only keeps inline links and adds no list. max_citations_per_content caps how many distinct source URLs one article may cite. Both follow the same PATCH rules: omit to preserve, null is refused. The values are fixed when an article's content kit is built, so a later change does not alter an approved kit.
POST /content/items/{item_id}/generate accepts optional citation_style (bottom_only or inline_only), which overrides default_citation_mode for that generation; omit it to follow the organization setting. It applies to v2 article drafts only and is independent of citation_mode. A bottom_only body ends with ## Sources followed by one numbered line per cited source, in first-citation order and matching ?include=sources. Each line is one Markdown link, n. [label](<url>): the label names the publisher and the page (American Express — What is a statement credit?), or the host and a topic read from the URL when no page title is known, and equals that source's title in ?include=sources; the URL is the link destination and is not shown as text. Drafts generated before 2026-11-20 keep their saved n. host — <url> lines; an inline_only body keeps its inline links and has no list.
Both topic and item generation accept optional content_quality. The request overrides the organization default. Generation responses include the effective value. A retry that replays or re-runs an existing start keeps that start's selection; starts created before this setting existed keep standard. An item request whose resolved quality differs from the earlier start, for example after the organization default changes, is a new start. A fresh topic attempt after a terminal job uses the current organization default when the request omits content_quality. Quick limits research calls; standard and high preserve current research limits. High uses the same research behavior as standard until enhanced brief research is available.
Brief create and PATCH accept article_template: standard, listicle, how_to, comparison, or an owned article-template UUID. Unknown or foreign templates return 422. Reads include the selection and server-owned template_snapshot; edits to the template never change that copy. PATCH null clears both. Selecting a template here does not apply its article spec or outline.
Prepared kits carry the frozen definition in directives.template_snapshot alongside its base key in directives.article_template. Older kits without a snapshot keep their existing serialization and hash; their structure is not inferred from current template defaults. Numbered-entry and required-comparison-table shortfalls are advisory findings only: they do not hold the article or trigger automatic repair.