Skip to main content

API Reference

The full, always-current reference for every field and status code is the in-app API reference, generated from the same contract the server enforces:

This page covers the concepts. Use the in-app reference for field names, types and the complete list of status codes.

Endpoint​

POST https://app.bike4mind.com/api/ai/v1/completions

Send a JSON body with a model and a messages array. Other options (tools, extended thinking, token limits) are listed in the in-app reference. Message content can be a string or an array of parts, including images. To attribute requests to a run, send an optional run object; see Runs.

Authentication​

Send your API key as Authorization: Bearer b4m_live_<key>, or with the legacy x-api-key: b4m_live_<key> header. The two are equivalent. The key needs the ai:chat or ai:generate scope. See Authentication for how to create a key (Profile menu -> More -> API Keys).

End users of your product​

If you call the API from your own product on behalf of many end users, one key normally looks to the model provider like a single end user. A key that an administrator has granted the ai:end-user-id scope can attribute each request to one of your end users by sending end_user_id (on models served directly by OpenAI or Anthropic; other providers receive no end-user identifier):

{
"model": "claude-opus-4-8",
"messages": [{ "role": "user", "content": "How do I reset my password?" }],
"end_user_id": "customer_42"
}
  • end_user_id is your own opaque identifier for the end user: 1 to 64 characters, letters, digits, _, : and - only. Never send an email address or other personal data; a value containing @ is rejected.
  • For models served directly by OpenAI or Anthropic, the provider receives an identifier derived from your account and this value, not the value itself, so your end users never collide with each other or with another account's. Other providers receive no end-user identifier.
  • Billing, rate limits and every other check still apply to your key and account, not to the end user.
  • A value that breaks the format rules returns 400 with errorCode: "invalid_end_user_id", whatever the credential. Sending end_user_id with a key that lacks ai:end-user-id, or with a signed-in session instead of a key, returns 400 with errorCode: "end_user_id_not_allowed"; the field is never silently ignored.
  • POST /api/ai/tts accepts the same field under the same rules.

To get the scope on a key, ask your Bike4Mind administrator. You cannot add it yourself when you create a key.

Choosing a model​

Call GET /api/v1/models with your API key to list the model ids you can use. The list depends on which providers the deployment and your own provider keys enable, so if a sample returns 400 unknown_model or 503 provider_not_configured, use an id from that list. An unknown model returns a 400 with errorCode: "unknown_model"; a catalogued model whose provider is not configured returns 503 provider_not_configured.

After adding or activating a provider key, allow up to 60 seconds for GET /api/v1/models to reflect it: model lists are cached per user.

Response​

A successful request is always answered with a server-sent event stream (text/event-stream), whether or not you set a stream flag. The stream carries a meta event, then content and tool_use events with usage and credits, and ends with data: [DONE]. The last content event carries usage and credits. The final content event also carries stopReason when the provider reports one. max_tokens means the reply was truncated (raise max_tokens or reduce thinking); an absent stopReason means unknown, not truncated. degenerate_repetition is an aborted repeating reply, refusal is a declined request, and pause_turn requires continuation rather than publishing a final answer. See Streaming for how to parse it.

Credits​

Each request is charged to your personal credit balance, or to your organization's balance when you work under an organization. An organization can also set a per-member credit cap.

  • Before the stream opens, a request you cannot afford fails with HTTP 422 and errorCode: "insufficient_credits". It is never 402.
  • During the stream, if credits run out mid-generation, the status is already 200, so the failure arrives as a final in-band error event with code: "insufficient_credits".

Either way, top up your balance (or ask your organization admin to raise the cap) before you retry. Retrying unchanged will fail again.

Free-tier daily allowance​

When credit enforcement is enabled, free-tier accounts also have a daily personal-spend allowance. Once your recorded spend reaches it, new requests return HTTP 429 with errorCode: "daily_free_limit_reached" and a Retry-After header in seconds until midnight UTC. The request that crosses the allowance is allowed to finish; concurrent requests can overshoot it.

The default allowance is 500 credits for accounts under 24 hours old, 300 credits from 24 hours to under seven days old, and 200 credits thereafter. Your deployment administrator can change these limits. Paid ladder-tier subscribers and organization-billed requests are exempt; organization spend does not count toward your personal allowance. See Troubleshooting.

Rate limits and size​

Each API key has a per-minute and a per-day request limit; the in-app reference lists the defaults. Exceeding either returns 429 with a Retry-After header in seconds. On this endpoint the X-RateLimit-Limit-*, X-RateLimit-Remaining-* and X-RateLimit-Reset-* headers (Minute and Day variants, reset as Unix epoch seconds) are sent only on an API-key 429, not on successful responses. A request body over the size limit returns 413. The in-app reference describes the limits shared across endpoints: https://app.bike4mind.com/api/v1/docs.

Errors​

Anything checked before the model provider is called fails with a JSON body and a real HTTP status, and no stream opens:

  • 400: with errorCode: "invalid_end_user_id", end_user_id broke the format rules; with errorCode: "end_user_id_not_allowed", the request sent end_user_id on a credential that may not send it (see End users of your product).
  • 401: missing or invalid credentials.
  • 403: with required_scopes in the body, the API key lacks a scope. Without it, the account may be suspended or under a dispute (contact support), or a JWT caller may need to enroll in MFA in the web app.
  • 422: the body failed schema validation, or insufficient credits (see above).
  • 429: rate limited. Wait Retry-After seconds.

After the stream opens, a failure is a single terminal error event. See Errors for the event shape and retry guidance, and the in-app reference for every status code.