---
title: "Create a response"
method: POST
path: "/responses"
tags: ["Responses"]
---

# Create a response

`POST /responses`

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>

## Headers

- `x-api-key` string, required

## Request body

- object
  - `knowledge_store_id` string, required — The unique identifier of the knowledge store to reason over.
  - `input` ResponseInputItem[], required — Provides context to Jockey for this request. Uses [Open Responses input item](https://www.openresponses.org/reference#input-items) conventions.
    - `type` 'message', required — The type of input item.
    - `role` 'user', required — The role of the message author.
    - `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.
  - `session_id` string — 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 — Additional guidance for Jockey, acting as a per-request system prompt.
  - `include` ResponsesPostRequestBodyContentApplicationJsonSchemaIncludeItems[] — 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.
  - `stream` true, required — When `true`, the response is returned as [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE).
  - `selections` ResponseSelection[] — 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.
    - `kind` 'item' | 'collection', 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.
    - `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.
  - `text` TextParam — Controls the output text format for the response.
    - `format` union — 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.
      - object — Plain text output format (default).
        - `type` 'text', required
      - object — Structured JSON output conforming to a provided schema.
        - `type` 'json_schema', required
        - `name` string, required — A name identifying the schema.
        - `description` string — A description of the schema.
        - `schema` object, 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.
        - `strict` boolean — 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.

## Response `200`

## Other responses

- `400` — The request has failed.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/b6d766c2c340/schema)