Rewrite API

Rewrite jobs ask DraftFilter to return a less AI-like version of each submitted item. The result includes the original public score, the selected rewritten public score, and the selected text.

Public is_ai fields are percentages of AI-like text: 0 means 0% AI-like, and 100 means 100% AI-like. Lower rewritten_is_ai is less AI-like than a higher value.

Create a rewrite job:

POST /v1/rewrite-jobs

Request body:

{
  "idempotencyKey": "rewrite-demo-001",
  "candidateCount": 1,
  "items": [
    {
      "id": "paragraph-1",
      "text": "This comprehensive solution empowers teams to seamlessly optimize productivity."
    }
  ]
}

Rewrite request limits from the OpenAPI contract:

items: 1 to 100
item id: 1 to 128 characters
item text: 1 to 5,000 characters
total text: 100,000 characters
idempotencyKey: optional, 1 to 128 characters
candidateCount: optional, 1 to 4, default 1
scope: optional, flagged or document, default flagged
webhookUrl: optional https completion webhook (see Webhooks)

Rewrite jobs have batch parity with score jobs: up to 100 items per request. The per-item ceiling stays at 5,000 characters (the same bound as synchronous rewrites), and total text matches the score-job total.

Accepted response:

{
  "jobId": "job_000401",
  "state": "queued"
}

Successful result:

{
  "jobId": "job_000401",
  "state": "succeeded",
  "results": [
    {
      "id": "paragraph-1",
      "segmentsVersion": 2,
      "original_is_ai": 83,
      "rewritten_is_ai": 28,
      "rewrittenText": "Teams can use the update to plan work faster and spot handoff gaps sooner.",
      "segments": [
        {
          "start": 0,
          "end": 79,
          "originalText": "This comprehensive solution empowers teams to seamlessly optimize productivity.",
          "originalIsAi": 83,
          "rewrittenText": "Teams can use the update to plan work faster and spot handoff gaps sooner.",
          "rewrittenIsAi": 28,
          "changed": true
        }
      ]
    }
  ]
}

Candidate details, raw detector scores, and prompt controls are not part of the public rewrite response.

Synchronous rewrites

POST /v1/rewrites rewrites one document in a single request and response: no job polling. By default (scope: "flagged") only paragraphs containing at least one sentence the detector flags (band other than likely_human) are rewritten; every other paragraph stays byte-identical. Use scope: "document" to rewrite every paragraph. For each target paragraph the API generates candidateCount alternatives, scores them with the detector, and keeps the least AI-like option; an exact tie keeps your original paragraph. The generator receives the full document as context for tone, meaning, and cross-paragraph references.

POST /v1/rewrites

Request body:

{
  "text": "This comprehensive solution empowers teams.\n\nMy own words stay put.",
  "scope": "flagged",
  "candidateCount": 2
}

Response:

{
  "rewriteId": "rewrite_9f2c1b4a8d3e46f0a1b2c3d4e5f60718",
  "segmentsVersion": 2,
  "original": { "is_ai": 78, "band": "likely_ai", "confidence": 0.74 },
  "rewritten": { "is_ai": 21, "band": "likely_human", "confidence": 0.82 },
  "text": "Teams can plan work faster with this update.\n\nMy own words stay put.",
  "segments": [
    {
      "start": 0,
      "end": 43,
      "originalText": "This comprehensive solution empowers teams.",
      "originalIsAi": 91,
      "rewrittenText": "Teams can plan work faster with this update.",
      "rewrittenIsAi": 17,
      "changed": true
    },
    {
      "start": 43,
      "end": 45,
      "originalText": "\n\n",
      "rewrittenText": "\n\n",
      "changed": false
    },
    {
      "start": 45,
      "end": 67,
      "originalText": "My own words stay put.",
      "originalIsAi": 12,
      "rewrittenText": "My own words stay put.",
      "rewrittenIsAi": 12,
      "changed": false
    }
  ],
  "iteration": 1,
  "createdAt": "2026-07-06T00:00:00Z"
}

The segments array is an ordered, non-overlapping partition of the input: concatenating originalText over all segments reproduces your text exactly, and concatenating rewrittenText yields the rewritten document (text). segmentsVersion: 2 identifies the paragraph-granularity shape; artifacts created before this contract are version 1. Blank-line gaps between paragraphs come back as unchanged segments without scores.

Synchronous rewrite limits and errors:

text: 1 to 5,000 characters (larger: 413 rewrite_input_too_large; use POST /v1/rewrite-jobs)
scope: optional, flagged or document, default flagged
candidateCount: optional, 1 to 4, default 1
target paragraphs per request: at most 20 (more: 422 rewrite_too_many_targets; use POST /v1/rewrite-jobs)
iterations per document chain: at most 3 (more: 429 rewrite_iteration_limit)
backend outage: 503 rewrite_backend_unavailable (retryable)

The iteration cap is enforced server-side per API key: when the text you submit is the output of an earlier rewrite, the request counts as the next iteration of that document chain, and a fourth iteration is rejected. Rewrite usage meters words at 3x the scan rate, for synchronous rewrites and rewrite jobs alike.