> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/v1.3/api-reference/responses/create/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Create a response POST https://api.twelvelabs.io/v1.3/responses Content-Type: application/json 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. ```json { "id": "resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff", "type": "response", "object": "response", "status": "completed", "incomplete_details": null, "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", "phase": "final_answer", "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 [1].", "annotations": [ { "type": "video_citation", "start_index": 211, "end_index": 213, "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde", "start_sec": 0.0, "end_sec": 9.0, "title": "Super Bowl LVIII sideline", "thumbnail_url": "https://example.com/thumbnail.jpg", "hls_url": "https://example.com/stream.m3u8" } ] } ] } ], "usage": { "input_tokens": 12625, "output_tokens": 289 }, "created_at": "2026-07-11T03:13:57Z" } ``` ``` event: response.created data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff","type":"response","object":"response","status":"in_progress","incomplete_details":null,"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","phase":"final_answer","content":[{"type":"output_text","text":"","annotations":[]}]}} event: response.content_part.added data: {"type":"response.content_part.added","sequence_number":3,"item_id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} 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 [1]."} event: response.content_part.done data: {"type":"response.content_part.done","sequence_number":125,"item_id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","output_index":0,"content_index":0,"part":{"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 [1].","annotations":[{"type":"video_citation","start_index":211,"end_index":213,"item_id":"ksi_069e9870-3c4d-7abc-9012-3456789abcde","start_sec":0.0,"end_sec":9.0,"title":"Super Bowl LVIII sideline","thumbnail_url":"https://example.com/thumbnail.jpg","hls_url":"https://example.com/stream.m3u8"}]}} event: response.completed data: {"type":"response.completed","sequence_number":127,"response":{"id":"resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff","type":"response","object":"response","status":"completed","incomplete_details":null,"output":[{"type":"message","id":"msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0","status":"completed","role":"assistant","phase":"final_answer","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 [1].","annotations":[{"type":"video_citation","start_index":211,"end_index":213,"item_id":"ksi_069e9870-3c4d-7abc-9012-3456789abcde","start_sec":0.0,"end_sec":9.0,"title":"Super Bowl LVIII sideline","thumbnail_url":"https://example.com/thumbnail.jpg","hls_url":"https://example.com/stream.m3u8"}]}]}],"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] ``` Reference: https://docs.twelvelabs.io/api-reference/responses/create ## Authentication - `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page. ## Request ### Body (application/json) This endpoint expects an object. - `knowledge_store_id` (string, required) — The unique identifier of the knowledge store to reason over. - `input` (list of ResponseInputItem, required) — Provides context to Jockey for this request. Uses [Open Responses input item](https://www.openresponses.org/reference#input-items) conventions. - `stream` (false, required) — When `true`, the response is returned as [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE). - `session_id` (string, optional) — 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`. - `instructions` (string, optional) — Additional guidance for Jockey, acting as a per-request system prompt. - `include` (list of enum, optional) — 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: `intermediate_outputs` - `selections` (list of ResponseSelection, optional) — 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. - `text` (TextParam, optional) — Controls the output text format for the response. ## Response ### 200 - `id` (string, optional) — A unique identifier for this response. - `knowledge_store_id` (string, optional) — The unique identifier of the knowledge store this response was generated against. - `session_id` (string, optional) — The session identifier for this conversation. Pass this value in subsequent requests to continue the multi-turn conversation. - `type` (enum, optional) — The object type. Always `response`. - Allowed values: `response` - `object` (enum, optional) — The object type, always `response`. It has the same value as the `type` field. Only the response itself has an `object` field. Output items, annotations, and stream events are identified by `type` alone and have no `object` field. - Allowed values: `response` - `status` (enum, optional) — The status. For the meaning of each value, see the [Response statuses](/v1.3/api-reference/responses/the-response-object#response-statuses) section on **The response object** page. - Allowed values: `completed`, `failed`, `in_progress`, `incomplete` - `incomplete_details` (ResponseIncompleteDetails, optional, nullable) — The reason the response was truncated before the answer was complete. Always present. Contains a value only when the `status` field is `incomplete`; the value is `null` on every other status, including `in_progress` and `failed`. A `null` value means the answer was not truncated. If the `reason` field contains a value you do not recognize, treat the response as truncated for an unknown reason, not as an error. - `output` (list of ResponseOutputItem, optional) — 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. - `usage` (ResponseUsage, optional) — Token usage statistics. - `created_at` (string, optional) — The timestamp when the response was created. ## Errors ### 400 Bad Request Error The request has failed. - `code` (string, optional) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details. - `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface. ## Types ### ResponseInputItem An input item using [Open Responses input item](https://www.openresponses.org/reference#input-items) conventions. - `type` (enum, required) — The type of input item. - Allowed values: `message` - `role` (enum, required) — The role of the message author. - Allowed values: `user` - `content` (string, required) — The message text, as a plain string. Must be between 1 and 10,000 characters. To narrow the message to a specific knowledge store item or item collection, include a `{{sel:N}}` token in the content, where `N` is the zero-based position in the `selections` array. ### ResponseSelection A reference to a specific knowledge store item or item collection to include in the request. - `kind` (enum, required) — The type of resource to select. **Values**: - `item`: A single knowledge store item. - `collection`: A knowledge store item collection. All items in the collection are included in the request. - Allowed values: `item`, `collection` - `id` (string, required) — The unique identifier of the selected resource. Must use the prefix that matches the `kind` field: `ksi_` for items and `ksic_` for collections. ### TextParam Controls the output text format for the response. - `format` (TextParamFormat, optional) — The output format for the response text. Defaults to plain text. Use `json_schema` to receive a structured JSON object conforming to a provided schema. ### ResponseIncompleteDetails Details about why a response is incomplete. Present when the `status` field is `incomplete`. - `reason` (string, required) — The reason the answer is incomplete. The `max_output_tokens` value means the answer reached the output token limit. The text in the response is an incomplete answer, not the full one; treat an unrecognized value as an incomplete answer for an unknown reason, not as an error. ### ResponseOutputItem An item in the response output. Items are polymorphic and discriminated by the `type` field. - `type` (enum, required) — The type of output item. - Allowed values: `message`, `function_call`, `function_call_output` - `id` (string, required) — A unique identifier for this item. - `status` (enum, required) — The status. For the meaning of each value, see the [Response statuses](/v1.3/api-reference/responses/the-response-object#response-statuses) section on **The response object** page. - Allowed values: `completed`, `failed`, `in_progress`, `incomplete` - `role` (enum, optional) — The role of the message author. Present when `type` is `message`. - Allowed values: `assistant` - `phase` (string, optional) — Which part of the turn this message contains: intermediate output or the answer. Present when the `type` field is `message`. A turn can produce intermediate messages before the answer, such as a message that describes the steps Jockey is taking. The `commentary` value identifies an intermediate message, and the `final_answer` value identifies the answer. The output contains intermediate output only when the request sets the `include` parameter to `["intermediate_outputs"]`. By default, the output contains the answer only. Treat a message without the `phase` field as the final answer. Treat an unrecognized `phase` value as intermediate output, not as the answer. - `content` (list of ResponseOutputContentPart, optional) — The content parts of the message. Present when `type` is `message`. - `name` (string, optional) — The name of the function. Present when `type` is `function_call`. - `call_id` (string, optional) — The unique identifier for the function call. Present when `type` is `function_call`. - `arguments` (string, optional) — The JSON-encoded arguments for the function call. Present when `type` is `function_call`. - `output` (string, optional) — The function call output. Present when `type` is `function_call_output`. ### ResponseUsage Token usage statistics. - `input_tokens` (integer, optional) — The number of input tokens consumed. - `output_tokens` (integer, optional) — The number of output tokens generated. ### TextParamFormat The output format for the response text. Defaults to plain text. Use `json_schema` to receive a structured JSON object conforming to a provided schema. - `type`: `text` (text) - `type`: `json_schema` (json_schema) - `name` (string, required) — A name identifying the schema. - `schema` (map from string to any, required) — The JSON Schema object defining the structure of the response. The schema must adhere to the [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) specification. **Supported data types** - `array` - `boolean` - `integer` - `null` - `number` - `object` - `string` **Automatic schema changes** The platform adds all object properties to `required` and sets `additionalProperties` to `false` on every object. You do not need to include `required` or `additionalProperties` in your schema. **Unsupported keywords** The following keywords are not supported and may produce incomplete or malformed output without returning an error. Remove them from your schema or replace them with the alternatives below: | Keyword | Recommended alternative | |---------|------------------------| | `oneOf` | Use `anyOf` instead | | `default` | Omit — the platform makes all properties required, so defaults have no effect | | `if` / `then` / `else` | No alternative — omit | | `not` | No alternative — omit | | `patternProperties` | Use `properties` instead | | `contains` | No alternative — omit | | `prefixItems` | No alternative — omit | **Subschema references** You can reference subschemas using `$ref` with these requirements: - Define subschemas within `$defs` at the root of the schema. - External URIs and relative-path references are not supported. For details, see the [JSON Schema documentation on $defs](https://json-schema.org/understanding-json-schema/structuring#defs). **Scale guidance** These are best-practice guidelines, not enforced limits — the platform does not reject schemas that exceed them: - Keep nesting to 5 levels of objects or fewer. - Keep the total number of properties across all objects to 100 or fewer. Schemas that exceed these values may degrade output quality. **Response validation** Check the `status` field on the response to verify the output is complete: - When `status` is `completed`, the response completed normally, and the JSON is valid and complete. - When `status` is `incomplete`, the platform truncated the response at the token limit. This may result in truncated, invalid JSON that fails to parse. - `description` (string, optional) — A description of the schema. - `strict` (boolean, optional) — Specifies whether Jockey must strictly follow the provided schema. This field is accepted and reserved for future use. It does not affect the behavior of Jockey. ### ResponseOutputContentPart A content part within a message output item. - `type` (enum, required) — The type of content part. - Allowed values: `output_text` - `text` (string, required) — The text content. It may contain citation markers, each a number in square brackets such as `[1]`. The `start_index` and `end_index` fields of a citation indicate the location of its marker. To resolve a marker, find the citation at that location. Not every marker has a matching citation; when a marker has none, treat it as a citation you cannot display, not as an error. - `annotations` (list of ResponseAnnotation, required) — Citations that tie spans of the `text` field to what they cite, in order of appearance. Always present, and may be empty. The `start_index` and `end_index` fields locate the marker within the `text` field of this content part, not within the whole response. Different citations can cover the same or overlapping video ranges. Each marker in the `text` field still resolves to at most one citation. ### ResponseAnnotation Ties a span of the message text to what it cites. One object covers all citation kinds. Read the `type` field to tell them apart. The fields fall into two groups that behave differently: `title`, `thumbnail_url` and `hls_url` are always present and nullable: `null` reports a value the platform could not resolve, or one that does not apply to this citation kind (an image has no video to play). `item_id`, `collection_id`, `start_sec` and `end_sec` are absent when they do not apply, never null. `start_sec` and `end_sec` are absent together, never one alone: absent on a `video_citation` means the citation covers the whole video. - `type` (enum, required) — What this citation refers to: - `video_citation`: a time range within a video item. - `image_citation`: a whole image item. - `collection_citation`: an item collection. - Allowed values: `video_citation`, `image_citation`, `collection_citation` - `start_index` (integer, required) — Start of the marker, as a zero-based offset into the `text` field, counted in Unicode code points. - `end_index` (integer, required) — End of the marker, inclusive, in the same units as the `start_index` field. Most languages slice up to but not including the end. To read the marker in Go, Python, or JavaScript, use `text[start_index : end_index + 1]`. - `title` (string, required, nullable) — Display title of the cited item or collection. Always present; `null` when it could not be resolved. - `thumbnail_url` (string, required, nullable) — A signed URL for a preview image. Always present. It is `null` when the image could not be resolved, and on a `collection_citation`, which has no preview. What it shows depends on the value of the `type` field: - `video_citation`: a still image from the video. - `image_citation`: a smaller version of the image. - `hls_url` (string, required, nullable) — A signed URL for video playback, in HLS format (`.m3u8`). Always present. It is `null` when the video could not be resolved, and on every kind except `video_citation`. - `item_id` (string, optional) — The cited item. Present when `type` is `video_citation` or `image_citation`. - `collection_id` (string, optional) — The cited collection. Present when `type` is `collection_citation`. - `start_sec` (double, optional) — Start of the cited range within the video, in seconds. Present when `type` is `video_citation` and the citation specifies a range. Absent (not null) together with the `end_sec` field when the citation covers the whole video, and on every other citation kind. - `end_sec` (double, optional) — End of the cited range within the video, in seconds. Present whenever the `start_sec` field is present. ## Examples **Request** ```json { "knowledge_store_id": "ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56", "input": [ { "type": "message", "role": "user", "content": "Give me the highlight." } ], "stream": false } ``` **SDK Code** ```python import requests url = "https://api.twelvelabs.io/v1.3/responses" payload = { "knowledge_store_id": "ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56", "input": [ { "type": "message", "role": "user", "content": "Give me the highlight." } ], "stream": False } headers = { "x-api-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.twelvelabs.io/v1.3/responses'; const options = { method: 'POST', headers: {'x-api-key': '', 'Content-Type': 'application/json'}, body: '{"knowledge_store_id":"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56","input":[{"type":"message","role":"user","content":"Give me the highlight."}],"stream":false}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/responses" payload := strings.NewReader("{\n \"knowledge_store_id\": \"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56\",\n \"input\": [\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": \"Give me the highlight.\"\n }\n ],\n \"stream\": false\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("x-api-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/responses") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-api-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"knowledge_store_id\": \"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56\",\n \"input\": [\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": \"Give me the highlight.\"\n }\n ],\n \"stream\": false\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.twelvelabs.io/v1.3/responses") .header("x-api-key", "") .header("Content-Type", "application/json") .body("{\n \"knowledge_store_id\": \"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56\",\n \"input\": [\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": \"Give me the highlight.\"\n }\n ],\n \"stream\": false\n}") .asString(); ``` ```php request('POST', 'https://api.twelvelabs.io/v1.3/responses', [ 'body' => '{ "knowledge_store_id": "ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56", "input": [ { "type": "message", "role": "user", "content": "Give me the highlight." } ], "stream": false }', 'headers' => [ 'Content-Type' => 'application/json', 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/responses"); var request = new RestRequest(Method.POST); request.AddHeader("x-api-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"knowledge_store_id\": \"ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56\",\n \"input\": [\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": \"Give me the highlight.\"\n }\n ],\n \"stream\": false\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "x-api-key": "", "Content-Type": "application/json" ] let parameters = [ "knowledge_store_id": "ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56", "input": [ [ "type": "message", "role": "user", "content": "Give me the highlight." ] ], "stream": false ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/responses")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```