Create a response | TwelveLabs

This method uses Jockey to reason over content in a knowledge store and create a response. It uses Open Responses conventions for input items and streaming events.

Before you use this method, you must create an asset, create a knowledge store, and add the asset to the knowledge store as an item.

Multi-turn conversations: Supported via a session identifier. The first request implicitly creates a session; subsequent requests pass the returned identifier to continue the conversation.

Selections: By default, Jockey reasons over every item in the knowledge store. To narrow the scope, set the optional selections parameter to specific items or item collections, then reference each one with a {{sel:N}} token in the content field of an input item (N is the zero-based position in the selections array). The narrowing is applied at the prompt level; the knowledge store does not block access to other items.

Streaming: Set the stream parameter to true to receive the response as Server-Sent Events (SSE). The reply streams in as a sequence of typed events and ends with a data: [DONE] message.

Example response

1 {
2   "id": "resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff",
3   "type": "response",
4   "status": "completed",
5   "session_id": "sess_019f4f2a-b69b-7a01-9018-cc51681121ea",
6   "knowledge_store_id": "ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56",
7   "output": [
8     {
9       "type": "message",
10       "id": "msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0",
11       "status": "completed",
12       "role": "assistant",
13       "content": [
14         {
15           "type": "output_text",
16           "text": "The video captures a heated sideline moment during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid, visibly frustrated, and briefly bumps him before being restrained by a teammate [00:00-00:09]."
17         }
18       ]
19     }
20   ],
21   "usage": {
22     "input_tokens": 12625,
23     "output_tokens": 289
24   },
25   "created_at": "2026-07-11T03:13:57Z"
26 }

Example streamed response (SSE)

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff","type":"response","status":"in_progress","output":[],"session_id":"sess_019f4f2a-b69b-7a01-9018-cc51681121ea","knowledge_store_id":"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56","created_at":"2026-07-11T03:13:47Z"}}
event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"type":"message","id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","status":"in_progress","role":"assistant","content":[{"type":"output_text","text":""}]}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","output_index":0,"content_index":0,"delta":"The video captures a heated sideline moment"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":5,"item_id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","output_index":0,"content_index":0,"delta":" during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid."}
event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":124,"item_id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","output_index":0,"content_index":0,"text":"The video captures a heated sideline moment during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid, visibly frustrated, and briefly bumps him before being restrained by a teammate [00:00-00:09]."}
event: response.completed
data: {"type":"response.completed","sequence_number":127,"response":{"id":"resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff","type":"response","status":"completed","output":[{"type":"message","id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","status":"completed","role":"assistant","content":[{"type":"output_text","text":"The video captures a heated sideline moment during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid, visibly frustrated, and briefly bumps him before being restrained by a teammate [00:00-00:09]."}]}],"usage":{"input_tokens":12625,"output_tokens":289},"session_id":"sess_019f4f2a-b69b-7a01-9018-cc51681121ea","knowledge_store_id":"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56","created_at":"2026-07-11T03:13:57Z"}}
data: [DONE]

