The ResponsesClient class provides methods to reason over the content in a knowledge store and generate responses.

Methods

Create a response

Description: 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: To receive the response as Server-Sent Events (SSE), use Stream a response.

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.

Function signature and example:

def create(
    self,
    *,
    knowledge_store_id: str,
    input: typing.Sequence[ResponseInputItem],
    session_id: typing.Optional[str] = OMIT,
    instructions: typing.Optional[str] = OMIT,
    include: typing.Optional[typing.Sequence[ResponsesCreateRequestIncludeItem]] = OMIT,
    tools: typing.Optional[typing.Sequence[ResponseToolInput]] = OMIT,
    selections: typing.Optional[typing.Sequence[ResponseSelection]] = OMIT,
    text: typing.Optional[TextParam] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> ResponseObject:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store to reason over.
`input`	`typing.` `Sequence` `[ResponseInputItem]`	Yes	Provides context to Jockey for this request. Uses Open Responses input item conventions.
`session_id`	`typing.` `Optional[str]`	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 `knowledge_store_id` field must match the knowledge store the session was originally created against, or the request returns `400`.
`instructions`	`typing.` `Optional[str]`	No	Additional guidance for Jockey, acting as a per-request system prompt.
`include`	`typing.` `Optional` `[typing.Sequence` `[...IncludeItem]]`	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.
`tools`	`typing.` `Optional` `[typing.Sequence` `[ResponseToolInput]]`	No	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 `[]`, 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.
`selections`	`typing.` `Optional` `[typing.Sequence` `[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`	`typing.` `Optional` `[TextParam]`	No	Controls the output text format for the response.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

The ResponseInputItem class 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`	`str`	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 ResponseToolInput class contains the following property:

Name	Type	Required	Description
`type`	`typing.Literal` `["jockey:web_search"]`	No	The type of tool. Defaults to `jockey:web_search`.

The ResponseSelection class 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`	`str`	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 class contains the following property:

Name	Type	Required	Description
`format`	`Optional` `[TextParamFormat]`	No	The output format for the response text. Defaults to plain text. Use `TextParamFormat_JsonSchema` to receive a structured JSON object conforming to a provided schema.

The TextParamFormat_JsonSchema class contains the following properties:

Name	Type	Required	Description
`name`	`str`	Yes	The name of the schema.
`schema_`	`typing.Dict` `[str, Any]`	Yes	The JSON Schema the response must conform to. Sent on the wire as `schema`.
`description`	`Optional[str]`	No	An optional description of the schema.
`strict`	`Optional[bool]`	No	Whether Jockey must strictly conform to the schema.

Return value

Returns a ResponseObject object. The ResponseObject class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	A unique identifier for this response.
`knowledge_store_id`	`Optional[str]`	The unique identifier of the knowledge store this response was generated against.
`session_id`	`Optional[str]`	The session identifier for this conversation. Pass this value in subsequent requests to continue the multi-turn conversation.
`type`	`Optional` `[ResponseObjectType]`	The object type. Always `response`.
`object`	`Optional` `[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`	`Optional` `[ResponseStatus]`	The status of the response. Values: `completed`, `failed`, `in_progress`, `incomplete`.
`output`	`Optional` `[typing.List` `[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.
`incomplete_details`	`Optional` `[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.
`billing`	`Optional` `[ResponseBilling]`	The billing information for this response: its list-price cost in US dollars.
`created_at`	`Optional` `[datetime]`	The timestamp when the response was created.

The ResponseOutputItem class contains the following properties:

Name	Type	Description
`type`	`ResponseOutputItemType`	The type of output item. Values: `message`, `function_call`, `function_call_output`.
`id`	`str`	A unique identifier for this item.
`status`	`ResponseStatus`	The status of the item. Values: `completed`, `failed`, `in_progress`, `incomplete`.
`role`	`Optional` `[ResponseOutputItemRole]`	The role of the message author. Present when `type` is `message`. Values: `assistant`.
`phase`	`Optional` `[str]`	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`	`Optional` `[typing.List` `[ResponseOutputContentPart]]`	The content parts of the message. Present when `type` is `message`.
`name`	`Optional` `[str]`	The name of the function. Present when `type` is `function_call`.
`call_id`	`Optional` `[str]`	The unique identifier for the function call. Present when `type` is `function_call`.
`arguments`	`Optional` `[str]`	The JSON-encoded arguments for the function call. Present when `type` is `function_call`.
`output`	`Optional` `[str]`	The function call output. Present when `type` is `function_call_output`.

The ResponseOutputContentPart class contains the following properties:

Name	Type	Description
`type`	`ResponseOutputContentPartType`	The type of content part. Values: `output_text`.
`text`	`str`	The text content. Media citations use numbered markers such as `[1]`. A web citation can cover text that is not a marker. Its span can also cover a provider marker, such as `\ue200cite\ue202turn0search1\ue201` (shown with Unicode escapes). Use the `start_index` and `end_index` fields of an annotation to locate the text that it covers, and its `url` to render a web source link. The annotation identifies the source; the marker text does not. Treat a marker without a matching annotation as a citation you cannot display, not as a response error.
`annotations`	`typing.List` `[ResponseAnnotation]`	Contains the citations. Each citation identifies a span of the `text` field and the source it cites. Always present, and may be empty. The `start_index` and `end_index` fields locate the cited span within the `text` field of this content part, not within the whole response. Both bounds are inclusive and count Unicode code points. Text spans can overlap or be identical, including across citation types. A web citation can cover a numbered media marker. Resolve each annotation independently; do not assume disjoint spans or array order by offset. Different video citations can also cover overlapping video time ranges.

For the full list of fields on each citation in the annotations array, see Create a response.

Citations: Each citation identifies a span of the answer text and the source that supports it. Media citations point to knowledge store items and collections, and web citations point to public web sources.

The platform can add new citation types. If you encounter a citation type you do not recognize, keep the response text and display the citations you do recognize.

Citation offsets count Unicode code points, and both bounds are inclusive. Use the offsets of an annotation to locate the text it covers. When multiple annotations cover the same text, keep the source of each one.

API Reference

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 iterator of ResponseStreamEvent objects. For the non-streaming variant, see Create a response.

Function signature and example:

def create_stream(
    self,
    *,
    knowledge_store_id: str,
    input: typing.Sequence[ResponseInputItem],
    session_id: typing.Optional[str] = OMIT,
    instructions: typing.Optional[str] = OMIT,
    include: typing.Optional[typing.Sequence[ResponsesCreateStreamRequestIncludeItem]] = OMIT,
    tools: typing.Optional[typing.Sequence[ResponseToolInput]] = OMIT,
    selections: typing.Optional[typing.Sequence[ResponseSelection]] = OMIT,
    text: typing.Optional[TextParam] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> typing.Iterator[ResponseStreamEvent]:

Parameters

This method accepts the same parameters as Create a response.

Return value

Returns an iterator of ResponseStreamEvent objects. 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, and a response.completed event signals the end of the stream. 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.

Streaming.

Methods

Create a response

Parameters

Return value

API Reference

Related guide

Stream a response

Parameters

Return value

API Reference

Related guide