Skip to content
Bkper
Sign In

Create a response

POST
/v1/responses

Creates 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].

Authorizations

Parameters

Header Parameters

bkper-ai-source
string
/^[a-z0-9][a-z0-9._-]{0,127}$/

Stable lowercase client or application identifier used for usage attribution. Invalid values are recorded as unknown.

Request Body required

object
model
required

A model ID returned by GET /v1/models.

string
input
required
One of:
string
<= 10485760 characters
include
Array<string>
Allowed values: reasoning.encrypted_content
tools

A list of tools that the model may call while generating the response.

Array
One of: discriminator: type

Defines a function tool. See Open Responses function tools.

object
name
required
string
>= 1 characters <= 64 characters /^[a-zA-Z0-9_-]+$/
description
Any of:
string
parameters
Any of:
object
strict

Whether to enforce strict function parameters. Some models require strict function tools and reject false.

boolean
type
required
string
default: function
Allowed values: function
tool_choice
object
One of:
One of:
object
type
required

The tool to call. Always function.

string
default: function
Allowed values: function
name
required

The name of the function tool to call.

string
>= 1 characters <= 64 characters /^[a-zA-Z0-9_-]+$/
text
Any of:
object
format
One of:
One of:
object
type
required
string
default: text
Allowed values: text
temperature
Any of:

Sampling temperature to use, between 0 and 2. Higher values make the output more random.

number
<= 2
top_p
Any of:

Nucleus sampling parameter, between 0 and 1. The model considers only the tokens with the top cumulative probability.

number
<= 1
presence_penalty
Any of:

Penalizes new tokens based on whether they appear in the text so far.

number
>= -2 <= 2
frequency_penalty
Any of:

Penalizes new tokens based on their frequency in the text so far.

number
>= -2 <= 2
parallel_tool_calls
Any of:

Whether the model may call multiple tools in parallel.

boolean
stream

Whether to stream response events as server-sent events.

boolean
max_output_tokens
Any of:

The maximum number of tokens the model may generate for this response.

integer
>= 16
reasoning
Any of:
object
effort
Any of:
One of:
string
Allowed values: none minimal low medium high xhigh max
summary
Any of:
string
Allowed values: concise detailed auto
prompt_cache_key
Any of:

A key to use when reading from or writing to the prompt cache.

string
<= 64 characters
instructions
Any of:

Additional instructions to guide the model for this request.

string
store

Bkper AI is stateless. The only supported value is false.

boolean
Examples

Complete response

{
  "model": "openai/gpt-5.6-luna",
  "input": "Reply with exactly: connected",
  "store": false
}

Responses

200

Success

The response object

The complete response object that was returned by the Responses API.

object
id
required

The unique ID of the response that was created.

string
object
required

The object type, which was always response.

string
default: response
Allowed values: response
created_at
required

The Unix timestamp (in seconds) for when the response was created.

integer
completed_at
required
Any of:

The Unix timestamp (in seconds) for when the response was completed, if it was completed.

integer
status
required

The status that was set for the response.

string
incomplete_details
required
Any of:
object
reason
required

The reason the response could not be completed.

string
model
required

The model that generated this response.

string
previous_response_id
required

Always null because Bkper AI does not persist response state.

null
instructions
required
Any of:
One of:
string
output
required

The output items that were generated by the model.

Array
One of: discriminator: type
Message

A message to or from the model.

object
type
required

The type of the message. Always set to message.

string
default: message
Allowed values: message
id
required

The unique ID of the message.

string
status
required
string
Allowed values: in_progress completed incomplete
role
required

The response message role. Always assistant.

string
Allowed value: assistant
content
required

The content of the message

Array
One of: discriminator: type
Output text

A text output from the model.

object
type
required

The type of the output text. Always output_text.

string
default: output_text
Allowed values: output_text
text
required

The text output from the model.

string
annotations
required

The annotations of the text output.

Array
One of: discriminator: type
URL citation

A citation for a web resource used to generate a model response.

object
type
required

The type of the URL citation. Always url_citation.

string
default: url_citation
Allowed values: url_citation
url
required

The URL of the web resource.

string
start_index
required

The index of the first character of the URL citation in the message.

integer
end_index
required

The index of the last character of the URL citation in the message.

integer
title
required

The title of the web resource.

