Responses API

Reference for POST /v1/responses — input items, reasoning, text controls, and the store=false default.

POST https://www.draftworks.dev/v1/responses

The Responses API is OpenAI's newer interface: item-based input and output, first-class reasoning configuration, and typed streaming events. Draftworks passes it through to GPT-5.5 with one deliberate change to defaults, described below.

store defaults to false on Draftworks. OpenAI and Azure default store to true, which persists your request and response server-side for 30 days. Draftworks defaults it to false: prompt and completion content is never written to disk, in line with our privacy posture. The practical consequence: previous_response_id requires the referenced response to have been created with an explicit "store": true. If you rely on server-side conversation state, opt in per request; otherwise send the full conversation as input each turn.

Parameters

Parameter	Type	Notes
`model`	string, required	`gpt-5.5` or `gpt-5.5-2026-04-24`.
`input`	string or array	A plain string, or an array of items (`message` items with `input_text` / `input_image` content parts, `function_call_output` items, etc.).
`instructions`	string	System-level guidance; equivalent to a `system` message.
`reasoning`	object	`{ "effort": "none" \| "low" \| "medium" \| "high" \| "xhigh", "summary": "auto" \| "concise" \| "detailed" }`. Default effort is `medium`. See reasoning effort.
`text`	object	`{ "verbosity": "low" \| "medium" \| "high", "format": { "type": "json_schema", ... } }` — output-length steering and structured outputs.
`max_output_tokens`	integer	Cap on generated tokens including reasoning tokens. Up to 128,000.
`tools`	array	Function tools: `{ "type": "function", "name", "parameters", "strict" }`.
`previous_response_id`	string	Continue from a prior response. Requires that response to have been stored (`store: true` on the earlier request) — see the note above.
`store`	boolean	Default `false` on Draftworks (OpenAI/Azure default `true`).
`metadata`	object	Up to 16 key-value string pairs, echoed back on the response object.
`stream`	boolean	Typed SSE events. See streaming.

Background responses are not currently supported: the background parameter is not accepted, and there is no GET /v1/responses/{id} polling endpoint. Use synchronous requests or streaming instead.

Example

Request

curl https://www.draftworks.dev/v1/responses \
  -H "Authorization: Bearer $DRAFTWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "reasoning": { "effort": "low" },
    "text": { "verbosity": "low" },
    "input": "Summarize the CAP theorem in one paragraph."
  }'

Response

{
  "id": "resp_68c1f0a2b9d34",
  "object": "response",
  "created_at": 1783382519,
  "status": "completed",
  "model": "gpt-5.5-2026-04-24",
  "store": false,
  "metadata": {},
  "output": [
    {
      "type": "reasoning",
      "id": "rs_68c1f0a2c1e02",
      "summary": []
    },
    {
      "type": "message",
      "id": "msg_68c1f0a2f4b71",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "The CAP theorem states that a distributed system can guarantee at most two of consistency, availability, and partition tolerance..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 146,
    "output_tokens_details": {
      "reasoning_tokens": 64
    },
    "total_tokens": 164
  }
}

Note the usage field names differ from Chat Completions: input_tokens / output_tokens here versus prompt_tokens / completion_tokens there. Cached prompt tokens appear in usage.input_tokens_details.cached_tokens and are billed at the cached-input rate — see pricing.

For convenient text extraction, the official SDKs expose response.output_text, the concatenation of all output_text parts.

Receipts

Responses API calls are signed exactly like Chat Completions calls: x-draftworks-receipt header on non-streamed responses, an SSE comment on streams, and permanent retrieval via GET /v1/receipts/{id}. The receipt's endpoint field records responses. See verification.

Parameters

Example

Receipts

On this page