# AI API > Full OpenAPI reference for Bkper AI — model discovery, complete responses, streaming events, and schemas. Public inference API implementing the stateless Bkper [Open Responses 2026-04-24](https://www.openresponses.org/specification/2026-04-24) profile. ## Base URL ```text https://ai.bkper.app ``` ## OpenAPI specification The canonical machine-readable contract is available at [https://ai.bkper.app/openapi.json](https://ai.bkper.app/openapi.json). ## Authentication Send a Bkper OAuth access token with every inference request: ```text Authorization: Bearer ``` See the [Bkper AI provider guide](https://bkper.com/docs/ai/bkper-ai-provider) for token setup and client configuration. ## Request workflow 1. Call `GET /v1/models` to discover the current public model IDs, capabilities, limits, and usage rates. 2. Select a returned model ID. 3. Call `POST /v1/responses` with that model and explicit input. Use `stream: false` for a complete JSON response. Use `stream: true` for semantic server-sent events ending with `data: [DONE]`. ## Stateless operation and privacy Bkper AI does not persist response state. Omitted `store` defaults to `false`; the only accepted explicit value is `store: false`. Continue a conversation by sending explicit prior items in `input`. Bkper usage logs record attribution, status, token, cache, and cost metadata. They exclude prompt and response content. Provider-specific retention and caching boundaries are documented in the Bkper AI provider guide. ## Usage Requests consume the authenticated user's Bkper AI allowance. The model catalog provides current effective rates and limits. New requests stop when the recorded allowance is exhausted; Bkper does not create automatic paid AI overages. See [Models and Usage](https://bkper.com/docs/ai/models) for policy details. ## Attribution Clients may send the optional `bkper-ai-source` header with a stable lowercase application identifier so usage can be attributed to that client. ## Specification - OpenAPI: `3.1.0` - API version: `v1` - External documentation: ```json { "description": "Bkper AI provider documentation", "url": "https://bkper.com/docs/ai/bkper-ai-provider" } ``` ### Servers ```json [ { "url": "https://ai.bkper.app" } ] ``` ### Specification extensions ```json { "x-open-responses-version": "2026-04-24", "x-open-responses-specification": "https://www.openresponses.org/specification/2026-04-24" } ``` ## Tags ```json [ { "name": "Models" }, { "name": "Responses" } ] ``` ## Authentication ```json { "bkperBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Bkper OAuth access token", "description": "Send a Bkper OAuth access token. See [token setup](https://bkper.com/docs/ai/bkper-ai-provider#get-a-token-for-local-testing)." } } ``` ## Operations ### `GET /v1/models` — List available models Returns the current model IDs and effective capabilities available through Bkper AI. Operation contract: ```json { "tags": [ "Models" ], "operationId": "listModels", "summary": "List available models", "description": "Returns the current model IDs and effective capabilities available through Bkper AI.", "security": [], "responses": { "200": { "description": "Available Bkper AI models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } } } } ``` ### `POST /v1/responses` — Generate a response Generates a response using the Bkper Open Responses 2026-04-24 profile. Bkper AI is stateless: send explicit prior input and output items to continue a conversation. Model IDs, reasoning levels, structured-output support, limits, and inline file types are published by GET /v1/models. Some request controls are model-dependent and return a 400 error when unavailable. Set stream to true to receive semantic server-sent events ending with data: [DONE]. Operation contract: ```json { "summary": "Generate a response", "description": "Generates a response using the Bkper Open Responses 2026-04-24 profile. Bkper AI is stateless: send explicit prior input and output items to continue a conversation. Model IDs, reasoning levels, structured-output support, limits, and inline file types are published by GET /v1/models. Some request controls are model-dependent and return a 400 error when unavailable. Set stream to true to receive semantic server-sent events ending with data: [DONE].", "operationId": "createResponse", "parameters": [ { "name": "bkper-ai-source", "in": "header", "required": false, "description": "Stable lowercase client or application identifier used for usage attribution. Invalid values are recorded as unknown.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponseBody" }, "examples": { "complete": { "summary": "Complete response", "value": { "model": "openai/gpt-5.6-luna", "input": "Reply with exactly: connected", "store": false } }, "streaming": { "summary": "Streaming response", "value": { "model": "openai/gpt-5.6-luna", "input": "Explain Bkper in one sentence.", "stream": true, "store": false } }, "structured": { "summary": "Structured JSON response", "value": { "model": "openai/gpt-5.6-luna", "input": "Return the invoice number.", "text": { "format": { "type": "json_schema", "name": "invoice", "schema": { "type": "object", "properties": { "invoice_number": { "type": "string" } }, "required": [ "invoice_number" ], "additionalProperties": false }, "strict": true } }, "store": false } } } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseResource" } }, "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ResponseCreatedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseQueuedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseInProgressStreamingEvent" }, { "$ref": "#/components/schemas/ResponseCompletedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFailedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseIncompleteStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryPartAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryPartDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseContentPartAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseContentPartDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseRefusalDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseRefusalDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextAnnotationAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFunctionCallArgumentsDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFunctionCallArgumentsDoneStreamingEvent" }, { "$ref": "#/components/schemas/ErrorStreamingEvent" } ], "discriminator": { "propertyName": "type" } } } } }, "400": { "description": "Invalid request or unsupported capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BkperErrorResponse" } } } }, "401": { "description": "Missing or invalid Bkper bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BkperErrorResponse" } } } }, "402": { "description": "Subscription payment is overdue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BkperErrorResponse" } } } }, "403": { "description": "Bkper AI entitlement is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BkperErrorResponse" } } } }, "429": { "description": "Monthly allowance exhausted or provider throttled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BkperErrorResponse" } } } }, "499": { "description": "Client aborted the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BkperErrorResponse" } } } }, "502": { "description": "Provider or transport failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BkperErrorResponse" } } } }, "default": { "description": "Other provider or transport rejection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BkperErrorResponse" } } } } }, "tags": [ "Responses" ], "security": [ { "bkperBearer": [] } ] } ``` ## Schemas ### ReasoningSummaryContentParam ```json { "properties": { "type": { "type": "string", "enum": [ "summary_text" ], "description": "The content type. Always `summary_text`.", "default": "summary_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The reasoning summary text." } }, "type": "object", "required": [ "type", "text" ], "additionalProperties": false } ``` ### ReasoningItemParam ```json { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this reasoning item.", "example": "rs_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "reasoning" ], "description": "The item type. Always `reasoning`.", "default": "reasoning" }, "summary": { "items": { "$ref": "#/components/schemas/ReasoningSummaryContentParam" }, "type": "array", "description": "Reasoning summary content associated with this item." }, "content": { "anyOf": [ { "type": "null" } ] }, "encrypted_content": { "anyOf": [ { "type": "string", "description": "An encrypted representation of the reasoning content." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "summary" ], "additionalProperties": false } ``` ### InputTextContentParam ```json { "properties": { "type": { "type": "string", "enum": [ "input_text" ], "description": "The type of the input item. Always `input_text`.", "default": "input_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The text input to the model." } }, "type": "object", "required": [ "type", "text" ], "title": "Input text", "description": "A text input to the model.", "x-unionDisplay": "section", "x-unionTitle": "Content Type", "additionalProperties": false } ``` ### InputImageContentParamAutoParam ```json { "properties": { "type": { "type": "string", "enum": [ "input_image" ], "description": "The type of the input item. Always `input_image`.", "default": "input_image" }, "image_url": { "type": "string", "maxLength": 20971520, "description": "An HTTP(S) URL or supported base64 image data URL. Remote URL availability depends on the selected model." }, "detail": { "allOf": [ { "$ref": "#/components/schemas/ImageDetail" }, { "description": "The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`." } ] } }, "type": "object", "required": [ "type", "image_url" ], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](https://www.openresponses.org/reference/2026-04-24#object-InputImageContentParamAutoParam)", "additionalProperties": false } ``` ### InputFileContentParam ```json { "properties": { "type": { "type": "string", "enum": [ "input_file" ], "description": "The type of the input item. Always `input_file`.", "default": "input_file" }, "filename": { "type": "string", "description": "The name of the file to be sent to the model.", "minLength": 1 }, "file_data": { "type": "string", "maxLength": 33554432, "description": "The base64-encoded data of the file to be sent to the model.", "minLength": 1 } }, "type": "object", "required": [ "type", "filename", "file_data" ], "title": "Input file", "description": "A file input to the model.", "additionalProperties": false } ``` ### UserMessageItemParam ```json { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "message" ], "description": "The item type. Always `message`." }, "role": { "type": "string", "enum": [ "user" ], "description": "The message role. Always `user`.", "default": "user" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" }, { "$ref": "#/components/schemas/InputImageContentParamAutoParam" }, { "$ref": "#/components/schemas/InputFileContentParam" } ], "description": "A piece of message content, such as text, an image, or a file.", "discriminator": { "propertyName": "type" } }, "type": "array", "minItems": 1 }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "anyOf": [ { "type": "string", "description": "The status of the message item." }, { "type": "null" } ] } }, "type": "object", "required": [ "role", "content" ], "additionalProperties": false } ``` ### SystemMessageItemParam ```json { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "message" ], "description": "The item type. Always `message`." }, "role": { "type": "string", "enum": [ "system" ], "description": "The message role. Always `system`.", "default": "system" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" } ], "discriminator": { "propertyName": "type" } }, "type": "array", "minItems": 1 }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "anyOf": [ { "type": "string", "description": "The status of the message item." }, { "type": "null" } ] } }, "type": "object", "required": [ "role", "content" ], "additionalProperties": false } ``` ### DeveloperMessageItemParam ```json { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "message" ], "description": "The item type. Always `message`." }, "role": { "type": "string", "enum": [ "developer" ], "description": "The message role. Always `developer`.", "default": "developer" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" } ], "discriminator": { "propertyName": "type" } }, "type": "array", "minItems": 1 }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "anyOf": [ { "type": "string", "description": "The status of the message item." }, { "type": "null" } ] } }, "type": "object", "required": [ "role", "content" ], "additionalProperties": false } ``` ### UrlCitationParam ```json { "properties": { "type": { "type": "string", "enum": [ "url_citation" ], "description": "The citation type. Always `url_citation`.", "default": "url_citation" }, "start_index": { "type": "integer", "minimum": 0, "description": "The index of the first character of the citation in the message." }, "end_index": { "type": "integer", "minimum": 0, "description": "The index of the last character of the citation in the message." }, "url": { "type": "string", "description": "The URL of the cited resource." }, "title": { "type": "string", "description": "The title of the cited resource." } }, "type": "object", "required": [ "type", "start_index", "end_index", "url", "title" ] } ``` ### OutputTextContentParam ```json { "properties": { "type": { "type": "string", "enum": [ "output_text" ], "description": "The content type. Always `output_text`.", "default": "output_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The text content." }, "annotations": { "oneOf": [ { "items": { "$ref": "#/components/schemas/UrlCitationParam" }, "type": "array" } ], "description": "Citations associated with the text content." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array" } }, "type": "object", "required": [ "type", "text" ], "additionalProperties": false } ``` ### RefusalContentParam ```json { "properties": { "type": { "type": "string", "enum": [ "refusal" ], "description": "The content type. Always `refusal`.", "default": "refusal" }, "refusal": { "type": "string", "maxLength": 10485760, "description": "The refusal text." } }, "type": "object", "required": [ "type", "refusal" ], "additionalProperties": false } ``` ### AssistantMessageItemParam ```json { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "message" ], "description": "The item type. Always `message`." }, "role": { "type": "string", "enum": [ "assistant" ], "description": "The role of the message author. Always `assistant`.", "default": "assistant" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/OutputTextContentParam" }, { "$ref": "#/components/schemas/RefusalContentParam" } ], "description": "A piece of assistant message content, such as text or a refusal.", "discriminator": { "propertyName": "type" } }, "type": "array", "minItems": 1 }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "phase": { "type": "string", "enum": [ "commentary", "final_answer" ], "description": "Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). when sending follow-up requests, preserve and resend phase on all assistant messages. Omitting it can degrade performance. Not used for user messages.", "x-openresponses-added-in": "2026-04-24" }, "status": { "anyOf": [ { "type": "string", "description": "The status of the message item." }, { "type": "null" } ] } }, "type": "object", "required": [ "role", "content" ], "additionalProperties": false } ``` ### FunctionCallItemParam ```json { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this function tool call.", "example": "fc_123" }, { "type": "null" } ] }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the function tool call generated by the model." }, "type": { "type": "string", "enum": [ "function_call" ], "description": "The item type. Always `function_call`.", "default": "function_call" }, "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The name of the function to call." }, "arguments": { "type": "string", "description": "The function arguments as a JSON string." }, "status": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/FunctionCallStatus" }, { "description": "The status of the function tool call." } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "call_id", "type", "name", "arguments" ], "additionalProperties": false } ``` ### FunctionCallOutputItemParam ```json { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of the function tool call output. Populated when this item is returned via API.", "example": "fc_123" }, { "type": "null" } ] }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the function tool call generated by the model." }, "type": { "type": "string", "enum": [ "function_call_output" ], "description": "The type of the function tool call output. Always `function_call_output`.", "default": "function_call_output" }, "output": { "oneOf": [ { "type": "string", "maxLength": 10485760, "description": "A JSON string of the output of the function tool call." }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" }, { "$ref": "#/components/schemas/InputImageContentParamAutoParam" }, { "$ref": "#/components/schemas/InputFileContentParam" } ], "description": "A piece of message content, such as text, an image, or a file.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "An array of content outputs (text, image, file) for the function tool call." } ], "description": "Text, image, or file output of the function tool call." }, "status": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/FunctionCallStatus" }, { "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "call_id", "type", "output" ], "title": "Function tool call output", "description": "The output of a function tool call. Inline file content is accepted only when the selected model supports that file type in function outputs.", "additionalProperties": false } ``` ### ItemParam ```json { "oneOf": [ { "$ref": "#/components/schemas/ReasoningItemParam" }, { "$ref": "#/components/schemas/UserMessageItemParam" }, { "$ref": "#/components/schemas/SystemMessageItemParam" }, { "$ref": "#/components/schemas/DeveloperMessageItemParam" }, { "$ref": "#/components/schemas/AssistantMessageItemParam" }, { "$ref": "#/components/schemas/FunctionCallItemParam" }, { "$ref": "#/components/schemas/FunctionCallOutputItemParam" } ], "x-unionDisplay": "section", "x-unionTitle": "Input Item Types" } ``` ### IncludeEnum ```json { "type": "string", "enum": [ "reasoning.encrypted_content" ], "description": "Additional response data to include. Only encrypted reasoning continuity data is supported.", "x-enumDescriptions": { "reasoning.encrypted_content": "Includes provider-sealed reasoning state for explicit stateless continuation." } } ``` ### EmptyModelParam ```json { "properties": {}, "type": "object", "required": [] } ``` ### FunctionToolParam ```json { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "$ref": "#/components/schemas/EmptyModelParam" }, { "type": "null" } ] }, "strict": { "type": "boolean", "description": "Whether to enforce strict function parameters. Some models require strict function tools and reject false." }, "type": { "type": "string", "enum": [ "function" ], "default": "function" } }, "type": "object", "required": [ "name", "type" ], "additionalProperties": false, "description": "Defines a function tool. See [Open Responses function tools](https://www.openresponses.org/reference/2026-04-24#object-FunctionToolParam)." } ``` ### ResponsesToolParam ```json { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolParam" } ], "discriminator": { "propertyName": "type" }, "x-unionDisplay": "section", "x-unionTitle": "Tool Types" } ``` ### SpecificFunctionParam ```json { "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The tool to call. Always `function`.", "default": "function" }, "name": { "type": "string", "description": "The name of the function tool to call.", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } }, "type": "object", "required": [ "type", "name" ], "additionalProperties": false } ``` ### SpecificToolChoiceParam ```json { "oneOf": [ { "$ref": "#/components/schemas/SpecificFunctionParam" } ] } ``` ### ToolChoiceValueEnum ```json { "type": "string", "enum": [ "none", "auto", "required" ], "x-enumDescriptions": { "auto": "Let the model choose the tools from among the provided set.", "none": "Restrict the model from calling any tools.", "required": "Require the model to call a tool." } } ``` ### ToolChoiceParam ```json { "oneOf": [ { "$ref": "#/components/schemas/SpecificToolChoiceParam" }, { "$ref": "#/components/schemas/ToolChoiceValueEnum" } ], "description": "Controls which tool the model should use, if any." } ``` ### TextParam ```json { "properties": { "format": { "description": "The format configuration for text output.", "oneOf": [ { "$ref": "#/components/schemas/TextFormatParam" }, { "type": "null" } ] } }, "type": "object", "required": [], "additionalProperties": false } ``` ### ReasoningEffortEnum ```json { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "x-enumDescriptions": { "high": "Use a higher reasoning effort to improve answer quality.", "max": "Use the highest reasoning effort available.", "medium": "Use a balanced reasoning effort.", "minimal": "Use minimal reasoning effort for the fastest responses.", "low": "Use a lower reasoning effort for faster responses.", "none": "Restrict the model from performing any reasoning before emitting a final answer.", "xhigh": "Use a very high reasoning effort." } } ``` ### ReasoningSummaryEnum ```json { "type": "string", "enum": [ "concise", "detailed", "auto" ], "x-enumDescriptions": { "auto": "Allow the model to decide when to summarize.", "concise": "Emit concise summaries of reasoning content.", "detailed": "Emit details summaries of reasoning content." } } ``` ### ReasoningParam ```json { "properties": { "effort": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffortEnum" } ], "description": "Controls the level of reasoning effort the model should apply. Higher effort may increase latency and cost." }, { "type": "null" } ] }, "summary": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningSummaryEnum" }, { "description": "Controls whether the response includes a reasoning summary." } ] }, { "type": "null" } ] } }, "type": "object", "required": [], "description": "Configuration options for [reasoning models](https://www.openresponses.org/reference/2026-04-24#enum-ReasoningEffortEnum).", "additionalProperties": false } ``` ### CreateResponseBody ```json { "properties": { "model": { "type": "string", "description": "A model ID returned by GET /v1/models.", "examples": [ "openai/gpt-5.6-luna", "openai/gpt-5.6-terra", "xai/grok-4.5", "google/gemini-3.6-flash" ] }, "input": { "oneOf": [ { "type": "string", "maxLength": 10485760 }, { "items": { "$ref": "#/components/schemas/ItemParam" }, "type": "array" } ], "description": "Context to provide to the model for the scope of this request. May either be a string or an array of input items. If a string is provided, it is interpreted as a user message." }, "include": { "items": { "$ref": "#/components/schemas/IncludeEnum" }, "type": "array" }, "tools": { "items": { "$ref": "#/components/schemas/ResponsesToolParam" }, "type": "array", "description": "A list of tools that the model may call while generating the response." }, "tool_choice": { "x-unionTitle": "ToolChoiceParam", "allOf": [ { "$ref": "#/components/schemas/ToolChoiceParam" }, { "description": "Controls which tool the model should use, if any." } ] }, "text": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextParam" }, { "description": "Configuration options for text output." } ] }, { "type": "null" } ] }, "temperature": { "anyOf": [ { "type": "number", "description": "Sampling temperature to use, between 0 and 2. Higher values make the output more random.", "minimum": 0, "maximum": 2 }, { "type": "null" } ] }, "top_p": { "anyOf": [ { "type": "number", "description": "Nucleus sampling parameter, between 0 and 1. The model considers only the tokens with the top cumulative probability.", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "presence_penalty": { "anyOf": [ { "type": "number", "description": "Penalizes new tokens based on whether they appear in the text so far.", "minimum": -2, "maximum": 2 }, { "type": "null" } ], "description": "Availability depends on the selected model. Unsupported values return an invalid request error." }, "frequency_penalty": { "anyOf": [ { "type": "number", "description": "Penalizes new tokens based on their frequency in the text so far.", "minimum": -2, "maximum": 2 }, { "type": "null" } ], "description": "Availability depends on the selected model. Unsupported values return an invalid request error." }, "parallel_tool_calls": { "anyOf": [ { "type": "boolean", "description": "Whether the model may call multiple tools in parallel." }, { "type": "null" } ], "description": "Availability depends on the selected model. Unsupported values return an invalid request error." }, "stream": { "type": "boolean", "description": "Whether to stream response events as server-sent events." }, "max_output_tokens": { "anyOf": [ { "type": "integer", "minimum": 16, "description": "The maximum number of tokens the model may generate for this response." }, { "type": "null" } ] }, "reasoning": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningParam" }, { "description": "Configuration options for reasoning behavior." } ] }, { "type": "null" } ] }, "prompt_cache_key": { "anyOf": [ { "type": "string", "maxLength": 64, "description": "A key to use when reading from or writing to the prompt cache." }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string", "description": "Additional instructions to guide the model for this request." }, { "type": "null" } ] }, "store": { "type": "boolean", "const": false, "default": false, "description": "Bkper AI is stateless. The only supported value is false." } }, "type": "object", "required": [ "model", "input" ], "additionalProperties": false } ``` ### IncompleteDetails ```json { "properties": { "reason": { "type": "string", "description": "The reason the response could not be completed." } }, "type": "object", "required": [ "reason" ], "title": "Incomplete details", "description": "Details about why the response was incomplete." } ``` ### UrlCitationBody ```json { "properties": { "type": { "type": "string", "enum": [ "url_citation" ], "description": "The type of the URL citation. Always `url_citation`.", "default": "url_citation" }, "url": { "type": "string", "description": "The URL of the web resource." }, "start_index": { "type": "integer", "description": "The index of the first character of the URL citation in the message." }, "end_index": { "type": "integer", "description": "The index of the last character of the URL citation in the message." }, "title": { "type": "string", "description": "The title of the web resource." } }, "type": "object", "required": [ "type", "url", "start_index", "end_index", "title" ], "title": "URL citation", "description": "A citation for a web resource used to generate a model response." } ``` ### Annotation ```json { "oneOf": [ { "$ref": "#/components/schemas/UrlCitationBody" } ], "description": "An annotation that applies to a span of output text.", "discriminator": { "propertyName": "type" } } ``` ### TopLogProb ```json { "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "items": { "type": "integer" }, "type": "array" } }, "type": "object", "required": [ "token", "logprob", "bytes" ], "title": "Top log probability", "description": "The top log probability of a token." } ``` ### LogProb ```json { "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "items": { "type": "integer" }, "type": "array" }, "top_logprobs": { "items": { "$ref": "#/components/schemas/TopLogProb" }, "type": "array" } }, "type": "object", "required": [ "token", "logprob", "bytes", "top_logprobs" ], "title": "Log probability", "description": "The log probability of a token." } ``` ### OutputTextContent ```json { "properties": { "type": { "type": "string", "enum": [ "output_text" ], "description": "The type of the output text. Always `output_text`.", "default": "output_text" }, "text": { "type": "string", "description": "The text output from the model." }, "annotations": { "items": { "$ref": "#/components/schemas/Annotation" }, "type": "array", "description": "The annotations of the text output." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array" } }, "type": "object", "required": [ "type", "text", "annotations" ], "title": "Output text", "description": "A text output from the model." } ``` ### SummaryTextContent ```json { "properties": { "type": { "type": "string", "enum": [ "summary_text" ], "description": "The type of the object. Always `summary_text`.", "default": "summary_text" }, "text": { "type": "string", "description": "A summary of the reasoning output from the model so far." } }, "type": "object", "required": [ "type", "text" ], "title": "Summary text", "description": "A summary text from the model." } ``` ### ReasoningTextContent ```json { "properties": { "type": { "type": "string", "enum": [ "reasoning_text" ], "description": "The type of the reasoning text. Always `reasoning_text`.", "default": "reasoning_text" }, "text": { "type": "string", "description": "The reasoning text from the model." } }, "type": "object", "required": [ "type", "text" ], "title": "Reasoning text", "description": "Reasoning text from the model." } ``` ### RefusalContent ```json { "properties": { "type": { "type": "string", "enum": [ "refusal" ], "description": "The type of the refusal. Always `refusal`.", "default": "refusal" }, "refusal": { "type": "string", "description": "The refusal explanation from the model." } }, "type": "object", "required": [ "type", "refusal" ], "title": "Refusal", "description": "A refusal from the model." } ``` ### ImageDetail ```json { "type": "string", "enum": [ "low", "high", "auto" ], "x-enumDescriptions": { "auto": "Choose the detail level automatically.", "high": "Allows the model to \"see\" a higher-resolution version of the image, usually increasing input token costs.", "low": "Restricts the model to a lower-resolution version of the image." } } ``` ### MessageStatus ```json { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "x-enumDescriptions": { "completed": "Model has finished sampling this item.", "in_progress": "Model is currently sampling this item.", "incomplete": "Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget." } } ``` ### Message ```json { "properties": { "type": { "type": "string", "enum": [ "message" ], "description": "The type of the message. Always set to `message`.", "default": "message" }, "id": { "type": "string", "description": "The unique ID of the message." }, "status": { "allOf": [ { "$ref": "#/components/schemas/MessageStatus" }, { "description": "The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." } ] }, "role": { "type": "string", "const": "assistant", "description": "The response message role. Always assistant." }, "content": { "items": { "oneOf": [ { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/RefusalContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The content of the message" }, "phase": { "type": "string", "enum": [ "commentary", "final_answer" ], "description": "Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). when sending follow-up requests, preserve and resend phase on all assistant messages. Omitting it can degrade performance. Not used for user messages.", "x-openresponses-added-in": "2026-04-24" } }, "type": "object", "required": [ "type", "id", "status", "role", "content" ], "title": "Message", "description": "A message to or from the model." } ``` ### FunctionCallStatus ```json { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "x-enumDescriptions": { "completed": "Model has finished sampling this item.", "in_progress": "Model is currently sampling this item.", "incomplete": "Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget." } } ``` ### FunctionCall ```json { "properties": { "type": { "type": "string", "enum": [ "function_call" ], "description": "The type of the item. Always `function_call`.", "default": "function_call" }, "id": { "type": "string", "description": "The unique ID of the function call item." }, "call_id": { "type": "string", "description": "The unique ID of the function tool call that was generated." }, "name": { "type": "string", "description": "The name of the function that was called." }, "arguments": { "type": "string", "description": "The arguments JSON string that was generated." }, "status": { "allOf": [ { "$ref": "#/components/schemas/FunctionCallStatus" }, { "description": "The status of the function call item that was recorded." } ] } }, "type": "object", "required": [ "type", "id", "call_id", "name", "arguments", "status" ], "title": "Function call", "description": "A function tool call that was generated by the model." } ``` ### ReasoningBody ```json { "properties": { "type": { "type": "string", "enum": [ "reasoning" ], "description": "The type of the item. Always `reasoning`.", "default": "reasoning" }, "id": { "type": "string", "description": "The unique ID of the reasoning item." }, "content": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ReasoningTextContent" } }, { "type": "null" } ], "description": "Reasoning content, when returned by the selected model." }, "summary": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryTextContent" }, "description": "Readable reasoning summary content." }, "encrypted_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provider-sealed reasoning state for explicit continuation." } }, "type": "object", "required": [ "type", "id", "summary" ], "title": "Reasoning item", "description": "A reasoning item that was generated by the model." } ``` ### ItemField ```json { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/FunctionCall" }, { "$ref": "#/components/schemas/ReasoningBody" } ], "description": "An item representing a message, tool call, tool output, reasoning, or other response element.", "discriminator": { "propertyName": "type" } } ``` ### Error ```json { "properties": { "code": { "type": "string", "description": "A machine-readable error code that was returned." }, "message": { "type": "string", "description": "A human-readable description of the error that was returned." } }, "type": "object", "required": [ "code", "message" ], "title": "Error", "description": "An error that occurred while generating the response." } ``` ### FunctionTool ```json { "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the function tool. Always `function`.", "default": "function" }, "name": { "type": "string", "description": "The name of the function to call." }, "description": { "anyOf": [ { "type": "string", "description": "A description of the function. Used by the model to determine whether or not to call the function." }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the parameters of the function." }, { "type": "null" } ] }, "strict": { "type": "boolean", "description": "The effective strictness applied to this function tool." } }, "type": "object", "required": [ "type", "name", "description", "parameters", "strict" ], "title": "Function", "description": "Defines a function in your own code the model can choose to call. Learn more about [function calling](https://www.openresponses.org/reference/2026-04-24#object-FunctionToolParam).", "additionalProperties": false } ``` ### Tool ```json { "oneOf": [ { "$ref": "#/components/schemas/FunctionTool" } ], "description": "A tool that can be used to generate a response.", "discriminator": { "propertyName": "type" } } ``` ### FunctionToolChoice ```json { "properties": { "type": { "type": "string", "enum": [ "function" ], "default": "function" }, "name": { "type": "string" } }, "type": "object", "required": [ "type" ] } ``` ### TextResponseFormat ```json { "properties": { "type": { "type": "string", "enum": [ "text" ], "default": "text" } }, "type": "object", "required": [ "type" ], "additionalProperties": false } ``` ### TextField ```json { "properties": { "format": { "$ref": "#/components/schemas/TextFormatParam" } }, "type": "object", "required": [ "format" ], "additionalProperties": false } ``` ### Reasoning ```json { "properties": { "effort": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffortEnum" } ], "description": "The reasoning effort that was requested for the model, if specified." }, { "type": "null" } ] }, "summary": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningSummaryEnum" }, { "description": "A model-generated summary of its reasoning that was produced, if available." } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "effort", "summary" ], "title": "Reasoning", "description": "Reasoning configuration and metadata that were used for the response." } ``` ### InputTokensDetails ```json { "properties": { "cached_tokens": { "type": "integer", "description": "The number of input tokens that were served from cache." }, "cache_write_tokens": { "type": "integer", "minimum": 0, "description": "The number of input tokens written to a provider prompt cache." } }, "type": "object", "required": [ "cached_tokens", "cache_write_tokens" ], "title": "Input tokens details", "description": "A breakdown of input token usage that was recorded." } ``` ### OutputTokensDetails ```json { "properties": { "reasoning_tokens": { "type": "integer", "description": "The number of output tokens that were attributed to reasoning." } }, "type": "object", "required": [ "reasoning_tokens" ], "title": "Output tokens details", "description": "A breakdown of output token usage that was recorded." } ``` ### Usage ```json { "properties": { "input_tokens": { "type": "integer", "description": "The number of input tokens that were used to generate the response." }, "output_tokens": { "type": "integer", "description": "The number of output tokens that were generated by the model." }, "total_tokens": { "type": "integer", "description": "The total number of tokens that were used." }, "input_tokens_details": { "allOf": [ { "$ref": "#/components/schemas/InputTokensDetails" }, { "description": "A breakdown of input token usage that was recorded." } ] }, "output_tokens_details": { "allOf": [ { "$ref": "#/components/schemas/OutputTokensDetails" }, { "description": "A breakdown of output token usage that was recorded." } ] } }, "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens", "input_tokens_details", "output_tokens_details" ], "title": "Usage", "description": "Token usage statistics that were recorded for the response." } ``` ### ResponseResource ```json { "properties": { "id": { "type": "string", "description": "The unique ID of the response that was created." }, "object": { "type": "string", "enum": [ "response" ], "description": "The object type, which was always `response`.", "default": "response" }, "created_at": { "type": "integer", "description": "The Unix timestamp (in seconds) for when the response was created." }, "completed_at": { "anyOf": [ { "type": "integer", "description": "The Unix timestamp (in seconds) for when the response was completed, if it was completed." }, { "type": "null" } ] }, "status": { "type": "string", "description": "The status that was set for the response." }, "incomplete_details": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/IncompleteDetails" }, { "description": "Details about why the response was incomplete, if applicable." } ] }, { "type": "null" } ] }, "model": { "type": "string", "description": "The model that generated this response." }, "previous_response_id": { "type": "null", "const": null, "description": "Always null because Bkper AI does not persist response state." }, "instructions": { "anyOf": [ { "oneOf": [ { "type": "string" } ], "description": "Additional instructions that were used to guide the model for this response." }, { "type": "null" } ] }, "output": { "items": { "$ref": "#/components/schemas/ItemField" }, "type": "array", "description": "The output items that were generated by the model." }, "error": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "description": "The error that occurred, if the response failed." } ] }, { "type": "null" } ] }, "tools": { "items": { "$ref": "#/components/schemas/Tool" }, "type": "array", "description": "The tools that were available to the model during response generation." }, "tool_choice": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolChoice" }, { "$ref": "#/components/schemas/ToolChoiceValueEnum" } ] }, "truncation": { "type": "string", "const": "disabled", "description": "Always disabled. Requests that exceed the context window fail explicitly." }, "parallel_tool_calls": { "type": "boolean", "description": "Whether the model was allowed to call multiple tools in parallel." }, "text": { "allOf": [ { "$ref": "#/components/schemas/TextField" }, { "description": "Configuration options for text output that were used." } ] }, "top_p": { "type": "number", "description": "The nucleus sampling parameter that was used for this response." }, "presence_penalty": { "type": "number", "description": "The presence penalty that was used to penalize new tokens based on whether they appear in the text so far." }, "frequency_penalty": { "type": "number", "description": "The frequency penalty that was used to penalize new tokens based on their frequency in the text so far." }, "top_logprobs": { "type": "integer", "const": 0 }, "temperature": { "type": "number", "description": "The sampling temperature that was used for this response." }, "reasoning": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reasoning" }, { "description": "Reasoning configuration and outputs that were produced for this response." } ] }, { "type": "null" } ] }, "usage": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/Usage" }, { "description": "Token usage statistics that were recorded for the response, if available." } ] }, { "type": "null" } ] }, "max_output_tokens": { "anyOf": [ { "type": "integer", "description": "The maximum number of tokens the model was allowed to generate for this response." }, { "type": "null" } ] }, "max_tool_calls": { "type": "null", "const": null }, "store": { "type": "boolean", "const": false, "description": "Always false because Bkper AI is stateless." }, "background": { "type": "boolean", "const": false, "description": "Always false because background responses are not supported." }, "service_tier": { "type": "string", "const": "default" }, "metadata": { "type": "object", "maxProperties": 0, "additionalProperties": false }, "safety_identifier": { "type": "null", "const": null }, "prompt_cache_key": { "anyOf": [ { "type": "string", "description": "A key that was used to read from or write to the prompt cache." }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "object", "created_at", "completed_at", "status", "incomplete_details", "model", "previous_response_id", "instructions", "output", "error", "tools", "tool_choice", "truncation", "parallel_tool_calls", "text", "top_p", "presence_penalty", "frequency_penalty", "top_logprobs", "temperature", "reasoning", "usage", "max_output_tokens", "max_tool_calls", "store", "background", "service_tier", "metadata", "safety_identifier", "prompt_cache_key" ], "title": "The response object", "description": "The complete response object that was returned by the Responses API.", "example": { "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", "object": "response", "created_at": 1741476777, "status": "completed", "completed_at": 1741476778, "model": "gpt-4o-2024-08-06", "output": [ { "type": "message", "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", "annotations": [] } ] } ], "parallel_tool_calls": true, "reasoning": {}, "store": true, "background": false, "temperature": 1, "presence_penalty": 0, "frequency_penalty": 0, "text": { "format": { "type": "text" } }, "tool_choice": "auto", "tools": [], "top_p": 1, "truncation": "disabled", "usage": { "input_tokens": 328, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 52, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 380 }, "metadata": {}, "service_tier": "default", "top_logprobs": 0 } } ``` ### ResponseCreatedStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.created" ], "description": "The type of the event, always `response.created`.", "default": "response.created" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response created event", "description": "A streaming event that indicated the response was created." } ``` ### ResponseQueuedStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.queued" ], "description": "The type of the event, always `response.queued`.", "default": "response.queued" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response queued event", "description": "A streaming event that indicated the response was queued." } ``` ### ResponseInProgressStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.in_progress" ], "description": "The type of the event, always `response.in_progress`.", "default": "response.in_progress" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response in progress event", "description": "A streaming event that indicated the response was in progress." } ``` ### ResponseCompletedStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.completed" ], "description": "The type of the event, always `response.completed`.", "default": "response.completed" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response completed event", "description": "A streaming event that indicated the response was completed." } ``` ### ResponseFailedStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.failed" ], "description": "The type of the event, always `response.failed`.", "default": "response.failed" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response failed event", "description": "A streaming event that indicated the response had failed." } ``` ### ResponseIncompleteStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.incomplete" ], "description": "The type of the event, always `response.incomplete`.", "default": "response.incomplete" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response incomplete event", "description": "A streaming event that indicated the response was incomplete." } ``` ### ResponseOutputItemAddedStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.output_item.added" ], "description": "The type of the event, always `response.output_item.added`.", "default": "response.output_item.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "output_index": { "type": "integer", "description": "The index of the output item that was added." }, "item": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ItemField" }, { "description": "An item representing a message, tool call, tool output, reasoning, or other response element." } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "sequence_number", "output_index", "item" ], "title": "Response output item added event", "description": "A streaming event that indicated an output item was added to the response." } ``` ### ResponseOutputItemDoneStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.output_item.done" ], "description": "The type of the event, always `response.output_item.done`.", "default": "response.output_item.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "output_index": { "type": "integer", "description": "The index of the output item that was completed." }, "item": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ItemField" }, { "description": "An item representing a message, tool call, tool output, reasoning, or other response element." } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "sequence_number", "output_index", "item" ], "title": "Response output item done event", "description": "A streaming event that indicated an output item was completed." } ``` ### ResponseReasoningSummaryPartAddedStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_part.added" ], "description": "The type of the event, always `response.reasoning_summary_part.added`.", "default": "response.reasoning_summary_part.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary part that was added." }, "part": { "$ref": "#/components/schemas/SummaryTextContent" } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "part" ], "title": "Response reasoning summary part added event", "description": "A streaming event that indicated a reasoning summary part was added." } ``` ### ResponseReasoningSummaryPartDoneStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_part.done" ], "description": "The type of the event, always `response.reasoning_summary_part.done`.", "default": "response.reasoning_summary_part.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary part that was completed." }, "part": { "$ref": "#/components/schemas/SummaryTextContent" } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "part" ], "title": "Response reasoning summary part done event", "description": "A streaming event that indicated a reasoning summary part was completed." } ``` ### ResponseContentPartAddedStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.content_part.added" ], "description": "The type of the event, always `response.content_part.added`.", "default": "response.content_part.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was added." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/RefusalContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "part" ], "title": "Response content part added event", "description": "A streaming event that indicated a content part was added." } ``` ### ResponseContentPartDoneStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.content_part.done" ], "description": "The type of the event, always `response.content_part.done`.", "default": "response.content_part.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was completed." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/RefusalContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "part" ], "title": "Response content part done event", "description": "A streaming event that indicated a content part was completed." } ``` ### ResponseOutputTextDeltaStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.output_text.delta" ], "description": "The type of the event, always `response.output_text.delta`.", "default": "response.output_text.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was updated." }, "delta": { "type": "string", "description": "The text delta that was appended." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array", "description": "The token log probabilities that were emitted with the delta, if any." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response output text delta event", "description": "A streaming event that indicated output text was incrementally added." } ``` ### ResponseOutputTextDoneStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.output_text.done" ], "description": "The type of the event, always `response.output_text.done`.", "default": "response.output_text.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was completed." }, "text": { "type": "string", "description": "The final text that was emitted." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array", "description": "The token log probabilities that were emitted with the final text, if any." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "text" ], "title": "Response output text done event", "description": "A streaming event that indicated output text was completed." } ``` ### ResponseRefusalDeltaStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.refusal.delta" ], "description": "The type of the event, always `response.refusal.delta`.", "default": "response.refusal.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the refusal content that was updated." }, "delta": { "type": "string", "description": "The refusal text delta that was appended." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response refusal delta event", "description": "A streaming event that indicated refusal text was incrementally added." } ``` ### ResponseRefusalDoneStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.refusal.done" ], "description": "The type of the event, always `response.refusal.done`.", "default": "response.refusal.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the refusal content that was completed." }, "refusal": { "type": "string", "description": "The final refusal text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "refusal" ], "title": "Response refusal done event", "description": "A streaming event that indicated refusal text was completed." } ``` ### ResponseReasoningDeltaStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.reasoning.delta" ], "description": "The type of the event, always `response.reasoning.delta`.", "default": "response.reasoning.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the reasoning content that was updated." }, "delta": { "type": "string", "description": "The reasoning text delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response reasoning delta event", "description": "A streaming event that indicated reasoning text was incrementally added." } ``` ### ResponseReasoningDoneStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.reasoning.done" ], "description": "The type of the event, always `response.reasoning.done`.", "default": "response.reasoning.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the reasoning content that was completed." }, "text": { "type": "string", "description": "The final reasoning text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "text" ], "title": "Response reasoning done event", "description": "A streaming event that indicated reasoning text was completed." } ``` ### ResponseReasoningSummaryDeltaStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_text.delta" ], "description": "The type of the event, always `response.reasoning_summary.delta`.", "default": "response.reasoning_summary_text.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary content that was updated." }, "delta": { "type": "string", "description": "The summary text delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "delta" ], "title": "Response reasoning summary delta event", "description": "A streaming event that indicated a reasoning summary was incrementally added." } ``` ### ResponseReasoningSummaryDoneStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_text.done" ], "description": "The type of the event, always `response.reasoning_summary.done`.", "default": "response.reasoning_summary_text.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary content that was completed." }, "text": { "type": "string", "description": "The final summary text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "text" ], "title": "Response reasoning summary done event", "description": "A streaming event that indicated a reasoning summary was completed." } ``` ### ResponseOutputTextAnnotationAddedStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.output_text.annotation.added" ], "description": "The type of the event, always `response.output_text.annotation.added`.", "default": "response.output_text.annotation.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the output text content that was updated." }, "annotation_index": { "type": "integer", "description": "The index of the annotation that was added." }, "annotation": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/Annotation" }, { "description": "An annotation that applies to a span of output text." } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "annotation_index", "annotation" ], "title": "Response output text annotation added event", "description": "A streaming event that indicated an output text annotation was added." } ``` ### ResponseFunctionCallArgumentsDeltaStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.function_call_arguments.delta" ], "description": "The type of the event, always `response.function_call_arguments.delta`.", "default": "response.function_call_arguments.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the tool call item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "delta": { "type": "string", "description": "The arguments delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "delta" ], "title": "Response function call arguments delta event", "description": "A streaming event that indicated function call arguments were incrementally added." } ``` ### ResponseFunctionCallArgumentsDoneStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "response.function_call_arguments.done" ], "description": "The type of the event, always `response.function_call_arguments.done`.", "default": "response.function_call_arguments.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the tool call item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "arguments": { "type": "string", "description": "The final arguments string that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "arguments" ], "title": "Response function call arguments done event", "description": "A streaming event that indicated function call arguments were completed." } ``` ### ErrorPayload ```json { "properties": { "type": { "type": "string", "description": "The error type that was emitted." }, "code": { "anyOf": [ { "type": "string", "description": "The error code that was emitted, if any." }, { "type": "null" } ] }, "message": { "type": "string", "description": "The human-readable error message that was emitted." }, "param": { "anyOf": [ { "type": "string", "description": "The parameter name that was associated with the error, if any." }, { "type": "null" } ] }, "headers": { "additionalProperties": { "type": "string", "description": "The header value that was emitted." }, "type": "object", "description": "The response headers that were emitted with the error, if any." } }, "type": "object", "required": [ "type", "code", "message", "param" ], "title": "Error payload", "description": "An error payload that was emitted for a streaming error event." } ``` ### ErrorStreamingEvent ```json { "properties": { "type": { "type": "string", "enum": [ "error" ], "description": "The type of the event, always `error`.", "default": "error" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "error": { "allOf": [ { "$ref": "#/components/schemas/ErrorPayload" }, { "description": "The error payload that was emitted." } ] } }, "type": "object", "required": [ "type", "sequence_number", "error" ], "title": "Error event", "description": "A streaming event that indicated an error was emitted." } ``` ### JsonSchemaResponseFormatParam ```json { "type": "object", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_schema`.", "enum": [ "json_schema" ] }, "description": { "anyOf": [ { "type": "string", "description": "A description of what the response format is for, used by the model to\ndetermine how to respond in the format.\n" }, { "type": "null" } ] }, "name": { "type": "string", "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64.\n", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" }, "schema": { "type": "object", "title": "JSON schema", "description": "The JSON Schema for the response. Bkper validates type, properties, required, additionalProperties, items, composition, enum, references, string constraints, numeric bounds, and array bounds before dispatch. With strict true, every object property must be required and additionalProperties must be false.", "additionalProperties": true }, "strict": { "type": "boolean", "description": "Whether to enforce exact schema adherence. The selected model must publish structured_output.strict as true." } }, "required": [ "type", "name", "schema", "strict" ], "additionalProperties": false } ``` ### TextFormatParam ```json { "oneOf": [ { "$ref": "#/components/schemas/TextResponseFormat" }, { "$ref": "#/components/schemas/JsonSchemaResponseFormatParam" } ] } ``` ### ModelList ```json { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type. Always list." }, "default_model": { "type": "string", "description": "Current default model ID." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "description": "Current discoverable model profiles." } }, "required": [ "object", "default_model", "data" ] } ``` ### Model ```json { "type": "object", "properties": { "id": { "type": "string", "description": "Stable model ID to send in POST /v1/responses." }, "object": { "type": "string", "enum": [ "model" ], "description": "Object type. Always model." }, "created": { "type": "integer", "minimum": 0, "description": "Unix timestamp for this public model profile." }, "owned_by": { "type": "string", "description": "Provider family represented by the public model ID." }, "display_name": { "type": "string", "description": "Human-readable model name." }, "input_modalities": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] }, "description": "Input modalities accepted by this model through Bkper AI." }, "pricing": { "$ref": "#/components/schemas/ModelPricing" }, "default_thinking_level": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "description": "Default reasoning effort when the client does not choose one." }, "context_window": { "type": "integer", "exclusiveMinimum": 0, "description": "Maximum supported request context in tokens." }, "max_output_tokens": { "type": "integer", "exclusiveMinimum": 0, "description": "Maximum output-token limit accepted for this model." }, "thinking_levels": { "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "description": "Reasoning-effort values accepted for this model." }, "structured_output": { "type": "object", "properties": { "json_schema": { "type": "boolean", "description": "Whether JSON Schema structured output is supported." }, "strict": { "type": "boolean", "description": "Whether strict JSON Schema enforcement is supported." } }, "required": [ "json_schema", "strict" ], "description": "Structured-output capabilities. Omitted when unsupported." }, "inline_file_extensions": { "type": "array", "items": { "type": "string" }, "description": "Supported inline file extensions. Omitted when unsupported." } }, "required": [ "id", "object", "created", "owned_by", "display_name", "input_modalities", "pricing", "default_thinking_level", "context_window", "max_output_tokens", "thinking_levels" ] } ``` ### ModelPricing ```json { "type": "object", "properties": { "inputNanoUsdPerToken": { "type": "integer", "minimum": 0, "description": "Effective uncached-input rate in nano-USD per token." }, "cachedInputNanoUsdPerToken": { "type": "integer", "minimum": 0, "description": "Effective cache-read input rate in nano-USD per token." }, "cacheWriteNanoUsdPerToken": { "type": "integer", "minimum": 0, "description": "Effective cache-write input rate in nano-USD per token." }, "outputNanoUsdPerToken": { "type": "integer", "minimum": 0, "description": "Effective output rate in nano-USD per token." } }, "required": [ "inputNanoUsdPerToken", "cachedInputNanoUsdPerToken", "cacheWriteNanoUsdPerToken", "outputNanoUsdPerToken" ], "description": "Effective Bkper AI usage rates. One nano-USD is 0.000000001 USD." } ``` ### BkperErrorResponse ```json { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "message", "type", "param", "code" ], "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "code": { "type": "string", "description": "Stable Bkper error code. New codes may be added over time." } } } } } ```