Skip to Content

REST API

Authentication

Create a key in API keys. A paid subscription is required; trials do not qualify. Unlimited accounts are exempt. Past-due subscriptions qualify only while the configured payment grace is enabled.

Send Authorization: Bearer $INK_API_KEY on every REST request. New keys use ink_live_ in production and ink_test_ elsewhere, independently of Stripe billing mode. Existing keys with either prefix remain valid until revoked. Browser requests that change state must pass Ink's Origin and Sec-Fetch-Site checks.

Request fields

Create a rewrite with text and optional settings, mode, profile, locks and unlocks. Unknown fields at any level are rejected. Text must contain words, valid Unicode and no null characters.

  • settings.context: general (default), work, casual or academic.
  • settings.formality: auto (default), more formal or less formal.
  • settings.strength: balanced (default), light or strong.
  • settings.target_words: reserved for staff requests and ignored for other callers.
  • profile: shared (default) or an owned, ready voice profile UUID. Direct mode requires shared.
  • locks and unlocks: verbatim input strings, in rewrite mode only. Each array allows 100 strings, with 20,000 characters across both arrays and 2,000 expanded occurrences. Locks add fixed wording to fact checks. Unlocks release automatic highlights, including nested spans. Invalid edits return HTTP 400 with a field. Lock strings follow text retention.

Rewrite input allows 20,000 words; direct input allows 4,000 words. Both allow 200,000 characters. JSON bodies allow 1,204,096 bytes. Oversized requests return 413 text_too_long.

Create and poll

POST requests require a UUID Idempotency-Key. Reuse it for the same request to avoid another job or charge. Changing text, mode, profile, effective settings, locks or unlocks with the same UUID returns 409 idempotency_conflict.

HTTP 200 returns the full finished result. HTTP 202 returns only id and status. Both include a Location header for /api/v1/rewrites/{id}. Poll GET job with the same Bearer key. A job that fails during POST returns an HTTP error and Location so you can retrieve its status. There is no collection GET.

Poll every two seconds while queued or starting the model, then every second while writing, rewriting or validating. Cold starts can take a few minutes. GET returns HTTP 200 even for failed jobs. Missing or unowned jobs return 404. Guest keys cannot access another key's jobs.

DELETE job requests cancellation and returns current state. It may remain pending until the worker stops.

Response fields

queued, rewriting and validating are pending statuses. completed, completed_with_warnings and needs_review are terminal results. Review a needs_review result even when warnings is empty. failed means no usable result; cancelled means stopped.

id is the job UUID. output and change_summary appear when available. warnings contains code, message, missing and optional missing_count. Deliver output with its warnings; do not retry automatically on details_added, first_person_added or sections_kept.

On details_added, deliver the output with its warning listing added details. The message is "Check added details before use: ...". On first_person_added, deliver the output with its warning listing added first-person words. The message is "Added first-person wording: ..." or, when the list is absent, "Added first-person wording. Check the rewrite.".

input_words counts input. charged_words is the net ledger charge after refunds; refunded_words appears when words were refunded. created_at and finished_at are ISO timestamps; unfinished jobs have a null finish time. Failed jobs include error with code and message.

blocks is an ordered array of completed index and text previews. progress contains phase, blocks_done and blocks_total. Phase is queued, starting_model, writing, rewriting, validating or null when finished. Missing indices are pending. Partial blocks are not final output; warnings and summaries are final only.

Lock-aware retained results can include fact_report with total, kept, groups and changed. Groups have type, total and kept; changed facts have text and type. See retention for fields that disappear after text expiry.

First-person wording

The first-person rule applies to the new rewrite policy. Personal narration anywhere in the whole source disables first-person prevention and checking. Code, contacts and active template placeholders are excluded. Straight or curly double quotes and Markdown blockquotes mark quotations; single quotes do not. Pronouns and contractions are matched case-insensitively, including lowercase i, apart from list and index syntax. A standalone I is a numeral only after a numbering word or name, such as World War, Phase, Part, Chapter, Type, Book, Class, Henry or Elizabeth, and before punctuation, a closing bracket, a line end or the end of text. A following word counts as personal, including World War I ended. and Phase I trials. Uppercase US is the country only when at least one of the three words on either side contains a lowercase letter; all-caps US counts as first person. U.S. is excluded.

Fully impersonal sources flag any first-person words in output, including quotations. When enabled, decode-time prevention applies only to these sources, with bans filtered to avoid matching source words or substrings in copyable literals. Sources whose only first person is quoted use per-section counts of each first-person word form, case-insensitive, with straight and curly apostrophes normalized and contractions grouped with their base pronoun. Only excess occurrences are flagged, regardless of output quotation style. Known limit: for sources whose only first person is quoted, a quoted pronoun moving into narration with the same count is not flagged.

First-person failures share the existing two-attempt section budget with other guards. Light and balanced deliver persistent additions with first_person_added and completed_with_warnings. The missing list contains unique lowercase words with straight apostrophes. Strong keeps the affected source section and refunds it through sections_kept. These checks do not apply to older saved policies, REST direct mode or writing from a prompt.

Meaning checks

