Creating content jobs
A complete reference for the POST /copywriter/jobs endpoint — every input field, valid values, execution modes, idempotency, and practical examples.
A complete reference for the POST /copywriter/jobs endpoint — every input field, valid values, execution modes, idempotency, and practical examples.
The POST /api/agent/v1/copywriter/jobs endpoint creates a new content job. This page covers every input field, execution modes, and how to handle retries safely.
Endpoint
POST /api/agent/v1/copywriter/jobs
Authorization: Bearer rk_live_...
Content-Type: application/jsonScope required: copywriter:run
Request body fields
topic
string
Yes
—
The primary keyword or topic for the content piece. Example: "emergency plumber st louis"
client_id
UUID
Yes
—
The client workspace to scope the job to. The job inherits the client’s brand voice, tone settings, and knowledge base context. The client must belong to your organization — list your clients with GET /api/agent/v1/clients to find a valid ID. Requests without a client_id are rejected with a 400 error.
intent
enum
No
"educate"
Search intent that shapes research and content structure. Values: educate, discover, compete, convert.
mode
enum
No
"auto"
Execution mode. auto runs the full pipeline end-to-end. stepped pauses after the brief for review. See Execution modes below.
location
string
No
—
Target location for SERP geo-targeting. Example: "St. Louis, MO", "London, UK". When set, competitor analysis uses location-specific search results.
language
string
No
"en"
Language code for the content. Controls SERP results language, brief language, draft language, and entity extraction language. See Supported languages for all codes.
tone
enum
No
—
Writing tone for the draft. Values: clear_practical, expert_detailed, friendly_simple, technical_precise, persuasive_direct. If omitted, the client’s default tone is used.
custom_instructions
string
No
—
Free-text guidance for the AI. Applied to both outline generation and draft writing. Example: "Mention 24/7 availability and licensed technicians".
word_count_target
integer
No
—
Target word count for the draft. Must be between 100 and 10,000. The AI uses this as a goal — actual word count may vary slightly.
project_mode
enum
No
"new"
new creates content from scratch. optimize creates a persistent optimization project for an existing page (requires source_url).
page_contract
enum
Conditional
—
Required for generated content. Choose article or commercial_service. It may be omitted only when supplying a pre-written draft_body.
source_url
URL
Conditional
—
Required when project_mode is "optimize". Rankability imports the existing page and researches optimization guidance; it does not change the live URL.
research_platforms
string array
No
Google Organic
Research sources to analyze. AI sources run only when explicitly selected. Broader research changes the evidence gathered, not the fixed completed-deliverable price.
Execution modes
Auto mode (default)
Set "mode": "auto". The API runs the entire pipeline — research, brief generation, brief approval, and draft writing — without stopping. Your agent only needs to poll until the status reaches completed, then fetch artifacts.
Auto mode consumes one current-plan content-asset unit or 750 existing full-platform credits when the run produces a usable new content asset. Research and brief generation do not consume a separate outcome.
Stepped mode
Set "mode": "stepped". The API runs research and generates the brief, then pauses at brief_ready. Your agent can fetch partial artifacts (outline, SEO metadata, entities, FAQs) to review the brief before approving it.
Research and the brief consume no Copywriter outcome or credits. Approving the brief does not itself create usage; one content-asset unit or 750 full-platform credits is consumed only when draft generation produces a usable new content asset.
To approve the brief and start draft generation:
Autopilot (separate endpoint)
For the most hands-off option, use the dedicated Autopilot endpoint instead of a content job. Autopilot runs research, brief, draft, extra optimization passes, and fact checking with citations for one completed content-asset outcome — consumed only when the run produces a usable draft. Images remain user-selected in the editor. See Running Autopilot content jobs.
How client_id works
client_id is required — every API-created content job is scoped to a client workspace. The job inherits context from that client:
Brand voice — tone, style, and terminology defined in the client’s Brand & voice settings.
Knowledge base — uploaded documents, URLs, and pasted text that inform the AI about the client’s products, services, and unique selling points.
Domain context — the client’s website domain used for competitor analysis.
If the client_id you send does not exist or belongs to another organization, the request is rejected with a 404 error. For one-off or test content, create a dedicated test client first.
How location affects SERP targeting
The location field tells the research engine where to simulate the search from. For example, setting "location": "Austin, TX" returns SERP results as if searching from Austin. This affects:
Which competitors appear in the analysis
Local pack results and map data (if applicable)
Location-specific content recommendations in the brief
If omitted, the search uses a generic US location.
How custom_instructions guides output
The custom_instructions field is free-text guidance that the AI applies during both outline creation and draft writing. Use it to:
Emphasize specific selling points:
"Highlight our 30-day money-back guarantee"Set structural preferences:
"Include a comparison table in the middle of the article"Add constraints:
"Do not mention competitor brand names"Guide the angle:
"Write from the perspective of an experienced practitioner"
Optimizing existing content
To optimize an existing page instead of creating new content, set project_mode to "optimize" and provide the source_url:
Rankability creates a persistent Copywriter optimization project, imports the source into the editor, and researches current competitors and guidance. The job does not modify or publish the live page automatically. A successful outcome consumes one current-plan optimization unit or 400 existing full-platform credits.
Idempotency keys
To safely retry a request without creating duplicate jobs, include an Idempotency-Key header:
If a job already exists for that idempotency key within your organization, the API returns the existing job instead of creating a new one. This is essential for:
Network retry logic — safely retry after a timeout without double-creating
Batch scripts — re-run a script without worrying about duplicates
Webhook handlers — handle duplicate webhook deliveries gracefully
Response
A successful request returns 201 Created:
credits_estimated describes the legacy full-platform equivalent. Call GET /api/agent/v1/usage before starting work and use metering_model to decide whether the account consumes an outcome allowance or shared credits.
If the idempotency key matches an existing job, the response is 200 OK with the existing job details.
Example requests
Minimal request (auto mode)
Full request with all fields
Optimize an existing page
Common errors
400
invalid_input
Missing client_id, topic, or required page_contract; invalid field values; or source_url missing when project_mode is "optimize".
401
unauthorized
Missing, invalid, expired, or revoked API key.
402
copywriter_allowance_exhausted
The matching current-plan content-asset or optimization allowance has no available unit.
402
insufficient_credits
Not enough credits to start the job. Purchase more or upgrade your plan.
403
plan_required
Active subscription required. Subscribe to any plan to access the API.
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.
Related articles
Running Autopilot content jobs — The fully hands-off pipeline with optimization and fact checking.
Supported languages — All 32 language codes and how the language field controls output.
Retrieving and using artifacts — How to fetch and use the outline, draft, SEO metadata, and more.
Content types reference — Details on Educate, Discover, Compete, and Convert intents.
Last updated
Was this helpful?