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.
Web sources: Jockey can search public web sources while it generates a response. To allow this, include { "type": "jockey:web_search" } in the tools array. The response can then cite these sources alongside content from the knowledge store, as url_citation annotations. Jockey decides whether to use an available tool, so enabling web search does not guarantee a search. To make a search more likely, explicitly tell Jockey what information to look up in input or instructions. A prompt that asks Jockey to search the web does not enable web search by itself. If you omit tools or pass [], Jockey cannot search public web sources, even when the prompt requests it.
Example response
Example streamed response (SSE)
Authentication
Your API key.
You can find your API key on the API Keys page.
Request
User messages that provide context to Jockey for this request. Uses Open Responses input item conventions.
Output items cannot be submitted as input. Use session_id to continue a conversation.
When true, the response is returned as Server-Sent Events (SSE).
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.
Additional guidance for Jockey, acting as a per-request system prompt.
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.
Tools that Jockey can use while it generates the response.
Include { "type": "jockey:web_search" } to allow web search. Jockey decides
whether to use an available tool, so enabling web search does not guarantee
a search. To make a search more likely, explicitly tell Jockey what
information to look up in input or instructions.
A prompt that asks Jockey to search the web does not enable web search by
itself. If you omit tools or pass null or [], Jockey cannot search
public web sources, even when the prompt requests it. The tools setting
applies to each request on its own, including requests that continue a
session.
This list does not control Jockey’s built-in knowledge store operations.
If a requested tool is unavailable for the request, the request fails
with HTTP 422 and code parameter_invalid. Remove the unavailable
tool from the tools array and retry.
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.
Response
Wraps a response object. Emitted for response.created, response.in_progress,
response.completed, and response.failed events.
Wraps a response object. Emitted for response.created, response.in_progress,
response.completed, and response.failed events.
Wraps a response object. Emitted for response.created, response.in_progress,
response.completed, and response.failed events.
Wraps a response object. Emitted for response.created, response.in_progress,
response.completed, and response.failed events.
Progress for a web-search call. Included only when the request sets include: ["intermediate_outputs"].
The item_id links to the corresponding jockey:web_search output item.
Progress for a web-search call. Included only when the request sets include: ["intermediate_outputs"].
The item_id links to the corresponding jockey:web_search output item.
Progress for a web-search call. Included only when the request sets include: ["intermediate_outputs"].
The item_id links to the corresponding jockey:web_search output item.