> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Responses > Reason over a knowledge store and generate responses with the Node.js SDK. The `Responses` class provides methods to reason over the content in a knowledge store and generate responses. # Methods ## Create a response **Description**: 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**: To receive the response as Server-Sent Events (SSE), use [Stream a response](#stream-a-response). **Function signature and example**: **`Function signature`** ```javascript Function signature create( request: TwelvelabsApi.ResponsesCreateRequest, requestOptions?: Responses.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.responses.create({ knowledgeStoreId: "", input: [ { type: "message", role: "user", content: "Summarize what happens in this knowledge store in two sentences.", }, ], // sessionId: "", // instructions: "Additional guidance for Jockey.", // include: ["intermediate_outputs"], // selections: [...], // see the Selections example // text: {...}, // see the Structured output example }); console.log(`ID: ${response.id} Session: ${response.sessionId}`); for (const item of response.output ?? []) { if (item.type === "message") { for (const part of item.content ?? []) { console.log(part.text); for (const a of part.annotations) { // The endIndex field is inclusive, so slice to endIndex + 1. const marker = part.text.slice(a.startIndex, a.endIndex + 1); console.log(` ${marker} -> ${a.type} ${a.title ?? ""}`); } } } } ``` **`Structured output`** ```javascript Structured output import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.responses.create({ knowledgeStoreId: "", input: [ { type: "message", role: "user", content: "Extract a title and a list of up to 3 tags for this content.", }, ], text: { format: { type: "json_schema", name: "content_summary", description: "A short structured summary of the knowledge store content.", schema: { type: "object", properties: { title: { type: "string", description: "A short title." }, tags: { type: "array", description: "Up to three descriptive tags.", items: { type: "string", description: "A single tag." }, }, }, required: ["title", "tags"], additionalProperties: false, }, strict: true, }, }, }); ``` **`Selections`** ```javascript Selections import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.responses.create({ knowledgeStoreId: "", input: [ { type: "message", role: "user", content: "Describe {{sel:0}} in one sentence.", }, ], selections: [{ kind: "item", id: "" }], }); ``` **`Multi-turn conversation`** ```javascript Multi-turn conversation import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.responses.create({ knowledgeStoreId: "", sessionId: "", input: [ { type: "message", role: "user", content: "Now list the three most important moments as bullet points.", }, ], }); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :--------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store to reason over. | | `input` | `ResponseInputItem[]` | Yes | Provides context to Jockey for this request. Uses [Open Responses input item](https://www.openresponses.org/reference#input-items) conventions. | | `sessionId` | `string` | No | 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 `knowledgeStoreId` field must match the knowledge store the session was originally created against, or the request returns `400`. | | `instructions` | `string` | No | Additional guidance for Jockey, acting as a per-request system prompt. | | `include` | `ResponsesCreate` `RequestIncludeItem[]` | No | Additional items to include in the response's `output` array. By default, the `output` array contains only Jockey's final reply. - `intermediate_outputs`: Also includes the steps Jockey took to produce the reply. | | `selections` | `ResponseSelection[]` | No | 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 for the session. Selections sent on later turns add to the set, so you can keep referencing earlier `{{sel:N}}` tokens without resending them. | | `text` | `TextParam` | No | Controls the output text format for the response. | | `requestOptions` | `Responses.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | The `ResponseInputItem` object contains the following properties: | Name | Type | Required | Description | | :-------- | :------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `ResponseInput` `ItemType` | Yes | The type of input item. Values: `message`. | | `role` | `ResponseInput` `ItemRole` | Yes | The role of the message author. Values: `user`. | | `content` | `string` | Yes | 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. | The `ResponseSelection` object contains the following properties: | Name | Type | Required | Description | | :----- | :---------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kind` | `ResponseSelectionKind` | Yes | The type of resource to select. - `item`: A single knowledge store item. - `collection`: A knowledge store item collection. All items in the collection are included in the request. | | `id` | `string` | Yes | The unique identifier of the selected resource. Must use the prefix that matches the `kind` field: `ksi_` for items and `ksic_` for collections. | The `TextParam` object contains the following property: | Name | Type | Required | Description | | :------- | :---------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `format` | `TextParamFormat` | No | The output format for the response text. Defaults to plain text. Set `type` to `json_schema` to receive a structured JSON object conforming to a provided schema. | When `format.type` is `json_schema`, the `format` object contains the following properties: | Name | Type | Required | Description | | :------------ | :--------------------------- | :------- | :-------------------------------------------------- | | `name` | `string` | Yes | The name of the schema. | | `schema` | `Record` `` | Yes | The JSON Schema the response must conform to. | | `description` | `string` | No | An optional description of the schema. | | `strict` | `boolean` | No | Whether Jockey must strictly conform to the schema. | ### Return value Returns a `ResponseObject` object. The `ResponseObject` object contains the following properties: | Name | Type | Description | | :------------------ | :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | A unique identifier for this response. | | `knowledgeStoreId` | `string` | The unique identifier of the knowledge store this response was generated against. | | `sessionId` | `string` | The session identifier for this conversation. Pass this value in subsequent requests to continue the multi-turn conversation. | | `type` | `ResponseObjectType` | The object type. Always `response`. | | `object` | `ResponseObjectObject` | 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. | | `status` | `ResponseStatus` | The status of the response. Values: `completed`, `failed`, `in_progress`, `incomplete`. | | `output` | `ResponseOutputItem[]` | 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. Each message item has a `phase` field: the `commentary` value identifies intermediate output, and the `final_answer` value identifies the answer. A message without the `phase` field is the final answer. | | `incompleteDetails` | `ResponseIncompleteDetails` | The reason the response was truncated before the answer was complete. Always sent. 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. The text in the response is an incomplete answer, not the full one. | | `usage` | `ResponseUsage` | Token usage for the response. | | `createdAt` | `string` | The timestamp when the response was created. | The `ResponseOutputItem` object contains the following properties: | Name | Type | Description | | :---------- | :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `ResponseOutputItemType` | The type of output item. Values: `message`, `function_call`, `function_call_output`. | | `id` | `string` | A unique identifier for this item. | | `status` | `ResponseStatus` | The status of the item. Values: `completed`, `failed`, `in_progress`, `incomplete`. | | `role` | `ResponseOutputItemRole` | The role of the message author. Present when `type` is `message`. Values: `assistant`. | | `phase` | `string` | Which part of the turn this message contains: intermediate output or the answer. Present when the `type` field is `message`. Treat an unrecognized `phase` value as intermediate output, not as the answer. | | `content` | `ResponseOutputContentPart[]` | The content parts of the message. Present when `type` is `message`. | | `name` | `string` | The name of the function. Present when `type` is `function_call`. | | `callId` | `string` | The unique identifier for the function call. Present when `type` is `function_call`. | | `arguments` | `string` | The JSON-encoded arguments for the function call. Present when `type` is `function_call`. | | `output` | `string` | The function call output. Present when `type` is `function_call_output`. | The `ResponseOutputContentPart` object contains the following properties: | Name | Type | Description | | :------------ | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `ResponseOutputContentPartType` | The type of content part. Values: `output_text`. | | `text` | `string` | 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` | `ResponseAnnotation[]` | 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. | For the full list of fields on each citation in the `annotations` array, see [Create a response](/v1.3/api-reference/responses/create). ### API Reference [Create a response](/v1.3/api-reference/responses/create). ### Related guide [Create a response](/v1.3/agents/guides/create-a-response). ## Stream a response **Description**: This method uses Jockey to reason over content in a knowledge store and create a response, streamed as Server-Sent Events (SSE). It returns an async-iterable stream of `ResponseStreamEvent` objects. For the non-streaming variant, see [Create a response](#create-a-response). **Function signature and example**: **`Function signature`** ```javascript Function signature createStream( request: TwelvelabsApi.ResponsesCreateStreamRequest, requestOptions?: Responses.RequestOptions ): Promise> ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const stream = await client.responses.createStream({ knowledgeStoreId: "", input: [ { type: "message", role: "user", content: "Give a one-sentence summary.", }, ], // sessionId: "", // instructions: "Additional guidance for Jockey.", // include: ["intermediate_outputs"], // selections: [...], // see the Selections example under Create a response // text: {...}, // see the Structured output example under Create a response }); for await (const event of stream) { if (event.type === "response.output_text.delta") { process.stdout.write(event.delta); } } ``` ### Parameters This method accepts the same parameters as [Create a response](#create-a-response). ### Return value Returns an async-iterable `Stream`. Each event has a `type` field that identifies the event; unlike the response object, events have no `object` field. For example, `response.output_text.delta` events deliver incremental output text in a `delta` field, a `keepalive` event is a heartbeat the server sends about every 10 seconds while no other events are being emitted; it contains no response data and can be ignored, and a `response.completed` event signals the end of the stream. `sequence_number` is a single counter shared by all event types, so skipping `keepalive` frames creates gaps in it; those gaps are not dropped events. When you request intermediate outputs, the `response.output_item.added` event delivers each message with its `phase` field already set, so you can identify intermediate output or the answer before any of its text streams in. Citations do not stream in with the text: the `annotations` array is empty while a content part is being generated, and the `response.content_part.done` event contains the completed part with all of its citations. ### API Reference [Create a response](/v1.3/api-reference/responses/create). ### Related guide [Streaming](/v1.3/agents/guides/create-a-response/streaming).