Bkper AI Gateway

Access selected AI models through Bkper authentication and your included allowance.

The Bkper AI Gateway lets the Bkper CLI Agent and compatible clients access selected third-party AI models with Bkper authentication. You do not need a separate model provider account or API key. Usage counts against the allowance included with eligible Bkper plans.

Bkper selects the available models and sets the usage rates. This is not an open gateway to arbitrary providers or a pass-through of provider pricing. It is not required to connect Bkper to ChatGPT or Claude; those assistants use their own models.

Compatible clients can use the Open Responses language-model profile or call the Bkper typed evaluation endpoint directly.

Bkper AI returns model responses. It does not give a model access to Books, files, tools, or local commands. The consuming client controls those capabilities and their permissions.

Requirements

You need:

a Bkper account with an eligible subscription or trial allowance;
a valid Bkper OAuth access token;
an Open Responses client with a custom base URL for language generation, or an HTTP client for typed evaluations.

Requests are attributed to the authenticated Bkper user. Business subscriptions use a shared domain allowance. See Models and Usage for allowance scope, current rates, and model capabilities.

Configure your client

Setting	Value
Base URL	`https://ai.bkper.app/v1`
Authentication	`Authorization: Bearer <Bkper access token>`
Model discovery	`GET /v1/models`
Language generation	`POST /v1/responses`
Typed evaluations	`POST /v1/evaluations`
Open Responses profile	`2026-04-24` for language generation only

The live GET /v1/models response is authoritative for available IDs, model types, capabilities, limits, and effective usage rates. The catalog publishes default_model as the default language model. Inspect each entry’s type before choosing its endpoint.

When a client asks for an API key, provide the Bkper access token. The client should send it as a bearer token. Do not use an OpenAI, Anthropic, or xAI API key with the Bkper AI base URL.

Bkper AI implements a documented subset of Open Responses. It does not claim full specification compliance.

Model IDs

Use the model IDs returned by GET /v1/models, such as gpt-luna, grok, gemini-flash, and jev.

Language model entries have type: "language" and use POST /v1/responses. Evaluation model entries have type: "evaluation" and use POST /v1/evaluations. Sending a model to the wrong endpoint fails explicitly.

Model IDs remain stable as Bkper updates the model behind them. Older versioned and publisher-prefixed IDs still work, but they select the current model, not the older version. Catalogs, responses, and usage reports use the current ID.

Get a token for local testing

Any supported Bkper OAuth flow can supply the access token. The Bkper CLI is a convenient way to obtain a short-lived token for local testing:

bkper auth login
export BKPER_TOKEN="$(bkper auth token)"

Treat the token as a secret. Do not commit it, print it in shared logs, or put it in a client-side application bundle.

Send a complete request

This request uses one current model ID as an example. Use GET /v1/models or Models and Usage for the current portfolio.

curl --fail-with-body https://ai.bkper.app/v1/responses \
  -H "Authorization: Bearer ${BKPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "bkper-ai-source: my-harness" \
  --data '{
    "model": "gpt-luna",
    "input": "Reply with exactly: connected",
    "store": false
  }'

The response is an Open Responses resource. Its model contains the canonical public Bkper model ID, and store is always false.

The bkper-ai-source header is optional. Set it to a stable lowercase identifier such as my-harness to see which client or application made a request in the usage dashboard. Without a valid identifier, the source appears as unknown.

Typed evaluations

Use Jev when application code needs bounded judgments rather than generated text. One request can evaluate the same state against independent boolean, choice, and score questions in parallel.

curl --fail-with-body https://ai.bkper.app/v1/evaluations \
  -H "Authorization: Bearer ${BKPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "bkper-ai-source: my-harness" \
  --data '{
    "model": "jev",
    "state": {
      "message": "Our payouts have failed for three days and payroll is tomorrow."
    },
    "questions": {
      "urgent": {
        "type": "boolean",
        "instructions": "Does the message require urgent handling?"
      },
      "route": {
        "type": "choice",
        "instructions": "Which team should handle this message?",
        "criteria": {
          "billing": "Payments, invoices, or refunds",
          "technical": "Bugs, outages, or integrations"
        }
      },
      "severity": {
        "type": "score",
        "instructions": "How severe is the operational impact?",
        "criteria": ["Low", "Material", "Critical"]
      }
    }
  }'

Find each question’s result under its ID in answers:

Boolean: probability is the probability of true.
Choice: choice is the selected option, and probabilities maps each supplied option to its probability.
Score: score is a numeric value that may be fractional. probabilities maps zero-based criteria indices ("0", "1", and so on) to probabilities.

Choice and score answers also include confidence when available (for example, answers.route.confidence).

Evaluation requests return complete JSON responses. They do not stream, create conversation state, or use the Open Responses resource shape. Keep deterministic rules and final actions in code; use the returned probabilities to decide whether to proceed, defer, or request human review.

Stream a response

Set stream to true to receive semantic server-sent events:

curl --no-buffer --fail-with-body https://ai.bkper.app/v1/responses \
  -H "Authorization: Bearer ${BKPER_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "grok",
    "input": "Explain the from-to movement model in one sentence.",
    "stream": true,
    "store": false
  }'

Each SSE event: name matches the event body’s type. Sequence numbers increase monotonically. A stream ends with one terminal response event followed by data: [DONE].

Language model capabilities

For language generation, Bkper AI supports:

