Chat Completions
Full reference for POST /v1/chat/completions — parameters, request and response shapes, headers.
POST https://www.draftworks.dev/v1/chat/completionsDraftworks passes requests through to GPT-5.5 on Azure's inference fleet with the OpenAI Chat Completions contract intact. Anything valid against OpenAI's endpoint is valid here; unknown parameters are forwarded upstream unmodified. The differences are additive: a signed receipt on every response, latency telemetry in usage, and prepaid-credit billing.
Parameters
| Parameter | Type | Notes |
|---|---|---|
model | string, required | gpt-5.5 or the pinned snapshot gpt-5.5-2026-04-24. Any other value returns 404 model_not_found. |
messages | array, required | Roles: system, developer, user, assistant, tool. user content may be a string or an array of content parts; image_url parts are supported for vision. |
max_completion_tokens | integer | Upper bound on generated tokens, including reasoning tokens. Up to 128,000. (The legacy max_tokens is not supported for reasoning models; use this.) |
reasoning_effort | string | none, low, medium (default), high, xhigh. See reasoning effort. |
temperature | number | 0–2, default 1. Fully supported on GPT-5.5. |
top_p | number | 0–1, default 1 (upstream reports an effective default of 0.98 on the Responses API). Fully supported. |
tools | array | Function definitions, OpenAI schema ({ type: "function", function: {...} }). |
tool_choice | string or object | auto (default with tools), none, required, or a specific function. |
parallel_tool_calls | boolean | Default true. Set false to force at most one tool call per turn. |
response_format | object | { type: "text" }, { type: "json_object" }, or { type: "json_schema", json_schema: { name, strict, schema } } for structured outputs. |
stream | boolean | SSE streaming. See streaming. |
stream_options | object | e.g. { "include_usage": true }. Draftworks always injects include_usage for metering; the final chunk carries usage whether or not you set it. |
stop | string or array | Up to 4 stop sequences. |
seed | integer | Best-effort determinism; compare system_fingerprint across responses. |
logprobs | boolean | Return log probabilities of output tokens. |
top_logprobs | integer | 0–20; requires logprobs: true. |
prediction | object | Predicted outputs ({ type: "content", content: "..." }) to speed up regeneration of mostly-known text. |
verbosity | string | low, medium (default), high. Steers response length independently of reasoning depth. |
n | integer | Number of choices. Each choice bills its own output tokens. |
presence_penalty | number | −2.0 to 2.0. |
frequency_penalty | number | −2.0 to 2.0. |
Prompt caching
Repeated prompt prefixes (long system prompts, few-shot blocks, tool definitions) are cached upstream automatically — no opt-in. Cache hits are reported in usage.prompt_tokens_details.cached_tokens and billed at $0.40 per 1M tokens at the base tier instead of $4.00. Structure prompts with the stable prefix first to maximize hits. See pricing.
Example
curl https://www.draftworks.dev/v1/chat/completions \
-H "Authorization: Bearer $DRAFTWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"reasoning_effort": "medium",
"max_completion_tokens": 4096,
"messages": [
{ "role": "system", "content": "You are a terse senior engineer." },
{ "role": "user", "content": "Why is my Postgres index not used for WHERE lower(email) = $1?" }
]
}'{
"id": "chatcmpl-a81f2c9b3e",
"object": "chat.completion",
"created": 1783382461,
"model": "gpt-5.5-2026-04-24",
"system_fingerprint": "fp_5c1d8a942f",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The index is on email, but the predicate is on lower(email) — a different expression. Create an expression index: CREATE INDEX ON users (lower(email)); or use citext."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 210,
"total_tokens": 252,
"prompt_tokens_details": {
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 128
},
"latency_checkpoint": {
"pre_inference_ms": 65,
"engine_ttft_ms": 318,
"engine_tbt_ms": 41,
"engine_ttlt_ms": 1893,
"service_ttft_ms": 520,
"service_tbt_ms": 42,
"service_ttlt_ms": 2160,
"user_visible_ttft_ms": 455,
"total_duration_ms": 2342
}
}
}Two fields to note in usage:
completion_tokens_details.reasoning_tokens— tokens the model spent thinking before answering. They are included incompletion_tokensand billed as output; see reasoning effort.latency_checkpoint— per-request timing measured at the Azure upstream, passed through by the Draftworks gateway. OpenAI's endpoint does not expose this; it comes free with the Azure path. Use it to separate model latency from your own network path when debugging.
Response headers
| Header | Meaning |
|---|---|
x-draftworks-model | The canonical model id served (gpt-5.5). The upstream-reported version string (gpt-5.5-2026-04-24) appears in the response body's model field and in the signed receipt, both passed through unmodified. |
x-draftworks-receipt | Signed receipt: base64url(payload) + "." + base64url(signature). Non-streamed responses only. See verification. |
x-draftworks-receipt-id | The request id; the receipt is retrievable forever at GET /v1/receipts/{id}. Non-streamed responses only — on streams, take the request id from the response body. |
x-draftworks-upstream-region | Azure region that served the request (e.g. eastus2). |
On streamed responses the receipt cannot be a header (the response is signed over the full stream), so it arrives as an SSE comment near the end of the stream instead — see streaming.
Vision
user messages accept image_url content parts:
{
"role": "user",
"content": [
{ "type": "text", "text": "What is wrong with this circuit?" },
{ "type": "image_url", "image_url": { "url": "https://example.com/schematic.png" } }
]
}Data URLs (data:image/png;base64,...) are also accepted. Image inputs are tokenized upstream and billed as input tokens.