Copywriter: content jobs
Create SEO content in auto, stepped or Autopilot mode, poll status, fetch artifacts, edit drafts externally and export.
Execution modes
Section titled “Execution modes”The API supports three ways to populate a Copywriter project:
Auto mode (default)
Section titled “Auto mode (default)”Creates a project, runs research, auto-approves the brief, and generates a draft — all from a single POST. The agent only needs to poll until status === "completed", then fetch artifacts.
POST /jobs (mode: "auto") → status: queued → researching → generating_draft → completedStepped mode
Section titled “Stepped mode”Creates a project and runs research, then pauses at brief_ready. The agent can review the brief/outline, then explicitly approve it to trigger draft generation. Gives more control for sophisticated workflows.
POST /jobs (mode: "stepped") → status: queued → researching → brief_ready → POST /jobs/:id/approve → status: generating_draft → completedPre-written draft upload
Section titled “Pre-written draft upload”Supply draft_body (and optionally draft_format) on the create-job request to push pre-written content directly into a new project. Rankability skips research/brief/draft generation entirely — no AI is invoked for the draft itself, no credits are reserved or deducted, and the project lands in completed immediately. The uploaded content is rendered in the standard Copywriter output UI and is returned by the existing GET /jobs/:id/artifacts endpoint just like a generated draft.
POST /jobs (draft_body: "...", draft_format: "markdown" | "html") → status: completedThis is useful when you already have copy (from a CMS, a writer, or another tool) and want to bring it into Rankability for tracking, scoring, or export. To run optimization on the uploaded draft afterward, create a separate Optimize job pointing at the published URL.
Content templates
Section titled “Content templates”The caller must explicitly choose page_contract before generated work. Rankability still detects specialized article subtypes from topic and intent, but detection is advisory and cannot silently turn an ambiguous commercial topic into an article. When a specialized template is detected within the confirmed contract, the outline and draft use that purpose-built structure.
Detected templates
Section titled “Detected templates”| Template | content_type value |
Trigger | Output |
|---|---|---|---|
| Alternatives | alternatives |
intent: "compete" + topic contains a brand name + “alternatives” or “competitors” (e.g., “semrush alternatives”) |
Comparison article with Quick Picks, Criteria, Comparison Table, per-tool breakdowns, and Decision Framework |
| Commercial / service | local_service |
Explicit page_contract: "commercial_service" |
Conversion-focused landing page wireframe (Hero, Trust Bar, Services/Offer, Why Choose, Social Proof, How It Works, optional location section, FAQ, CTA). Covers local services and non-local offers such as training, courses, and consulting. |
| Versus | versus |
intent: "compete" + topic contains “vs” or “versus” |
Standard article (specialized template planned) |
| Review | review |
intent: "compete" + topic contains “review(s)” |
Standard article (specialized template planned) |
| Standard | null |
All other topics | Standard SEO article |
How detection works
Section titled “How detection works”- The caller confirms
page_contract(articleorcommercial_service) - Within that contract, the API runs heuristic pattern matching on the topic and intent
- If a potential specialized article template is detected, it validates with a lightweight AI call (e.g., confirming “semrush” is a brand and not a category)
- The confirmed contract, validated template, confidence/provenance, and extracted metadata are stored on the project
- The research and draft workers use this metadata to generate template-specific content
Examples
Section titled “Examples”Alternatives template:
{ "topic": "semrush alternatives", "intent": "compete", "page_contract": "article"}Response includes "content_type": "alternatives". Draft follows the alternatives comparison structure with product research enrichment.
Local service template:
{ "topic": "emergency plumber st louis", "intent": "convert", "page_contract": "commercial_service", "location": "St. Louis, MO"}Response includes "content_type": "local_service". Draft produces a conversion-focused landing page wireframe.
Standard (no template):
{ "topic": "how to improve page speed", "intent": "educate", "page_contract": "article"}Response includes "content_type": null. Draft follows standard article format.
Endpoints
Section titled “Endpoints”Key management
Section titled “Key management”These endpoints require Clerk admin session auth (not Bearer tokens). They are used by organization admins to create and manage API keys.
Key management cannot be scripted with an
rk_live_API key. The/keysendpoints use Clerk session authentication (the same session cookie the browser uses when you are logged into the Rankability UI).rk_live_Bearer tokens are intentionally not accepted here — key rotation and creation require a human-authenticated session. To automate key rotation in a CI/CD pipeline, use the Rankability UI to generate keys manually, then inject them as secrets.
Create API key
Section titled “Create API key”POST /api/agent/v1/keysRequest body:
{ "name": "Production Agent", "scopes": ["copywriter:run", "copywriter:read"], "expiresAt": "2027-01-01T00:00:00.000Z"}| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Human-readable label for the key |
scopes |
string[] | Yes | Permission scopes (min 1) |
expiresAt |
ISO 8601 | No | Expiration timestamp (null = never expires) |
Response (201):
{ "id": "uuid", "name": "Production Agent", "key": "rk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901", "key_prefix": "rk_live_aBcDeFgH", "scopes": ["copywriter:run", "copywriter:read"], "expires_at": "2027-01-01T00:00:00.000Z", "created_at": "2026-02-25T15:30:00.000Z"}The
keyfield contains the full plaintext API key. It is only returned once — store it securely.
List API keys
Section titled “List API keys”GET /api/agent/v1/keysResponse (200):
{ "keys": [ { "id": "uuid", "name": "Production Agent", "key_prefix": "rk_live_aBcDeFgH", "scopes": ["copywriter:run", "copywriter:read"], "last_used_at": "2026-02-25T15:45:00.000Z", "expires_at": null, "created_at": "2026-02-25T15:30:00.000Z" } ]}Revoke API key
Section titled “Revoke API key”DELETE /api/agent/v1/keys/:idResponse (200):
{ "id": "uuid", "revoked": true, "revoked_at": "2026-02-25T16:00:00.000Z"}Returns 404 if key not found, 409 if already revoked.
Content jobs
Section titled “Content jobs”These endpoints use Bearer token authentication.
Create a job
Section titled “Create a job”POST /api/agent/v1/copywriter/jobsAuthorization: Bearer rk_live_...Request body:
{ "client_id": "uuid", "topic": "emergency plumber st louis", "intent": "convert", "page_contract": "commercial_service", "mode": "auto", "location": "St. Louis, MO", "language": "en", "tone": "clear_practical", "custom_instructions": "Mention 24/7 availability and licensed technicians", "word_count_target": 1200, "project_mode": "new", "source_url": "https://example.com/existing-page", "research_platforms": ["organic", "ai_overview", "perplexity"]}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
topic |
string | Yes | — | Primary keyword/topic |
client_id |
UUID | Yes | — | Client workspace to scope the project to (must belong to your org). Required so drafts inherit the client’s brand voice, knowledge base sources, and excluded topics. Find valid ids with GET /api/agent/v1/clients. Omitting it returns 400 invalid_input. |
intent |
enum | No | "educate" |
Search intent: educate, discover, compete, convert |
page_contract |
enum | Yes for generated work | — | Explicit page shape: article or commercial_service. Required before research/generation so an ambiguous topic cannot silently fall back to an article. commercial_service covers local services and broader offers such as training, courses, and consulting. Optional only when draft_body is supplied because that path performs no generation. |
mode |
enum | No | "auto" |
Execution mode: auto or stepped |
location |
string | No | — | Target location (e.g., “St. Louis, MO”) |
language |
string | No | "en" |
Content language code. Controls SERP language, brief language, draft language, and entity extraction language. See Supported languages for all codes. |
tone |
enum | No | — | Writing tone: clear_practical, expert_detailed, friendly_simple, technical_precise, persuasive_direct |
custom_instructions |
string | No | — | Additional guidance for AI generation |
word_count_target |
integer | No | — | Target word count (100–10,000) |
project_mode |
enum | No | "new" |
new (create from scratch) or optimize (optimize existing page) |
source_url |
URL | No | — | Page URL to optimize (required when project_mode is optimize) |
draft_body |
string | No | — | Pre-written draft content. When supplied, Rankability skips the research/brief/draft pipeline, no AI generation runs for the draft, no credits are charged, and the project is created in completed state with this body as the finished draft. Max length: 500,000 characters. Cannot be combined with project_mode: "optimize" or source_url. |
draft_format |
enum | No | "markdown" |
Format of draft_body: markdown or html. The exact body and format you send are preserved and returned unchanged by GET /jobs/:id/artifacts and the matching /export/markdown or /export/html route. Ignored when draft_body is not supplied. |
research_platforms |
string[] | No | ["organic"] |
Which research platforms to run. Changes evidence coverage, not the fixed completed-deliverable price. Allowed values: organic, ai_overview, ai_mode, perplexity, chatgpt, grok, gemini, brave, claude. organic is always required and force-enabled. Hidden google_video_pack and youtube_search compatibility keys are also added to the resolved selection. When omitted, no AI source is selected. Unknown keys are ignored. The resolved list is echoed as research_platforms. |
Pre-written draft example:
{ "client_id": "uuid", "topic": "how to fix a leaky faucet", "intent": "educate", "draft_body": "# How to fix a leaky faucet\n\nA leaky faucet wastes water and money. Here's how to fix one in under 30 minutes...\n\n## Step 1: Shut off the water\n\nLocate the shutoff valves...", "draft_format": "markdown"}Returns immediately with "status": "completed" and "job_id". Calling GET /copywriter/jobs/:id/artifacts returns the uploaded body under draft.content. The same field is available through the Serena bridge (/api/serena/v1/...) since Serena re-dispatches into this router.
Idempotency: Include an Idempotency-Key header to safely retry requests. If a job already exists for that key within your org, the existing job is returned instead of creating a duplicate.
Idempotency-Key: my-unique-request-id-123Response (201):
{ "job_id": "uuid", "status": "queued", "content_type": "alternatives", "created_at": "2026-02-25T15:30:00.000Z", "research_platforms": ["organic", "google_video_pack", "youtube_search"], "credits_estimated": 750}The content_type field indicates which specialized template was auto-detected (see Content templates). Returns null for standard article content.
The research_platforms array is the resolved platform selection actually used for this run (after force-including organic and the hidden video-pack / YouTube-search sources). credits_estimated is the rate-card cost for that mix — the amount the worker will deduct on success. For a pre-written draft upload (draft_body), credits_estimated is 0 because no research runs. See Control your cost.
Scopes required: copywriter:run
Poll job status
Section titled “Poll job status”GET /api/agent/v1/copywriter/jobs/:idAuthorization: Bearer rk_live_...Response (200):
{ "job_id": "uuid", "status": "researching", "marked_complete": false, "marked_complete_at": null, "content_type": "alternatives", "progress": { "stage": "fetching_serp", "percent": 0.25 }, "error": null, "created_at": "2026-02-25T15:30:00.000Z", "updated_at": "2026-02-25T15:31:00.000Z"}Status values:
| Status | Description | Next action |
|---|---|---|
queued |
Job created, waiting to start | Poll |
researching |
Analyzing competitors and SERPs | Poll |
brief_ready |
Brief complete, awaiting approval (stepped mode only) | Approve or poll artifacts |
generating_draft |
Draft being written by AI | Poll |
completed |
All artifacts ready | Fetch artifacts |
failed |
Job failed | Check error, retry |
Scopes required: copywriter:read
status describes generation, not the Projects Complete tab. The independent
marked_complete flag reflects the editor’s Mark as done action.
marked_complete_at is its UTC ISO timestamp, or null when not marked Done or
when a legacy Done project’s original date is unknown. Do not substitute updated_at.
Mark or unmark a project as Done
Section titled “Mark or unmark a project as Done”PATCH /api/agent/v1/copywriter/jobs/:idAuthorization: Bearer rk_live_...Content-Type: application/json
{"marked_complete": true}Scope required: copywriter:run. Send only the required boolean
marked_complete field. Use false to undo Done.
Response (200):
{ "job_id": "uuid", "status": "completed", "marked_complete": true, "marked_complete_at": "2026-10-03T12:30:00.000Z", "updated_at": "2026-10-03T12:30:00.000Z"}This updates the same project flag as the web editor, so the Projects Complete tab reflects the change. It does not change generation status, publish content, verify a live URL, create a publishing receipt, or consume generation usage.
For an external publishing pipeline: save the approved draft, successfully
publish it through your CMS, then send this PATCH. Read back the flag on
GET /copywriter/jobs/:id or GET /copywriter/jobs with copywriter:read.
Repeated requests for the same flag are safe and retain the completion timestamp.
Undo clears the timestamp; marking Done again records a new date.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_input |
Missing/non-boolean flag or additional fields |
| 401 | unauthorized |
Missing/invalid API credential |
| 403 | forbidden |
Credential lacks copywriter:run (existing plan/access gates also apply) |
| 404 | not_found |
Missing job, different organization, or Page Auditor editor handoff rather than a content job |
| 409 | job_in_progress |
Attempt to mark Done while research/generation is still running |
| 409 | COPYWRITER_DONE_REQUIRES_CONTENT |
No meaningful draft or saved content; intentional manual/no-draft workflows follow the editor’s existing exception |
Read project keyword exclusions
Section titled “Read project keyword exclusions”GET /api/agent/v1/copywriter/jobs/:id/keyword-exclusionsRead the saved project ignore list without modifying content, scores or usage. The project must belong to the authenticated organization. Page Auditor-only editor handoffs are not content jobs. The response names the workspace ignore-list URL separately; a project restore cannot override workspace exclusions. API keys and OAuth retain their existing plan/access gates.
Query parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit |
integer | No | 200 | Keywords per page, 1–500. |
offset |
integer | No | 0 | Start offset, 0–100000. |
Response (200):
{ "scope": "project", "project_id": "project-id", "client_id": "client-id", "keywords": ["unrelated product", "unrelated location"], "pagination": {"total": 2, "limit": 200, "offset": 0, "has_more": false, "next_offset": null}, "workspace_exclusions": {"count": 1, "href": "/api/agent/v1/clients/client-id/keyword-exclusions"}, "updated_at": "2026-10-30T12:00:00.000Z"}Bulk ignore or restore project keywords
Section titled “Bulk ignore or restore project keywords”PATCH /api/agent/v1/copywriter/jobs/:id/keyword-exclusionsAdd or remove exact terms from the same saved ignore list used by the editor. This affects one owned content project, not its workspace or sibling articles. Preview with dry_run: true; it returns the proposed changes without changing saved lists, scores or timestamps. No draft text is rewritten, no research/publishing starts and no generation usage is consumed. The existing deterministic editor score is recomputed when research/draft inputs are available; read the normal job/artifact endpoints for that score.
Request body:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
ignore |
string[] | No | [] | Exact terms to ignore. At least one term in ignore or restore is required; 200 input entries combined per request. |
restore |
string[] | No | [] | Exact terms to remove from this project’s ignore list. The same normalized term cannot appear in both arrays. |
dry_run |
boolean | No | false | Preview without any saved changes. |
Each string must contain 1–500 characters after trimming. Matching is case-insensitive and collapses repeated whitespace, like the editor. Wildcards, substring and semantic matching are not supported. Other body fields are rejected. Unrelated exclusions are retained. The saved list supports up to 5,000 distinct terms; restores are still allowed when a legacy list is already larger. Read lists with the GET endpoint; normal keyword CSV exports omit ignored terms and are not an exclusion import format.
Request example:
{"ignore": ["unrelated product", "unrelated location"], "dry_run": true}Response (200):
{ "scope": "project", "project_id": "project-id", "client_id": "client-id", "dry_run": true, "changed": false, "would_change": true, "previous_exclusion_count": 0, "exclusion_count": 2, "changes": {"ignored": ["unrelated product", "unrelated location"], "restored": [], "already_ignored": [], "not_ignored": []}, "still_ignored_by_workspace": [], "updated_at": "2026-10-30T12:00:00.000Z"}Repeat with dry_run: false (or omit it) to apply. changed means a write occurred; would_change describes the proposed current-state change. Repeating an already-applied request is a no-op and preserves the timestamp. Operations merge against the current saved list under a row lock. An Idempotency-Key is not required or response-cached: a later explicit restore can be followed by a new ignore. changes.already_ignored and changes.not_ignored explain no-ops. still_ignored_by_workspace names requested restores that remain excluded by the workspace. Other existing topic/eligibility rules also remain in force.
Read workspace keyword exclusions
Section titled “Read workspace keyword exclusions”GET /api/agent/v1/clients/:id/keyword-exclusionsRead the selected website workspace’s saved blocked-keyword list. This is not the agency/organization-wide excluded-topics setting. The response uses scope: "workspace", client_id, keywords, pagination and updated_at, without a project ID. It never reads another organization’s workspace or starts work.
Query parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit |
integer | No | 200 | Keywords per page, 1–500. |
offset |
integer | No | 0 | Start offset, 0–100000. |
Bulk ignore or restore workspace keywords
Section titled “Bulk ignore or restore workspace keywords”PATCH /api/agent/v1/clients/:id/keyword-exclusionsEdit the existing workspace blocked-keyword list, affecting current and future content projects in that workspace only. Requires clients:write, not just copywriter:run. Preview before applying broad changes. Existing article drafts and project-level ignore lists stay unchanged. Current score readers detect the changed workspace context and refresh affected scores on their next read; this request does not synchronously rescore every article. Refresh an already-open editor to see the latest workspace list. Workspace exclusions also feed the existing research/writing recommendation controls, not only the displayed content score.
Request body:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
ignore |
string[] | No | [] | Terms to add to this workspace list, using the same 200-entry combined batch limit. |
restore |
string[] | No | [] | Terms to remove from this workspace list; project ignores are not removed. |
dry_run |
boolean | No | false | Preview the changes without saving. |
The validation, 5,000-term list limit, exact matching, no-op and concurrency behavior are the same as the project endpoint. The response uses scope: "workspace" and client_id, with the same dry-run/count/change fields but no project ID or still_ignored_by_workspace. Restore affects only this list, so a term can remain ignored separately in an article. Existing organization-level excluded topics are not changed.
Errors for keyword-exclusion endpoints: 400 invalid_input for invalid inputs, 400 exclusion_limit when additions exceed the saved-list cap, 401 for missing/invalid credentials, 403 for insufficient scope or existing account/access restrictions, 404 for a missing or unowned target, and 429 for the normal API rate limit. Responses use Cache-Control: private, no-store.
Retrieve artifacts
Section titled “Retrieve artifacts”GET /api/agent/v1/copywriter/jobs/:id/artifactsAuthorization: Bearer rk_live_...Returns 409 if job is not yet completed. In stepped mode at brief_ready, returns partial artifacts (outline, SEO, entities, FAQs) with draft and score as null.
Response (200) — completed job:
{ "content_type": "alternatives", "outline": [ { "heading": "What Is Emergency Plumbing?", "level": "h2", "subheadings": [ { "heading": "Signs You Need Emergency Service", "level": "h3" } ] } ], "draft": { "format": "markdown", "content": "# Emergency Plumber St. Louis\n\nWhen a pipe bursts...", "word_count": 1247 }, "seo": { "title_tag": "Emergency Plumber St. Louis | 24/7 Licensed Service", "meta_description": "Need an emergency plumber in St. Louis? ...", "h1": "Emergency Plumber St. Louis" }, "entities": [ { "name": "St. Louis", "type": "location", "relevance": 0.95 } ], "faqs": [ { "question": "How much does an emergency plumber cost in St. Louis?", "answer": "Emergency plumbing in St. Louis typically costs..." } ], "faq_schema_json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"FAQPage\",...}", "score": { "overall": 82, "overall_max": 100, "calculated_at": "2026-09-22T17:36:39.879Z", "scored_revision": "sha256:abc123...", "draft_revision": "sha256:abc123...", "freshness_state": "current", "score_source": "editor", "categories": { "copywriting": 17, "readability": 8, "seo": 13 }, "category_details": { "copywriting": { "score": 17, "max_score": 20, "percent": 85 }, "readability": { "score": 8, "max_score": 10, "percent": 80 }, "seo": { "score": 13, "max_score": 15, "percent": 86.7 } } }}Scopes required: copywriter:read
For an editor-parity read, request draft and quality_score together and
require score.freshness_state to be current. stale means the score belongs
to an earlier saved body; unverified is normally a historical record without
revision provenance. If calculation_state is legacy_mismatch, preserve the
stored overall shown by the editor and do not recompute it from the category
values.
Editor word targets, keyword checklist, and score breakdown
Section titled “Editor word targets, keyword checklist, and score breakdown”GET /copywriter/jobs/:id now includes target_word_count_min,
target_word_count_max, and word_count_target (min, max, median,
source, locked_at). These are the editor’s actual range, available as soon
as the brief is ready. Explicitly requested word-count overrides remain honored.
source: "fallback" means there was insufficient competitor word-count data;
an unresearched project returns null targets. The older target_word_count
artifact is only the brief’s single-number drafting hint, not the editor range.
Normal artifacts include the range at the top level and inside seo.
Filtered reads can request include=word_count_target or include=seo_assets.
Use include=keywords,quality_score after saving a draft to close coverage gaps:
GET /api/agent/v1/copywriter/jobs/:id/artifacts?include=word_count_target,keywords,quality_score&keyword_limit=50&keyword_offset=0keywords includes each recommendation’s name, source, importance,
covered, usage_count, recommended_usage, over_optimized, ignored,
score_eligible, and verification_required. It includes saved research and
brand recommendations, not just brief entities. Ignored rows remain visible but
do not count toward the score. Topic and research-only guidance may also be
visible without being score eligible; do not treat a verification-required
service/claim as permission to write it as a confirmed client fact.
keyword_checklist reports total/covered counts and limit, offset,
has_more, next_offset. Keep paging until has_more is false (limit 1–100,
default 50). Coverage/counts are null before drafting, not a failing score.
This is the unfiltered saved project: unsaved editor drafts, browser-local
custom keywords, and UI search/sort filters are not included. Checklist totals
can differ from score-eligible totals for that reason and for ignored/guidance rows.
score.editor_breakdown returns model: "coverage_placement_v2",
calculation_state: "available", coverage and placement scores (each out of
100), weights 0.85/0.15, scored keyword totals, and individual placement checks.
These are derived read-only using the same deterministic editor scorer for the
saved body; score.freshness_state is current and revisions match that body.
The separate seven-category categories/category_details contract is unchanged.
calculation_state: "categories_unavailable" does not mean the editor breakdown
is missing. Do not invent seven-category values from the editor’s overall score.
If research/score inputs are absent, existing fallback score provenance remains
stale/unverified as appropriate and no breakdown is invented.
These reads do not regenerate research, approve a brief, queue work, write
scores or drafts, or consume provider credits. Both REST and MCP keep the
existing copywriter:read permission and tenant checks.
Structured formats: ?format=blocks and ?format=gutenberg
Section titled “Structured formats: ?format=blocks and ?format=gutenberg”The artifacts endpoint also serves the article content as a typed block contract so integrators don’t have to re-parse HTML. Pass a format query parameter:
GET /api/agent/v1/copywriter/jobs/:id/artifacts?format=blocksGET /api/agent/v1/copywriter/jobs/:id/artifacts?format=gutenbergAuthorization: Bearer rk_live_...Same auth (copywriter:read), same rate limits. When format is absent the response is exactly the standard artifacts payload shown above — nothing changes for existing callers.
format=blocks — Response (200):
{ "job_id": "uuid", "format": "blocks", "contract_version": 1, "parser_version": "2026-07-08.1", "blocks_json": { "contract_version": 1, "parser_version": "2026-07-08.1", "kind": "article", "generated_at": "2026-07-08T12:00:00.000Z", "meta": { "title": "Emergency Plumber St. Louis | 24/7 Licensed Service", "slug": "emergency-plumber-st-louis", "meta_description": "Need an emergency plumber in St. Louis? ..." }, "blocks": [ { "type": "heading", "level": 1, "text": "Emergency Plumber St. Louis", "html": "<h1>Emergency Plumber St. Louis</h1>" }, { "type": "rich_text", "html": "<p>When a pipe bursts...</p><ul><li>...</li></ul>" }, { "type": "image", "src": "https://...", "alt": "Technician fixing a pipe", "caption": "Optional caption" }, { "type": "raw_html", "html": "<table>...</table>" } ] }}Block contract (v1, additive-only — new optional fields may appear without a version bump; removals/retypes bump contract_version):
| Block type | Fields | Notes |
|---|---|---|
heading |
level (1–6), text (plain), html (inline formatting kept) |
Every h1–h6 is its own block |
rich_text |
html |
ALL flow content between headings coalesced into ONE block (never per-paragraph) |
image |
src, alt, caption? |
Images break out as standalone blocks, even mid-paragraph |
raw_html |
html |
Tables / embeds / iframes / script-dependent content, verbatim — never mangled |
The sequence is ordered and lossless: concatenating the blocks reproduces the article’s full text content.
Copy-pasteable example — fetch blocks, loop, map to your target CMS:
import requests
BASE = "https://app.rankability.com/api/agent/v1"HEADERS = {"Authorization": "Bearer rk_live_..."}
r = requests.get(f"{BASE}/copywriter/jobs/{job_id}/artifacts", params={"format": "blocks"}, headers=HEADERS)payload = r.json()assert payload["contract_version"] == 1 # pin the contract you coded against
for block in payload["blocks_json"]["blocks"]: if block["type"] == "heading": cms.add_heading(level=block["level"], html=block["html"]) elif block["type"] == "rich_text": cms.add_rich_text(html=block["html"]) elif block["type"] == "image": cms.add_image(src=block["src"], alt=block["alt"], caption=block.get("caption")) elif block["type"] == "raw_html": cms.add_embed(html=block["html"]) else: # Additive contract: treat unknown block types as raw HTML if present if block.get("html"): cms.add_embed(html=block["html"])format=gutenberg — Response (200):
{ "job_id": "uuid", "format": "gutenberg", "contract_version": 1, "content": "<!-- wp:heading {\"level\":1} -->\n<h1 class=\"wp-block-heading\">Emergency Plumber St. Louis</h1>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph -->\n<p>When a pipe bursts...</p>\n<!-- /wp:paragraph -->"}content is the deterministic WordPress Gutenberg comment-delimited block markup serialized from the same blocks contract — paste it into a WordPress post (code editor view) or send it via the WordPress REST API as post content and it opens as native, editable blocks.
| Error | When |
|---|---|
400 invalid_input |
Unknown format value |
409 not_ready |
Job not completed yet (including stepped-mode brief_ready) |
format=elementor is NOT offered. Raw Elementor data without its postmeta, media sideloading, and CSS regeneration produces broken pages. Elementor sites should publish through the Rankability WordPress plugin instead — it detects the layout builder and delivers clean HTML the builder renders correctly in its own widgets.
Scopes required: copywriter:read
Approve brief (stepped mode)
Section titled “Approve brief (stepped mode)”POST /api/agent/v1/copywriter/jobs/:id/approveAuthorization: Bearer rk_live_...Approves the brief and triggers draft generation. Only valid for stepped-mode jobs in brief_ready status.
Response (200):
{ "job_id": "uuid", "status": "generating_draft", "brief_approved": true, "approved_at": "2026-02-25T15:35:00.000Z"}| Error | When |
|---|---|
400 invalid_operation |
Job is in auto mode |
409 already_approved |
Brief already approved |
409 not_ready |
Brief not yet generated |
Scopes required: copywriter:run
Replace draft on existing project
Section titled “Replace draft on existing project”PUT /api/agent/v1/copywriter/jobs/:id/draftAuthorization: Bearer rk_live_...Content-Type: application/jsonReplaces generated_draft on an existing copywriter project with a pre-written body. Useful when you’ve iterated on a draft outside Rankability (in a CMS, a writer’s doc, or another tool) and want to push the new copy back without deleting and recreating the project — project metadata (topic, client, tone, brief, exclusions, share token, …) is preserved.
No AI is invoked, no credits are reserved or deducted. The word count is recomputed from the supplied body. Rankability score, category scores, editorial review, and the score/review content hashes are cleared so the next access re-scores against the new content; previously-applied or dismissed editorial edits are reset.
Request body:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
draft_body |
string | Yes | — | Replacement draft content. Max length: 500,000 characters. Cannot be empty or whitespace-only. |
draft_format |
enum | No | "markdown" |
Format of draft_body: markdown or html. The exact body and format you send are preserved and returned unchanged by GET /jobs/:id/artifacts and the matching /export/markdown or /export/html route. |
Example:
{ "draft_body": "# How to fix a leaky faucet (v2)\n\nUpdated guide with new diagrams...", "draft_format": "markdown"}Response (200):
{ "job_id": "uuid", "status": "completed", "draft": { "format": "markdown", "word_count": 1342 }, "replaced_at": "2026-05-08T15:30:00.000Z"}After the call, the project’s status is complete and briefApproved is true. The new body is returned by GET /jobs/:id/artifacts (under draft.content) and the /export/{markdown,html} routes, exactly as supplied.
| Error | When |
|---|---|
400 invalid_input |
Missing/empty draft_body, body too long, or markdown that fails to parse |
404 not_found |
Job does not exist or belongs to a different organization |
409 job_in_progress |
Job is still analyzing or generating_draft; wait for it to settle before re-uploading |
Scopes required: copywriter:run
This endpoint is also available through the Serena bridge as PUT /api/serena/v1/copywriter/jobs/:id/draft (action: copywriter.draft.replace).
Start an Autopilot run
Section titled “Start an Autopilot run”POST /api/agent/v1/copywriter/autopilotAuthorization: Bearer rk_live_...Content-Type: application/jsonIdempotency-Key: my-unique-key (optional)Autopilot is the fully-orchestrated, one-shot pipeline: research → auto-approved brief → draft → automatic optimize passes → fact-check → final review summary. It costs a flat 750 credits, charged once a usable draft exists. A run that fails before producing a draft is not charged. Images remain user-selected in the editor.
Request body:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
topic |
string | Yes | — | Topic/keyword to create content for |
intent |
enum | No | "educate" |
educate, discover, compete, or convert |
page_contract |
enum | Yes | — | article or commercial_service. The explicit choice is persisted before the flat credit reservation. |
client_id |
UUID | Yes | — | Client workspace to scope the run to (must belong to your org). Required so drafts inherit the client’s brand voice, knowledge base sources, and excluded topics. Find valid ids with GET /api/agent/v1/clients. Omitting it returns 400 invalid_input. |
context |
string | No | — | Free-form steering context (max 2,000 chars) threaded into the brief and draft |
language |
string | No | "en" |
Content language code |
location |
string | No | — | Target location for geo-specific content. A conflict with saved workspace service-area knowledge returns 409 before credits or allowance are reserved. |
location_lat / location_lng |
number | No | — | Optional target coordinates |
allow_location_conflict |
boolean | No | false |
Set to true only after reviewing a location_conflict response and confirming the different market is intentional. |
research_platforms |
string[] | No | Google Organic | Same values and fixed-price semantics as /copywriter/jobs |
If you send an Idempotency-Key header and a project with that key already exists in your organization, the existing run is returned with a 200 instead of creating a duplicate.
Response (202):
{ "job_id": "uuid", "status": "queued", "stage": "researching", "flat_credits": 750, "created_at": "2026-07-07T12:00:00.000Z"}| Error | When |
|---|---|
400 invalid_input |
Missing/invalid topic, missing client_id, or malformed body |
402 subscription_required |
Organization has no active subscription |
402 insufficient_credits |
Not enough credits for the flat run price |
404 not_found |
client_id does not belong to your organization, or Autopilot is disabled by the operator kill-switch |
409 location_conflict |
Target location differs from the workspace’s saved service area; correct it or explicitly acknowledge the returned conflict |
503 service_unavailable |
Queue service unavailable |
Scopes required: copywriter:run
Poll Autopilot status
Section titled “Poll Autopilot status”GET /api/agent/v1/copywriter/autopilot/:idAuthorization: Bearer rk_live_...Returns the live orchestration state. New runs progress through queued, researching, briefing, drafting, optimizing, fact_checking, finalizing, then complete or failed. Older persisted runs can still report an image stage. Poll until stage is complete or failed, then fetch the finished draft with GET /copywriter/jobs/:id/artifacts (the Autopilot job_id is a regular copywriter job id).
Response (200):
{ "job_id": "uuid", "status": "complete", "stage": "complete", "started_at": "2026-07-07T12:00:00.000Z", "updated_at": "2026-07-07T12:14:05.000Z", "completed_at": "2026-07-07T12:14:05.000Z", "optimize_passes": 2, "optimize_pass_cap": 3, "charged": true, "released": false, "error": null, "review": { "verdict": "ready", "summary": "...", "flags": [] }, "publish": { "status": "idle", "heldReason": null, "error": null, "pushedAt": null }}review is the final editorial review summary (claims needing citations are reconciled against the current draft content). charged flips to true when the flat price is deducted (usable draft produced); released is true when a failed run’s reservation was returned.
Scopes required: copywriter:read
Example: full auto-mode workflow
Section titled “Example: full auto-mode workflow”import requestsimport time
BASE = "https://your-app.replit.app/api/agent/v1"HEADERS = { "Authorization": "Bearer rk_live_your_key_here", "Content-Type": "application/json"}
# 1. Create jobresp = requests.post(f"{BASE}/copywriter/jobs", headers=HEADERS, json={ "client_id": "uuid", "topic": "emergency plumber st louis", "intent": "convert", "page_contract": "commercial_service", "mode": "auto", "location": "St. Louis, MO", "word_count_target": 1200})job_id = resp.json()["job_id"]
# 2. Poll until completedwhile True: status = requests.get(f"{BASE}/copywriter/jobs/{job_id}", headers=HEADERS).json() print(f"Status: {status['status']} — {status.get('progress', {}).get('stage', '')}") if status["status"] == "completed": break if status["status"] == "failed": raise Exception(f"Job failed: {status.get('error')}") time.sleep(10)
# 3. Get artifactsartifacts = requests.get(f"{BASE}/copywriter/jobs/{job_id}/artifacts", headers=HEADERS).json()print(f"Draft: {artifacts['draft']['word_count']} words")print(f"Title: {artifacts['seo']['title_tag']}")print(f"Score: {artifacts['score']['overall']}")Example: iterate on a draft externally
Section titled “Example: iterate on a draft externally”A common workflow is to generate a draft in Rankability, pull it into your own editor (a CMS, a writer’s doc, a script), make changes, and push the new copy back into the same project — preserving the topic, client, brief, exclusions, share token, and any history attached to it. Use GET /jobs/:id/export/markdown (or /html) to pull, then PUT /jobs/:id/draft to push the edited body back.
BASE="https://your-app.replit.app/api/agent/v1"KEY="rk_live_your_key_here"JOB_ID="00000000-0000-0000-0000-000000000000"
# 1. Pull the current draft as markdowncurl -s "$BASE/copywriter/jobs/$JOB_ID/export/markdown" \ -H "Authorization: Bearer $KEY" \ -o draft.md
# 2. Edit draft.md externally (CMS, editor, script, AI pass, …)
# 3. Push the edited body back into the same projectcurl -s -X PUT "$BASE/copywriter/jobs/$JOB_ID/draft" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ --data "$(jq -Rs '{draft_body: ., draft_format: "markdown"}' draft.md)"The response includes the new word_count and a replaced_at timestamp. After the call, GET /jobs/:id/artifacts and the /export/{markdown,html} routes return the body you just uploaded, byte-for-byte.
Python
Section titled “Python”import requests
BASE = "https://your-app.replit.app/api/agent/v1"HEADERS = {"Authorization": "Bearer rk_live_your_key_here"}JOB_ID = "00000000-0000-0000-0000-000000000000"
# 1. Pull the current draft as markdowncurrent = requests.get( f"{BASE}/copywriter/jobs/{JOB_ID}/export/markdown", headers=HEADERS,).text
# 2. Edit externally — here we just append a new section as a stand-inedited = current + "\n\n## Updated FAQ\n\n**Q: Is this re-uploadable?**\nYes — PUT /draft replaces the body in place.\n"
# 3. Push the edited body back into the same projectresp = requests.put( f"{BASE}/copywriter/jobs/{JOB_ID}/draft", headers={**HEADERS, "Content-Type": "application/json"}, json={"draft_body": edited, "draft_format": "markdown"},)resp.raise_for_status()print(resp.json())# {"job_id": "...", "status": "completed", "draft": {"format": "markdown", "word_count": 1378}, "replaced_at": "..."}Tips:
- The format you send is the format that’s preserved. Send
draft_format: "html"with an HTML body if you’d rather round-trip HTML — the matching/export/htmlwill return it unchanged. PUT /draftonly works when the project has settled into a terminal state. If the job is stillanalyzingorgenerating_draft, the call returns409 job_in_progress— wait for it to reachcompleted(orerror) before re-uploading.- No credits are charged for the re-upload — only the original generation consumed credits.
- To run optimization scoring on the newly uploaded draft, create a separate Optimize-mode job pointing at the published URL once the content is live.
Getting started
Section titled “Getting started”1. Generate an API key
Section titled “1. Generate an API key”Go to Settings > API keys in the Rankability app (requires admin role; available on all plans). Click “Create API key”, give it a name, select scopes, and copy the key. You will only see the full key once.
Alternatively, use the key management API endpoint:
curl -X POST https://app.rankability.com/api/agent/v1/keys \ -H "Content-Type: application/json" \ -b "your-clerk-session-cookie" \ -d '{ "name": "Claude Integration", "scopes": ["copywriter:run", "copywriter:read"] }'2. Create a content job
Section titled “2. Create a content job”curl -X POST https://app.rankability.com/api/agent/v1/copywriter/jobs \ -H "Authorization: Bearer rk_live_YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{ "client_id": "uuid", "topic": "best crm for small business", "intent": "discover", "page_contract": "article", "mode": "auto" }'3. Poll until complete
Section titled “3. Poll until complete”curl https://app.rankability.com/api/agent/v1/copywriter/jobs/JOB_ID \ -H "Authorization: Bearer rk_live_YOUR_KEY_HERE"4. Get the finished content
Section titled “4. Get the finished content”curl https://app.rankability.com/api/agent/v1/copywriter/jobs/JOB_ID/artifacts \ -H "Authorization: Bearer rk_live_YOUR_KEY_HERE"Using with Claude or other AI tools
Section titled “Using with Claude or other AI tools”Give the AI tool two things:
- Your API key (
rk_live_...) - Your base URL (
https://app.rankability.com/api/agent/v1)
The tool can then create content jobs, poll for completion, and retrieve the finished article with SEO metadata, FAQ schema, and a quality score — all programmatically.
Supported languages
Section titled “Supported languages”The language field controls four things: SERP results language, brief generation language, draft writing language, and entity extraction language. When set to a non-English value (e.g., "he"), the entire pipeline — headings, title tag, meta description, entities, FAQs, and draft — will be generated in that language.
Special values
Section titled “Special values”| Code | Behavior |
|---|---|
"auto" |
Auto-detect: uses English for SERP queries, no forced language instruction in prompts. The AI writes naturally based on topic context. |
"none" |
No language targeting: same behavior as "auto". |
Language codes
Section titled “Language codes”| Code | Language | Code | Language | |
|---|---|---|---|---|
en-US |
English (US) | ja |
Japanese | |
en-GB |
English (UK) | ko |
Korean | |
ar |
Arabic | ms |
Malay | |
bn |
Bengali | no |
Norwegian | |
zh |
Chinese | pl |
Polish | |
cs |
Czech | pt |
Portuguese | |
da |
Danish | ro |
Romanian | |
nl |
Dutch | ru |
Russian | |
tl |
Filipino | es |
Spanish | |
fi |
Finnish | sv |
Swedish | |
fr |
French | th |
Thai | |
de |
German | tr |
Turkish | |
el |
Greek | uk |
Ukrainian | |
he |
Hebrew | vi |
Vietnamese | |
hi |
Hindi | |||
hu |
Hungarian | |||
id |
Indonesian | |||
it |
Italian |
Base codes like "en" are also accepted and treated as "en-US".
Copywriter — Entity-only research (canary)
Section titled “Copywriter — Entity-only research (canary)”Enabled organizations can run competitor research and retrieve prioritized entities without generating an outline or draft. This uses the same canonical Copywriter projects and research queue as the content workflow. During the canary, excluded organizations receive 404; reconnecting or retrying does not enable the feature.
POST /entities/jobs requires copywriter:run, an owned client, an active eligible plan, and a stable Idempotency-Key header. Consult GET /usage first: entity-only work follows the existing Quick/Optimize usage contract. Hosted MCP exposes extract_entities with its existing paid-work confirmation requirement and get_entity_research for retrieval.
{ "client_id": "11111111-1111-4111-8111-111111111111", "topics": ["HVAC company", "Air conditioning repair", "Furnace repair"], "location": "Ballwin, Missouri", "content_intent": "business_page", "language": "en", "research_platforms": ["organic", "ai_overview", "ai_mode", "perplexity", "chatgpt", "grok", "gemini", "brave", "claude"]}Supply exactly one topic or a topics list of 1–5 distinct topics. Each topic receives its own research job. Optional content_intent accepts business_page, educational, comparison, or research; explicit intent takes precedence over inference. Optional location supplies query context without requiring a Places coordinate.
The 202 response contains jobs, requested_topics, and partial. After partial acceptance, retain the returned IDs and retry the exact request with the same idempotency key: accepted jobs are reused and only unaccepted topics start. Changing the request under an existing key returns an idempotency conflict.
GET /entities/jobs/:job_id requires copywriter:read and returns queued, running, complete, or failed. Completed results contain ordered core/supporting entities, relevance, aliases, source URLs/excerpts/text offsets, topic coverage, and source coverage. Discovered citations are separate from successfully captured and accepted sources. requires_revalidation identifies readable historical research that must be reviewed before new writing. Display entities and writing_entities can differ when a concept lacks permission for a client-specific claim. The getter does not run providers, mutate the report, or create a draft.
Copywriter — Queue Status
Section titled “Copywriter — Queue Status”GET /api/agent/v1/copywriter/queue/status
Returns the current health of the research and draft queues — including global queue depth, number of active workers, your organization’s queued job count and estimated position, and any active service alerts. Use this endpoint to monitor queue congestion without polling individual job statuses.
Scope required: copywriter:read
Response (200)
Section titled “Response (200)”{ "research": { "queue_depth": 4, "active": 1, "org_queued_count": 2, "org_position": 3, "estimated_wait_minutes": 9 }, "draft": { "queue_depth": 1, "active": 1, "org_queued_count": 0, "org_position": null, "estimated_wait_minutes": null }, "service_alerts": [], "retrieved_at": "2026-04-30T12:00:00.000Z"}Response field reference
Section titled “Response field reference”| Field | Type | Description |
|---|---|---|
research.queue_depth |
integer | Total jobs currently waiting in the research queue (global, across all orgs) |
research.active |
integer | Number of research jobs currently being processed |
research.org_queued_count |
integer | Number of research jobs your org has in the queue right now |
research.org_position |
integer | null | Your org’s position in the global research queue. null if your org has no queued research jobs |
research.estimated_wait_minutes |
integer | null | Estimated minutes until your org’s first research job starts, based on your org’s position and a 3-minute median duration per position. null if your org has no queued research jobs |
draft.queue_depth |
integer | Total jobs currently waiting in the draft queue (global, across all orgs) |
draft.active |
integer | Number of draft jobs currently being processed |
draft.org_queued_count |
integer | Number of draft jobs your org has in the queue right now |
draft.org_position |
integer | null | Your org’s position in the global draft queue. null if your org has no queued draft jobs |
draft.estimated_wait_minutes |
integer | null | Estimated minutes until your org’s first draft job starts, based on your org’s position and a 2-minute median duration per position. null if your org has no queued draft jobs |
service_alerts |
string[] | Human-readable alerts about service disruptions. Non-empty when a queue is paused and new jobs will not be processed until the queue resumes |
retrieved_at |
ISO 8601 string | UTC timestamp of when this snapshot was taken |
org_positionandestimated_wait_minutesarenullwhen your org has no jobs in the queue — they are only populated when there is work to track.org_positionis a best-effort estimate derived by scanning up to the first 50 waiting jobs in the queue. On heavily backlogged queues the actual position may be higher; treat it as an approximate indicator rather than an exact rank.- Wait time estimates assume a median processing time per position (3 min for research, 2 min for draft) and are approximate.
- When
service_alertsis non-empty, your jobs remain queued but will not be processed until the disruption is resolved. Monitor this field to detect platform-wide issues. - This endpoint has the same per-key rate limit as all other agent endpoints (see Rate limits). Polling every 30–60 seconds is sufficient for most use cases.
Copywriter — List Jobs
Section titled “Copywriter — List Jobs”GET /api/agent/v1/copywriter/jobs
List all copywriter jobs for your organization, with optional filtering.
Scope required: copywriter:read
Query parameters
Section titled “Query parameters”| Parameter | Type | Description |
|---|---|---|
client_id |
string (UUID) | Filter by client |
status |
string | Filter by status (e.g., completed, researching, brief_ready, failed). Raw internal statuses (complete, analyzing, error, …) are accepted for back-compat. |
limit |
integer | Max results (default 50, max 100) |
offset |
integer | Pagination offset (default 0) |
Response
Section titled “Response”{ "jobs": [ { "job_id": "uuid", "topic": "Best SEO tools 2025", "status": "completed", "marked_complete": false, "marked_complete_at": null, "content_type": null, "client_id": "uuid", "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:30:00.000Z" } ], "pagination": { "limit": 50, "offset": 0, "count": 1, "total": 1 }}Each job includes the same completion flag/date as the detail endpoint. A
status=completed filter selects generation-completed jobs, not only projects
marked Done; use each job’s marked_complete flag to identify Done projects.
Copywriter — Delete Job
Section titled “Copywriter — Delete Job”DELETE /api/agent/v1/copywriter/jobs/:id
Permanently delete a copywriter job/project.
Scope required: copywriter:run
Response
Section titled “Response”{ "job_id": "uuid", "deleted": true}Copywriter — Export Content
Section titled “Copywriter — Export Content”GET /api/agent/v1/copywriter/jobs/:id/export/:format
Export a completed job’s draft content in the specified format.
Scope required: copywriter:read
Path parameters
Section titled “Path parameters”| Parameter | Values | Description |
|---|---|---|
format |
markdown, html |
Export format |
Response
Section titled “Response”Returns the content as a file download with appropriate Content-Type and Content-Disposition headers.
markdown:text/markdownwith.mdextensionhtml:text/htmlwith.htmlextension (includes full HTML document structure with SEO meta tags)
Errors
Section titled “Errors”| HTTP | Code | Description |
|---|---|---|
| 400 | invalid_input |
Unsupported export format |
| 400 | invalid_operation |
No draft content to export (job must be completed) |