Ink silently checks rewrite meaning with OpenAI when configured. Every changed candidate is checked, including retries. A meaning finding can use the section's single shared retry, with source-quote hints. Deterministic guards take precedence when choosing a candidate, then fewer material or critical findings win, with the retry winning a tie. Light and balanced deliver persistent meaning problems silently. Strong keeps and refunds a source section through sections_kept only when the chosen candidate still has a critical added claim, changed fact or speaker problem. Material findings are delivered silently; dropped findings can trigger a retry and affect selection but do not keep source by themselves. Unavailable checks fail open. Older saved policies keep their behavior.

Write from a prompt

POST writes accepts only prompt. Put all instructions in the prompt. Ink sends it exactly as one user message without a system prompt and retries rejected output once within the deadline.

Prompts allow 6,000 words and 200,000 characters, with up to 4,000 output words. Ink reserves available words up to that output cap. Admission requires at least the smaller of 300 and 4,000 available words, plus the API minimum of 100 words. It charges actual output words and refunds the remainder. Failed or cancelled jobs refund the full reservation. Unlimited and guest keys reserve the cap without the API minimum; guest gross budgets count reservations after refunds.

Poll, cancel and give feedback through the same rewrite job URLs. Prompt jobs have mode: write and progress phase writing. They have no source comparison, context, formality, strength or personal voice fields. Prompt and output follow the same retention and feedback policy. When writing is disabled, new requests return tool_unavailable.

Direct mode

Set mode to direct on POST rewrites to send text exactly as one user message without a system prompt or rewrite processing. Ink trims only surrounding whitespace from the reply. Direct mode ignores all settings and requires the shared profile. It charges input words, uses the same job URLs and is available only with REST keys. Direct jobs are excluded from web history.

curl https://ink.ego.ist/api/v1/rewrites \
  -H "Authorization: Bearer $INK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mode":"direct","text":"What is the capital of France?"}'

Feedback

GET feedback reads feedback; POST feedback saves or clears it. Only completed, completed_with_warnings or needs_review jobs accept feedback. Send rating as up, down or null to clear.

Only down accepts reasons: Changed my meaning, Still reads as AI, Wrong tone, Dropped facts or details, Other. Either rating accepts a note of up to 500 Unicode characters. Feedback bodies allow 8,192 bytes; oversized bodies return 422 input_too_long. Unknown fields, text fields and body job_id are rejected. The job ID belongs in the path.

Responses include feedback, creditedWords and note_retention_days. Reads also include eligibleForCredit and creditRequiresPaidPlan. Read feedback sharing before sending a rating.

Charges and rate limits

Rewrite and direct requests reserve the larger of input words and 100 words. Final charged_words can be lower. Cancellation refunds words not yet rewritten; failure refunds all reserved words. Unlimited accounts record actual input words without the minimum. Replaying the same idempotency key does not charge again.

All REST calls, including polling and feedback, share 60 requests per minute per key. New rewrite jobs also share 10 per minute per user across clients. Feedback writes share 30 per minute per user. A key's optional monthly word cap also applies.

Guest keys have a daily ceiling of 200,000 reserved words per key, resetting at 00:00 UTC. Gross reservations count even after refunds. Unlimited accounts have no daily word ceiling. Limit errors return 429; wait for the window to reset and use Retry-After when supplied.

Errors

Errors use {"error":{"code":"invalid_input","message":"...","field":"settings.strength"}}. Field errors name the field without returning submitted text. Terms errors include action_url; quota errors include a purchase hint. See terms_required for the acceptance flow. Unsupported methods return 405 with Allow; HEAD has no response body.

CodeHTTP statusMeaning
idempotency_key_required400Send a UUID in the Idempotency-Key header.
invalid_json400Send valid JSON in the request body.
unauthorized401A valid API key is required.
paid_plan_required402API keys require a paid subscription. Trials do not qualify.
setup_required402Choose an Ink plan to rewrite.
quota_exceeded402This rewrite exceeds your remaining word allowance.
payment_past_due402Your last payment failed. Update your card in Billing.
terms_required403Accept Ink terms to continue.
forbidden_origin403This request must come from Ink.
permission_required403Passport permission is required to use this voice. Review access or delete the adapter.
not_found404Rewrite not found.
method_not_allowed405This method is not allowed for this endpoint.
idempotency_conflict409This Idempotency-Key was already used with different text or settings.
text_too_long413This text exceeds the request limit.
unknown_field422Remove the unknown field.
invalid_input422Enter text and choose valid rewrite settings.
input_too_long422This text exceeds the request limit.
training_in_progress422This voice profile is still training.
insufficient_samples422This voice profile needs approved samples and an active adapter.
output_unreliable422This draft did not rewrite reliably, so we stopped. Your words were not used. Try a shorter section.
key_cap_exceeded429This rewrite exceeds this API key's monthly word cap.
rate_limited429Too many rewrite requests. Try again later.
daily_ceiling_exceeded429The daily safety limit has been reached. Try again after 00:00 UTC.
tool_unavailable503Writing from a prompt is unavailable right now.
model_unavailable503The model is starting or unavailable. Try again shortly.
model_rejected503The model could not process this rewrite.
pinned_adapter_unavailable503The model version pinned to this rewrite is unavailable. Start a new rewrite.