Responses API

Overview

Aurora exposes OpenAI-format Responses API endpoints under /v1/responses.

Create requests use the translated model routing pipeline, so aliases, 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.

Supported Endpoints

Create a Response

curl http://your-aurora-host/v1/responses \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Write one short sentence about reliable gateways."
  }'
 

Streaming

Add "stream": true to the create request. Aurora emits OpenAI-shaped SSE events:

curl http://your-aurora-host/v1/responses \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Count to 5.",
    "stream": true
  }'

SSE event stream (one event per line, terminated by data: [DONE]):

event: response.created
data: {"type":"response.created","response":{"id":"resp_abc","status":"in_progress"}}
 
event: response.output_item.added
data: {"type":"response.output_item.added","item":{"type":"message","role":"assistant"}}
 
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"1, 2, 3, 4, 5."}
 
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_abc","status":"completed"}}
 
data: [DONE]

The exact event order and field set depend on the upstream provider; Aurora preserves whatever the upstream emits and only normalizes the framing.

Stored Responses

For non-streaming POST /v1/responses calls, Aurora stores the normalized response body and the normalized input items from the request. This enables GET /v1/responses/{id}, GET /v1/responses/{id}/input_items, and DELETE /v1/responses/{id} even when the provider does not expose native response deletion.

Streaming responses are not stored as response snapshots.

Retrieve a stored response

curl http://your-aurora-host/v1/responses/resp_abc123 \
  -H "Authorization: Bearer $AURORA_MASTER_KEY"

The response shape matches the original create response:

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1728000000,
  "model": "openai-primary/gpt-4o",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "Reliable gateways keep the boring parts boring."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 11,
    "total_tokens": 23
  }
}

Retrieve input items

curl http://your-aurora-host/v1/responses/resp_abc123/input_items \
  -H "Authorization: Bearer $AURORA_MASTER_KEY"

Returns the normalized input array. String input becomes a single user message with an input_text content item; structured input arrays are returned as-is.

Delete a stored response

curl -X DELETE http://your-aurora-host/v1/responses/resp_abc123 \
  -H "Authorization: Bearer $AURORA_MASTER_KEY"

Returns 200 on success. When the upstream provider supports native deletion, Aurora also forwards the delete upstream.

Native Provider Lookup

When a response was not created through the current Aurora 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
 

Input Items

Aurora 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"
    }
  ]
}
 

Compatibility Errors

Some providers do not support every Responses lifecycle or utility endpoint. When the selected provider cannot perform an operation, Aurora returns:

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

Returned with HTTP 501 Not Implemented.