Responses API

Use OpenAI-compatible response creation, lifecycle, input items, and utility endpoints through GoModel.

Overview

GoModel exposes OpenAI-compatible Responses API endpoints under /v1/responses.

Create requests use the translated model routing pipeline, so virtual models, workflows, guardrails, failover, usage logging, and response caching continue to apply. Lifecycle and utility endpoints use native provider capabilities when available, and return explicit compatibility errors when the selected provider does not support the requested operation.

For feature-level behavior, including hosted tools and chat-translated providers, see Responses compatibility.

Supported endpoints

Endpoint	Behavior
POST /v1/responses	Creates a response through translated model routing. Responses are stored for later retrieval.
GET /v1/responses/{id}	Returns a stored gateway response when available. Otherwise, proxies to a native provider lookup when supported.
GET /v1/responses/{id}/input_items	Returns normalized input items captured from the original create request when available. Otherwise, proxies to a native provider lookup when supported.
POST /v1/responses/{id}/cancel	Cancels the response through the native provider when supported.
DELETE /v1/responses/{id}	Deletes the stored gateway response. When the provider supports native deletion, GoModel also forwards the delete request upstream.
POST /v1/responses/input_tokens	Counts input tokens through the native provider utility endpoint when supported.
POST /v1/responses/compact	Compacts a response input through the native provider utility endpoint when supported.

Stored responses

For POST /v1/responses calls, unless the request sets store: false, GoModel stores the normalized response body and the normalized input items of the request as the client sent them (before guardrails edit them, and without the history a previous_response_id or conversation added). A streamed response is stored from its terminal event (response.completed, response.incomplete, or response.failed). The snapshot is written in the background after the response is returned, so storage latency never delays the client. A GET /v1/responses/{id} issued immediately after the POST can arrive before the snapshot is stored; graceful shutdown waits for pending snapshot writes, but a hard process exit can lose one that has not finished. A snapshot write that fails is logged and counted in the gomodel_response_snapshot_store_failures_total metric.

This enables:

• GET /v1/responses/{id} for responses created through GoModel.
• GET /v1/responses/{id}/input_items for the original normalized input.
• DELETE /v1/responses/{id} even when the provider does not expose native response deletion.
• previous_response_id on chat-translated providers such as Anthropic and Gemini: GoModel follows the stored response and each response it was chained from, and prepends their input items and output to the new input, so the provider receives the whole chain each turn. The response names its predecessor in previous_response_id, streamed or not. On these providers an id that is not stored (the previous response was sent with store: false), or belongs to another tenant, returns 404. Native Responses providers receive the id itself and resolve it on their side, so they need no GoModel snapshot.

The replayed history, like the items of a gateway-managed conversation, is merged into the input before the prompt-phase guardrails run, so they check and rewrite it like any other input: a stored response holds what its client saw, and a presidio guardrail anonymizes the values it restored there again before the next turn reaches the provider. When guardrails run and a failover target is chat-translated, a native primary receives the replayed history instead of the id as well.

Background responses

background: true returns immediately with a queued snapshot. Because that snapshot is not final, GET /v1/responses/{id} re-reads it from the provider that created it on every poll and stores the result once the response reaches a terminal status (completed, incomplete, failed, or cancelled), so the usual SDK loop — poll until the status is terminal, then read output — works through the gateway. Terminal snapshots are served from the store without an upstream call. If the refresh fails, the stored snapshot is returned unchanged.

Background creates are never served from the response cache: a queued body carries an id that belongs to one caller’s response.

Native provider lookup

When a response was not created through the current GoModel process or response store, lifecycle endpoints can still use a native provider lookup.

Specify the provider when the response ID is not stored locally:

GET /v1/responses/resp_abc123?provider=openai

Without a stored response or provider hint, GoModel checks providers that expose native Responses lifecycle support. If lifecycle routing is unavailable, GoModel returns a compatibility error. If lifecycle routing is available but no provider can serve the response, GoModel returns a normal not-found error.

Input items

GoModel normalizes stored input into OpenAI-compatible response input items. String input becomes a user message with an input_text content item:

{
  "type": "message",
  "role": "user",
  "content": [
    {
      "type": "input_text",
      "text": "hello"
    }
  ]
}

Structured input arrays preserve message, function call, and function call output items where possible.

Compatibility errors

Some providers do not support every Responses lifecycle or utility endpoint. When the selected provider cannot perform an operation, GoModel returns an OpenAI-compatible error with:

{
  "error": {
    "type": "invalid_request_error",
    "message": "response compaction is not supported by this provider",
    "param": null,
    "code": "unsupported_response_operation"
  }
}

GoModel uses OpenAI’s invalid_request_error type for unsupported operations so the public error type set stays closed. The unsupported_response_operation code identifies the unsupported operation, returned with HTTP 501 Not Implemented.

Example

Create a response:

curl

curl http://localhost:8080/v1/responses \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "input": "Write one short sentence about reliable gateways."
  }'

Retrieve it later:

curl

curl http://localhost:8080/v1/responses/resp_abc123 \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"

List its stored input items:

curl

curl http://localhost:8080/v1/responses/resp_abc123/input_items \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"