---
title: "Copywriter: content jobs"
description: "Create SEO content in auto, stepped or Autopilot mode, poll status, fetch artifacts, edit drafts externally and export."
canonical_url: "https://developers.rankability.com/guides/copywriter"
section: "Guides"
last_updated: 2026-11-14
---

# Copywriter: content jobs

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

## Execution modes

The API supports three ways to populate a Copywriter project:

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

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

### 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: 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.

## 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

| 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

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

### Examples

**Alternatives template:**
```json
{
  "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:**
```json
{
  "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):**
```json
{
  "topic": "how to improve page speed",
  "intent": "educate",
  "page_contract": "article"
}
```
Response includes `"content_type": null`. Draft follows standard article format.

## Endpoints

### 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 `/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.

#### Create API key

```
POST /api/agent/v1/keys
```

**Request body:**

```json
{
  "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):**

```json
{
  "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.

#### List API keys

```
GET /api/agent/v1/keys
```

**Response (200):**

```json
{
  "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

```
DELETE /api/agent/v1/keys/:id
```

**Response (200):**

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

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

---

### Content jobs

These endpoints use **Bearer token authentication**.

#### Create a job

```
POST /api/agent/v1/copywriter/jobs
Authorization: Bearer rk_live_...
```

**Request body:**

```json
{
  "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](#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:**

```json
{
  "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):**

```json
{
  "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](#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](/guides/usage#control-your-cost).

**Scopes required:** `copywriter:run`

#### Poll job status

```
GET /api/agent/v1/copywriter/jobs/:id
Authorization: Bearer rk_live_...
```

**Response (200):**

```json
{
  "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

```http
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):**

```json
{
  "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

```http
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):**

```json
{
  "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

```http
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:**

```json
{"ignore": ["unrelated product", "unrelated location"], "dry_run": true}
```

**Response (200):**

```json
{
  "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

```http
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. |

#### Bulk ignore or restore workspace keywords

```http
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`.

#### Retrieve artifacts

```
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:**

```json
{
  "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

`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`

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):**

```json
{
  "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:**

```python
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):**

```json
{
  "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)

```
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):**

```json
{
  "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

```
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:**

```json
{
  "draft_body": "# How to fix a leaky faucet (v2)\n\nUpdated guide with new diagrams...",
  "draft_format": "markdown"
}
```

**Response (200):**

```json
{
  "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

```
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):**

```json
{
  "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

```
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):**

```json
{
  "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

```python
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']}")
```

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

### cURL

```bash
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.

### Python

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

## Getting started

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

```bash
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

```bash
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

```bash
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

```bash
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

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.

## 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

| 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

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

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.

```json
{
  "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

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

```json
{
  "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

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

### Notes

- `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](/guides/authentication#rate-limits)). Polling every 30–60 seconds is sufficient for most use cases.

## 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

| 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

```json
{
  "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

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

Permanently delete a copywriter job/project.

**Scope required**: `copywriter:run`

### Response

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

## 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

| Parameter | Values | Description |
|---|---|---|
| `format` | `markdown`, `html` | Export format |

### Response

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)

### Errors

| HTTP | Code | Description |
|---|---|---|
| 400 | `invalid_input` | Unsupported export format |
| 400 | `invalid_operation` | No draft content to export (job must be completed) |