This method uses [Jockey](/v1.3/agents/concepts/jockey) to reason over content in a knowledge store and create a response. It uses [Open Responses](https://www.openresponses.org/specification) conventions for input items and streaming events. Before you use this method, you must create an asset, create a knowledge store, and add the asset to the knowledge store as an item. **Multi-turn conversations**: Supported via a session identifier. The first request implicitly creates a session; subsequent requests pass the returned identifier to continue the conversation. **Selections**: By default, Jockey reasons over every item in the knowledge store. To narrow the scope, set the optional `selections` parameter to specific items or item collections, then reference each one with a `{{sel:N}}` token in the `content` field of an `input` item (`N` is the zero-based position in the `selections` array). The narrowing is applied at the prompt level; the knowledge store does not block access to other items. **Streaming**: Set the `stream` parameter to `true` to receive the response as [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE). The reply streams in as a sequence of typed events and ends with a `data: [DONE]` message. <Accordion title="Example response"> ```json { "id": "resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff", "type": "response", "status": "completed", "session_id": "sess_019f4f2a-b69b-7a01-9018-cc51681121ea", "knowledge_store_id": "ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56", "output": [ { "type": "message", "id": "msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "The video captures a heated sideline moment during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid, visibly frustrated, and briefly bumps him before being restrained by a teammate [00:00-00:09]." } ] } ], "usage": { "input_tokens": 12625, "output_tokens": 289 }, "created_at": "2026-07-11T03:13:57Z" } ``` </Accordion> <Accordion title="Example streamed response (SSE)"> ``` event: response.created data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff","type":"response","status":"in_progress","output":[],"session_id":"sess_019f4f2a-b69b-7a01-9018-cc51681121ea","knowledge_store_id":"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56","created_at":"2026-07-11T03:13:47Z"}} event: response.output_item.added data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"type":"message","id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","status":"in_progress","role":"assistant","content":[{"type":"output_text","text":""}]}} event: response.output_text.delta data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","output_index":0,"content_index":0,"delta":"The video captures a heated sideline moment"} event: response.output_text.delta data: {"type":"response.output_text.delta","sequence_number":5,"item_id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","output_index":0,"content_index":0,"delta":" during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid."} event: response.output_text.done data: {"type":"response.output_text.done","sequence_number":124,"item_id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","output_index":0,"content_index":0,"text":"The video captures a heated sideline moment during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid, visibly frustrated, and briefly bumps him before being restrained by a teammate [00:00-00:09]."} event: response.completed data: {"type":"response.completed","sequence_number":127,"response":{"id":"resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff","type":"response","status":"completed","output":[{"type":"message","id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","status":"completed","role":"assistant","content":[{"type":"output_text","text":"The video captures a heated sideline moment during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid, visibly frustrated, and briefly bumps him before being restrained by a teammate [00:00-00:09]."}]}],"usage":{"input_tokens":12625,"output_tokens":289},"session_id":"sess_019f4f2a-b69b-7a01-9018-cc51681121ea","knowledge_store_id":"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56","created_at":"2026-07-11T03:13:57Z"}} data: [DONE] ``` </Accordion>

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

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

Request body for the Responses endpoint.

knowledge_store_idstringRequired

The unique identifier of the knowledge store to reason over.

inputlist of objectsRequired

Provides context to Jockey for this request. Uses Open Responses input item conventions.

Provides context to Jockey for this request. Uses [Open Responses input item](https://www.openresponses.org/reference#input-items) conventions.

streamfalseRequired

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

When `true`, the response is returned as [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE).

session_idstringOptional

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

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

instructionsstringOptional<=2000 characters

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

includelist of enumsOptional

Additional items to include in the response’s output array. By default, the output array contains only Jockey’s final reply.

Values:

intermediate_outputs: Also includes the steps Jockey took to produce the reply.

Additional items to include in the response's `output` array. By default, the `output` array contains only Jockey's final reply. **Values**: - `intermediate_outputs`: Also includes the steps Jockey took to produce the reply.

Allowed values:

selectionslist of objectsOptional

Selections persist in the session context, and selections sent on later turns are added to that context. You can reference selections from earlier turns in natural language without repeating their {{sel:N}} tokens.

Restricts the request to specific knowledge store items or item collections. The restriction is applied at the prompt level; the knowledge store does not block access to other items. Treat it as a strong preference, not a hard access boundary. Omit to run against every item. Selections persist in the session context, and selections sent on later turns are added to that context. You can reference selections from earlier turns in natural language without repeating their `{{sel:N}}` tokens.

textobjectOptional

Controls the output text format for the response.

Response

idstring

A unique identifier for this response.

knowledge_store_idstring

The unique identifier of 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.

statusenum

The status. For the meaning of each value, see the Response statuses section on The response object page.

outputlist of objects

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

usageobject

Token usage statistics.

created_atstringformat: "date-time"

The timestamp when the response was created.

Errors

400

Bad Request Error