Skip to navigation
Agents (Research preview)Responses

Create a response (streaming)

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.

{
  "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]

Authentication

x-api-keystring

Your API key.

Note

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

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.

streamtrueRequired

When true, the response is returned as 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.
Allowed values:
selectionslist of objectsOptional

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

This endpoint returns a stream of object.
response.createdobject

Wraps a response object. Emitted for response.created, response.in_progress, response.completed, and response.failed events.

OR
response.in_progressobject

Wraps a response object. Emitted for response.created, response.in_progress, response.completed, and response.failed events.

OR
response.completedobject

Wraps a response object. Emitted for response.created, response.in_progress, response.completed, and response.failed events.

OR
response.failedobject

Wraps a response object. Emitted for response.created, response.in_progress, response.completed, and response.failed events.

OR
response.output_item.addedobject
Emitted when a new output item starts.
OR
response.content_part.addedobject
Emitted when a content part starts within a message.
OR
response.output_text.deltaobject
Emitted for each incremental text chunk during streaming.
OR
response.output_text.doneobject
Emitted when text streaming for a content part completes.
OR
response.content_part.doneobject
Emitted when a content part is finalized.
OR
response.output_item.doneobject
Emitted when an output item is finalized.
OR
response.function_call_arguments.doneobject
Emitted when function call arguments are complete.
OR
keepaliveobject

A heartbeat frame the server sends about every 10 seconds when no other event has been emitted, for example while a tool call is still running. It carries no response data. Use it to keep the connection alive and to detect stalled streams; otherwise you can ignore it.

sequence_number uses the same counter as all other event types. If you skip keepalive frames, the numbers you see will have gaps; these gaps do not mean events were dropped.

Errors

400
Bad Request Error