Skip to content

Copywriter: content jobs

Create SEO content in auto, stepped or Autopilot mode, poll status, fetch artifacts, edit drafts externally and export.

The API supports three ways to populate a Copywriter project:

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 → completed

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 → completed

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: completed

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

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.

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
  1. The caller confirms page_contract (article or commercial_service)
  2. Within that contract, the API runs heuristic pattern matching on the topic and intent
  3. 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)
  4. The confirmed contract, validated template, confidence/provenance, and extracted metadata are stored on the project
  5. The research and draft workers use this metadata to generate template-specific content

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.

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 /keys endpoints 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.

POST /api/agent/v1/keys

Request 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 key field contains the full plaintext API key. It is only returned once — store it securely.

GET /api/agent/v1/keys

Response (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"
}
]
}
DELETE /api/agent/v1/keys/:id

Response (200):

{
"id": "uuid",
"revoked": true,
"revoked_at": "2026-02-25T16:00:00.000Z"
}

Returns 404 if key not found, 409 if already revoked.


These endpoints use Bearer token authentication.

POST /api/agent/v1/copywriter/jobs
Authorization: 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-123

Response (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

GET /api/agent/v1/copywriter/jobs/:id
Authorization: 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.

PATCH /api/agent/v1/copywriter/jobs/:id
Authorization: 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
GET /api/agent/v1/copywriter/jobs/:id/keyword-exclusions

Read 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"
}
PATCH /api/agent/v1/copywriter/jobs/:id/keyword-exclusions

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

GET /api/agent/v1/clients/:id/keyword-exclusions

Read 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.
PATCH /api/agent/v1/clients/:id/keyword-exclusions

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

GET /api/agent/v1/copywriter/jobs/:id/artifacts
Authorization: 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=0

keywords 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=blocks
GET /api/agent/v1/copywriter/jobs/:id/artifacts?format=gutenberg
Authorization: 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

POST /api/agent/v1/copywriter/jobs/:id/approve
Authorization: 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

PUT /api/agent/v1/copywriter/jobs/:id/draft
Authorization: Bearer rk_live_...
Content-Type: application/json

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

POST /api/agent/v1/copywriter/autopilot
Authorization: Bearer rk_live_...
Content-Type: application/json
Idempotency-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

GET /api/agent/v1/copywriter/autopilot/:id
Authorization: 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

import requests
import time
BASE = "https://your-app.replit.app/api/agent/v1"
HEADERS = {
"Authorization": "Bearer rk_live_your_key_here",
"Content-Type": "application/json"
}
# 1. Create job
resp = 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 completed
while 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 artifacts
artifacts = 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']}")

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.

Terminal window
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 markdown
curl -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 project
curl -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.

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 markdown
current = 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-in
edited = 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 project
resp = 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/html will return it unchanged.
  • PUT /draft only works when the project has settled into a terminal state. If the job is still analyzing or generating_draft, the call returns 409 job_in_progress — wait for it to reach completed (or error) 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.

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:

Terminal window
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"]
}'
Terminal window
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"
}'
Terminal window
curl https://app.rankability.com/api/agent/v1/copywriter/jobs/JOB_ID \
-H "Authorization: Bearer rk_live_YOUR_KEY_HERE"
Terminal window
curl https://app.rankability.com/api/agent/v1/copywriter/jobs/JOB_ID/artifacts \
-H "Authorization: Bearer rk_live_YOUR_KEY_HERE"

Give the AI tool two things:

  1. Your API key (rk_live_...)
  2. 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.

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.

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

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

{
"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"
}
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_position and estimated_wait_minutes are null when your org has no jobs in the queue — they are only populated when there is work to track.
  • org_position is 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_alerts is 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.

GET /api/agent/v1/copywriter/jobs

List all copywriter jobs for your organization, with optional filtering.

Scope required: copywriter:read

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

DELETE /api/agent/v1/copywriter/jobs/:id

Permanently delete a copywriter job/project.

Scope required: copywriter:run

{
"job_id": "uuid",
"deleted": true
}

GET /api/agent/v1/copywriter/jobs/:id/export/:format

Export a completed job’s draft content in the specified format.

Scope required: copywriter:read

Parameter Values Description
format markdown, html Export format

Returns the content as a file download with appropriate Content-Type and Content-Disposition headers.

  • markdown: text/markdown with .md extension
  • html: text/html with .html extension (includes full HTML document structure with SEO meta tags)
HTTP Code Description
400 invalid_input Unsupported export format
400 invalid_operation No draft content to export (job must be completed)