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 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 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).

Related articles

• Creating content jobs — The standard auto and stepped content pipelines.
• Retrieving and using artifacts — Fetch the finished draft, outline, and SEO metadata.
• Usage limits reference — Pooled windows and recovery behavior.