all language model IDs listed by GET /v1/models;
string input and explicit conversation item arrays;
system, developer, user, and assistant messages;
text and image input;
inline PDF input through Base64 input_file.file_data on models that support files;
JSON Schema structured output through text.format on models that support it;
function tools, function calls, function outputs, and multiple tool calls where the model supports them;
reasoning effort and summaries where supported;
encrypted reasoning continuity where the provider supplies it;
prompt_cache_key for short cache and session affinity;
complete JSON responses and semantic SSE streaming.

Check GET /v1/models for each model’s capabilities and limits. Requests with unsupported settings are rejected rather than silently changed.

Structured JSON output

Set text.format.type to json_schema and provide a standard JSON Schema. Bkper AI maps the schema to each model provider’s native structured-output mechanism.

strict: true is preserved only when the selected model can enforce the submitted schema subset.
strict: false supports schemas that require provider-supported flexibility, such as typed dynamic maps.
Malformed supported keywords and incompatible schemas fail before provider dispatch. Bkper AI never silently changes a strict schema to non-strict behavior.

The returned structured JSON is contained in the assistant output_text and should still be parsed and validated by the client before use.

Inline PDF input

Use one inline PDF source with a filename:

{
    "type": "input_file",
    "filename": "document.pdf",
    "file_data": "<base64>"
}

Bkper AI validates the Base64 content and selected model capability before dispatch. It sends inline content through the provider’s native document input and does not upload it to a hidden provider Files API.

Inline files are available only on models that advertise native support. The current xAI model does not support inline file_data. Use GET /v1/models to inspect current capabilities.

Privacy, retention, and caching

Zero data retention where available. Minimum retention everywhere. Bkper disables provider application storage on every request and keeps prompt and response content out of usage logs.

Bkper applies these boundaries across the inference path:

omitted store becomes false, and store: true is rejected before provider dispatch;
Bkper usage records contain attribution, status, token, cache, and cost metadata—not prompt or response content;
detailed Bkper usage events are retained for 180 days, while daily aggregate usage remains available for allowance enforcement and reporting;
Cloudflare AI Gateway payload logging is disabled, while content-free request metadata remains available for observability;
exact, non-streaming structured JSON requests and responses sent through POST /v1/responses may be cached by Cloudflare for up to 24 hours;
provider-native prompt caches may hold language-model content temporarily under the selected provider’s caching policy.

Provider retention controls differ:

Provider	Bkper configuration	Provider retention boundary
xAI	`store: false`; Zero Data Retention is active for Bkper’s xAI team	Prompt and response retention is disabled under the enabled Zero Data Retention control.
OpenAI	`store: false`; Bkper organization API-call logging is disabled	API data is not used for training by default. Customer content may remain in abuse-monitoring logs for up to 30 days because Bkper does not currently have OpenAI Zero Data Retention.
Google Gemini paid API	`store: false`; Bkper avoids Search and Maps grounding, the File API, and explicit context caching	Paid API content is not used for training. Content may be retained for limited abuse monitoring because Bkper’s AI Studio project does not currently have approved Zero Data Retention. Gemini may also use project-isolated in-memory caching for up to 24 hours.
Fireworks AI	`store: false`; Zero Data Retention is active by default; used as the current serving route for open-weight models	Fireworks does not log or persist prompt or generation data for open models without explicit opt-in. Prompt caching may retain data in volatile memory for several minutes. `store: false` prevents Response API conversation storage.
TypeSafe	Typed evaluation requests use Bkper’s server-side TypeSafe credential; Bkper usage logs exclude state and answers	TypeSafe states that customer requests and responses are not used for training. Retention and Zero Data Retention availability follow TypeSafe’s current service terms.

Caching does not create a retrievable conversation or add prompt content to usage logs. If you set prompt_cache_key, use an opaque identifier: it may appear in the usage dashboard.

Provider policies and Bkper configurations can change. Review these primary references for the current boundaries:

Stateless behavior

Bkper AI does not persist response state:

omitted store behaves as false;
store: false is accepted;
store: true is rejected;
continue conversations by sending explicit prior items in input.

prompt_cache_key is a bounded cache hint. It is not a persisted response identifier.

Unsupported features

The current profile rejects:

previous_response_id;
background responses;
response retrieval or deletion;
client metadata;
input_file.file_id and input_file.file_url;
inline file types or models without advertised native support, including xAI inline files;
remote HTTP/HTTPS image URLs for Gemini; send Gemini images as inline data URLs;
hosted provider tools;
compaction endpoints;
WebSocket transport;
image generation, audio, speech, batches, and fine-tuning.

Unsupported fields fail explicitly rather than being ignored or passed to only one provider.

Errors

Errors use an Open Responses-shaped envelope with stable Bkper error codes.

Status	Meaning
`400`	Invalid request, unavailable model, unsupported capability, or context overflow
`401`	Missing or invalid Bkper bearer token
`402`	The authenticated subscription payment is overdue
`403`	The account is not entitled to use Bkper AI
`429`	The monthly Bkper AI allowance is exhausted or the upstream provider is throttled
`499`	The client aborted the request
`502`	The selected upstream model provider or transport failed
`503`	Evaluation provider is overloaded or quota usage is temporarily unavailable

Bkper AI blocks new requests once the recorded monthly allowance is exhausted. There are no automatic paid Bkper AI overages and no automatic fallback to another protocol. Review the authenticated Bkper AI usage dashboard for the current allowance and request attribution.

Bkper CLI Agent

The Bkper CLI Agent connects to Bkper AI with your Bkper login and uses language models. Jev evaluations are available to apps and other API clients, not the CLI Agent.

bkper auth login
bkper agent