API & MCP

Use your Deft bearer API key to identify your account and load your saved Copyeditor preferences. Copyeditor costs $0.10 per 1,000 submitted input tokens ($100 per million), rounded up to the nearest cent per run. It uses API credits and accepts up to 10,000 words and 10 MiB of UTF-8 text. Credits are reserved when you submit and charged once the edited result is ready. Failed analyses are not charged. Alternative selections are included. Keep the key on your server.

Create an API key and add credits in Account. The key owner is the user identifier; do not send an email or user ID. API credits are separate from website subscriptions and free daily allowances. Input must contain at least 20 characters. Tokens are counted once from the canonical source using the bundled Qwen3 tokenizer, with a one-cent minimum.

For drafting new copy, use /v1/generate with prompt. For a full rewrite, also send generationMode: "rewrite" and optional rewriteInstructions. Those calls use generation pricing. Copyeditor takes sourceText and returns individual edit choices.

Quick start: submit and choose

Run this example on your server with Node.js 18 or later and DEFT_API_KEY set. The request stays open while the document is analyzed and returns the reviewable result. For safe retries, send an Idempotency-Key header with a persisted unique ID per run (1–200 printable ASCII characters, no spaces). Reusing the same key and canonical source returns the finished result without another model call or charge. An in-flight replay returns 409 request_in_progress. Different source text with that key returns 409 idempotency_conflict. Keys are account-scoped and retained for the session’s lifetime. Without a key, resubmitting starts another paid run.

// Node.js 18+. Set DEFT_API_KEY in your server environment.
const baseUrl = "https://deftwriting.com";
const headers = {
  Authorization: `Bearer ${process.env.DEFT_API_KEY}`,
  "Content-Type": "application/json",
};
async function api(path, body) {
  const response = await fetch(new URL(path, baseUrl), {
    method: body === undefined ? "GET" : "POST",
    headers,
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  const data = await response.json();
  if (!response.ok) {
    throw new Error(JSON.stringify({ status: response.status, body: data }));
  }
  return data;
}

// Optional: set a persisted unique ID per intended run for safe retries.
// headers["Idempotency-Key"] = process.env.DEFT_COPYEDIT_REQUEST_ID;
// The request returns when request-bound analysis reaches review.
const run = await api("/v1/copyedit", {
  sourceText: "The documents is ready for review.",
});
console.log(run.result.text); // All proposed corrections applied by default.

// Optional automation: follow available recommendations; keep uncertain edits.
const selections = run.result.edits.map(choice => ({
  editId: choice.editId,
  optionId: choice.recommendationAvailable ? choice.recommendedOptionId : "keep",
}));
const selected = await api(`/v1/copyedit/${run.sessionId}/resolve`, { selections });
console.log(JSON.stringify(selected, null, 2)); // Full response and selected draft.

Endpoint reference

POST /v1/copyedit
Authorization: Bearer <DEFT_API_KEY>
Content-Type: application/json

{"sourceText":"The documents is ready for review."}

// 200: { sessionId, userId, status: "review", usage, result }
// The request stays open until analysis finishes.
// result contains:
// sourceText, text, offsetEncoding: "utf-16", edits
// Each choice: editId, start, end, original, category,
// consensus, recommendationAvailable, recommendedOptionId,
// defaultOptionId, selectedOptionId, options
// Each option: id, text, rationale

POST /v1/copyedit/<sessionId>/resolve
Authorization: Bearer <DEFT_API_KEY>
Content-Type: application/json

{"selections":[{"editId":"<returned-edit-id>","optionId":"keep"}]}

The returned text applies every proposed correction, including proposals recommended for rejection. Conflicts use the selected replacement, or option A if none was selected. Choices include keep, apply, and both A/B alternatives when present. Offsets address the returned canonical sourceText in UTF-16, with an exclusive end. Resolve accepts returned option IDs and uses defaults for omitted edits. It makes no model calls, saves no completion, and does not train preferences.

POST /v1/copyedit/<sessionId>/complete
Authorization: Bearer <DEFT_API_KEY>
Content-Type: application/json

{
  "decisions": [{ "editId": "<returned-edit-id>", "decision": "accept" }],
  "finalText": "The author-reviewed final document.",
  "idempotencyKey": "completion-unique-1"
}

Each choice includes recommendedOptionId, defaultOptionId,selectedOptionId, and recommendationAvailable, plus each option’s replacement text and rationale. The example follows recommendations when available and keeps the original text otherwise. Send an empty selections array to restore the all-applied defaults. Resolve returns every option again so you can try another policy without paying for another analysis.

Usage contains only input_tokens and rate_usd_per_1000_tokens(0.1 USD). Input tokens count the canonical source actually charged, once per run; the count is zero for failed analyses and website sessions. Resolve repeats the original charge without charging again. No output or thinking tokens, credit amounts, totals, or internal billing state appear in usage. A 402 insufficient_credits response means the available balance cannot cover the quote. Unknown or duplicate edit IDs and invalid option IDs return 400; resolving before review returns 409. Another owner’s session returns 404. API errors contain error.code anderror.message.

Response: edited text and all edit options

This illustrative response excerpt shows result.edits, the complete list of proposed edits, including automatically applied edits and recommendations to reject. An unchanged document returns an empty list. Each edit includes every available option’s ID, text, and rationale. Conflicts include keep, A, and B. Actual edit IDs and token counts vary. Resolve retains the full edits list.

{
  "sessionId": "11111111-1111-4111-8111-111111111111",
  "status": "review",
  "usage": {
    "input_tokens": 7,
    "rate_usd_per_1000_tokens": 0.1
  },
  "result": {
    "sourceText": "The documents is ready for review.",
    "text": "The documents are ready for review.",
    "offsetEncoding": "utf-16",
    "edits": [
      {
        "editId": "edit-1",
        "start": 14,
        "end": 16,
        "original": "is",
        "category": "agreement",
        "consensus": true,
        "recommendationAvailable": true,
        "recommendedOptionId": "apply",
        "defaultOptionId": "apply",
        "selectedOptionId": "apply",
        "options": [
          {
            "id": "keep",
            "text": "is",
            "rationale": "Keep the original text."
          },
          {
            "id": "apply",
            "text": "are",
            "rationale": "Use a plural verb with documents."
          }
        ]
      }
    ]
  }
}

Creation uses your key’s request limit; resolve permits 60 requests per minute per key. Honor Retry-After on 429 responses. Result and billing are read in one database snapshot. After a successful result is durable, auto-recharge uses your existing account settings and cannot fail or repeat the edit. A disconnected analysis is not resumable; replay it with the same idempotency key, or submit a new paid request if the original request had no key.