# Bkper AI Gateway 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](https://bkper.com/docs/ai/models.md) for allowance scope, current rates, and model capabilities. ## Configure your client | Setting | Value | | ---------------------- | -------------------------------------------- | | Base URL | `https://ai.bkper.app/v1` | | Authentication | `Authorization: Bearer ` | | 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: ```bash 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](https://bkper.com/docs/ai/models.md) for the current portfolio. ```bash 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. ```bash 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: ```bash 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: ```json { "type": "input_file", "filename": "document.pdf", "file_data": "" } ``` 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: - [Google Gemini API zero data retention](https://ai.google.dev/gemini-api/docs/zdr) - [OpenAI platform data controls](https://developers.openai.com/api/docs/guides/your-data) - [Fireworks AI zero data retention](https://docs.fireworks.ai/guides/security_compliance/data_handling) - [Cloudflare AI Gateway caching](https://developers.cloudflare.com/ai-gateway/features/caching/) - [Cloudflare AI Gateway logging](https://developers.cloudflare.com/ai-gateway/observability/logging/) - [TypeSafe legal and data handling](https://docs.typesafe.ai/legal) ## 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](https://ai.bkper.app) 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. ```bash bkper auth login bkper agent ``` ## Next steps - [Browse the generated AI API reference](https://bkper.com/docs/api/ai.md). - [Download the canonical OpenAPI specification](https://ai.bkper.app/openapi.json). - [Compare models, capabilities, rates, and allowance rules](https://bkper.com/docs/ai/models.md). - [Use the preconfigured Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md). - [Review Bkper CLI Agent security](https://bkper.com/docs/ai/cli-agent-security.md).