API

Build against the Deft server-to-server generation API. Approval, keys, and API billing are managed from Account.

Endpoint

POST /v1/generate

Use /v1/generate for complete JSON compatibility, or POST /v1/generations and poll the returned status URL for durable long-running work. Keys are created from Account after approval.

Manage access

curl https://deftwriting.com/v1/generate   -H "Authorization: Bearer $DEFT_API_KEY"   -H "Content-Type: application/json"   -d '{"prompt":"Write a concise launch memo for a new analytics feature."}'

const response = await fetch("https://deftwriting.com/v1/generate", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.DEFT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "Write a concise launch memo for a new analytics feature.",
  }),
});

const result = await response.json();

const job = await fetch("https://deftwriting.com/v1/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.DEFT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prompt: "Write a concise launch memo." }),
}).then((response) => response.json());

// Poll job.status_url with the same bearer key until status is terminal.

Authentication

Send an approved account's API key as a bearer token. API keys are separate from website sessions and must stay server-side.

Rate limits

Keys are limited to 60 requests / 60 seconds. Back off on 429 responses and retry later.

Billing

Billing posts after a successful result is available, so credit updates never delay delivery. A posted negative balance blocks future requests. Judge and post-processing model tokens are not charged.

Best practices

Ask for complete documents

Deft was trained to produce whole samples of text from the web. Requests for full documents with the complete context and desired structure generally work best. Requesting fragments, isolated chunks, or partial continuations won't work as well as full documents.

Request

Prompt-first body

Send JSON with a non-empty prompt. Optional generationMode accepts simple, legacy prompt_optimizer, or rewrite. In rewrite mode, prompt is the source text and optional rewriteInstructions describes how to transform it.

For best results, keep inputs below an estimated 100,000 tokens. The API can accept longer prompts, but quality may degrade as inputs grow. Prompts above an estimated 150,000 tokens are rejected before preprocessing or billing.

Optional thinkingLevel accepts faster, smarter, or max. Smarter is the default.

For generate-mode requests, optional detailMode accepts strict or creative. Strict mode keeps outline details grounded in facts and context from your prompt. Creative mode may invent supporting specifics to flesh out sparse, narrative, opinion, or exploratory requests. Omit detailMode to let Deft choose the better mode for the prompt.

Optional style and styleKind fields are accepted as preprocessing guidance. The endpoint returns a complete JSON response. Streaming, user-facing model selection, temperature controls, source-material controls, and token budgeting controls are not exposed.

{
  "prompt": "Write a concise launch memo for a new analytics feature.",
  "thinkingLevel": "max",
  "detailMode": "strict"
}

{
  "prompt": "Write a concise launch memo for a new analytics feature.",
  "thinkingLevel": "faster"
}

{
  "generationMode": "rewrite",
  "prompt": "The source text to rewrite goes here.",
  "rewriteInstructions": "Make it shorter and less formal."
}

Response

Generated text and usage

{
  "text": "The generated draft text...",
  "usage": {
    "input_tokens": 512,
    "output_tokens": 1024,
    "thinking_tokens": 180
  }
}

text is the final Deft output.

usage reports OpenRouter preprocessing prompt tokens, Qwen/Qwen3-14B final-output tokens, and preprocessing completion plus unselected DFT candidate output as thinking tokens. Other internal evaluation and post-processing model tokens are excluded.

Operational behavior

Errors, retries, and limits

Status	Code	Action
400	invalid_json, invalid_request	Fix the JSON body.
401	missing_api_key, invalid_api_key	Send a valid bearer API key.
402	insufficient_balance	Review billing from Account.
403	api_key_revoked, api_account_disabled	Use an active key/account.
429	rate_limited	Back off for 60 seconds before retrying.
503	generation_queue_full	Retry after the response Retry-After delay.
500/502/503/504	generation_failed or upstream errors	Retry the request when safe.

Terminology

How Deft measures usage

Website generation: One completed draft created in Deft's website or console. It appears in generation history and counts toward website limits.
API token: A metering unit reported for API input, output, and thinking work. Tokens are not API keys and are not a spendable balance.
API credit: Prepaid balance used only for server-to-server API charges. API credits do not increase website generation capacity.
Subscription capacity: The monthly allowance of website generations included in a paid plan. It resets with the billing period and is separate from API credits.

API billing

Token-based API pricing

Server-to-server API calls are billed at $2.50 per million preprocessing input tokens and $12 per million final output and thinking tokens, rounded up to the nearest cent. Failed generations are not charged.

Preprocessing, final DFT output, and unselected candidate output are billable. Unselected candidate output is reported as thinking tokens; other internal evaluation and post-processing model tokens are excluded.

Charges and auto-recharge run after result delivery. A charge may take the balance negative; future requests are blocked once that negative balance is posted.

Manage billing

Rate

$2.50 per 1M input tokens; $12 per 1M output and thinking tokens

Rounding

Usage rounds up to the nearest cent.

Failures

Failed generations are not charged.