Create a response
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
The session identifier for this conversation. Pass this value in subsequent requests to continue the multi-turn conversation.
The object type. Always response.
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.
The status. For the meaning of each value, see the Response statuses section on The response object page.
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.
The response output items. By default, only the final message is included.
Set include to ["intermediate_outputs"] to also receive intermediate
messages, function calls and results, and jockey:web_search items.
The billing information for this response. Only a finished response carries this object:
the last event of a stream (response.completed or response.failed) and the
non-streamed response. Earlier stream events do not carry it. This amount is
informational: it is the list price, before your plan and any discount on your account.
Your invoice is the authoritative record of charges.