Responses

Create a model response in the format of OpenAI's Responses API, with the hosted tools that a model enables.

POST /v1/responses creates a model response in the format of OpenAI's Responses API.

The provider of the model must support the Responses API. For an OpenAI or Azure OpenAI model, also set responses_api: enabled in the model's params. Hosted tools, such as web_search and code_interpreter, are available here and not from chat completions. See OpenAI and Azure OpenAI.

Create a response

POST https://data.spiceai.io/v1/responses

Headers

Header	Type	Description
`X-API-Key`	string	Your project API key
`Content-Type`	string	`application/json`

Body

The body follows OpenAI's request schema. These are the fields that most requests use. OpenAI's reference lists every field.

Field	Type	Description
`model`	string	The name of a model in the Spicepod of the project.
`input`	string or array	Text, image, or file inputs to the model. Required.
`instructions`	string	A system or developer message for the model.
`stream`	boolean	Stream the response as server-sent events.
`tools`	array	The tools that the model can call, such as the hosted tools it enables.
`tool_choice`	string or object	Which tool the model calls.
`previous_response_id`	string	The ID of an earlier response, to continue its conversation.
`max_output_tokens`	integer	The most tokens that the response can use, reasoning tokens included.
`temperature`	number	The sampling temperature, from 0 to 2.
`reasoning`	object	Reasoning options, for a reasoning model.
`text`	object	The format of the text output, such as a JSON schema.

curl -X POST "https://data.spiceai.io/v1/responses" \
  -H "X-API-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Summarize the open support tickets.",
    "stream": false
  }'

Response

A response object. output holds the model's messages and tool calls, and usage counts the tokens.

{
  "id": "resp_68a4ed5e2258819485ece563a803bbf2075163a5e5b1c982",
  "object": "response",
  "created_at": 1755639134,
  "model": "gpt-4o",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_68a4ed5eb7e88194bf0b2560d8b5c0c1075163a5e5b1c982",
      "role": "assistant",
      "status": "completed",
      "content": [{"type": "output_text", "annotations": [], "text": "Thank you! How can I assist you today?"}]
    }
  ],
  "usage": {"input_tokens": 13, "output_tokens": 11, "total_tokens": 24}
}

Errors

Status	Cause
`400`	The provider of the model does not support the Responses API, or the request is not valid.
`404`	No model has this name.
`500`	The runtime failed while it created the response.
`503`	The model is not available from the Responses API.