Running Autopilot content jobs

Run a hands-off Autopilot content job using the active Rankability outcome-allowance or full-platform credit contract.

Autopilot runs research, brief, draft, optimization passes, and fact checking in one hands-off job. It consumes one current-plan content-asset unit or 750 existing full-platform credits after it produces a usable draft.

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 resolve the account's metering model. If a run fails before it produces a usable draft, the reserved outcome or credits are 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 content-asset outcome, 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, not the completed content-asset outcome.

Response

A successful request returns 202 Accepted — the run continues in the background:

{
  "job_id": "uuid",
  "status": "queued",
  "stage": "researching",
  "flat_credits": 750,
  "created_at": "2026-07-07T15:30:00.000Z"
}

flat_credits is retained as a legacy compatibility field. Do not use it to infer that a current-plan account has a shared credit balance; use /usage and its metering_model.

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 reserved outcome or 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 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	copywriter_allowance_exhausted	The current-plan content-asset allowance has no available unit. The response includes outcome, required, and remaining.
402	insufficient_credits	The existing full-platform account lacks the 750 credits required for the run.
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.
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.

• Credit costs reference — What every operation costs.