Bkper AI Gateway API
Bkper AI Gateway API reference, version v1.
Bkper AI Gateway API (v1)
The Bkper AI Gateway serves the models behind Bkper’s agents and apps to your own clients and code: typed answers from System One models and the stateless Bkper Open Responses 2026-04-24 profile for language models.
Models and Usage covers the models, usage rates, the monthly allowance, and privacy. To run an agent that works on Books instead of calling a model, use the Managed Agent API. Building a Bkper app? Start with Add Bkper AI to an App. The canonical machine-readable contract is https://ai.bkper.app/openapi.json.
Request workflow
- Call
GET /v1/modelsto discover the current public model IDs, types, capabilities, limits, and usage rates. - Select a returned model ID.
- Call
POST /v1/responsesfor language models orPOST /v1/systemonefor System One models.
Responses support complete JSON with stream: false or semantic server-sent events with stream: true. System One models return complete JSON and do not stream.
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 or TypeSafe SDK for System One models.
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 |
| System One models | POST /v1/systemone |
| 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. System One model entries have type: "system-one", list the question types they answer in question_types, and use POST /v1/systemone. Entries with preview: true are provider previews whose answers, limits, and availability may change without notice. 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.
Call from a browser
Web pages on any origin can call POST /v1/responses, POST /v1/systemone, and GET /v1/models directly. Bkper AI authenticates only the bearer token and uses no cookies, so browser requests carry no credentials.
- Use the signed-in user’s token at runtime. On
*.bkper.apppages,@bkper/web-authsupplies it. On other domains, use your own Bkper OAuth flow. Never ship a fixed token in a page. - Usage counts against the signed-in user’s allowance. Label it with a
bkper-ai-sourceheader, such asmy-page. - The user can see the whole request, including prompts, questions, and criteria. Keep private prompts on a server.
- Retry hints and limits are readable. Browsers can read the
retry-afterandx-should-retryresponse headers, and the user limit headers.
import { BkperAuth } from '@bkper/web-auth';
const auth = new BkperAuth();
await auth.init();
const response = await auth.authenticatedFetch('https://ai.bkper.app/v1/systemone', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'bkper-ai-source': 'my-page' },
body: JSON.stringify({
model: 'jev',
state: { description: 'NETFLIX.COM monthly plan' },
questions: { streaming: { type: 'noul', instructions: 'Is this a streaming service?' } },
}),
});
authenticatedFetch() sets the current token and refreshes it once after a 401.
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.
Decision questions
POST /v1/systemone answers typed questions about a shared state instead of generating text. Each question returns a noul probability, one choice from options you define, or a level on an ordered score, and your code decides what to do with it. Designing the questions, thresholds, and human review is covered in the System One Models guide. POST /v1/decisions is a deprecated alias with identical behavior.
For an incoming bank line, this request asks for three judgments at once: which Account it belongs to, whether it is already recorded, and how unusual it is as a business expense. Code combines the answers with facts, such as the amount, into what to do with the line.
curl --fail-with-body https://ai.bkper.app/v1/systemone \
-H "Authorization: Bearer ${BKPER_TOKEN}" \
-H "Content-Type: application/json" \
-H "bkper-ai-source: my-app" \
--data '{
"model": "jev",
"state": {
"bank_line": {
"date": "2025-03-11",
"description": "AMAZON MKTPL*2K4LM",
"amount": 89.90,
"direction": "money out of Checking"
},
"existing_transaction": {
"date": "2025-03-10",
"amount": 89.90,
"from": "Checking",
"to": "Office Supplies",
"description": "Printer toner, Amazon order 114-2K4LM",
"origin": "manual entry"
}
},
"questions": {
"account": {
"type": "choice",
"instructions": "Which Account should receive the money that left Checking in `bank_line`?",
"criteria": {
"Cloud Hosting": "Servers, cloud infrastructure, storage, and hosting providers",
"Software Subscriptions": "SaaS tools and per-seat software licenses",
"Office Supplies": "Physical supplies and equipment for the office",
"Travel": "Flights, hotels, ground transport, and meals while traveling"
}
},
"already_recorded": {
"type": "noul",
"instructions": "Does `existing_transaction` already record the movement in `bank_line`?"
},
"unusual": {
"type": "score",
"instructions": "How unusual is `bank_line` as a business expense?",
"criteria": [
"Routine: a common business expense",
"Unusual: plausible, but uncommon for a business",
"Suspicious: looks like fraud, an error, or a personal expense"
]
}
}
}'
Decision request
modelis any model withtype: "system-one"inGET /v1/models, such asjevorclef. Each entry lists itsquestion_types,context_window, andmax_state_question_tokens; a question whose type is not in the model’squestion_typesreturnsunsupported_question_type.stateis what every question judges: a string, JSON object, or array. Prefer an object with descriptive field names. Send images and files asassetsto models that read them; convert other files to text first.questionsis a nonempty map. Question IDs such asaccountare yours, and answers come back under the same IDs, but IDs are not sent to the model, so eachinstructionsmust stand on its own. Refer to state fields by name in backticks, as in`bank_line`.- Each question accepts only
type,instructions, andcriteria. Instructions, descriptions, and levels can be strings or structured JSON:noul: optionalcriteriadescribe what yes and no mean.choice:criteriamaps 1–255 options to descriptions, which may benull.score:criterialists 2–10 levels, lowest first.
assetsmaps placeholders that appear in the state or instructions to images,{ "type": "image", "format": "png", "data_base64": "…" }, or files,{ "type": "file", "media_type": "application/pdf", "data_base64": "…" }, or to the parts of a multipart request.input_modalitiesandinline_file_extensionsinGET /v1/modelsshow what each model reads:gemini-decisionreads PDFs, audio, video, and more image formats; the other models read images only. A PNG, JPEG, or WebP file is an image. A file the model does not read returnsunsupported_parameterbefore the model is called.- The body accepts only
model,state, andquestions, plusassetson models with image or file input.reference_dateapplies only to extraction questions;jevandclefreject it withunsupported_parameter. Responses fields such asinput,stream,store,temperature, andmetadataare rejected. - Questions without
instructionsare asked by their name on models that need instructions: noul questions onjev, and every question onclef,gemini-decision, andgpt-luna-decision. clefanswers at most 64 questions, named with up to 100 letters, digits,_,., or-, and needs at least 2 choice options and at least 2 score levels. It reads up to 4 imageassets(4 MiB each, 8 MiB in total) before the state, inassetsorder. Requests beyond these limits returnunsupported_parameter; input over its 65,536-token context returnsprovider_rejected.gemini-decision, a Google preview, answers at most 1,000 questions, named with up to 64 letters, digits,_, or-, and needs at least 2 choice options, named with up to 128 characters without leading or trailing spaces, and at least 2 nonempty score levels. It reads image and fileassetsbefore the state, each labeled with its placeholder, and structured state and instructions as compact JSON text. Requests beyond these limits returnunsupported_parameter.gpt-luna-decisionanswers at most 400 questions and needs at least 2 choice options and at least 2 score levels. It reads imageassetsbefore the state, each labeled with its placeholder. Noulcriteriabecome part of its instructions. Requests beyond these limits returnunsupported_parameter.
The model evaluates each question independently and in parallel against the same state.
Decision answers
A real response to the request above:
{
"model": "jev-1.13.0",
"answers": {
"account": {
"type": "choice",
"choice": "Office Supplies",
"confidence": 1,
"probabilities": {
"Cloud Hosting": 0,
"Software Subscriptions": 0,
"Office Supplies": 1,
"Travel": 0
}
},
"already_recorded": {
"type": "noul",
"noul": 0.91
},
"unusual": {
"type": "score",
"score": 0.17,
"confidence": 0.74,
"legend": {
"0": "Routine: a common business expense",
"1": "Unusual: plausible, but uncommon for a business",
"2": "Suspicious: looks like fraud, an error, or a personal expense"
},
"probabilities": {
"0": 0.9,
"1": 0.03,
"2": 0.07
}
}
},
"usage": { "input_tokens": 614, "output_tokens": 87 }
}
Bkper validates every answer before returning it, so your code can rely on these guarantees:
answershas exactly one entry per question ID, and each answer’stypematches its question.noulis the probability of yes, from 0 to 1.choiceis always one of yourcriteriakeys.scoreis the probability-weighted level, from0to the number of levels minus one. It can fall between levels.probabilitieshas one entry per option or level, andlegendmaps level indexes back to your text. Read both by key: order is not guaranteed, and values can be exactly0or1.confidence, on choice and score answers, runs from 0 to 1 and is higher when probability concentrates on one answer. Noul answers have noconfidence; the probability itself is the signal. See TypeSafe’s Confidence.modelis the concrete revision that answered, such asjev-1.13.0. Log it.
Usage counts against the allowance at the model’s usage rates.
Decision errors
Decision errors use the shared error envelope. Validation failures name the field in error.param:
{
"error": {
"message": "Unknown field: questions.route.threshold.",
"type": "invalid_request_error",
"param": "questions.route.threshold",
"code": "invalid_request"
}
}
Besides invalid_request, decision validation returns 400 with missing_model, unsupported_model, invalid_state, invalid_questions, invalid_question, unsupported_question_type, or unsupported_parameter. The last two follow Open System One: unsupported_question_type for a question type the selected model does not answer, and unsupported_parameter for a field the specification defines that the model cannot honor, such as reference_date. Fix the field named in error.param; do not retry unchanged. A 400 with provider_rejected means the model rejected the request: check its size against the model’s limits. A 422 with refused, Open System One’s standard refusal, means the model refused to answer for safety or policy reasons, and no answers are returned; error.param names the refused question, or is null when the whole request was refused. Route the item to a person instead of retrying it unchanged. A refusal counts against the allowance when the provider billed it. A 502 with provider_invalid_answer means the model’s answers broke an Open System One answer guarantee; error.message names the question and the rule, and no answers are returned.
TypeSafe compatibility
Decision questions come from TypeSafe’s System One, and request and answer shapes match TypeSafe’s POST /v1/systemone. TypeSafe’s guidance on questions, state, confidence, and patterns applies unchanged. Only the surroundings differ:
- Endpoint and authentication. Call
https://ai.bkper.app/v1/systemonewith a Bkper access token. TypeSafe API keys do not work here. - SDKs. TypeSafe SDKs work with base URL
https://ai.bkper.app, without/v1, and a Bkper access token. See Add Bkper AI to an App. - Errors. Bkper returns
400where TypeSafe returns422, and503withprovider_overloadedwhere TypeSafe returns529. A429can also mean the Bkper AI allowance or your own monthly limit is reached. - Usage. Requests count against the Bkper AI allowance, not a TypeSafe account.
- Requests. Bodies can be gzip- or zstd-compressed, as TypeSafe SDKs send bodies of 1 KiB or more, and at most 32 MiB before and after decompression.
- Images. Send images as TypeSafe’s Images guide shows: with the SDKs’
image(), which uploads them as multipart, or as base64assetsin a JSON request. Bkper turns on TypeSafe’s experimental image input for you. Jev readspng,jpg, andjpegimages;webp, whichclefandclairicread, returnsunsupported_parameter. Box questions are not supported. Image tokens count as input tokens. - Coding agents. TypeSafe’s agent skill teaches questions and patterns. For a Bkper integration, also point the agent to this guide,
https://bkper.com/docs/api/ai-gateway.md, for the endpoint, authentication, model IDs, and errors.
Extraction questions
Extraction questions to POST /v1/systemone ask for values read, computed, estimated, or forecast from the state instead of judgments: text, number, date, time, datetime, duration, list, estimate, and forecast. clairic is a Cloudflare preview (preview: true in GET /v1/models). Question and answer shapes follow Open System One.
This request reads a supplier email: it copies the invoice number, reads the issue date and payment terms, and estimates when the invoice will be paid. An extraction question can also ask for a computed value, such as a due date, but when a value feeds a Book, ask for its inputs and compute it in code.
curl --fail-with-body https://ai.bkper.app/v1/systemone \
-H "Authorization: Bearer ${BKPER_TOKEN}" \
-H "Content-Type: application/json" \
-H "bkper-ai-source: my-app" \
--data '{
"model": "clairic",
"state": "Hi, this is Marta Silva from Acme Paper. Invoice AP-5531 for 3 boxes of A4 paper is attached: total $184.50, issued 2026-03-02 with net 30 terms. Delivery is booked for March 9 at 10:15 am, and unloading takes about 40 minutes. Our last four monthly invoices were $172.00, $178.25, $181.10 and $184.50.",
"reference_date": "2026-03-05",
"questions": {
"invoice_number": {"type": "text", "instructions": "Invoice number"},
"contacts": {"type": "list", "items": "text", "instructions": "Each person named"},
"total": {"type": "number", "decimals": 2, "unit": "USD", "instructions": "Invoice total"},
"issue_date": {"type": "date", "instructions": "Invoice issue date"},
"net_days": {"type": "number", "integer": true, "unit": "days", "instructions": "Net payment terms"},
"delivery_time": {"type": "time", "instructions": "Time the delivery is booked for"},
"delivery_at": {"type": "datetime", "instructions": "Date and time of the delivery"},
"unloading": {"type": "duration", "unit": "minutes", "integer": true, "instructions": "How long unloading takes"},
"monthly_amounts": {"type": "list", "items": "number", "decimals": 2, "instructions": "Each monthly invoice amount"},
"days_to_pay": {"type": "estimate", "min": 0, "max": 90, "step": 1, "instructions": "Days after issue until this invoice is paid"},
"next_invoices": {"type": "forecast", "min": 0, "max": 1000, "horizon": 2, "interval": "month", "unit": "USD", "instructions": "Amount of the next monthly invoices", "step": 0.01},
"po_number": {"type": "text", "instructions": "Purchase order number"}
}
}'
Extraction request
- Settings are optional except
itemson lists andminandmax(andhorizonon forecasts) on estimates and forecasts:null_thresholdon value types;unit,integer, anddecimalson numbers and durations;stepandscaleon estimates and forecasts;quantiles: trueon estimates for the 1st to 99th percentiles;intervalon forecasts. An invalid setting returns400withinvalid_questionand the setting inerror.param. instructionsis optional. Structured state and instructions are read as compact JSON text.reference_date(YYYY-MM-DD) resolves relative and year-less dates, such as “March 9” above.clairicaccepts question names of up to 64 letters, digits,_,., or-, starting with a letter or_, forecasts of up to 64 steps, and up to 4 imageassets(4 MiB each, 8 MiB in total). Requests beyond these limits returnunsupported_parameter.
Extraction answers
A real response to the request above, with probabilities and means rounded:
{
"model": "clairic",
"answers": {
"invoice_number": {"type": "text", "value": "AP-5531", "guess": "AP-5531", "span": [49, 56], "p_null": 0, "confidence": 1},
"contacts": {"type": "list", "value": ["Marta Silva"], "spans": [[12, 23]], "confidence": 0.28},
"total": {"type": "number", "value": 184.5, "guess": 184.5, "p_null": 0, "confidence": 1},
"issue_date": {"type": "date", "value": "2026-03-02", "guess": "2026-03-02", "p_null": 0, "confidence": 1},
"net_days": {"type": "number", "value": 30, "guess": 30, "p_null": 0, "confidence": 1},
"delivery_time": {"type": "time", "value": "10:15:00", "guess": "10:15:00", "p_null": 0, "confidence": 1},
"delivery_at": {"type": "datetime", "value": "2026-03-09T10:15:00", "guess": "2026-03-09T10:15:00", "p_null": 0, "confidence": 1},
"unloading": {"type": "duration", "value": 40, "guess": 40, "p_null": 0, "confidence": 1, "unit": "minutes"},
"monthly_amounts": {"type": "list", "value": [172, 178.25, 181.1, 184.5], "confidence": 0.74},
"days_to_pay": {"type": "estimate", "value": 30, "median": 30, "p10": 24, "p90": 35, "mean": 29.78, "p_below": 0, "p_above": 0},
"next_invoices": {"type": "forecast", "steps": [{"value": 182.95, "median": 183.47, "p10": 171.24, "p90": 195.86, "mean": 182.95, "p_below": 0, "p_above": 0}, {"value": 183.74, "median": 184.1, "p10": 171.64, "p90": 196.86, "mean": 183.74, "p_below": 0, "p_above": 0}]},
"po_number": {"type": "text", "value": null, "guess": "AP-5531", "span": [49, 56], "p_null": 1, "confidence": 0.99}
},
"truncated": false,
"usage": { "input_tokens": 1337, "output_tokens": 0 }
}
Bkper checks every answer against the Open System One answer guarantees before returning it:
- Value types have
value,p_null, andconfidence.valueisnullexactly whenp_nullis above the question’snull_threshold(default 0.5), as forpo_number;guessis still the most likely value. spanis whereguesswas read: a half-open[start, end)range of Unicode code point offsets intostate_textwhen present, else intostate. Fortext, it covers exactly the guess. Computed values, and values read from images, have anullor absent span.- Lists are never
nulland keep input order. Text lists havespans, one entry per item: its span, ornullfor an item read from an image. - Estimates and every forecast step are within
[min, max], on thestepgrid, withp10≤median≤p90. A forecast has exactlyhorizonsteps, nearest first. Estimates havequantilesonly when their question setsquantiles: true; forecast steps never do. state_text, the text the model read, is returned when it differs fromstate, for example for structured state.truncated: truemeans the model read only the start of the state.
System One caching
Bkper caches System One results, for decision and extraction questions alike, for 15 minutes per user. An identical request in that window returns the same answers without calling the model or consuming allowance, and repeats the original usage. Aliases of the same model share one cache entry. To get fresh answers, change the request or wait. See Privacy, retention, and caching.
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_dataon models that support files; - JSON Schema structured output through
text.formaton 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_keyfor 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: trueis preserved only when the selected model can enforce the submitted schema subset.strict: falsesupports 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 and retention
Bkper disables provider storage on every request and keeps prompt and response content out of usage logs. Provider retention, caching, and Zero Data Retention status are listed in Privacy, retention, and caching.
Stateless behavior
Bkper AI does not persist response state:
- omitted
storebehaves asfalse; store: falseis accepted;store: trueis 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_idandinput_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. POST /v1/responses and POST /v1/systemone normalize provider failures the same way. Branch on error.code, not only on the HTTP status, because 429 has several meanings.
| Status | Meaning | error.code examples | Retry |
|---|---|---|---|
400 | Invalid request, unavailable model, unsupported capability, or context overflow | invalid_request, context_length_exceeded, provider_rejected | No. Fix the field in error.param. |
400 | The selected model’s provider does not serve the caller’s region | provider_region_unsupported | No. Choose a model from another provider. |
401 | Missing or invalid Bkper bearer token | unauthorized | No. Get a new Bkper token. |
402 | The authenticated subscription payment is overdue | billing_overdue | No |
403 | The account is not entitled to use Bkper AI | entitlement_unavailable | No |
422 | A System One model refused to answer for safety or policy reasons | refused | No. Route the item to a person. |
429 | The monthly Bkper AI allowance is exhausted | usage_limit_exceeded | No |
429 | Your own monthly limit inside a domain allowance is reached | user_limit_exceeded | No. Ask the domain billing admin to raise it. |
429 | The upstream provider is throttled | provider_rate_limited | Yes, with backoff |
499 | The client aborted the request | request_aborted | — |
502 | The selected upstream model provider or transport failed | provider_error, provider_rejected, provider_invalid_answer | A limited number of times |
503 | The provider is overloaded or quota usage is temporarily unavailable | provider_overloaded, usage_unavailable | Yes, with backoff |
When a provider sends retry-after with a 429 or 503, Bkper AI forwards it; wait at least that long before retrying. 401 and 403 always refer to your Bkper token or account. Upstream provider credential problems surface as 502.
Bkper AI blocks new requests once the recorded monthly allowance is exhausted. Where a domain shares one allowance, each user also has a monthly limit within it, set by the domain billing admin; reaching it blocks only that user’s requests. 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.
User limit headers
When a domain shares one allowance, every POST /v1/responses and POST /v1/systemone response, including streams and 429 errors, reports the user’s own monthly limit. Amounts are integers in nano-USD (0.000000001 USD), like model pricing in GET /v1/models. Values are taken before the request runs, so they do not include its cost. Without a domain allowance, the headers are absent.
| Header | Value |
|---|---|
bkper-ai-user-limit | The user’s monthly limit, never above the domain allowance |
bkper-ai-user-used | The user’s spend this month |
bkper-ai-user-remaining | The limit minus the spend, at least 0 |
bkper-ai-user-status | normal, warning from 80% of the limit, or critical from 90% |
Bkper AI models and usage: models, usage rates, allowance, and privacy
- OpenAPI version: 3.1.0
Authentication
bkperBearer
Send a Bkper OAuth access token. See token setup.
Security scheme type: http
Bearer format: Bkper OAuth access token