string
logprobs
Array<object>
Log probability

The log probability of a token.

object
token
required
string
logprob
required
number
bytes
required
Array<integer>
top_logprobs
required
Array<object>
Top log probability

The top log probability of a token.

object
token
required
string
logprob
required
number
bytes
required
Array<integer>
phase

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.

string
Allowed values: commentary final_answer
error
required
Any of:
object
code
required

A machine-readable error code that was returned.

string
message
required

A human-readable description of the error that was returned.

string
tools
required

The tools that were available to the model during response generation.

Array
One of: discriminator: type
Function

Defines a function in your own code the model can choose to call. Learn more about function calling.

object
type
required

The type of the function tool. Always function.

string
default: function
Allowed values: function
name
required

The name of the function to call.

string
description
required
Any of:

A description of the function. Used by the model to determine whether or not to call the function.

string
parameters
required
Any of:

A JSON schema object describing the parameters of the function.

object
key
additional properties
strict
required

The effective strictness applied to this function tool.

boolean
tool_choice
required
One of:
object
type
required
string
default: function
Allowed values: function
name
string
truncation
required

Always disabled. Requests that exceed the context window fail explicitly.

string
Allowed value: disabled
parallel_tool_calls
required

Whether the model was allowed to call multiple tools in parallel.

boolean
text
required
object
format
required
One of:
object
type
required
string
default: text
Allowed values: text
top_p
required

The nucleus sampling parameter that was used for this response.

number
presence_penalty
required

The presence penalty that was used to penalize new tokens based on whether they appear in the text so far.

number
frequency_penalty
required

The frequency penalty that was used to penalize new tokens based on their frequency in the text so far.

number
top_logprobs
required
integer
0
temperature
required

The sampling temperature that was used for this response.

number
reasoning
required
Any of:
object
effort
required
Any of:
One of:
string
Allowed values: none minimal low medium high xhigh max
summary
required
Any of:
string
Allowed values: concise detailed auto
usage
required
Any of:
object
input_tokens
required

The number of input tokens that were used to generate the response.

integer
output_tokens
required

The number of output tokens that were generated by the model.

integer
total_tokens
required

The total number of tokens that were used.

integer
input_tokens_details
required
object
cached_tokens
required

The number of input tokens that were served from cache.

integer
cache_write_tokens
required

The number of input tokens written to a provider prompt cache.

integer
output_tokens_details
required
object
reasoning_tokens
required

The number of output tokens that were attributed to reasoning.

integer
max_output_tokens
required
Any of:

The maximum number of tokens the model was allowed to generate for this response.

integer
max_tool_calls
required
null
store
required

Always false because Bkper AI is stateless.

boolean
background
required

Always false because background responses are not supported.

boolean
service_tier
required
string
Allowed value: default
metadata
required
object
0
safety_identifier
required
null
prompt_cache_key
required
Any of:

A key that was used to read from or write to the prompt cache.

string
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
}

400

Invalid request or unsupported capability

object
error
required
object
message
required
string
type
required
string
param
required
string | null
code
required

Stable Bkper error code. New codes may be added over time.

string

401

Missing or invalid Bkper bearer token

object
error
required
object
message
required
string
type
required
string
param
required
string | null
code
required

Stable Bkper error code. New codes may be added over time.

string

402

Subscription payment is overdue

object
error
required
object
message
required
string
type
required
string
param
required
string | null
code
required

Stable Bkper error code. New codes may be added over time.

string

403

Bkper AI entitlement is unavailable

object
error
required
object
message
required
string
type
required
string
param
required
string | null
code
required

Stable Bkper error code. New codes may be added over time.

string

429

Monthly allowance exhausted or provider throttled

object
error
required
object
message
required
string
type
required
string
param
required
string | null
code
required

Stable Bkper error code. New codes may be added over time.

string

499

Client aborted the request

object
error
required
object
message
required
string
type
required
string
param
required
string | null
code
required

Stable Bkper error code. New codes may be added over time.

string

502

Provider or transport failure

object
error
required
object
message
required
string
type
required
string
param
required
string | null
code
required

Stable Bkper error code. New codes may be added over time.

string

default

Other provider or transport rejection

object
error
required
object
message
required
string
type
required
string
param
required
string | null
code
required

Stable Bkper error code. New codes may be added over time.

string