Skip to main content
The Responses API is compatible with the OpenAI Responses API. It allows you to create stateful model interactions where each response can reference previous ones via an ID. Portkey proxies these requests to the configured provider.
The Responses API is currently supported for providers that implement the OpenAI Responses API contract. Check your provider’s documentation to confirm compatibility.

​
Create a model response

POST /v1/responses Creates a new model response. The request body is forwarded to the provider.

​
Request

​
x-portkey-provider
string
required
The provider to route the request to (e.g. openai).
​
x-portkey-api-key
string
required
Your Portkey API key or provider API key.
​
model
string
required
The model to use for the response (e.g. gpt-4o).
​
input
string | array
required
The input for the model. Can be a plain text string or an array of message objects.
​
previous_response_id
string
The ID of a previous response to continue from. Enables multi-turn stateful conversations.
​
instructions
string
System-level instructions to guide the model’s behavior.
​
tools
array
A list of tools the model may call. Follows the OpenAI tool definition format.
​
stream
boolean
default:"false"
Whether to stream the response. When true, the gateway returns server-sent events.
​
max_output_tokens
number
Maximum number of tokens in the output.

​
Response

​
id
string
Unique identifier for the response.
​
object
string
Always response.
​
model
string
The model that generated the response.
​
status
string
Response status. Values: completed, in_progress, failed, cancelled.
​
output
array
Array of output items generated by the model.
​
usage
object
curl https://your-gateway.example.com/v1/responses \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai" \
  -d '{
    "model": "gpt-4o",
    "input": "Explain quantum entanglement in simple terms."
  }'

​
Get a response

GET /v1/responses/:id Retrieves a previously created model response by its ID.

​
Request

​
id
string
required
The ID of the response to retrieve.
​
x-portkey-provider
string
required
The provider to route the request to.
​
x-portkey-api-key
string
required
Your Portkey API key or provider API key.

​
Response

Returns the response object. See Create a model response for the full field list. 
curl https://your-gateway.example.com/v1/responses/resp-abc123 \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

​
Delete a response

DELETE /v1/responses/:id Deletes a stored model response.
Deletion is permanent. Any response chain built on top of this response via previous_response_id may become incomplete.

​
Request

​
id
string
required
The ID of the response to delete.
​
x-portkey-provider
string
required
The provider to route the request to.
​
x-portkey-api-key
string
required
Your Portkey API key or provider API key.

​
Response

​
id
string
The ID of the deleted response.
​
object
string
Always response.
​
deleted
boolean
true if the response was successfully deleted.
curl https://your-gateway.example.com/v1/responses/resp-abc123 \
  -X DELETE \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

​
List response input items

GET /v1/responses/:id/input_items Returns the input items that were included in a response. This is useful for inspecting the full context that was sent to the model.

​
Request

​
id
string
required
The ID of the response whose input items to list.
​
x-portkey-provider
string
required
The provider to route the request to.
​
x-portkey-api-key
string
required
Your Portkey API key or provider API key.
​
limit
number
default:"20"
Maximum number of input items to return.
​
after
string
Cursor for pagination.

​
Response

​
object
string
Always list.
​
data
array
Array of input item objects representing the messages and context sent in the request.
​
has_more
boolean
Whether additional input items are available.
curl https://your-gateway.example.com/v1/responses/resp-abc123/input_items \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

Build docs developers (and LLMs) love

Get started for freeTalk to us