Responses

Stateless text and function items with typed response lifecycle events.

Updated 2026-10-30 · Contract 0.2.0

POST/v1/responses

Request contract

Use string input or bounded typed input items, optional instructions and max_output_tokens. This subset is stateless: omit storage or set store:false. Carry previous text/function items forward explicitly.

Tool correlation

Assistant function_call items may be sent back with function_call_output using the matching call_id. Preserve every call and its result. Missing, duplicate or orphaned results are rejected.

Streaming lifecycle

Events include ordered sequence numbers and native response/output events. Successful output ends in response.completed. Output-bound exhaustion ends in response.incomplete with max_output_tokens; the stream does not use [DONE].

Storage boundary

store:true, previous_response_id, conversation IDs, background execution and native retrieve/delete/cancel semantics are unsupported. store:false disables public native response retrieval; it does not erase required durable safety and accounting records.

Request example

Use your own customer key. Confirm the model is published and your API wallet is funded. Copying an example never sends a request.

curl

curl https://notholy.com/v1/responses \
  -H "Authorization: Bearer $NOTHOLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "notholy-pulse",
  "input": "Explain least privilege.",
  "max_output_tokens": 256,
  "store": false
}'

HTTP contract fixture. Fixture checks are separate from production availability.

Request fields

Generated from the versioned contract. Refinement rules above still apply.

modelstringrequired

Up to 100 characters.

inputstring | array<object | object | object>required

Show accepted variants

Variant 1string

Up to 131072 characters.

Variant 2array<object | object | object>

Up to 128 items. At least 1 item.

instructionsstring

Up to 131072 characters.

max_output_tokensinteger

Minimum 32. Maximum 4096.

streamboolean

storefalse

backgroundfalse

toolsarray<object>

Up to 8 items.

Show item fields

type"function"required

namestringrequired

descriptionstring

Up to 1000 characters.

parametersobjectrequired

strictfalse

tool_choice"auto" | "none" | "required" | object

Show accepted variants

Variant 1"auto" | "none" | "required"

Variant 2object

Unknown fields rejected.

Show object fields

type"function"required

namestringrequired

Response schema

idstringrequired

object"response"required

created_atintegerrequired

Minimum -9007199254740991. Maximum 9007199254740991.

status"in_progress" | "completed" | "failed" | "incomplete"required

errorobject | nullrequired

Show accepted variants

Variant 1object

Unknown fields rejected.

Show object fields

codestringrequired

messagestringrequired

Variant 2null

incomplete_detailsobject | nullrequired

Show accepted variants

Variant 1object

Unknown fields rejected.

Show object fields

reason"max_output_tokens"required

Variant 2null

instructionsstring | nullrequired

max_output_tokensintegerrequired

Minimum -9007199254740991. Maximum 9007199254740991.

modelstringrequired

outputarray<object | object>required

parallel_tool_callsbooleanrequired

tool_choicestring | objectrequired

Show accepted variants

Variant 1string

Variant 2object

Unknown fields rejected.

Show object fields

type"function"required

namestringrequired

toolsarray<object>required

Show item fields

type"function"required

namestringrequired

descriptionstring

Up to 1000 characters.

parametersobjectrequired

strictfalse

usageobject | nullrequired

Show accepted variants

Variant 1object

Unknown fields rejected.

Show object fields

input_tokensintegerrequired