> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-copywriter-autopilot.md). # Running Autopilot content jobs Autopilot runs research, brief, draft, optimization passes, and fact checking in one hands-off job. Full-platform work is included in pooled usage; Copywriter Core uses its separate completed-outcome allowance. Autopilot is the most hands-off way to create content through the API. One request runs the full pipeline — research, brief, draft, optimization passes, and fact checking with citations — and delivers a review-ready draft. Call `GET /api/agent/v1/usage` first to check the current pooled windows. If a run fails before it produces a usable draft, its pending usage is released. Autopilot does not silently choose an image. Add an approved image in the editor after generation so the asset and alt text stay under your control. ## When to use Autopilot vs. content jobs * **Autopilot** — you want a finished, polished draft with no intermediate steps. One completed draft, one poll loop. * **Content jobs (auto mode)** — you want the standard research-to-draft pipeline without the extra optimization and fact-checking passes. * **Content jobs (stepped mode)** — you want to review or edit the brief before the draft is written. See [Creating content jobs](/api/api-creating-content-jobs.md) for the standard pipeline. ## Start a run ``` POST /api/agent/v1/copywriter/autopilot Authorization: Bearer rk_live_... Content-Type: application/json ``` **Scope required:** `copywriter:run` ### Request body fields | Field | Type | Required | Default | Description | | ------------------------------- | ------- | -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `topic` | string | Yes | — | The primary keyword or topic for the content piece. | | `client_id` | UUID | Yes | — | Scope the run to a client. The run inherits the client’s brand voice, tone, knowledge base, and excluded-topic context. The client must belong to your organization. | | `intent` | enum | No | `"educate"` | Search intent: `educate`, `discover`, `compete`, or `convert`. | | `language` | string | No | `"en"` | Language code for the generated content. | | `context` | string | No | — | Free-text guidance for the run (up to 2,000 characters), such as selling points to emphasize or angles to take. | | `location` | string | No | — | Target location for geo-specific content. If it differs from the workspace’s saved service area, the request returns `409 location_conflict` before paid work starts. | | `location_lat` / `location_lng` | number | No | — | Optional coordinates for the target location. | | `allow_location_conflict` | boolean | No | `false` | Retry with `true` only after confirming that a different target market is intentional. | | `page_contract` | enum | Yes | — | Choose `article` or `commercial_service`. | | `research_platforms` | array | No | Google Organic | Research platforms to analyze. AI sources run only when selected. Research breadth changes evidence coverage and can affect usage impact. | ### Response A successful request returns `202 Accepted` — the run continues in the background: ``` { "job_id": "uuid", "status": "queued", "stage": "researching", "usage_impact": { "level": "high", "included": true }, "created_at": "2026-07-07T15:30:00.000Z" } ``` `usage_impact` describes the relative impact on the account's pooled windows. Use `/usage` to check the current 24-hour and 7-day remaining percentages before starting work. ### Idempotency keys Include an `Idempotency-Key` header to safely retry a request. If an Autopilot run already exists for that key within your organization, the API returns the existing run instead of starting (and charging for) a new one. ## Poll run status ``` GET /api/agent/v1/copywriter/autopilot/:id Authorization: Bearer rk_live_... ``` **Scope required:** `copywriter:read` The response includes the live stage, timestamps, how many optimization passes have run, whether reserved usage was consumed or released, any error, and — once available — a review summary of the finished draft: ``` { "job_id": "uuid", "status": "generating_draft", "stage": "optimizing", "started_at": "2026-07-07T15:30:05.000Z", "updated_at": "2026-07-07T15:34:41.000Z", "completed_at": null, "optimize_passes": 1, "optimize_pass_cap": 3, "charged": false, "released": false, "error": null, "review": null, "publish": null } ``` ### Run stages Runs move through these stages in order: ``` queued → researching → briefing → drafting → optimizing → fact_checking → finalizing → complete ``` A run that cannot finish ends in the `failed` stage with a human-readable `error`, and its pending usage is released. ## Fetch the finished draft When the run completes, fetch the draft and all other outputs through the standard artifacts endpoint: ``` GET /api/agent/v1/copywriter/jobs/:id/artifacts ``` See [Retrieving and using artifacts](/api/api-retrieving-artifacts.md) for the full artifact reference. ## Example ``` curl -X POST https://app.rankability.com/api/agent/v1/copywriter/autopilot \ -H "Authorization: Bearer rk_live_YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: autopilot-2026-07-07-drain-cleaning" \ -d '{ "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "topic": "drain cleaning services st louis", "intent": "convert", "language": "en", "location": "St. Louis, Missouri", "page_contract": "commercial_service", "research_platforms": ["organic", "chatgpt", "claude"], "context": "Emphasize same-day service and licensed technicians." }' ``` ## Common errors | HTTP | Code | Cause | | ---- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_input` | Missing `client_id`, `topic`, or `page_contract`, or invalid field values. | | 402 | `subscription_required` | Active subscription required. | | 404 | `not_found` | `client_id` does not exist or does not belong to your organization. | | 409 | `location_conflict` | The requested target differs from the workspace’s saved service area. Review the returned locations, then correct the target or retry with `allow_location_conflict: true`. | | 429 | `rate_limit_exceeded` | Too many requests. Wait and retry. | | 429 | `usage_limit_reached` | A pooled on-demand window has reached its current limit; retry at the returned recovery time. | | 503 | `service_unavailable` | Queue service is temporarily unavailable. Retry with exponential backoff. | ## Using Autopilot from AI assistants (MCP) If you connect Rankability to an AI assistant through MCP, two tools expose the same capability: `create_content_autopilot` starts a run and `get_autopilot_status` polls it. See [Connecting Rankability to AI assistants (MCP)](/api/mcp-getting-started.md). ## Related articles * [Creating content jobs](/api/api-creating-content-jobs.md) — The standard auto and stepped content pipelines. * [Retrieving and using artifacts](/api/api-retrieving-artifacts.md) — Fetch the finished draft, outline, and SEO metadata. * [Usage limits reference](/account-and-settings/credit-costs-reference.md) — Pooled windows and recovery behavior.