Skip to Content

Write from a prompt

POST
/api/v1/writes

Send all instructions in prompt, up to 6,000 words and 200,000 characters. Ink sends one user message without a system prompt. Reserve up to 4,000 output words; admission requires at least min(300, 4,000) available words and the API minimum of 100. Charge actual output words and refund the remainder. Failed or cancelled jobs refund the full reservation. Poll, cancel and give feedback through rewrite job URLs.

Authorization

Bearer
headerAuthorizationBearer <token>

Ink API key from /app/api-keys.

Header Parameters

Idempotency-Key*string

Reuse a UUID for the same request. A changed request with the same UUID returns idempotency_conflict.

Formatuuid

Request Body

application/json
  1. body
prompt*string

Response Body

Finished job. Review warnings and needs_review before using output.

application/json
  1. response
id*string
Formatuuid
status*unknown
Value in"queued""rewriting""validating""completed""completed_with_warnings""needs_review""failed""cancelled"
mode?unknown
output?string
change_summary?string
input_words*integer
Range0 <= value
charged_words*integer
Range0 <= value
refunded_words?integer
Range0 <= value
created_at*string
Formatdate-time
finished_at*|
Formatdate-time
warnings*array<>

Deliver output with its warnings. On details_added, show the warning listing added details: "Check added details before use: ...". On first_person_added, show the warning listing added first-person words: "Added first-person wording: ..." or, when the list is absent, "Added first-person wording. Check the rewrite.". Do not retry details_added, first_person_added or sections_kept automatically. For the new rewrite policy, light and balanced deliver persistent first-person additions with completed_with_warnings; missing 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. See /docs/api#first-person-wording for source context rules and the quotation limit. Rewrite meaning checks run silently with OpenAI when configured and may use one shared retry per section. Light and balanced deliver persistent meaning problems silently. Strong keeps and refunds a section through sections_kept only for a persistent critical added claim, changed fact or speaker problem. Material findings are delivered silently. Older saved policies keep their behavior. Unavailable checks fail open.

blocks*array<>
progress*
fact_report?
error?
Example Request
curl -X POST 'https://ink.ego.ist/api/v1/writes' \
  -H 'Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Content-Type: application/json' \
  -d '{
  "prompt": "string"
}'
Example Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "queued",
  "mode": "write",
  "output": "string",
  "change_summary": "string",
  "input_words": 0,
  "charged_words": 0,
  "refunded_words": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z",
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "missing": [
        "string"
      ],
      "missing_count": 0
    }
  ],
  "blocks": [
    {
      "index": 0,
      "text": "string"
    }
  ],
  "progress": {
    "phase": "queued",
    "blocks_done": 0,
    "blocks_total": 0
  },
  "fact_report": {
    "total": 0,
    "kept": 0,
    "groups": [
      {
        "type": "string",
        "total": 0,
        "kept": 0
      }
    ],
    "changed": [
      {
        "text": "string",
        "type": "string"
      }
    ]
  },
  "error": {
    "code": "string",
    "message": "string"
  }
}