> 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 the entire content pipeline — research, brief, draft, optimization passes, fact checking, and imagery — in one hands-off job for a flat 3,000 credits. Autopilot is the most hands-off way to create content through the API. One request runs the full pipeline — research, brief, draft, optimization passes, fact checking with citations, and imagery — and delivers a review-ready draft. You are charged a flat 3,000 credits, and only when the run produces a usable draft. If a run fails before that point, the reserved credits are released back to your balance. ## When to use Autopilot vs. content jobs * **Autopilot** — you want a finished, polished draft with no intermediate steps. One flat price, one poll loop. * **Content jobs (auto mode)** — you want the standard research-to-draft pipeline without the extra optimization, fact-checking, and imagery 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 | No | — | Associate the run with a client. The run inherits the client’s brand voice, tone, and knowledge base context. The client must belong to your organization. | | `intent` | enum | No | `"educate"` | Search intent: `educate`, `discover`, `compete`, or `convert`. | | `context` | string | No | — | Free-text guidance for the run (up to 2,000 characters), such as selling points to emphasize or angles to take. | | `research_platforms` | array | No | Recommended set | Which research platforms to analyze. If omitted, Rankability uses the recommended subset. | ### Response A successful request returns `202 Accepted` — the run continues in the background: ``` { "job_id": "uuid", "status": "queued", "stage": "researching", "flat_credits": 3000, "created_at": "2026-07-07T15:30:00.000Z" } ``` ### 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 credits were charged 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 → image → finalizing → complete ``` A run that cannot finish ends in the `failed` stage with a human-readable `error`, and any reserved credits are 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://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", "context": "Emphasize same-day service and licensed technicians." }' ``` ## Common errors | HTTP | Code | Cause | | ---- | ----------------------- | ------------------------------------------------------------------------------------------- | | 400 | `invalid_input` | Missing `topic` or invalid field values. | | 402 | `insufficient_credits` | Not enough credits for the flat 3,000-credit run. The response includes `credits_required`. | | 402 | `subscription_required` | Active subscription required. | | 404 | `not_found` | `client_id` does not exist or does not belong to your organization. | | 429 | `rate_limit_exceeded` | Too many requests. Wait and retry. | | 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. * [Credit costs reference](/account-and-settings/credit-costs-reference.md) — What every operation costs. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.rankability.com/api/api-copywriter-autopilot.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.