> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel-fix-guardrail-enforcement-gaps.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/advanced/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](/advanced/guardrails)
run, so they check and rewrite it like any other input: a stored response
holds what its client saw, and a [presidio](/advanced/guardrails#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](/features/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:

```http theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash curl theme={null}
  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."
    }'
  ```

  ```python Python theme={null}
  import os

  from openai import OpenAI

  client = OpenAI(
      base_url="http://localhost:8080/v1",
      api_key=os.environ["GOMODEL_MASTER_KEY"],
  )

  response = client.responses.create(
      model="gpt-5-mini",
      input="Write one short sentence about reliable gateways.",
  )

  print(response.output_text)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "http://localhost:8080/v1",
    apiKey: process.env.GOMODEL_MASTER_KEY,
  });

  const response = await client.responses.create({
    model: "gpt-5-mini",
    input: "Write one short sentence about reliable gateways.",
  });

  console.log(response.output_text);
  ```
</CodeGroup>

Retrieve it later:

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/v1/responses/resp_abc123 \
    -H "Authorization: Bearer $GOMODEL_MASTER_KEY"
  ```

  ```python Python theme={null}
  import os

  from openai import OpenAI

  client = OpenAI(
      base_url="http://localhost:8080/v1",
      api_key=os.environ["GOMODEL_MASTER_KEY"],
  )

  response = client.responses.retrieve("resp_abc123")
  print(response.output_text)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "http://localhost:8080/v1",
    apiKey: process.env.GOMODEL_MASTER_KEY,
  });

  const response = await client.responses.retrieve("resp_abc123");
  console.log(response.output_text);
  ```
</CodeGroup>

List its stored input items:

<CodeGroup>
  ```bash curl theme={null}
  curl http://localhost:8080/v1/responses/resp_abc123/input_items \
    -H "Authorization: Bearer $GOMODEL_MASTER_KEY"
  ```

  ```python Python theme={null}
  import os

  from openai import OpenAI

  client = OpenAI(
      base_url="http://localhost:8080/v1",
      api_key=os.environ["GOMODEL_MASTER_KEY"],
  )

  for item in client.responses.input_items.list("resp_abc123"):
      print(item)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "http://localhost:8080/v1",
    apiKey: process.env.GOMODEL_MASTER_KEY,
  });

  for await (const item of client.responses.inputItems.list("resp_abc123")) {
    console.log(item);
  }
  ```
</CodeGroup>