Responses API

ModelHive serves POST /v1/responses and the stateful surface around it — retrieving a turn, chaining onto a previous one, background execution, conversations. The gateway keeps that state itself, which is what makes the stateful half work on any provider in the catalogue, not only the ones that implement it.

Endpoints

Method	Path	Purpose
POST	/v1/responses	Create a turn
GET	/v1/responses/{id}	Retrieve a stored turn
DELETE	/v1/responses/{id}	Delete a stored turn
POST	/v1/responses/{id}/cancel	Cancel a background turn
GET	/v1/responses/{id}/input_items	List the input items of a turn
POST	/v1/conversations	Create a conversation
GET POST DELETE	/v1/conversations/{id}	Read, update, delete
GET POST	/v1/conversations/{id}/items	List or append items
GET DELETE	/v1/conversations/{id}/items/{item_id}	Read or delete one item

Creating and chaining

# a turn worth keeping
curl https://api.modelhive.ai/v1/responses \
  -H "Authorization: Bearer sk-mh-..." \
  -d '{"model": "gpt-4o", "input": "Ricorda il numero 41.", "store": true}'
# → {"id": "resp_...", ...}

# the next turn continues from it
curl https://api.modelhive.ai/v1/responses \
  -H "Authorization: Bearer sk-mh-..." \
  -d '{"model": "gpt-4o",
       "input": "Quale numero ti ho chiesto di ricordare?",
       "previous_response_id": "resp_..."}'

A stored turn belongs to the key that created it. The id is not a bearer token: another key asking for the same resp_... does not get it.

Retention

A stored turn stays retrievable for 30 days by default, matching OpenAI's retention, and expired rows are purged hourly. Both are configurable:

responses:
  ttl: 720h                  # how long a stored turn stays retrievable
  cleanup_interval: 1h       # how often expired rows are purged
  background_timeout: 1h     # when a queued or in-progress turn is declared dead

Sending store: false keeps the turn out of the table entirely.

Why there is a background timeout

A worker killed mid-turn leaves its row in_progress forever, and a client polling that row would wait for an answer nobody is producing. Any turn older than background_timeout is failed regardless of which replica owns it, so set it above the slowest turn you expect.

What else applies

The Responses path is not a bypass. Everything documented elsewhere applies to it in the same order:

• Guardrails read instructions, input, and function_call_output items — a tool result returning into a Responses conversation is redacted or refused exactly as it would be in a chat request;
• HiveCache, HiveState and Live Compression run on it;
• budget, rate limits and model whitelists are enforced identically.