API ReferenceResponses

Create a response

Creates a response using an AI model that can understand and reason about content within a knowledge store. This endpoint follows the [Open Responses](https://www.openresponses.org/specification) specification. **Prerequisites** — Before using this endpoint, you must: 1. [Upload an asset](/v1.3/api-reference/upload-assets/create-asset) using the `POST /assets` endpoint. 2. Create a knowledge store and add items to it. Multi-turn conversations are supported via `session_id`. The first request implicitly creates a session; subsequent requests pass the returned `session_id` to continue the conversation. Set `stream` to `true` to receive the response as Server-Sent Events (SSE).

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Request

This endpoint expects an object.
modelenumRequired
The AI model to use for generating the response.
Allowed values:
knowledge_store_idstringRequired
The unique identifier of the knowledge store this response reasons over.
inputlist of objectsRequired

An array of input items following the Open Responses input items specification.

session_idstringOptional

The session identifier for a multi-turn conversation. Pass the session_id returned from a previous response to continue that conversation. Omit to start a new session.

When provided, knowledge_store_id must match the knowledge store the session was originally created against, or the request returns 400.

instructionsstringOptional<=2000 characters

Additional guidance for the model, acting as a per-request system prompt.

includelist of enumsOptional
Additional fields to include in the response.
Allowed values:
streambooleanOptionalDefaults to false

When true, the response is returned as Server-Sent Events (SSE).

textobjectOptional
Controls the output text format for the response.
metadatamap from strings to stringsOptional

Key-value pairs to attach to the request. Up to 16 pairs allowed.

Response

Response created successfully. When stream is false or omitted, returns a single JSON response. When stream is true, returns a stream of Server-Sent Events.

idstring
A unique identifier for this response.
knowledge_store_idstring
The knowledge store this response was generated against.
session_idstring

The session identifier for this conversation. Pass this value in subsequent requests to continue the multi-turn conversation.

typeenum

The object type. Always response.

Allowed values:
statusenum
The status of the response.
Allowed values:
modelstring
The model used for this response.
outputlist of objects

The response output items. By default, only the final message is included. Set include to ["intermediate_outputs"] in the request to also receive function call items.

usageobject
Token usage statistics.
created_atstringformat: "date-time"
The timestamp when the response was created.

Errors

400
Bad Request Error