{ "openapi": "3.1.0", "info": { "title": "Bike4Mind API", "version": "16.1.0", "description": "Programmatic access to the Bike4Mind API. Schemas are generated from the same Zod definitions that validate requests at runtime, so this spec cannot drift from the implementation - with one documented exception: a `pollResult` schema (see the `x-poll-result` extension) describes a handoff response's outcome on a plain, non-contract endpoint, so it is hand-maintained against that handler rather than runtime-validated, and can drift if the handler changes without a matching schema update.\n\n## Getting started\n1. Create a key in the web app under **Profile > API Keys** (pick a scope preset).\n2. Make a first call: `GET /api/v1/me` with `Authorization: Bearer b4m_live_`. It needs only the `me:read` scope, spends no credits, and returns your identity, plan tier and credit balance.\n3. Read the rest of this page for the behaviour shared across endpoints: rate limits, credits, errors and async jobs.\n\nEndpoints are grouped by tag: **AI** (chat, completions, embeddings, agent runs, tools, quest polling), **Images**, **Audio**, **Videos**, **Music**, **Transcriptions**, **Sessions**, **Artifacts**, **Files**, **Projects**, **Agents**, **Data Lakes** and **Account**.\n\n## Authentication\nSend an API key as `Authorization: Bearer b4m_live_` (canonical), `x-api-key: b4m_live_` (legacy), or `Authorization: ApiKey b4m_live_`. A JWT access token is also accepted in the `Authorization: Bearer` header.\n\n## Scopes\nAPI keys carry `resource:action` scopes. The canonical set (from the runtime `ApiKeyScope` enum) is:\n- `notebooks:read`\n- `notebooks:write`\n- `files:read`\n- `files:write`\n- `ai:generate`\n- `ai:decide`\n- `ai:chat`\n- `projects:read`\n- `projects:write`\n- `agents:read`\n- `agents:write`\n- `cc-bridge:connect`\n- `me:read`\n- `admin:*`\n- `marketing-reports:read`\n- `marketing-reports:write`\n- `overwatch-ingest:write`\n- `embed:chat`\n- `hearth:read`\n- `hearth:write`\n- `optihashi:read`\n- `optihashi:compute`\n- `datalake:read`\n- `datalake:write`\n- `datalake:share`\n- `datalake:query`\n- `overwatch:read`\n- `qa:ingest`\n\nPer-operation required scopes are published via the `x-required-scopes` extension. Semantics are OR: a key needs ANY ONE of an operation's listed scopes, not all of them. Operations with no `x-required-scopes` enforce no scope (e.g. the JWT-only tools endpoint).\n\n## Rate limits\nEach API key has a per-minute and a per-day request ceiling, by default 60 requests/minute and 1000 requests/day (a key can be minted with its own ceilings). Responses from rate-limited operations carry the current state of both windows (the streaming completions endpoint sends them only on an API-key `429`):\n- `X-RateLimit-Limit-Minute`\n- `X-RateLimit-Remaining-Minute`\n- `X-RateLimit-Reset-Minute`\n- `X-RateLimit-Limit-Day`\n- `X-RateLimit-Remaining-Day`\n- `X-RateLimit-Reset-Day`\n\nReset values are Unix epoch seconds. Exceeding a ceiling returns `429` with a `Retry-After` header; wait that long before retrying. This includes `POST /api/ai/v1/completions`, which rate-limits before it opens its event stream. `GET /api/v1/me`, `GET /api/v1/credits`, `GET /api/v1/models`, `GET /api/v1/video-models`, `GET /api/v1/music-models`, the `GET` list endpoints for `/api/v1/sessions`, `/api/v1/video-generations` and `/api/v1/music-generations`, and the poll endpoints listed under Async jobs are exempt from the per-day ceiling: a poll consumes no daily slot, and only the per-minute limit applies. A request refused at the route scope gate (`403`) or for a bad key (`401`) never reaches the limiter and carries no rate-limit headers.\n\n## Credits\nGeneration endpoints spend credits from the balance shown at `credits.balance` on `GET /api/v1/me` (the caller's personal ledger). A key without `me:read` reads the same number from `GET /api/v1/credits`, which accepts `ai:chat`, `ai:generate` and `ai:decide` too. A synchronous call that cannot be paid for fails with `422` and `errorCode: \"insufficient_credits\"`. On a queued job the same code arrives on the polled result instead (see Async jobs), so check both places.\n\n## Errors\nError bodies use one envelope, the `ErrorResponse` schema: `{ \"error\": string, \"request_id\"?: string }`, plus an `errorCode` on failures a client is expected to branch on (`insufficient_credits`, `spend_cap_exceeded`, `provider_not_configured`, ...). A deprecated `name` field may also appear until its sunset date; do not rely on it. Branch on the HTTP status and `errorCode`, never on the `error` prose. A few operations declare a bespoke error shape for a specific status (e.g. the `500` of the tools endpoint and the `413` of text-to-speech); each operation lists the statuses it can return and the body for each.\n\nThe shared statuses: a malformed JSON body is `400`, a body that fails schema validation is `422`, a missing or invalid credential is `401`, a valid key without the required scope is `403`, an unknown resource is `404` and an exceeded rate limit is `429`. A `401` carrying `errorCode: \"provider_rejected\"` means the upstream provider refused the provider key the request used - the platform key by default, or your own stored provider key when you configured one - so your API key itself was accepted.\n\n## Async jobs\nWork that is not provably fast is queued and polled rather than held open:\n- **Chat** (`POST /api/chat`) and **image generation/editing** (`POST /api/v1/image-generations`, `POST /api/v1/image-edits`) return a quest. Poll `GET /api/v1/quests/{id}` until `status` is `done` or `stopped`; chat text arrives in `reply`, generated images in `images`, edited images in `files[].url`. Check for failure before reading results: a job that ends `done` with `type: \"error\"` failed (the reason is in `reply`), and a job that ends `stopped` also failed even when `type` is not `\"error\"` (its `reply` carries an explanation, not an answer). The outcome schema of each of these quest handoffs is linked from its response via the `x-poll-result` extension. Chat also accepts `wait: true` to block until the reply is ready.\n- **Agent runs** (`POST /api/v1/agent-executions`) return `202`. Poll `GET /api/v1/agent-executions/{id}` until `status` is `completed`, `failed` or `aborted`.\n- **Video generation** (`POST /api/v1/video-generations`) returns `202`. Poll `GET /api/v1/video-generations/{id}` until `state` is `succeeded`, `failed`, `blocked` or `cancelled`.\n- **Music generation** (`POST /api/v1/music-generations`) returns `202`. Poll `GET /api/v1/music-generations/{id}` until `state` is `succeeded`, `failed`, `blocked` or `cancelled`.\n- **File uploads** (`POST /api/v1/files`) return a presigned `upload_url`; after the `PUT`, poll `GET /api/v1/files/{id}` until `moderation_status` is `clean` before passing the id elsewhere.\n- **Audio** endpoints are synchronous and return the result directly.\n- **Transcriptions** (`POST /api/v1/transcriptions`) are synchronous too: after the upload, one call returns the text. Long audio can outlast the request timeout and fail with a `504`; see that endpoint for the limit.\n\nPoll with a backoff of a few seconds: each poll counts against the per-minute limit.\n\n## Versioning\nNew endpoints live under `/api/v1`. Published endpoints are forward-only: a live URL is never renamed or removed, and a breaking change ships as a new path while the old one keeps working. Nothing published is removed silently - a deprecated field or endpoint is marked `deprecated` in this spec with a sunset date in its description, and keeps working until that date.\n\n## CORS\nThe spec (`/api/v1/openapi.json`) is served publicly with permissive CORS. The API endpoints themselves are called server-to-server with a secret key and are not intended for browser CORS use.\n\n## Correlation\nEvery response carries an `X-Request-ID` header (echoed as `request_id`/`requestId` in bodies and events) for log correlation.", "contact": { "name": "Bike4Mind", "url": "https://your-deployment.example.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://your-deployment.example.com", "description": "Production" }, { "url": "https://staging.your-deployment.example.com", "description": "Staging" }, { "url": "http://localhost:3000", "description": "Local dev" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Canonical auth. Send `Authorization: Bearer b4m_live_`. A JWT access token is also accepted in this header; a token beginning with `b4m_` is treated as an API key, anything else as a JWT." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Legacy auth. Send `x-api-key: b4m_live_`. Equivalent to `bearerAuth` for API keys." }, "jwtAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token only. Send `Authorization: Bearer `. API keys are NOT accepted here." } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message." }, "request_id": { "type": "string", "description": "Correlation id, mirrors the X-Request-ID header." }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." } }, "required": [ "error" ], "example": { "error": "Missing or invalid toolName", "request_id": "abc-123" } }, "sendChatMessage200PollResult": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "stopped", "running", "done" ] }, "type": { "type": "string", "enum": [ "message", "oob", "error", "system", "voice_transcript" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] }, "reply": { "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "type": "string" } }, "fallbackInfo": { "type": "object", "properties": { "primaryModel": { "type": "string" }, "primaryModelName": { "type": "string" }, "fallbackModel": { "type": "string" }, "fallbackModelName": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "primaryModel", "primaryModelName", "fallbackModel", "fallbackModelName" ] } }, "required": [ "id" ], "description": "Outcome fields of the quest polled at `GET /api/v1/quests/{id}` after this ACK. A finished turn that failed is `status: \"done\"` with `type: \"error\"` and the failure text in `reply`, so a caller reading `reply` alone cannot tell a failure from an answer - check `type` first, and also treat a terminal `status: \"stopped\"` (a missing session, a user-cancelled turn) as failure even though it never sets `type`. `errorCode` is an optional refinement of `type: \"error\"`, present only for a classified billing failure; credit exhaustion arrives here as `insufficient_credits`, the same vocabulary the synchronous 422s on `/api/ai/music`, `/api/ai/sound-effects` and `/api/ai/tts` use. `QUEST_ERROR_CODES` publishes a second member, `spend_cap_exceeded`, but no current throw site on this endpoint raises it as a quest errorCode: its only one, the embed chat route's pre-flight 422, fires outside the process try/catch that would classify it onto the quest. Most `type: \"error\"` turns - an abort, a provider timeout or overload - have NO `errorCode`; its absence does not mean success, only that the failure is unclassified. A recovered stuck quest that still has renderable content is not a failure at all: it keeps `type: \"message\"` even though it did not finish, so a caller gets the content rather than an error. `fallbackInfo` is present only when the requested model failed and another model produced the reply: `fallbackModel` answered, `primaryModel` is what was asked for, and `reason` is the error from the first failed attempt on the requested model. The poll body carries further fields not modelled here, including `images`, `files`, `toolPayloads`, `promptMeta`, and the attachment report (`attachmentNotices`/`attachmentDelivery`) - only the outcome subset is modelled here.", "example": { "id": "664f1c2b9a1e4d0012ab34cd", "status": "done", "type": "error", "errorCode": "insufficient_credits", "reply": "You're out of credits. This request needs about 12 credits, but only 3 are available." } }, "generateImage200PollResult": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "stopped", "running", "done" ] }, "type": { "type": "string", "enum": [ "message", "oob", "error", "system", "voice_transcript" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] }, "reply": { "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "type": "string" } }, "fallbackInfo": { "type": "object", "properties": { "primaryModel": { "type": "string" }, "primaryModelName": { "type": "string" }, "fallbackModel": { "type": "string" }, "fallbackModelName": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "primaryModel", "primaryModelName", "fallbackModel", "fallbackModelName" ] }, "sessionId": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "sessionId" ], "description": "The quest polled at `GET /api/v1/quests/{id}` after this ACK. The render is finished once `status` is `\"done\"`: on success `images` holds the rendered images; a render that FAILED is `type: \"error\"` with the reason in `reply`, never a 4xx. That covers credit exhaustion (tagged `errorCode: \"insufficient_credits\"`, the same vocabulary as the synchronous 422s on the audio endpoints), a provider error, and a reference image that is missing, not an image, or still in moderation. Check `type` before reading `images`; `errorCode` is absent on unclassified failures, so its absence does not mean success.", "example": { "id": "664f1c2b9a1e4d0012ab34cd", "sessionId": "664f1c2b9a1e4d0012ab34aa", "status": "done", "type": "message", "images": [ "3f6c1a52-9d1e-4b7a-8c2f-5e0d4a9b1c7e.png" ] } }, "editImage200PollResult": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "stopped", "running", "done" ] }, "type": { "type": "string", "enum": [ "message", "oob", "error", "system", "voice_transcript" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] }, "reply": { "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "type": "string" } }, "fallbackInfo": { "type": "object", "properties": { "primaryModel": { "type": "string" }, "primaryModelName": { "type": "string" }, "fallbackModel": { "type": "string" }, "fallbackModelName": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "primaryModel", "primaryModelName", "fallbackModel", "fallbackModelName" ] }, "sessionId": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "sessionId" ], "description": "The quest polled at `GET /api/v1/quests/{id}` after this ACK. The render is finished once `status` is `\"done\"`: on success `images` holds the rendered images; a render that FAILED is `type: \"error\"` with the reason in `reply`, never a 4xx. That covers credit exhaustion (tagged `errorCode: \"insufficient_credits\"`, the same vocabulary as the synchronous 422s on the audio endpoints), a provider error, and a reference image that is missing, not an image, or still in moderation. Check `type` before reading `images`; `errorCode` is absent on unclassified failures, so its absence does not mean success.", "example": { "id": "664f1c2b9a1e4d0012ab34cd", "sessionId": "664f1c2b9a1e4d0012ab34aa", "status": "done", "type": "message", "images": [ "3f6c1a52-9d1e-4b7a-8c2f-5e0d4a9b1c7e.png" ] } }, "sendChatMessageResponse200": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "message_received": { "type": "boolean" }, "timestamp": { "type": "string" }, "model": { "type": "string" }, "sessionId": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "oob", "error", "system", "voice_transcript" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] }, "tools": { "type": "object", "properties": { "toolMode": { "type": "string", "enum": [ "fast", "smart" ] }, "autoSelectedTools": { "type": "array", "items": { "type": "string" } }, "effectiveTools": { "type": "array", "items": { "type": "string" } }, "unrecognizedTools": { "type": "array", "items": { "type": "string" } } }, "required": [ "effectiveTools" ] }, "tracking_info": { "type": "object", "properties": { "quest_id": { "type": "string" }, "check_status_url": { "type": "string" }, "poll_url": { "type": "string" } }, "required": [ "quest_id", "check_status_url" ] }, "response": { "type": [ "string", "null" ] }, "responses": { "type": "array", "items": { "type": "string" } }, "toolPayloads": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "payload": {} }, "required": [ "type" ] } }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ] }, "promptDetails": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "hardcoded", "admin", "user", "project", "session", "org", "caller" ] }, "name": { "type": "string" }, "tokenCount": { "type": "number" }, "wasIncluded": { "type": "boolean" }, "exclusionReason": { "type": "string", "enum": [ "duplicate", "disabled", "token_limit" ] } }, "required": [ "source", "name", "tokenCount", "wasIncluded" ] } }, "promptText": { "type": "string" }, "performance": { "type": "object", "properties": { "total_ms": { "type": "number" }, "phases": { "type": "object", "additionalProperties": { "type": "number" } }, "pipeline_phases": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "total_ms", "phases" ] } }, "required": [ "id", "status", "message_received", "timestamp", "model", "type", "tracking_info", "response", "responses", "toolPayloads", "createdAt", "performance" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "message_received": { "type": "boolean" }, "timestamp": { "type": "string" }, "model": { "type": "string" }, "sessionId": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "oob", "error", "system", "voice_transcript" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] }, "tools": { "type": "object", "properties": { "toolMode": { "type": "string", "enum": [ "fast", "smart" ] }, "autoSelectedTools": { "type": "array", "items": { "type": "string" } }, "effectiveTools": { "type": "array", "items": { "type": "string" } }, "unrecognizedTools": { "type": "array", "items": { "type": "string" } } }, "required": [ "effectiveTools" ] }, "tracking_info": { "type": "object", "properties": { "quest_id": { "type": "string" }, "check_status_url": { "type": "string" }, "poll_url": { "type": "string" } }, "required": [ "quest_id", "check_status_url" ] } }, "required": [ "id", "status", "message_received", "timestamp", "model", "tracking_info" ] } ] }, "ScopeForbiddenResponse": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route accepts. Holding any one of them satisfies it." }, "also_required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route also requires. Every one must be held, on top of `required_scopes`." } }, "required": [ "error" ] }, "sendChatMessageResponse504": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "request_timeout" ] }, "quest_id": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "error", "errorCode", "quest_id" ] }, "sendChatMessageRequest": { "type": "object", "properties": { "sessionId": { "type": [ "string", "null" ] }, "newConversation": { "type": "boolean" }, "message": { "type": "string" }, "organizationId": { "type": "string" }, "model": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "number", "exclusiveMinimum": 0 }, "maxTokens": { "type": "number", "exclusiveMinimum": 0 }, "maxOutputTokens": { "type": "number", "exclusiveMinimum": 0 }, "stream": { "type": "boolean", "default": false }, "historyCount": { "type": "number", "exclusiveMinimum": 0, "default": 10 }, "fileIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "wait": { "type": "boolean", "default": false }, "enableTools": { "type": "boolean", "default": false }, "toolMode": { "type": "string", "enum": [ "fast", "smart" ] }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Explicit tool ids to offer the model. A non-empty array enables tools on its own; no companion `toolMode` or `enableTools` is required. Merged with the auto-selected set under `toolMode: \"smart\"`, and ignored under `toolMode: \"fast\"`. This list ADDS to what is offered rather than restricting it - the server still offers tools of its own (for example knowledge retrieval when the session has reachable documents). Unrecognized ids are dropped rather than rejecting the request; the response reports the surviving set as `tools.effectiveTools` and the ids that are not tools in this deployment as `tools.unrecognizedTools`, since no endpoint enumerates the valid ids. `unrecognizedTools` is reported under every `toolMode` - it describes the ids, not what the mode did with them - so under `toolMode: \"fast\"` an id can be absent from `effectiveTools` (the mode discarded it) without being unrecognized. Both reported lists are deduplicated, and `unrecognizedTools` names at most the first 10 distinct ids." }, "enableQuestMaster": { "type": "boolean" }, "enableMementos": { "type": "boolean" }, "enableAgents": { "type": "boolean" }, "promptMode": { "type": "string", "enum": [ "raw", "grounded", "surface" ] }, "skip_auto_offers": { "type": "boolean", "description": "Suppress tools the server would otherwise attach on its own for this session (the knowledge-base search offer, in-app view navigation, blog drafting/editing/publishing, skill invocation, and every tool from a connected MCP server). Native tools you request explicitly in `tools` are unaffected, but an MCP server tool cannot be named through this field, so with this flag set a caller with an MCP server connected sees none of its tools regardless of `tools`. One system-prompt block goes with them: withholding in-app view navigation also drops the view-registry block that exists only to describe it. No other prompt content changes. This does not switch off retrieval: a session with forced knowledge retrieval still retrieves, and documents already attached to the session are still placed in the prompt directly. Any promptMode suppresses these too, so false has no effect alongside one." }, "includePromptDetails": { "type": "boolean" }, "includeSystemPrompt": { "type": "boolean" }, "systemPrompt": { "type": "string", "maxLength": 16000, "description": "System-prompt text for this request only, never persisted. Rendered as a defended block appended after every other system-prompt source, with prose instructing the model to defer to organization, session and data-lake guidance. Over the cap is a 422, never truncated." } }, "required": [ "message" ], "example": { "message": "How do I reset my password?", "toolMode": "smart" } }, "startAgentExecutionResponse202": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] }, "session_id": { "type": "string" }, "model": { "type": "string" }, "timestamp": { "type": "string" }, "tracking_info": { "type": "object", "properties": { "execution_id": { "type": "string" }, "quest_id": { "type": "string" }, "poll_url": { "type": "string" } }, "required": [ "execution_id", "poll_url" ] } }, "required": [ "id", "status", "session_id", "model", "timestamp", "tracking_info" ] }, "startAgentExecutionRequest": { "type": "object", "properties": { "session_id": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "model": { "type": "string" }, "agent_id": { "type": "string" }, "organization_id": { "type": "string" }, "tools": { "type": "array", "items": { "type": "string" } }, "max_iterations": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "integer", "exclusiveMinimum": 0 }, "thinking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "budget_tokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 32000 } }, "required": [ "enabled" ] }, "file_ids": { "type": "array", "items": { "type": "string" } }, "session_file_ids": { "type": "array", "items": { "type": "string" } }, "enable_mementos": { "type": "boolean" }, "enable_lattice": { "type": "boolean" }, "enable_artifacts": { "type": "boolean" } }, "required": [ "session_id", "message" ], "example": { "session_id": "", "message": "Audit this data set and summarize what stands out." } }, "getAgentExecutionResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "continuing", "awaiting_permission", "awaiting_subagent", "awaiting_dag_children", "paused", "completed", "failed", "aborted" ] }, "session_id": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thought", "action", "observation", "final_answer" ] }, "content": { "type": "string" }, "iteration": { "type": "integer", "minimum": 0 }, "tool_name": { "type": "string" } }, "required": [ "type", "content" ] } }, "total_iterations": { "type": [ "number", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "status", "session_id", "answer", "error", "steps", "total_iterations", "created_at", "updated_at" ] }, "getSessionResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "_id": { "type": "string" }, "name": { "type": "string" }, "userId": { "type": "string" }, "knowledgeIds": { "type": "array", "items": { "type": "string" } }, "artifactIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "name", "strength" ] } }, "forceKnowledgeRetrieval": { "type": "boolean" }, "retrievalTags": { "type": "array", "items": { "type": "string" } }, "lakeScopeExplicit": { "type": "boolean", "description": "True when `retrievalTags` is a deliberate choice, so an empty list means \"no lake\" rather than \"any\"." }, "includeLibraryFiles": { "type": "boolean", "description": "Whether the session grounds on your own library alongside its lakes. Absent when never set." }, "lastUsedModel": { "type": [ "string", "null" ] }, "firstCreated": { "type": "string", "format": "date-time" }, "lastUpdated": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "userId", "firstCreated", "lastUpdated" ] }, "updateSessionResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "_id": { "type": "string" }, "name": { "type": "string" }, "userId": { "type": "string" }, "knowledgeIds": { "type": "array", "items": { "type": "string" } }, "artifactIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "name", "strength" ] } }, "forceKnowledgeRetrieval": { "type": "boolean" }, "retrievalTags": { "type": "array", "items": { "type": "string" } }, "lakeScopeExplicit": { "type": "boolean", "description": "True when `retrievalTags` is a deliberate choice, so an empty list means \"no lake\" rather than \"any\"." }, "includeLibraryFiles": { "type": "boolean", "description": "Whether the session grounds on your own library alongside its lakes. Absent when never set." }, "lastUsedModel": { "type": [ "string", "null" ] }, "firstCreated": { "type": "string", "format": "date-time" }, "lastUpdated": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "userId", "firstCreated", "lastUpdated" ] }, "updateSessionRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "knowledgeIds": { "type": "array", "items": { "type": "string" } }, "artifactIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "name", "strength" ] } }, "lastUsedModel": { "type": [ "string", "null" ], "minLength": 1, "description": "Pin a specific model id, or omit/send null to leave the current pin unchanged. Sending null does NOT clear it." }, "forceKnowledgeRetrieval": { "type": "boolean" }, "lakeScope": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The data lakes this session searches, as lake tags (the `datalake_tag` of each lake from GET /api/v1/data-lakes). Send a list to search only those lakes, `[]` to search no lake at all, or `null` to clear the choice so retrieval falls back to every lake you can reach. Omit to leave the current choice unchanged. Tags naming a lake you cannot reach are ignored at retrieval time rather than rejected here. A non-empty list also turns forced retrieval on for a session that has never set it, unless `forceKnowledgeRetrieval` is sent in the same request; a value the session already stores is left as it is. Conversely `[]` leaves a session with forced retrieval nothing to retrieve from, so its forced retrieval is skipped rather than run against every lake." }, "includeLibraryFiles": { "type": "boolean", "description": "Whether the session grounds on your own library (files you own, or that are shared with you or your groups) alongside its lakes. `false` confines retrieval to lake content, including when every lake is in scope; the session's attached files still reach the model and stay searchable by its knowledge-base tools. Omit to leave it unchanged; while never set, the library is excluded only when a lake was picked for the session (Data Lakes mode or an explicit lake scope), not when lake tags were derived from an attached file. While `forceKnowledgeRetrieval` is `false` the library is included regardless; the stored value applies again once it is turned back on." }, "propagateToProjects": { "type": "boolean", "description": "Defaults to true when omitted. When knowledgeIds grows, the newly-added file ids are also appended to every project that contains this session, granting every member of that project access to those files. This propagation is append-only and cannot be undone through the UI - pass false if newly-attached files should not be shared with the project." } }, "example": { "knowledgeIds": [ "" ], "forceKnowledgeRetrieval": true } }, "deleteSessionResponse200": { "type": "object", "properties": { "newLastNotebookId": { "type": [ "string", "null" ], "description": "The caller's most recently updated remaining session, which the product UI opens next; null when none remains." } }, "required": [ "newLastNotebookId" ] }, "cloneSessionResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "_id": { "type": "string" }, "name": { "type": "string" }, "userId": { "type": "string" }, "knowledgeIds": { "type": "array", "items": { "type": "string" } }, "artifactIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "name", "strength" ] } }, "forceKnowledgeRetrieval": { "type": "boolean" }, "retrievalTags": { "type": "array", "items": { "type": "string" } }, "lakeScopeExplicit": { "type": "boolean", "description": "True when `retrievalTags` is a deliberate choice, so an empty list means \"no lake\" rather than \"any\"." }, "includeLibraryFiles": { "type": "boolean", "description": "Whether the session grounds on your own library alongside its lakes. Absent when never set." }, "lastUsedModel": { "type": [ "string", "null" ] }, "firstCreated": { "type": "string", "format": "date-time" }, "lastUpdated": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "userId", "firstCreated", "lastUpdated" ] }, "cloneSessionRequest": { "type": "object", "properties": { "targetSurface": { "type": [ "string", "null" ] } }, "default": {}, "example": {} }, "executeToolResponse200": { "type": "object", "properties": { "success": { "type": "boolean" }, "result": {}, "error": { "type": "string" }, "errorType": { "type": "string" }, "executionTimeMs": { "type": "number" }, "request_id": { "type": "string" } }, "required": [ "success", "request_id" ], "example": { "success": true, "result": { "summary": "Top results for the query." }, "executionTimeMs": 842, "request_id": "abc-123" } }, "executeToolResponse500": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "result": {}, "error": { "type": "string" }, "errorType": { "type": "string" }, "executionTimeMs": { "type": "number" }, "request_id": { "type": "string" } }, "required": [ "success", "request_id" ] }, { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "error" ] } ] }, "executeToolRequest": { "type": "object", "properties": { "toolName": { "type": "string", "enum": [ "weather_info", "web_search", "web_fetch" ] }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolName", "input" ], "example": { "toolName": "web_search", "input": { "query": "how to reset a password" } } }, "createCompletionResponse200": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "meta" ] }, "requestId": { "type": "string" } }, "required": [ "type", "requestId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content", "tool_use" ] }, "text": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" }, "id": { "type": "string" } }, "required": [ "name" ] } }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "reasoningTokens": { "type": "number", "description": "Reasoning/thinking tokens the provider reported. A subset of outputTokens, not additive and not billed on top. Absent when the provider or adapter reports no count." }, "cacheReadInputTokens": { "type": "number" }, "cacheCreationInputTokens": { "type": "number" } } }, "credits": { "type": "object", "properties": { "used": { "type": "number" }, "usdCost": { "type": "number" } } }, "responseFormatMode": { "type": "string", "enum": [ "native", "tool_use", "best-effort" ] }, "stopReason": { "type": "string" }, "thinking": { "type": "array", "items": {} }, "toolStarted": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "provider_block" ] }, "provider": { "type": "string", "enum": [ "anthropic" ] }, "block": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "provider", "block" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded", "provider_error", "provider_rejected", "content_blocked" ] } }, "required": [ "type", "message" ] } ], "example": { "type": "content", "text": "To reset your password, click 'Forgot password' on the login screen.", "usage": { "inputTokens": 42, "outputTokens": 12 }, "credits": { "used": 1, "usdCost": 0.00037 }, "stopReason": "end_turn" } }, "createCompletionResponse400": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "unknown_model", "tool_search_unsupported", "all_tools_deferred", "deferred_tool_cache_control", "unknown_tool_reference" ] } }, "required": [ "error" ] }, "createCompletionResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] } }, "required": [ "error" ] }, "createCompletionResponse503": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "provider_not_configured" ] } }, "required": [ "error" ] }, "createCompletionRequest": { "type": "object", "properties": { "model": { "type": "string", "maxLength": 256 }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ] }, "cache": { "type": "boolean" } }, "required": [ "role", "content" ] } }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "type": "boolean", "default": true } }, "required": [ "name", "schema" ] } }, "required": [ "type", "json_schema" ] } ] }, "stream": { "type": "boolean" }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSchema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "properties": { "type": "object", "additionalProperties": {} }, "additionalProperties": { "type": "boolean" }, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "additionalProperties": {} }, "strict": { "type": "boolean" }, "defer_loading": { "type": "boolean", "description": "Keep this definition out of the model context until the tool search server tool (or a `tool_reference`) loads it. Honoured only on models served by the direct Anthropic API whose `supports_tool_search` is true; on every other model (including Bedrock-served Claude, for now) it is ignored and the tool is sent as usual. At least one tool, or a `serverTool` entry, must stay non-deferred (`errorCode: \"all_tools_deferred\"`)." }, "cache_control": { "description": "Accepted for validation only and not forwarded. Rejected on a deferred tool (`errorCode: \"deferred_tool_cache_control\"`)." } }, "required": [ "name", "description", "parameters" ] }, "_isMcpTool": { "type": "boolean" } }, "required": [ "toolSchema" ] }, { "type": "object", "properties": { "serverTool": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_search_tool_regex_20251119" ] }, "name": { "type": "string", "enum": [ "tool_search_tool_regex" ] } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_search_tool_bm25_20251119" ] }, "name": { "type": "string", "enum": [ "tool_search_tool_bm25" ] } }, "required": [ "type", "name" ] } ], "description": "A provider-run tool, sent to the provider as `{ type, name }`. Only the Anthropic tool search tools exist today, and only on models served by the direct Anthropic API whose `supports_tool_search` is true; any other model, Bedrock-served Claude included, is refused with `errorCode: \"tool_search_unsupported\"` rather than run without it." } }, "required": [ "serverTool" ] } ] } }, "temperature": { "type": "number" }, "max_tokens": { "type": "number" }, "options": { "type": "object", "properties": { "temperature": { "type": "number" }, "maxTokens": { "type": "number" }, "stream": { "type": "boolean" }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSchema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "properties": { "type": "object", "additionalProperties": {} }, "additionalProperties": { "type": "boolean" }, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "additionalProperties": {} }, "strict": { "type": "boolean" }, "defer_loading": { "type": "boolean", "description": "Keep this definition out of the model context until the tool search server tool (or a `tool_reference`) loads it. Honoured only on models served by the direct Anthropic API whose `supports_tool_search` is true; on every other model (including Bedrock-served Claude, for now) it is ignored and the tool is sent as usual. At least one tool, or a `serverTool` entry, must stay non-deferred (`errorCode: \"all_tools_deferred\"`)." }, "cache_control": { "description": "Accepted for validation only and not forwarded. Rejected on a deferred tool (`errorCode: \"deferred_tool_cache_control\"`)." } }, "required": [ "name", "description", "parameters" ] }, "_isMcpTool": { "type": "boolean" } }, "required": [ "toolSchema" ] }, { "type": "object", "properties": { "serverTool": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_search_tool_regex_20251119" ] }, "name": { "type": "string", "enum": [ "tool_search_tool_regex" ] } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_search_tool_bm25_20251119" ] }, "name": { "type": "string", "enum": [ "tool_search_tool_bm25" ] } }, "required": [ "type", "name" ] } ], "description": "A provider-run tool, sent to the provider as `{ type, name }`. Only the Anthropic tool search tools exist today, and only on models served by the direct Anthropic API whose `supports_tool_search` is true; any other model, Bedrock-served Claude included, is refused with `errorCode: \"tool_search_unsupported\"` rather than run without it." } }, "required": [ "serverTool" ] } ] } }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "type": "boolean", "default": true } }, "required": [ "name", "schema" ] } }, "required": [ "type", "json_schema" ] } ] }, "reasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ], "description": "Reasoning effort hint. Honoured by the OpenAI (reasoning models only, and not alongside tools on some of them), Kimi (K3 only), DeepSeek and Anthropic Claude (direct and Bedrock) adapters; each maps it onto its own scale. On Claude, `none` turns thinking off where the model allows it (otherwise it runs at the lowest effort), so short `max_tokens` replies stream visible text from the start; `minimal` maps to `low`. When `thinking.enabled` is also set on a Claude model, thinking stays on and this sets its effort instead, with `none` and `minimal` mapping to `low`. Claude models that reason inside `max_tokens` never have that ceiling raised, and on older Claude models any level above `none` turns thinking on (it is off by default there), forces temperature to 1 and drops top_p, and a thinking budget that cannot fit under `max_tokens` is skipped. On the direct Anthropic API, a json_schema `response_format` with no tools is served by a forced tool on models that support forced tool use, and that tool cannot run alongside thinking, so there only `none` is honoured; models served by native structured outputs honour every level. Silently ignored by every other adapter (Gemini, xAI, Ollama) and by non-reasoning models, so sending it there is a no-op." }, "thinking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "budget_tokens": { "type": "integer", "minimum": 1024 } }, "required": [ "enabled" ], "description": "Ask a model that can think to think on this turn. On Claude, `reasoningEffort` then sets how much it thinks, and `budget_tokens` (default 16000, minimum 1024) sizes thinking on older Claude models. Ignored by models that cannot think, and on the direct Anthropic API when a json_schema `response_format` is served by a forced tool, which cannot run alongside thinking." } } } }, "required": [ "model", "messages" ], "example": { "model": "claude-opus-4-8", "messages": [ { "role": "user", "content": "How do I reset my password?" } ], "max_tokens": 500 } }, "synthesizeSpeechResponse200": { "anyOf": [ { "type": "object", "properties": { "contentType": { "type": "string" }, "saved": { "type": "boolean" }, "fabFileId": { "type": "string" }, "fileName": { "type": "string" }, "fileUrl": { "type": "string" }, "saveSkippedReason": { "type": "string", "enum": [ "storage_limit", "file_too_large", "error" ] }, "format": { "type": "string", "enum": [ "mp3", "wav", "opus", "aac", "flac", "pcm" ] }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "fallbackFrom": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "delivery": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 } }, "required": [ "contentType", "format", "delivery", "url", "bytes" ] }, { "type": "object", "properties": { "contentType": { "type": "string" }, "saved": { "type": "boolean" }, "fabFileId": { "type": "string" }, "fileName": { "type": "string" }, "fileUrl": { "type": "string" }, "saveSkippedReason": { "type": "string", "enum": [ "storage_limit", "file_too_large", "error" ] }, "format": { "type": "string", "enum": [ "mp3", "wav", "opus", "aac", "flac", "pcm" ] }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "fallbackFrom": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "delivery": { "type": "string", "enum": [ "inline" ] }, "audio": { "type": "string" } }, "required": [ "contentType", "format", "audio" ] } ], "example": { "delivery": "inline", "audio": "SUQzBAAAAAAA...", "format": "mp3", "contentType": "audio/mpeg", "saved": true, "fabFileId": "664f1c2b9a1e4d0012ab34cd" } }, "synthesizeSpeechResponse400": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "synthesizeSpeechResponse401": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "synthesizeSpeechResponse403": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route accepts. Holding any one of them satisfies it." }, "also_required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route also requires. Every one must be held, on top of `required_scopes`." }, "errorCode": { "type": "string", "enum": [ "billing_organization_mismatch" ] }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] } }, "required": [ "error" ] }, "synthesizeSpeechResponse404": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "synthesizeSpeechResponse413": { "type": "object", "properties": { "error": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "saved": { "type": "boolean", "enum": [ true ] }, "fabFileId": { "type": "string" }, "fileUrl": { "type": "string" } }, "required": [ "error", "provider" ] }, "synthesizeSpeechResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "synthesizeSpeechResponse429": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "synthesizeSpeechResponse502": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "synthesizeSpeechRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 10000 }, "provider": { "type": "string", "enum": [ "openai", "elevenlabs" ] }, "model": { "type": "string" }, "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "mp3", "wav", "opus", "aac", "flac", "pcm" ] }, "stability": { "type": "number", "minimum": 0, "maximum": 1 }, "similarityBoost": { "type": "number", "minimum": 0, "maximum": 1 }, "languageCode": { "type": "string", "pattern": "^[a-z]{2}$" }, "organization_id": { "type": [ "string", "null" ], "minLength": 1, "description": "The organization to bill: one you belong to, or null for your personal credits. Omitted bills your personal credits, as this endpoint always has. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (`errorCode: billing_organization_mismatch`)." }, "encoding": { "type": "string", "enum": [ "binary", "base64" ] }, "preview": { "type": "boolean" } }, "required": [ "text" ], "example": { "text": "Your password has been reset.", "provider": "openai", "voice": "alloy", "format": "mp3" } }, "generateMusicResponse200": { "anyOf": [ { "type": "object", "properties": { "contentType": { "type": "string" }, "saved": { "type": "boolean" }, "fabFileId": { "type": "string" }, "fileName": { "type": "string" }, "fileUrl": { "type": "string" }, "saveSkippedReason": { "type": "string", "enum": [ "storage_limit", "file_too_large", "error" ] }, "delivery": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 } }, "required": [ "contentType", "delivery", "url", "bytes" ] }, { "type": "object", "properties": { "contentType": { "type": "string" }, "saved": { "type": "boolean" }, "fabFileId": { "type": "string" }, "fileName": { "type": "string" }, "fileUrl": { "type": "string" }, "saveSkippedReason": { "type": "string", "enum": [ "storage_limit", "file_too_large", "error" ] }, "delivery": { "type": "string", "enum": [ "inline" ] }, "audio": { "type": "string" } }, "required": [ "contentType", "audio" ] } ], "example": { "delivery": "inline", "audio": "SUQzBAAAAAAA...", "contentType": "audio/mpeg", "saved": true } }, "generateMusicResponse413": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "generateMusicResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] } }, "required": [ "error" ] }, "generateMusicRequest": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "elevenlabs" ], "default": "elevenlabs" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "lengthMs": { "type": "integer", "minimum": 3000, "maximum": 120000, "default": 10000 }, "forceInstrumental": { "type": "boolean" }, "modelId": { "type": "string", "enum": [ "music_v1" ], "default": "music_v1" }, "format": { "type": "string" }, "encoding": { "type": "string", "enum": [ "binary", "base64" ] }, "preview": { "type": "boolean" } }, "required": [ "prompt" ], "example": { "prompt": "calm lo-fi study beat with soft piano", "lengthMs": 30000, "forceInstrumental": true } }, "generateSoundEffectResponse200": { "anyOf": [ { "type": "object", "properties": { "contentType": { "type": "string" }, "saved": { "type": "boolean" }, "fabFileId": { "type": "string" }, "fileName": { "type": "string" }, "fileUrl": { "type": "string" }, "saveSkippedReason": { "type": "string", "enum": [ "storage_limit", "file_too_large", "error" ] }, "delivery": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 } }, "required": [ "contentType", "delivery", "url", "bytes" ] }, { "type": "object", "properties": { "contentType": { "type": "string" }, "saved": { "type": "boolean" }, "fabFileId": { "type": "string" }, "fileName": { "type": "string" }, "fileUrl": { "type": "string" }, "saveSkippedReason": { "type": "string", "enum": [ "storage_limit", "file_too_large", "error" ] }, "delivery": { "type": "string", "enum": [ "inline" ] }, "audio": { "type": "string" } }, "required": [ "contentType", "audio" ] } ], "example": { "delivery": "inline", "audio": "SUQzBAAAAAAA...", "contentType": "audio/mpeg", "saved": true } }, "generateSoundEffectResponse403": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route accepts. Holding any one of them satisfies it." }, "also_required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route also requires. Every one must be held, on top of `required_scopes`." }, "errorCode": { "type": "string", "enum": [ "billing_organization_mismatch" ] } }, "required": [ "error" ] }, "generateSoundEffectResponse413": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "generateSoundEffectResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] } }, "required": [ "error" ] }, "generateSoundEffectRequest": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "elevenlabs" ], "default": "elevenlabs" }, "text": { "type": "string", "minLength": 1, "maxLength": 1000 }, "durationSeconds": { "type": "number", "minimum": 0.5, "maximum": 30 }, "promptInfluence": { "type": "number", "minimum": 0, "maximum": 1 }, "format": { "type": "string" }, "organization_id": { "type": [ "string", "null" ], "minLength": 1, "description": "The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (`errorCode: billing_organization_mismatch`)." }, "encoding": { "type": "string", "enum": [ "binary", "base64" ] }, "preview": { "type": "boolean" } }, "required": [ "text" ], "example": { "text": "heavy wooden door creaking open", "durationSeconds": 3, "promptInfluence": 0.5 } }, "getMeResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tier": { "type": "string", "enum": [ "free", "basic", "pro", "other" ] }, "subscription": { "type": [ "object", "null" ], "properties": { "plan_name": { "type": "string" }, "price_id": { "type": "string" }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "current_period_ends_at": { "type": "string" } }, "required": [ "plan_name", "price_id", "interval", "current_period_ends_at" ] }, "credits": { "type": "object", "properties": { "balance": { "type": "number" } }, "required": [ "balance" ] }, "entitlements": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "tier", "subscription", "credits", "entitlements" ], "example": { "id": "507f1f77bcf86cd799439011", "name": "Ada Lovelace", "tier": "basic", "subscription": { "plan_name": "Professional", "price_id": "price_123", "interval": "monthly", "current_period_ends_at": "2026-10-18T00:00:00.000Z" }, "credits": { "balance": 31667 }, "entitlements": [ "base" ] } }, "getCreditBalanceResponse200": { "type": "object", "properties": { "balance": { "type": "number" } }, "required": [ "balance" ], "example": { "balance": 31667 } }, "listModelsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Pass as `model` on the generation endpoints." }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "image", "speech-to-text", "video" ] }, "backend": { "type": "string", "enum": [ "openai", "bedrock", "anthropic", "gemini", "ollama", "bfl", "xai", "kimi", "deepseek", "voyageai", "aws", "local-image" ], "description": "The provider that serves the model." }, "description": { "type": [ "string", "null" ] }, "context_window": { "type": "integer", "description": "Input context, in tokens." }, "max_output_tokens": { "type": "integer" }, "supports_streaming": { "type": "boolean" }, "supports_thinking": { "type": "boolean" }, "reasons_within_output_budget": { "type": "boolean", "description": "Whether reasoning tokens are spent inside `max_output_tokens` on every turn. When true, a small `max_tokens` can be used up by reasoning alone and return an empty reply, so leave room above the answer you expect." }, "reasoning_efforts": { "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] }, "description": "The `reasoningEffort` levels this model acts on, lowest first; empty when it ignores the option. `none` is listed only where it turns reasoning off. Each level is mapped to the nearest one the provider offers. A listed level can still be dropped on one request: some OpenAI models drop it on tool turns, and Claude models with a fixed thinking budget drop it when `max_tokens` leaves no room for the budget plus the answer." }, "supports_tools": { "type": "boolean" }, "supports_tool_search": { "type": "boolean", "description": "Whether the model accepts the tool search server tool and `defer_loading: true` on tool definitions, so a large tool catalog is searched on demand instead of loaded into context up front. Describes the model: `/api/ai/v1/completions` honours it only for models whose `backend` is `anthropic`. A `bedrock` model with this flag set is not served with tool search there yet: a `serverTool` entry is refused with `errorCode: \"tool_search_unsupported\"` and `defer_loading` is ignored." }, "supports_tool_changes": { "type": "boolean", "description": "Whether a system-role message can carry `tool_addition` and `tool_removal` blocks, which add or remove a declared tool mid-conversation. Describes the model only: `/api/ai/v1/completions` does not accept these blocks yet, and will accept them first for models whose `backend` is `anthropic`." }, "supports_vision": { "type": "boolean" }, "deprecation_date": { "type": [ "string", "null" ], "description": "`YYYY-MM-DD`; null when no retirement is scheduled." }, "replaced_by": { "type": [ "string", "null" ], "description": "The id of the recommended successor, when there is one." }, "image": { "type": [ "object", "null" ], "properties": { "sizing": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "presets" ] }, "presets": { "type": "array", "items": { "type": "string" }, "description": "Accepted `size` values, as `WxH`." }, "default_size": { "type": "string" } }, "required": [ "kind", "presets", "default_size" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "constrained" ] }, "presets": { "type": "array", "items": { "type": "string" }, "description": "Suggested `size` values; any `WxH` meeting `constraints` is accepted." }, "default_size": { "type": "string" }, "auto_size": { "type": "string", "description": "The `size` value that lets the provider choose." }, "constraints": { "type": "object", "properties": { "max_edge": { "type": "integer" }, "min_total_pixels": { "type": "integer" }, "max_total_pixels": { "type": "integer" }, "edge_multiple": { "type": "integer", "description": "Both edges must be a multiple of this." }, "max_aspect_ratio": { "type": "number", "description": "Longest edge divided by shortest edge." } }, "required": [ "max_edge", "min_total_pixels", "max_total_pixels", "edge_multiple", "max_aspect_ratio" ] } }, "required": [ "kind", "presets", "default_size", "auto_size", "constraints" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dimensions" ] }, "presets": { "type": "array", "items": { "type": "string" } }, "default_size": { "type": "string" }, "min_width": { "type": "integer" }, "max_width": { "type": "integer" }, "min_height": { "type": "integer" }, "max_height": { "type": "integer" }, "step": { "type": "integer", "description": "`width` and `height` are rounded to the nearest multiple of this." } }, "required": [ "kind", "presets", "default_size", "min_width", "max_width", "min_height", "max_height", "step" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "aspect_ratio" ], "description": "Takes an `aspect_ratio` such as `16:9`, not a `size`." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "input_image" ], "description": "Sized by the input image; takes no `size`." }, "aspect_ratio": { "type": "boolean", "description": "Whether an `aspect_ratio` override is honoured." } }, "required": [ "kind", "aspect_ratio" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "fixed" ], "description": "The provider takes no size at all." } }, "required": [ "kind" ] } ] }, "supports": { "type": "object", "properties": { "transparent_background": { "type": "boolean", "description": "`background: 'transparent'` yields real alpha." }, "seed": { "type": "boolean" }, "qualities": { "type": "array", "items": { "type": "string", "enum": [ "standard", "hd", "low", "medium", "high", "xhigh", "max", "auto" ] }, "description": "Accepted `quality` tiers; empty when none is taken." }, "max_images": { "type": "integer", "description": "Most images one request may ask for via `n`." }, "max_reference_images": { "type": "integer", "description": "Most `referenceImageFabFileIds` honoured; 0 when the model takes none." }, "edit": { "type": "boolean", "description": "Accepted by `POST /api/v1/image-edits`." }, "requires_input_image": { "type": "boolean" } }, "required": [ "transparent_background", "seed", "qualities", "max_images", "max_reference_images", "edit", "requires_input_image" ] } }, "required": [ "sizing", "supports" ], "description": "Size rules and supported parameters. Present on image models only; null for every other type." }, "credits_per_1m_tokens": { "type": [ "object", "null" ], "properties": { "input": { "type": "number", "description": "Credits per 1M input tokens." }, "output": { "type": "number", "description": "Credits per 1M output tokens." }, "cached_input": { "type": [ "number", "null" ], "description": "Credits per 1M input tokens served from the provider prompt cache. Null where cached tokens are not billed separately, so they cost the `input` rate." } }, "required": [ "input", "output", "cached_input" ], "description": "What a call is billed, in credits per 1M tokens, at the base context tier. Use it to compare models by cost. Null on non-text models and on any model with no published price; never 0 for an unpriced model." } }, "required": [ "id", "name", "type", "backend", "description", "context_window", "max_output_tokens", "supports_streaming", "supports_thinking", "reasons_within_output_budget", "reasoning_efforts", "supports_tools", "supports_tool_search", "supports_tool_changes", "supports_vision", "deprecation_date", "replaced_by", "image", "credits_per_1m_tokens" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "example": { "data": [ { "id": "claude-sonnet-5", "name": "Claude Sonnet 5", "type": "text", "backend": "anthropic", "description": null, "context_window": 1000000, "max_output_tokens": 128000, "supports_streaming": true, "supports_thinking": true, "reasons_within_output_budget": true, "reasoning_efforts": [ "none", "minimal", "low", "medium", "high", "xhigh" ], "supports_tools": true, "supports_tool_search": true, "supports_tool_changes": false, "supports_vision": true, "deprecation_date": null, "replaced_by": null, "image": null, "credits_per_1m_tokens": { "input": 6000, "output": 30000, "cached_input": 600 } }, { "id": "gpt-image-1", "name": "GPT Image 1", "type": "image", "backend": "openai", "description": null, "context_window": 0, "max_output_tokens": 0, "supports_streaming": false, "supports_thinking": false, "reasons_within_output_budget": false, "reasoning_efforts": [], "supports_tools": false, "supports_tool_search": false, "supports_tool_changes": false, "supports_vision": false, "deprecation_date": null, "replaced_by": null, "credits_per_1m_tokens": null, "image": { "sizing": { "kind": "presets", "presets": [ "1024x1024", "1024x1536", "1536x1024" ], "default_size": "1024x1024" }, "supports": { "transparent_background": true, "seed": false, "qualities": [ "low", "medium", "high", "auto" ], "max_images": 10, "max_reference_images": 15, "edit": true, "requires_input_image": false } } } ], "next_cursor": null } }, "generateImageResponse200": { "type": "object", "properties": { "quest": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "stopped", "running", "done" ] }, "type": { "type": "string", "enum": [ "message", "oob", "error", "system", "voice_transcript" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] }, "reply": { "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "type": "string" } }, "fallbackInfo": { "type": "object", "properties": { "primaryModel": { "type": "string" }, "primaryModelName": { "type": "string" }, "fallbackModel": { "type": "string" }, "fallbackModelName": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "primaryModel", "primaryModelName", "fallbackModel", "fallbackModelName" ] }, "sessionId": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "sessionId" ] }, "session": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "originalPrompt": { "type": "string" }, "enhancedPrompt": { "type": "string" }, "promptWasEnhanced": { "type": "boolean" }, "intent": { "type": "string", "enum": [ "fresh", "continuation" ] } }, "required": [ "quest", "session", "originalPrompt", "enhancedPrompt", "promptWasEnhanced", "intent" ] }, "generateImageResponse403": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route accepts. Holding any one of them satisfies it." }, "also_required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route also requires. Every one must be held, on top of `required_scopes`." }, "errorCode": { "type": "string", "enum": [ "billing_organization_mismatch" ] } }, "required": [ "error" ] }, "generateImageRequest": { "type": "object", "properties": { "prompt": { "type": "string" }, "model": { "anyOf": [ { "type": "string", "enum": [ "gpt-image-1", "gpt-image-1.5", "gpt-image-1-mini", "gpt-image-2", "gpt-image-2.5-sunburst", "gpt-image-2.5-flare", "flux-pro-1.1", "flux-pro", "flux-pro-1.1-ultra", "flux-pro-1.0-fill", "flux-kontext-pro", "flux-kontext-max", "grok-imagine-image-quality", "gemini-2.5-flash-image", "gemini-3-pro-image-preview", "gemini-3-pro-image", "gemini-3.1-flash-image" ] }, { "type": "string", "pattern": "^local-image\\/(?=.*\\S)[\\w.:/ -]+$" } ] }, "n": { "type": "number", "minimum": 1, "maximum": 10 }, "quality": { "type": "string", "enum": [ "standard", "hd", "low", "medium", "high", "xhigh", "max", "auto" ] }, "response_format": { "type": "string", "enum": [ "b64_json", "url" ] }, "size": { "anyOf": [ { "type": "string", "enum": [ "1024x1024", "1024x1536", "1536x1024", "2048x2048", "2048x1152", "3840x2160", "2160x3840", "auto", "1024x768" ] }, { "type": "string", "pattern": "^\\d+x\\d+$" }, { "type": "null" } ] }, "style": { "type": "string", "enum": [ "vivid", "natural" ] }, "background": { "type": [ "string", "null" ], "enum": [ "transparent", "opaque", "auto", null ] }, "width": { "type": "number" }, "height": { "type": "number" }, "aspect_ratio": { "type": "string" }, "sessionId": { "type": "string" }, "questId": { "type": "string" }, "organizationId": { "type": [ "string", "null" ], "minLength": 1, "description": "The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (`errorCode: billing_organization_mismatch`)." }, "fabFileIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "referenceImageFabFileIds": { "type": "array", "items": { "type": "string" }, "maxItems": 15 }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "dice_roll", "image_generation", "edit_image", "music_generation", "audio_generation", "video_generation", "weather_info", "web_search", "web_fetch", "wolfram_alpha", "math_evaluate", "mermaid_chart", "current_datetime", "deep_research", "prompt_enhancement", "recharts", "edit_file", "blog_publish", "blog_edit", "blog_draft", "wikipedia_on_this_day", "moon_phase", "sunrise_sunset", "iss_tracker", "planet_visibility", "search_knowledge_base", "chess_engine", "retrieve_knowledge_content", "count_knowledge_base", "describe_knowledge_base", "list_my_data_lakes", "create_data_lake", "save_content_to_data_lake", "delegate_to_agent", "optihashi_schedule", "optihashi_formulate", "optihashi_edit_problem", "navigate_view", "generate_jupyter_notebook", "excel_generation", "fmp_financial_data", "bob_panel_read", "skill" ] }, { "type": "string" } ] } }, "safety_tolerance": { "type": "number", "minimum": 0, "maximum": 6, "default": 2 }, "prompt_upsampling": { "type": "boolean" }, "seed": { "type": [ "number", "null" ] }, "output_format": { "type": [ "string", "null" ], "enum": [ "png", "jpeg", "webp", null ] }, "sessionName": { "type": "string" }, "organization_id": { "type": [ "string", "null" ], "minLength": 1, "description": "Alias of `organizationId`, for callers used to the snake_case video and music bodies. Sending both with different values is a 422." }, "callbackUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Optional https URL that receives one signed POST when the job settles (success or failure). Requires API-key authentication and a callback signing secret on that key. The body is the GET /api/v1/quests/{id} response. Verify it with the `X-Webhook-Signature-256` header: `sha256=` + hex HMAC-SHA256 of `.` keyed with the signing secret. Polling keeps working either way." }, "projectId": { "type": "string" }, "prompt_resolution": { "type": "string", "enum": [ "auto", "literal" ], "description": "How the prompt is treated before it reaches the image model. `\"auto\"` (the default) resolves it against the session history, so a follow-up such as \"make it darker\" is rewritten to carry the previous subject and the prior image is fed back as input. `\"literal\"` skips that step: the prompt is sent unchanged (apart from truncation to the model's prompt limit), `intent` is `\"fresh\"`, `promptWasEnhanced` is `false`, and a prior session image is carried forward only for models that cannot run without an input image. Use `\"literal\"` when the prompt is already self-contained, for example when an agent or pipeline builds it." } }, "required": [ "prompt", "model" ], "example": { "prompt": "a watercolor lighthouse at dusk", "model": "gpt-image-1", "size": "1024x1024" } }, "editImageResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "stopped", "running", "done" ] }, "type": { "type": "string", "enum": [ "message", "oob", "error", "system", "voice_transcript" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] }, "reply": { "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "type": "string" } }, "fallbackInfo": { "type": "object", "properties": { "primaryModel": { "type": "string" }, "primaryModelName": { "type": "string" }, "fallbackModel": { "type": "string" }, "fallbackModelName": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "primaryModel", "primaryModelName", "fallbackModel", "fallbackModelName" ] }, "sessionId": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "sessionId" ] }, "editImageResponse403": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route accepts. Holding any one of them satisfies it." }, "also_required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route also requires. Every one must be held, on top of `required_scopes`." }, "errorCode": { "type": "string", "enum": [ "billing_organization_mismatch" ] } }, "required": [ "error" ] }, "editImageRequest": { "type": "object", "properties": { "prompt": { "type": "string" }, "model": { "anyOf": [ { "type": "string", "enum": [ "gpt-image-1", "gpt-image-1.5", "gpt-image-1-mini", "gpt-image-2", "gpt-image-2.5-sunburst", "gpt-image-2.5-flare", "flux-pro-1.1", "flux-pro", "flux-pro-1.1-ultra", "flux-pro-1.0-fill", "flux-kontext-pro", "flux-kontext-max", "grok-imagine-image-quality", "gemini-2.5-flash-image", "gemini-3-pro-image-preview", "gemini-3-pro-image", "gemini-3.1-flash-image" ] }, { "type": "string", "pattern": "^local-image\\/(?=.*\\S)[\\w.:/ -]+$" } ] }, "n": { "type": "number", "minimum": 1, "maximum": 10 }, "quality": { "type": "string", "enum": [ "standard", "hd", "low", "medium", "high", "xhigh", "max", "auto" ] }, "response_format": { "type": "string", "enum": [ "b64_json", "url" ] }, "size": { "anyOf": [ { "type": "string", "enum": [ "1024x1024", "1024x1536", "1536x1024", "2048x2048", "2048x1152", "3840x2160", "2160x3840", "auto", "1024x768" ] }, { "type": "string", "pattern": "^\\d+x\\d+$" }, { "type": "null" } ] }, "style": { "type": "string", "enum": [ "vivid", "natural" ] }, "background": { "type": [ "string", "null" ], "enum": [ "transparent", "opaque", "auto", null ] }, "width": { "type": "number" }, "height": { "type": "number" }, "aspect_ratio": { "type": "string" }, "sessionId": { "type": "string" }, "questId": { "type": "string" }, "organizationId": { "type": [ "string", "null" ], "minLength": 1, "description": "The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (`errorCode: billing_organization_mismatch`)." }, "organization_id": { "type": [ "string", "null" ], "minLength": 1, "description": "Alias of `organizationId`, for callers used to the snake_case video and music bodies. Sending both with different values is a 422." }, "fabFileIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "referenceImageFabFileIds": { "type": "array", "items": { "type": "string" }, "maxItems": 15 }, "image": { "type": "string" }, "output_format": { "type": [ "string", "null" ], "enum": [ "png", "jpeg", "webp", null ] }, "seed": { "type": [ "number", "null" ] }, "callbackUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Optional https URL that receives one signed POST when the job settles (success or failure). Requires API-key authentication and a callback signing secret on that key. The body is the GET /api/v1/quests/{id} response. Verify it with the `X-Webhook-Signature-256` header: `sha256=` + hex HMAC-SHA256 of `.` keyed with the signing secret. Polling keeps working either way." } }, "required": [ "prompt", "model", "sessionId", "image" ], "example": { "prompt": "replace the sky with a starry night", "model": "gpt-image-1", "sessionId": "664f1c2b9a1e4d0012ab34aa", "image": "https://example.com/source.png", "fabFileIds": [ "664f1c2b9a1e4d0012ab34bb" ] } }, "createFileUploadResponse201": { "type": "object", "properties": { "id": { "type": "string" }, "upload_url": { "type": "string" }, "upload_url_expires_at": { "type": "string" } }, "required": [ "id", "upload_url", "upload_url_expires_at" ], "example": { "id": "", "upload_url": "https://.s3.amazonaws.com/?X-Amz-Signature=...", "upload_url_expires_at": "2026-09-29T12:10:00.000Z" } }, "createFileUploadResponse400": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "storage_limit_exceeded", "org_storage_limit_exceeded", "file_too_large" ], "description": "Stable refusal code: `storage_limit_exceeded` (your total storage), `org_storage_limit_exceeded` (the organization limit), or `file_too_large` (the per-file size limit). Branch on this, not on the message." }, "used_bytes": { "type": "number", "minimum": 0, "description": "Bytes already stored against the limit. 0 for `org_storage_limit_exceeded` and `file_too_large`." }, "limit_bytes": { "type": "number", "minimum": 0, "description": "The limit, in bytes, that the request ran into." }, "requested_bytes": { "type": "number", "minimum": 0, "description": "Size of the refused upload, in bytes." }, "owner": { "type": "string", "enum": [ "user", "org" ], "description": "Whose limit was hit: `user` or `org`. Always `user` for `file_too_large`, a platform-wide cap." } }, "required": [ "error" ] }, "createFileUploadRequest": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1 }, "mime_type": { "type": "string", "minLength": 1 }, "file_size": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "file_name", "mime_type", "file_size" ], "example": { "file_name": "reference.png", "mime_type": "image/png", "file_size": 482133 } }, "getFileResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "file_size": { "type": "number" }, "moderation_status": { "type": [ "string", "null" ], "enum": [ "pending", "scanning", "clean", "blocked", null ] }, "download_url": { "type": [ "string", "null" ] }, "download_url_expires_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "file_name", "mime_type", "file_size", "moderation_status", "download_url", "download_url_expires_at", "created_at" ], "example": { "id": "", "file_name": "reference.png", "mime_type": "image/png", "file_size": 482133, "moderation_status": "clean", "download_url": "https:///?Signature=...", "download_url_expires_at": "2026-09-30T12:00:00.000Z", "created_at": "2026-09-29T12:00:00.000Z" } }, "listFilesResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "file_size": { "type": "number" }, "moderation_status": { "type": [ "string", "null" ], "enum": [ "pending", "scanning", "clean", "blocked", null ] }, "created_at": { "type": "string" } }, "required": [ "id", "file_name", "mime_type", "file_size", "moderation_status", "created_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "example": { "data": [ { "id": "", "file_name": "reference.png", "mime_type": "image/png", "file_size": 482133, "moderation_status": "clean", "created_at": "2026-09-29T12:00:00.000Z" } ], "next_cursor": null } }, "updateFileResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "file_size": { "type": "number" }, "moderation_status": { "type": [ "string", "null" ], "enum": [ "pending", "scanning", "clean", "blocked", null ] }, "created_at": { "type": "string" } }, "required": [ "id", "file_name", "mime_type", "file_size", "moderation_status", "created_at" ] }, "updateFileRequest": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "notes": { "type": "string", "maxLength": 10000 } }, "additionalProperties": false, "example": { "file_name": "q3-notes.pdf" } }, "createEmbeddingsResponse200": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "index": { "type": "integer" }, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] } }, "required": [ "object", "index", "embedding" ] } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "required": [ "prompt_tokens", "total_tokens" ] } }, "required": [ "object", "data", "model", "usage" ], "example": { "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [ 0.0023, -0.0093, 0.0158 ] }, { "object": "embedding", "index": 1, "embedding": [ -0.0112, 0.0047, 0.0201 ] } ], "model": "text-embedding-3-small", "usage": { "prompt_tokens": 9, "total_tokens": 9 } } }, "createEmbeddingsResponse401": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "createEmbeddingsResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "createEmbeddingsResponse503": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected" ] } }, "required": [ "error" ] }, "createEmbeddingsRequest": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "text-embedding-3-small", "text-embedding-3-large", "text-embedding-ada-002" ] }, { "type": "string", "enum": [ "voyage-3-large", "voyage-3", "voyage-3-lite", "voyage-code-3", "voyage-finance-3", "voyage-law-3" ] }, { "type": "string", "enum": [ "amazon.titan-embed-text-v2:0" ] }, { "type": "string", "enum": [ "qwen3-embedding:0.6b", "qwen3-embedding:4b", "qwen3-embedding:8b", "nomic-embed-text", "mxbai-embed-large", "bge-m3", "snowflake-arctic-embed" ] } ] }, "input": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 2048 } ] }, "dimensions": { "type": "integer", "exclusiveMinimum": 0 }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "default": "float" } }, "required": [ "model", "input" ], "example": { "model": "text-embedding-3-small", "input": [ "The quick brown fox", "jumps over the lazy dog" ], "dimensions": 1024 } }, "createDecisionResponse200": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique per decision." }, "object": { "type": "string", "enum": [ "decision" ] }, "model": { "type": "string", "description": "The resolved model version. Pin it when you tune thresholds." }, "answers": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "predicate" ] }, "name": { "type": "string" }, "probability": { "type": "number", "minimum": 0, "maximum": 1, "description": "Probability that the statement is true." } }, "required": [ "type", "name", "probability" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "choice" ] }, "name": { "type": "string" }, "choice": { "type": "string", "description": "The most probable value." }, "probabilities": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "probability": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "value", "probability" ] }, "description": "In request order." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "(n * p_max - 1) / (n - 1), computed by B4M for every model." } }, "required": [ "type", "name", "choice", "probabilities", "confidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "score" ] }, "name": { "type": "string" }, "score": { "type": "number", "description": "Probability-weighted mean of the 0-based level indices." }, "probabilities": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "integer" }, "label": { "type": "string" }, "probability": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "value", "label", "probability" ] }, "description": "In level order; value is the level index." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Distance-aware: 1 - sum(p_i * |i - peak|) / mean_i(|i - (n-1)/2|)." } }, "required": [ "type", "name", "score", "probabilities", "confidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "name": { "type": "string" } }, "required": [ "type", "name" ] } ] }, "description": "One per question, in question order." }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ] } }, "required": [ "id", "object", "model", "answers", "usage" ], "example": { "id": "dec_8f14e45fceea167a5a36dedd4bea2543", "object": "decision", "model": "gpt-6-luna", "answers": [ { "type": "predicate", "name": "is_urgent", "probability": 0.93 }, { "type": "choice", "name": "team", "choice": "billing", "probabilities": [ { "value": "billing", "probability": 0.88 }, { "value": "technical", "probability": 0.1 }, { "value": "sales", "probability": 0.02 } ], "confidence": 0.82 }, { "type": "score", "name": "frustration", "score": 1.1, "probabilities": [ { "value": 0, "label": "calm", "probability": 0.1 }, { "value": 1, "label": "frustrated", "probability": 0.7 }, { "value": 2, "label": "angry", "probability": 0.2 } ], "confidence": 0.55 } ], "usage": { "input_tokens": 412, "output_tokens": 0, "total_tokens": 412 } } }, "createDecisionResponse401": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected", "provider_overloaded", "provider_error", "context_length_exceeded", "limit_exceeded", "unsupported_input", "invalid_request", "model_unavailable", "input_image_not_found" ] }, "param": { "type": "string", "description": "Path of the offending field, e.g. questions[1].choices." } }, "required": [ "error" ] }, "createDecisionResponse404": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected", "provider_overloaded", "provider_error", "context_length_exceeded", "limit_exceeded", "unsupported_input", "invalid_request", "model_unavailable", "input_image_not_found" ] }, "param": { "type": "string", "description": "Path of the offending field, e.g. questions[1].choices." } }, "required": [ "error" ] }, "createDecisionResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected", "provider_overloaded", "provider_error", "context_length_exceeded", "limit_exceeded", "unsupported_input", "invalid_request", "model_unavailable", "input_image_not_found" ] }, "param": { "type": "string", "description": "Path of the offending field, e.g. questions[1].choices." } }, "required": [ "error" ] }, "createDecisionResponse502": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected", "provider_overloaded", "provider_error", "context_length_exceeded", "limit_exceeded", "unsupported_input", "invalid_request", "model_unavailable", "input_image_not_found" ] }, "param": { "type": "string", "description": "Path of the offending field, e.g. questions[1].choices." } }, "required": [ "error" ] }, "createDecisionResponse503": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "provider_not_configured", "provider_rejected", "provider_overloaded", "provider_error", "context_length_exceeded", "limit_exceeded", "unsupported_input", "invalid_request", "model_unavailable", "input_image_not_found" ] }, "param": { "type": "string", "description": "Path of the offending field, e.g. questions[1].choices." } }, "required": [ "error" ] }, "createDecisionRequest": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 128, "description": "A decision model id from `GET /api/v1/decision-models`." }, "input": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 262144 }, { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 262144 } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json" ] }, "json": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ], "description": "Structured state. Sent natively to models that accept it, otherwise serialized to text." } }, "required": [ "type", "json" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "file_id": { "type": "string", "minLength": 1, "description": "A Files entry the caller can read. Exactly one of file_id or image_url." }, "image_url": { "type": "string", "pattern": "^data:image\\/(png|jpeg|webp|gif);base64,[A-Za-z0-9+/]+={0,2}$", "description": "A base64 data: URL. http(s) URLs are rejected; upload the image and pass file_id instead." } }, "required": [ "type" ], "additionalProperties": false } ] }, "minItems": 1 } ] }, "questions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "predicate" ] }, "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Unique within the request; answers carry it back." }, "instructions": { "type": "string", "minLength": 1, "maxLength": 262144, "description": "A statement to judge true or false against the input." } }, "required": [ "type", "name", "instructions" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "choice" ] }, "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Unique within the request; answers carry it back." }, "instructions": { "type": "string", "minLength": 1, "maxLength": 262144 }, "choices": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "value" ], "additionalProperties": false }, "minItems": 2, "maxItems": 64 } }, "required": [ "type", "name", "instructions", "choices" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "score" ] }, "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Unique within the request; answers carry it back." }, "instructions": { "type": "string", "minLength": 1, "maxLength": 262144 }, "levels": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "label" ], "additionalProperties": false }, "minItems": 2, "maxItems": 10, "description": "Ordered lowest to highest; the answer score is a 0-based index into this list." } }, "required": [ "type", "name", "instructions", "levels" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 50 }, "safety_identifier": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A stable, non-identifying id for your end user. Defaults to a hash of the B4M user id." } }, "required": [ "model", "input", "questions" ], "additionalProperties": false, "example": { "model": "gpt-6-luna", "input": [ { "type": "text", "text": "Help! My payouts have been failing for 3 days." }, { "type": "json", "json": { "plan": "pro", "open_tickets": 2 } } ], "questions": [ { "type": "predicate", "name": "is_urgent", "instructions": "The customer needs a reply within 24 hours." }, { "type": "choice", "name": "team", "instructions": "Which team should handle this?", "choices": [ { "value": "billing", "description": "Payments, payouts, refunds" }, { "value": "technical", "description": "Bugs, outages" }, { "value": "sales" } ] }, { "type": "score", "name": "frustration", "instructions": "How frustrated is the customer?", "levels": [ { "label": "calm" }, { "label": "frustrated" }, { "label": "angry", "description": "Threatens to churn" } ] } ] } }, "listDecisionModelsResponse200": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "decision_model" ] }, "display_name": { "type": "string" }, "provider": { "type": "string" }, "alias_of": { "type": [ "string", "null" ], "description": "Set on a floating alias; pin the versioned id to keep thresholds stable." }, "supports_images": { "type": "boolean" }, "limits": { "type": "object", "properties": { "max_questions": { "type": "integer" }, "max_choices": { "type": "integer" }, "max_levels": { "type": "integer" }, "max_images": { "type": "integer" }, "max_input_tokens": { "type": "integer" } }, "required": [ "max_questions", "max_choices", "max_levels", "max_images", "max_input_tokens" ] }, "pricing": { "type": "object", "properties": { "usd_per_million_input_tokens": { "type": "number" }, "usd_per_million_output_tokens": { "type": "number" } }, "required": [ "usd_per_million_input_tokens", "usd_per_million_output_tokens" ] } }, "required": [ "id", "object", "display_name", "provider", "alias_of", "supports_images", "limits", "pricing" ] } } }, "required": [ "models" ] }, "getQuestResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "stopped" ] }, "type": { "type": "string", "enum": [ "message", "oob", "error", "system", "voice_transcript" ] }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] }, "reply": { "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "type": "string" } }, "fallbackInfo": { "type": "object", "properties": { "primaryModel": { "type": "string" }, "primaryModelName": { "type": "string" }, "fallbackModel": { "type": "string" }, "fallbackModelName": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "primaryModel", "primaryModelName", "fallbackModel", "fallbackModelName" ] }, "sessionId": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "description": "Presigned download URL. Short-lived (about an hour): fetch it promptly, do not store it." }, "isImage": { "type": "boolean" }, "isAudio": { "type": "boolean" }, "isVideo": { "type": "boolean" } }, "required": [ "name", "url", "isImage", "isAudio", "isVideo" ] } }, "toolPayloads": { "type": "array", "items": {} }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "promptMeta": { "type": "object", "additionalProperties": {} }, "attachmentNotices": { "type": "array", "items": { "type": "string" } }, "attachmentDelivery": { "type": "object", "additionalProperties": {} }, "executionTracking": {} }, "required": [ "id", "sessionId", "images", "videos", "files", "toolPayloads" ] }, "listQuestFilesResponse200": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "file_size": { "type": "number" }, "moderation_status": { "type": [ "string", "null" ], "enum": [ "pending", "scanning", "clean", "blocked", null ] }, "download_url": { "type": [ "string", "null" ] }, "download_url_expires_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "file_name", "mime_type", "file_size", "moderation_status", "download_url", "download_url_expires_at", "created_at" ] } } }, "required": [ "files" ], "example": { "files": [ { "id": "", "file_name": "chart.png", "mime_type": "image/png", "file_size": 482133, "moderation_status": "clean", "download_url": "https:///?Signature=...", "download_url_expires_at": "2026-10-09T13:00:00.000Z", "created_at": "2026-10-09T12:00:00.000Z" } ] } }, "createSessionResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "_id": { "type": "string" }, "name": { "type": "string" }, "userId": { "type": "string" }, "knowledgeIds": { "type": "array", "items": { "type": "string" } }, "artifactIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "name", "strength" ] } }, "forceKnowledgeRetrieval": { "type": "boolean" }, "retrievalTags": { "type": "array", "items": { "type": "string" } }, "lakeScopeExplicit": { "type": "boolean", "description": "True when `retrievalTags` is a deliberate choice, so an empty list means \"no lake\" rather than \"any\"." }, "includeLibraryFiles": { "type": "boolean", "description": "Whether the session grounds on your own library alongside its lakes. Absent when never set." }, "lastUsedModel": { "type": [ "string", "null" ] }, "firstCreated": { "type": "string", "format": "date-time" }, "lastUpdated": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "userId", "firstCreated", "lastUpdated" ] }, "createSessionRequest": { "type": "object", "properties": { "name": { "type": "string" }, "projectId": { "type": "string", "description": "Adds the new session to this project." }, "dataLakeId": { "type": [ "string", "null" ], "description": "Seeds retrieval defaults from this data lake and turns on forced retrieval. Get ids from `GET /api/v1/data-lakes`." }, "preauthorizedLakeIds": { "description": "Data lakes the caller manages, armed for this session. At most 10; requires management rights." }, "knowledgeIds": { "type": "array", "items": { "type": "string" } }, "artifactIds": { "type": "array", "items": { "type": "string" } }, "agentIds": { "type": "array", "items": { "type": "string" } }, "systemPromptText": { "type": "string", "description": "Write-only: never returned in a session response." }, "systemPromptId": { "type": "string" }, "surface": { "type": "string" }, "enabledTools": { "type": "array", "items": { "type": "string" } }, "disabledTools": { "type": "array", "items": { "type": "string" } }, "disableUserIntegrations": { "type": "boolean" }, "forceKnowledgeRetrieval": { "type": "boolean" }, "retrievalTags": { "type": "array", "items": { "type": "string" } }, "lakeScopeExplicit": { "type": "boolean" }, "includeLibraryFiles": { "type": "boolean" }, "corpusGroundingMode": { "type": "string", "enum": [ "inline", "retrieve", "auto-by-size" ], "description": "Honored only when a lake is named by `retrievalTags` without `dataLakeId`." }, "retrievalExcludeFilenameMarkers": { "type": "array", "items": { "type": "string" } }, "retrievalVectorizedOnly": { "type": "boolean" }, "citationStyle": { "type": "string", "enum": [ "named", "indexed" ] }, "temperature": { "type": "number" }, "maxToolCalls": { "type": "integer", "exclusiveMinimum": 0 }, "autoNamePlaceholder": { "type": "string" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "name", "strength" ] } }, "lastUsedModel": { "type": [ "string", "null" ] } }, "required": [ "name" ], "example": { "name": "Quarterly analysis" } }, "listSessionsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "_id": { "type": "string" }, "name": { "type": "string" }, "userId": { "type": "string" }, "knowledgeIds": { "type": "array", "items": { "type": "string" } }, "artifactIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "name", "strength" ] } }, "forceKnowledgeRetrieval": { "type": "boolean" }, "retrievalTags": { "type": "array", "items": { "type": "string" } }, "lakeScopeExplicit": { "type": "boolean", "description": "True when `retrievalTags` is a deliberate choice, so an empty list means \"no lake\" rather than \"any\"." }, "includeLibraryFiles": { "type": "boolean", "description": "Whether the session grounds on your own library alongside its lakes. Absent when never set." }, "lastUsedModel": { "type": [ "string", "null" ] }, "firstCreated": { "type": "string", "format": "date-time" }, "lastUpdated": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "userId", "firstCreated", "lastUpdated" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "listDataLakesResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "datalake_tag": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "string", "null" ] }, "is_public": { "type": "boolean" }, "built_in": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "active", "archiving", "archived", "unarchiving", "restoring", "deleting", "deleted", "purging" ] }, "file_count": { "type": "integer", "minimum": 0 }, "total_size_bytes": { "type": "number", "minimum": 0 }, "last_sync_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "datalake_tag", "description", "organization_id", "is_public", "built_in", "status", "file_count", "total_size_bytes", "last_sync_at", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "getDataLakeResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "datalake_tag": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "string", "null" ] }, "is_public": { "type": "boolean" }, "built_in": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "active", "archiving", "archived", "unarchiving", "restoring", "deleting", "deleted", "purging" ] }, "file_count": { "type": "integer", "minimum": 0 }, "total_size_bytes": { "type": "number", "minimum": 0 }, "last_sync_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "datalake_tag", "description", "organization_id", "is_public", "built_in", "status", "file_count", "total_size_bytes", "last_sync_at", "created_at", "updated_at" ] }, "getDataLakeFileResponse200": { "type": "object", "properties": { "lake_id": { "type": "string" }, "file_id": { "type": "string" }, "file_name": { "type": "string" }, "ingestion_status": { "type": "string", "enum": [ "not_ingested", "indexing", "paused", "ready", "failed" ] }, "chunk_count": { "type": "integer", "minimum": 0 }, "vectorized_chunk_count": { "type": "integer", "minimum": 0 }, "error": { "type": [ "string", "null" ] } }, "required": [ "lake_id", "file_id", "file_name", "ingestion_status", "chunk_count", "vectorized_chunk_count", "error" ] }, "addDataLakeFileResponse200": { "type": "object", "properties": { "lake_id": { "type": "string" }, "file_id": { "type": "string" }, "file_count": { "type": "integer", "minimum": 0 }, "total_size_bytes": { "type": "number", "minimum": 0 } }, "required": [ "lake_id", "file_id", "file_count", "total_size_bytes" ] }, "removeDataLakeFileResponse200": { "type": "object", "properties": { "lake_id": { "type": "string" }, "file_id": { "type": "string" }, "file_count": { "type": "integer", "minimum": 0 }, "total_size_bytes": { "type": "number", "minimum": 0 } }, "required": [ "lake_id", "file_id", "file_count", "total_size_bytes" ] }, "searchDataLakeResponse200": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "chunk_id": { "type": "string" }, "file_id": { "type": "string" }, "file_name": { "type": "string" }, "chunk_text": { "type": "string" }, "score": { "type": "number" } }, "required": [ "chunk_id", "file_id", "file_name", "chunk_text", "score" ] } }, "embedding_model": { "type": "string" }, "partial_results": { "type": "boolean" }, "retrieval_unavailable": { "type": "object", "properties": { "indexing_files": { "type": "integer", "minimum": 0 }, "paused_files": { "type": "integer", "minimum": 0 } }, "required": [ "indexing_files", "paused_files" ] } }, "required": [ "results", "embedding_model", "partial_results", "retrieval_unavailable" ] }, "searchDataLakeResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] } }, "required": [ "error" ] }, "searchDataLakeResponse503": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "provider_not_configured" ] } }, "required": [ "error" ] }, "searchDataLakeRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 4000 }, "top_k": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "min_score": { "type": "number", "minimum": -1, "maximum": 1, "default": 0 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 130 }, "maxItems": 100 } }, "required": [ "query" ], "example": { "query": "What is our refund policy for annual plans?", "top_k": 5 } }, "cancelVideoGenerationResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "video_generation" ] }, "state": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "model": { "type": "string" }, "mode": { "type": "string", "enum": [ "text_to_video", "image_to_video" ] }, "prompt": { "type": "string" }, "duration_seconds": { "type": "number" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9" ] }, "resolution": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ] }, "source": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "content_blocked", "provider_timeout", "provider_error", "region_unavailable", "output_too_large", "input_image_not_found", "cancelled" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "output": { "type": [ "object", "null" ], "properties": { "availability": { "type": "string", "enum": [ "ready", "pending_scan", "unavailable" ], "description": "`ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling." }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null." }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601. When url stops working; null whenever url is." }, "content_type": { "type": "string" }, "duration_seconds": { "type": "number" }, "file_id": { "type": [ "string", "null" ], "description": "The Files entry, or null when the clip was stored outside Files." } }, "required": [ "availability", "url", "expires_at", "content_type", "duration_seconds", "file_id" ] }, "credits": { "type": "object", "properties": { "reserved": { "type": [ "number", "null" ] }, "settled": { "type": [ "number", "null" ] } }, "required": [ "reserved", "settled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "state", "model", "mode", "prompt", "duration_seconds", "aspect_ratio", "resolution", "source", "progress", "error", "output", "credits", "created_at", "updated_at" ], "example": { "id": "664f1c2b9a1e4d0012ab34cd", "object": "video_generation", "state": "pending", "model": "grok-imagine-video-1.5", "mode": "text_to_video", "prompt": "A slow dolly shot of a red lighthouse at dusk", "duration_seconds": 6, "aspect_ratio": "16:9", "resolution": "480p", "source": "api", "progress": null, "error": null, "output": null, "credits": { "reserved": 960, "settled": null }, "created_at": "2026-10-06T00:00:00.000Z", "updated_at": "2026-10-06T00:00:00.000Z" } }, "createVideoGenerationResponse202": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "video_generation" ] }, "state": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "model": { "type": "string" }, "mode": { "type": "string", "enum": [ "text_to_video", "image_to_video" ] }, "prompt": { "type": "string" }, "duration_seconds": { "type": "number" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9" ] }, "resolution": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ] }, "source": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "content_blocked", "provider_timeout", "provider_error", "region_unavailable", "output_too_large", "input_image_not_found", "cancelled" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "output": { "type": [ "object", "null" ], "properties": { "availability": { "type": "string", "enum": [ "ready", "pending_scan", "unavailable" ], "description": "`ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling." }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null." }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601. When url stops working; null whenever url is." }, "content_type": { "type": "string" }, "duration_seconds": { "type": "number" }, "file_id": { "type": [ "string", "null" ], "description": "The Files entry, or null when the clip was stored outside Files." } }, "required": [ "availability", "url", "expires_at", "content_type", "duration_seconds", "file_id" ] }, "credits": { "type": "object", "properties": { "reserved": { "type": [ "number", "null" ] }, "settled": { "type": [ "number", "null" ] } }, "required": [ "reserved", "settled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "state", "model", "mode", "prompt", "duration_seconds", "aspect_ratio", "resolution", "source", "progress", "error", "output", "credits", "created_at", "updated_at" ], "example": { "id": "664f1c2b9a1e4d0012ab34cd", "object": "video_generation", "state": "pending", "model": "grok-imagine-video-1.5", "mode": "text_to_video", "prompt": "A slow dolly shot of a red lighthouse at dusk", "duration_seconds": 6, "aspect_ratio": "16:9", "resolution": "480p", "source": "api", "progress": null, "error": null, "output": null, "credits": { "reserved": 960, "settled": null }, "created_at": "2026-10-06T00:00:00.000Z", "updated_at": "2026-10-06T00:00:00.000Z" } }, "createVideoGenerationResponse403": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route accepts. Holding any one of them satisfies it." }, "also_required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route also requires. Every one must be held, on top of `required_scopes`." }, "errorCode": { "type": "string", "enum": [ "billing_organization_mismatch" ] } }, "required": [ "error" ] }, "createVideoGenerationResponse404": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "unsupported_duration", "unsupported_aspect_ratio", "unsupported_resolution", "unsupported_mode", "missing_input_image", "unexpected_input_image", "unsupported_audio_option", "invalid_request", "model_disabled", "model_unavailable", "insufficient_credits", "input_image_not_found", "idempotency_key_reused", "invalid_idempotency_key" ] } }, "required": [ "error" ] }, "createVideoGenerationResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "unsupported_duration", "unsupported_aspect_ratio", "unsupported_resolution", "unsupported_mode", "missing_input_image", "unexpected_input_image", "unsupported_audio_option", "invalid_request", "model_disabled", "model_unavailable", "insufficient_credits", "input_image_not_found", "idempotency_key_reused", "invalid_idempotency_key" ] } }, "required": [ "error" ] }, "createVideoGenerationRequest": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "description": "A model id from GET /api/v1/video-models." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "mode": { "type": "string", "enum": [ "text_to_video", "image_to_video" ], "description": "Defaults to image_to_video when input_image_file_id is set, else text_to_video." }, "duration_seconds": { "type": "number", "exclusiveMinimum": 0, "description": "Defaults to the model's default duration." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9" ] }, "resolution": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ] }, "input_image_file_id": { "type": "string", "minLength": 1, "description": "An image file you own, for image_to_video." }, "audio": { "type": "boolean" }, "organization_id": { "type": [ "string", "null" ], "minLength": 1, "description": "The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (`errorCode: billing_organization_mismatch`)." } }, "required": [ "model", "prompt" ], "additionalProperties": false, "example": { "model": "grok-imagine-video-1.5", "prompt": "A slow dolly shot of a red lighthouse at dusk" } }, "getVideoGenerationResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "video_generation" ] }, "state": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "model": { "type": "string" }, "mode": { "type": "string", "enum": [ "text_to_video", "image_to_video" ] }, "prompt": { "type": "string" }, "duration_seconds": { "type": "number" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9" ] }, "resolution": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ] }, "source": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "content_blocked", "provider_timeout", "provider_error", "region_unavailable", "output_too_large", "input_image_not_found", "cancelled" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "output": { "type": [ "object", "null" ], "properties": { "availability": { "type": "string", "enum": [ "ready", "pending_scan", "unavailable" ], "description": "`ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling." }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null." }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601. When url stops working; null whenever url is." }, "content_type": { "type": "string" }, "duration_seconds": { "type": "number" }, "file_id": { "type": [ "string", "null" ], "description": "The Files entry, or null when the clip was stored outside Files." } }, "required": [ "availability", "url", "expires_at", "content_type", "duration_seconds", "file_id" ] }, "credits": { "type": "object", "properties": { "reserved": { "type": [ "number", "null" ] }, "settled": { "type": [ "number", "null" ] } }, "required": [ "reserved", "settled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "state", "model", "mode", "prompt", "duration_seconds", "aspect_ratio", "resolution", "source", "progress", "error", "output", "credits", "created_at", "updated_at" ], "example": { "id": "664f1c2b9a1e4d0012ab34cd", "object": "video_generation", "state": "pending", "model": "grok-imagine-video-1.5", "mode": "text_to_video", "prompt": "A slow dolly shot of a red lighthouse at dusk", "duration_seconds": 6, "aspect_ratio": "16:9", "resolution": "480p", "source": "api", "progress": null, "error": null, "output": null, "credits": { "reserved": 960, "settled": null }, "created_at": "2026-10-06T00:00:00.000Z", "updated_at": "2026-10-06T00:00:00.000Z" } }, "listVideoGenerationsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "video_generation" ] }, "state": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "model": { "type": "string" }, "mode": { "type": "string", "enum": [ "text_to_video", "image_to_video" ] }, "prompt": { "type": "string" }, "duration_seconds": { "type": "number" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9" ] }, "resolution": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ] }, "source": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "progress": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "content_blocked", "provider_timeout", "provider_error", "region_unavailable", "output_too_large", "input_image_not_found", "cancelled" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "output": { "type": [ "object", "null" ], "properties": { "availability": { "type": "string", "enum": [ "ready", "pending_scan", "unavailable" ], "description": "`ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling." }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null." }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601. When url stops working; null whenever url is." }, "content_type": { "type": "string" }, "duration_seconds": { "type": "number" }, "file_id": { "type": [ "string", "null" ], "description": "The Files entry, or null when the clip was stored outside Files." } }, "required": [ "availability", "url", "expires_at", "content_type", "duration_seconds", "file_id" ] }, "credits": { "type": "object", "properties": { "reserved": { "type": [ "number", "null" ] }, "settled": { "type": [ "number", "null" ] } }, "required": [ "reserved", "settled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "state", "model", "mode", "prompt", "duration_seconds", "aspect_ratio", "resolution", "source", "progress", "error", "output", "credits", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "listVideoModelsResponse200": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "video_model" ] }, "display_name": { "type": "string" }, "provider": { "type": "string" }, "modes": { "type": "array", "items": { "type": "string", "enum": [ "text_to_video", "image_to_video" ] } }, "duration": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "range" ] }, "min": { "type": "number" }, "max": { "type": "number" }, "step": { "type": "number" } }, "required": [ "kind", "min", "max", "step" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "discrete" ] }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "kind", "values" ] } ] }, "aspect_ratios": { "type": "array", "items": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9" ] } }, "resolutions": { "type": "array", "items": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ] } }, "defaults": { "type": "object", "properties": { "duration_seconds": { "type": "number" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9" ] }, "resolution": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ] } }, "required": [ "duration_seconds", "aspect_ratio", "resolution" ] }, "audio": { "type": "string", "enum": [ "always", "optional", "none" ] }, "credits_per_second": { "type": [ "object", "null" ], "additionalProperties": { "type": "number" }, "description": "Credits per second of output by resolution; null for per-clip priced models." }, "deprecation_date": { "type": [ "string", "null" ] } }, "required": [ "id", "object", "display_name", "provider", "modes", "duration", "aspect_ratios", "resolutions", "defaults", "audio", "credits_per_second", "deprecation_date" ] } } }, "required": [ "models" ] }, "cancelMusicGenerationResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "music_generation" ] }, "state": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "model": { "type": "string" }, "prompt": { "type": "string" }, "lyrics": { "type": [ "string", "null" ], "description": "The lyrics you sent, or null." }, "instrumental": { "type": "boolean" }, "duration_seconds": { "type": "number", "description": "The length requested (the model default when omitted)." }, "source": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "content_blocked", "provider_timeout", "provider_error", "region_unavailable", "output_too_large", "cancelled" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "output": { "type": [ "object", "null" ], "properties": { "availability": { "type": "string", "enum": [ "ready", "pending_scan", "unavailable" ], "description": "`ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling." }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null." }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601. When url stops working; null whenever url is." }, "content_type": { "type": "string" }, "duration_seconds": { "type": "number", "description": "The length of the song produced, which can differ from the request." }, "lyrics": { "type": [ "string", "null" ], "description": "What the model sang, as plain lines; null for instrumental output or when the provider does not report it." }, "file_id": { "type": [ "string", "null" ], "description": "The Files entry, or null when the song was stored outside Files." } }, "required": [ "availability", "url", "expires_at", "content_type", "duration_seconds", "lyrics", "file_id" ] }, "credits": { "type": "object", "properties": { "reserved": { "type": [ "number", "null" ] }, "settled": { "type": [ "number", "null" ] } }, "required": [ "reserved", "settled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "state", "model", "prompt", "lyrics", "instrumental", "duration_seconds", "source", "error", "output", "credits", "created_at", "updated_at" ], "example": { "id": "664f1c2b9a1e4d0012ab34cd", "object": "music_generation", "state": "pending", "model": "lyria-3.5", "prompt": "An upbeat synth-pop song about a road trip at sunrise", "lyrics": null, "instrumental": false, "duration_seconds": 120, "source": "api", "error": null, "output": null, "credits": { "reserved": 160, "settled": null }, "created_at": "2026-10-14T00:00:00.000Z", "updated_at": "2026-10-14T00:00:00.000Z" } }, "cancelMusicGenerationResponse409": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "unsupported_duration", "unsupported_lyrics", "unsupported_vocals", "lyrics_with_instrumental", "lyrics_too_long", "invalid_request", "model_disabled", "model_unavailable", "insufficient_credits", "idempotency_key_reused", "invalid_idempotency_key", "not_cancellable" ] } }, "required": [ "error" ] }, "createMusicGenerationResponse202": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "music_generation" ] }, "state": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "model": { "type": "string" }, "prompt": { "type": "string" }, "lyrics": { "type": [ "string", "null" ], "description": "The lyrics you sent, or null." }, "instrumental": { "type": "boolean" }, "duration_seconds": { "type": "number", "description": "The length requested (the model default when omitted)." }, "source": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "content_blocked", "provider_timeout", "provider_error", "region_unavailable", "output_too_large", "cancelled" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "output": { "type": [ "object", "null" ], "properties": { "availability": { "type": "string", "enum": [ "ready", "pending_scan", "unavailable" ], "description": "`ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling." }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null." }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601. When url stops working; null whenever url is." }, "content_type": { "type": "string" }, "duration_seconds": { "type": "number", "description": "The length of the song produced, which can differ from the request." }, "lyrics": { "type": [ "string", "null" ], "description": "What the model sang, as plain lines; null for instrumental output or when the provider does not report it." }, "file_id": { "type": [ "string", "null" ], "description": "The Files entry, or null when the song was stored outside Files." } }, "required": [ "availability", "url", "expires_at", "content_type", "duration_seconds", "lyrics", "file_id" ] }, "credits": { "type": "object", "properties": { "reserved": { "type": [ "number", "null" ] }, "settled": { "type": [ "number", "null" ] } }, "required": [ "reserved", "settled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "state", "model", "prompt", "lyrics", "instrumental", "duration_seconds", "source", "error", "output", "credits", "created_at", "updated_at" ], "example": { "id": "664f1c2b9a1e4d0012ab34cd", "object": "music_generation", "state": "pending", "model": "lyria-3.5", "prompt": "An upbeat synth-pop song about a road trip at sunrise", "lyrics": null, "instrumental": false, "duration_seconds": 120, "source": "api", "error": null, "output": null, "credits": { "reserved": 160, "settled": null }, "created_at": "2026-10-14T00:00:00.000Z", "updated_at": "2026-10-14T00:00:00.000Z" } }, "createMusicGenerationResponse400": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "storage_limit_exceeded", "org_storage_limit_exceeded", "file_too_large" ], "description": "Stable refusal code: `storage_limit_exceeded` (your total storage), `org_storage_limit_exceeded` (the organization limit), or `file_too_large` (the per-file size limit). Branch on this, not on the message." }, "used_bytes": { "type": "number", "minimum": 0, "description": "Bytes already stored against the limit. 0 for `org_storage_limit_exceeded` and `file_too_large`." }, "limit_bytes": { "type": "number", "minimum": 0, "description": "The limit, in bytes, that the request ran into." }, "requested_bytes": { "type": "number", "minimum": 0, "description": "Size of the refused upload, in bytes." }, "owner": { "type": "string", "enum": [ "user", "org" ], "description": "Whose limit was hit: `user` or `org`. Always `user` for `file_too_large`, a platform-wide cap." } }, "required": [ "error" ] }, "createMusicGenerationResponse403": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route accepts. Holding any one of them satisfies it." }, "also_required_scopes": { "type": "array", "items": { "type": "string" }, "description": "API key scopes this route also requires. Every one must be held, on top of `required_scopes`." }, "errorCode": { "type": "string", "enum": [ "billing_organization_mismatch" ] } }, "required": [ "error" ] }, "createMusicGenerationResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "unsupported_duration", "unsupported_lyrics", "unsupported_vocals", "lyrics_with_instrumental", "lyrics_too_long", "invalid_request", "model_disabled", "model_unavailable", "insufficient_credits", "idempotency_key_reused", "invalid_idempotency_key", "not_cancellable" ] } }, "required": [ "error" ] }, "createMusicGenerationRequest": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "description": "A model id from GET /api/v1/music-models." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "The style, mood and subject of the song." }, "lyrics": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Lyrics to sing. Only for models whose `lyrics` is not null, within that model's limits." }, "instrumental": { "type": "boolean", "description": "true for no vocals. Defaults to false, or to true for an instrumental-only model." }, "duration_seconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Whole seconds. Defaults to the model's default; see the model's `duration` for how it is honoured." }, "organization_id": { "type": [ "string", "null" ], "minLength": 1, "description": "The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (`errorCode: billing_organization_mismatch`)." } }, "required": [ "model", "prompt" ], "additionalProperties": false, "example": { "model": "lyria-3.5", "prompt": "An upbeat synth-pop song about a road trip at sunrise" } }, "getMusicGenerationResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "music_generation" ] }, "state": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "model": { "type": "string" }, "prompt": { "type": "string" }, "lyrics": { "type": [ "string", "null" ], "description": "The lyrics you sent, or null." }, "instrumental": { "type": "boolean" }, "duration_seconds": { "type": "number", "description": "The length requested (the model default when omitted)." }, "source": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "content_blocked", "provider_timeout", "provider_error", "region_unavailable", "output_too_large", "cancelled" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "output": { "type": [ "object", "null" ], "properties": { "availability": { "type": "string", "enum": [ "ready", "pending_scan", "unavailable" ], "description": "`ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling." }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null." }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601. When url stops working; null whenever url is." }, "content_type": { "type": "string" }, "duration_seconds": { "type": "number", "description": "The length of the song produced, which can differ from the request." }, "lyrics": { "type": [ "string", "null" ], "description": "What the model sang, as plain lines; null for instrumental output or when the provider does not report it." }, "file_id": { "type": [ "string", "null" ], "description": "The Files entry, or null when the song was stored outside Files." } }, "required": [ "availability", "url", "expires_at", "content_type", "duration_seconds", "lyrics", "file_id" ] }, "credits": { "type": "object", "properties": { "reserved": { "type": [ "number", "null" ] }, "settled": { "type": [ "number", "null" ] } }, "required": [ "reserved", "settled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "state", "model", "prompt", "lyrics", "instrumental", "duration_seconds", "source", "error", "output", "credits", "created_at", "updated_at" ], "example": { "id": "664f1c2b9a1e4d0012ab34cd", "object": "music_generation", "state": "pending", "model": "lyria-3.5", "prompt": "An upbeat synth-pop song about a road trip at sunrise", "lyrics": null, "instrumental": false, "duration_seconds": 120, "source": "api", "error": null, "output": null, "credits": { "reserved": 160, "settled": null }, "created_at": "2026-10-14T00:00:00.000Z", "updated_at": "2026-10-14T00:00:00.000Z" } }, "listMusicGenerationsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "music_generation" ] }, "state": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "model": { "type": "string" }, "prompt": { "type": "string" }, "lyrics": { "type": [ "string", "null" ], "description": "The lyrics you sent, or null." }, "instrumental": { "type": "boolean" }, "duration_seconds": { "type": "number", "description": "The length requested (the model default when omitted)." }, "source": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "content_blocked", "provider_timeout", "provider_error", "region_unavailable", "output_too_large", "cancelled" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "output": { "type": [ "object", "null" ], "properties": { "availability": { "type": "string", "enum": [ "ready", "pending_scan", "unavailable" ], "description": "`ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling." }, "url": { "type": [ "string", "null" ], "description": "Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null." }, "expires_at": { "type": [ "string", "null" ], "description": "ISO 8601. When url stops working; null whenever url is." }, "content_type": { "type": "string" }, "duration_seconds": { "type": "number", "description": "The length of the song produced, which can differ from the request." }, "lyrics": { "type": [ "string", "null" ], "description": "What the model sang, as plain lines; null for instrumental output or when the provider does not report it." }, "file_id": { "type": [ "string", "null" ], "description": "The Files entry, or null when the song was stored outside Files." } }, "required": [ "availability", "url", "expires_at", "content_type", "duration_seconds", "lyrics", "file_id" ] }, "credits": { "type": "object", "properties": { "reserved": { "type": [ "number", "null" ] }, "settled": { "type": [ "number", "null" ] } }, "required": [ "reserved", "settled" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "state", "model", "prompt", "lyrics", "instrumental", "duration_seconds", "source", "error", "output", "credits", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "listMusicModelsResponse200": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "music_model" ] }, "display_name": { "type": "string" }, "provider": { "type": "string" }, "vocals": { "type": "string", "enum": [ "optional", "never" ], "description": "`never`: instrumental only." }, "lyrics": { "type": [ "object", "null" ], "properties": { "max_chars": { "type": "number" }, "max_line_chars": { "type": [ "number", "null" ] } }, "required": [ "max_chars", "max_line_chars" ], "description": "Limits on custom lyrics, or null when the model does not accept them." }, "duration": { "oneOf": [ { "type": "object", "properties": { "control": { "type": "string", "enum": [ "exact", "approximate" ] }, "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "required": [ "control", "min", "max", "default" ] }, { "type": "object", "properties": { "control": { "type": "string", "enum": [ "fixed" ] }, "seconds": { "type": "number" } }, "required": [ "control", "seconds" ] } ], "description": "`exact`: the song has the requested length. `approximate`: the length is steered by the prompt, so the song may run shorter or longer. `fixed`: every song has this length; omit duration_seconds or repeat it." }, "output_formats": { "type": "array", "items": { "type": "string", "enum": [ "mp3" ] } }, "typical_render_seconds": { "type": "number", "description": "A rough wall-clock estimate, to set expectations. Not billed on." }, "pricing": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "per_song", "per_second" ] }, "credits": { "type": "number" } }, "required": [ "unit", "credits" ], "description": "`per_song`: a flat price whatever the length. `per_second`: credits per second of output." }, "preview": { "type": "boolean", "description": "Labelled preview by its provider: may change or be retired at short notice." }, "deprecation_date": { "type": [ "string", "null" ] } }, "required": [ "id", "object", "display_name", "provider", "vocals", "lyrics", "duration", "output_formats", "typical_render_seconds", "pricing", "preview", "deprecation_date" ] } } }, "required": [ "models" ] }, "listVoicesResponse200": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ElevenLabs voice id." }, "name": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-supplied labels (accent, gender, age, descriptive). May be empty." }, "previewUrl": { "type": "string", "description": "Short preview MP3 hosted by ElevenLabs, when the provider has one." } }, "required": [ "id", "name", "labels" ] } } }, "required": [ "voices" ], "example": { "voices": [ { "id": "21m00Tcm4TlvDq8ikWAM", "name": "Rachel", "labels": { "accent": "american", "gender": "female" }, "previewUrl": "https://storage.googleapis.com/eleven-public-prod/premade/voices/rachel.mp3" } ] } }, "listVoicesResponse503": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "provider_not_configured" ] } }, "required": [ "error" ] }, "createVoiceSessionResponse200": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "reasoningModelId": { "type": "string", "description": "The model that will answer, after any platform remap." }, "clientBootstrap": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "elevenlabs-conversational" ] }, "signedUrl": { "type": "string", "description": "Short-lived ElevenLabs signed WebSocket URL for this conversation." }, "agentId": { "type": "string", "description": "ElevenLabs agent the conversation runs on." }, "voiceOverrideId": { "type": "string", "description": "Caller's TTS voice override, applied via the SDK `overrides.tts.voiceId`." }, "systemPromptOverride": { "type": "string", "description": "Caller's system-prompt override, applied via the SDK `overrides.agent.prompt.prompt`." }, "sessionToken": { "type": "string", "description": "Signed, session-bound token to forward to ElevenLabs as `custom_llm_extra_body.b4m_session`. Treat it as a credential." } }, "required": [ "transport", "signedUrl", "agentId", "sessionToken" ] } }, "required": [ "session", "reasoningModelId", "clientBootstrap" ], "example": { "session": { "id": "664f1c2b9a1e4d0012ab34aa", "name": "Voice • claude-sonnet-4-6" }, "reasoningModelId": "claude-sonnet-4-6", "clientBootstrap": { "transport": "elevenlabs-conversational", "signedUrl": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=agent_123&conversation_signature=sig", "agentId": "agent_123", "sessionToken": "eyJhbGciOiJIUzI1NiJ9.." } } }, "createVoiceSessionResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] } }, "required": [ "error" ] }, "createVoiceSessionResponse503": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "provider_not_configured" ] } }, "required": [ "error" ] }, "createVoiceSessionRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Attach the call to this existing session (notebook). Omit to create a new one." }, "reasoningModelId": { "type": "string", "description": "Chat model that answers each spoken turn. Defaults to the platform voice default." }, "isReconnect": { "type": "boolean", "description": "Set when re-establishing a dropped transport for the same `sessionId`: the live credit hold from the original connect is reused instead of reserving (and charging) a second time." } }, "example": { "sessionId": "664f1c2b9a1e4d0012ab34aa" } }, "endVoiceSessionResponse200": { "type": "object", "properties": { "refunded": { "type": "number", "description": "Credits returned to the caller from the up-front reservation." }, "elapsedSeconds": { "type": "integer", "description": "Billed call duration. Absent when the session had already been reconciled." }, "alreadyReconciled": { "type": "boolean", "enum": [ true ], "description": "Present when there was no live hold left to reconcile; the call is a no-op." } }, "required": [ "refunded" ], "example": { "refunded": 42, "elapsedSeconds": 95 } }, "listWhatsNewResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "release_tag": { "type": "string" }, "headline": { "type": "string" }, "summary": { "type": "string" }, "published_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "new", "improved", "fixed" ] }, "text": { "type": "string" }, "importance": { "type": "integer", "minimum": 1, "maximum": 3 } }, "required": [ "category", "text", "importance" ] } } }, "required": [ "id", "release_tag", "headline", "summary", "published_at", "items" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "listProjectsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "session_ids": { "type": "array", "items": { "type": "string" }, "description": "Sessions grouped in the project. Anyone the project is shared with can read them." }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "Files grouped in the project. Anyone the project is shared with can read them." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "description", "session_ids", "file_ids", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "getProjectResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "session_ids": { "type": "array", "items": { "type": "string" }, "description": "Sessions grouped in the project. Anyone the project is shared with can read them." }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "Files grouped in the project. Anyone the project is shared with can read them." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "description", "session_ids", "file_ids", "created_at", "updated_at" ] }, "createProjectResponse201": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "session_ids": { "type": "array", "items": { "type": "string" }, "description": "Sessions grouped in the project. Anyone the project is shared with can read them." }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "Files grouped in the project. Anyone the project is shared with can read them." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "description", "session_ids", "file_ids", "created_at", "updated_at" ] }, "createProjectRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Unique among your live projects." }, "description": { "type": "string", "minLength": 1 }, "session_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "description": "Sessions to group in the project. Each must be readable by the caller." }, "file_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "description": "Files to group in the project. Each must be readable by the caller." } }, "required": [ "name", "description" ], "additionalProperties": false, "example": { "name": "Market research", "description": "Sources and notes for the Q3 market analysis.", "session_ids": [ "664f1c2b9a1e4d0012ab34aa" ], "file_ids": [ "664f1c2b9a1e4d0012ab34bb" ] } }, "listArtifactsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "mermaid", "recharts", "chess", "python", "react", "html", "svg", "code", "quest", "file", "questmaster", "lattice", "blog-draft" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "description": "The current version. Starts at 1; each content change adds one." }, "version_tag": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "review", "published", "archived" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "session_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "private", "project", "organization", "public" ] }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "content": { "type": [ "string", "null" ], "description": "The current version's content. `null` in a list (fetch the artifact by id for it), and in an update response to a caller who may edit the artifact but not read it, unless that update sent content." } }, "required": [ "id", "type", "title", "description", "version", "version_tag", "status", "tags", "session_id", "project_id", "visibility", "created_at", "updated_at", "content" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "example": { "data": [ { "id": "", "type": "mermaid", "title": "Signup flow", "description": null, "version": 2, "version_tag": null, "status": "draft", "tags": [ "onboarding" ], "session_id": "", "project_id": null, "visibility": "private", "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-02T09:30:00.000Z", "content": null } ], "next_cursor": null } }, "createArtifactResponse201": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "mermaid", "recharts", "chess", "python", "react", "html", "svg", "code", "quest", "file", "questmaster", "lattice", "blog-draft" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "description": "The current version. Starts at 1; each content change adds one." }, "version_tag": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "review", "published", "archived" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "session_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "private", "project", "organization", "public" ] }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "content": { "type": [ "string", "null" ], "description": "The current version's content. `null` in a list (fetch the artifact by id for it), and in an update response to a caller who may edit the artifact but not read it, unless that update sent content." } }, "required": [ "id", "type", "title", "description", "version", "version_tag", "status", "tags", "session_id", "project_id", "visibility", "created_at", "updated_at", "content" ], "example": { "id": "", "type": "mermaid", "title": "Signup flow", "description": null, "version": 1, "version_tag": null, "status": "draft", "tags": [ "onboarding" ], "session_id": "", "project_id": null, "visibility": "private", "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-02T09:30:00.000Z", "content": "graph TD; A[Sign up] --> B[Verify email]" } }, "createArtifactRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mermaid", "recharts", "chess", "python", "react", "html", "svg", "code", "quest", "file", "questmaster", "lattice", "blog-draft" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 1000 }, "session_id": { "type": "string", "minLength": 1, "description": "A session you can edit, to file the artifact under." }, "project_id": { "type": "string", "minLength": 1, "description": "A project you can read, to file the artifact under." }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 } }, "required": [ "type", "title", "content" ], "additionalProperties": false, "example": { "type": "mermaid", "title": "Signup flow", "content": "graph TD; A[Sign up] --> B[Verify email]", "tags": [ "onboarding" ] } }, "getArtifactResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "mermaid", "recharts", "chess", "python", "react", "html", "svg", "code", "quest", "file", "questmaster", "lattice", "blog-draft" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "description": "The current version. Starts at 1; each content change adds one." }, "version_tag": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "review", "published", "archived" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "session_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "private", "project", "organization", "public" ] }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "content": { "type": [ "string", "null" ], "description": "The current version's content. `null` in a list (fetch the artifact by id for it), and in an update response to a caller who may edit the artifact but not read it, unless that update sent content." } }, "required": [ "id", "type", "title", "description", "version", "version_tag", "status", "tags", "session_id", "project_id", "visibility", "created_at", "updated_at", "content" ], "example": { "id": "", "type": "mermaid", "title": "Signup flow", "description": null, "version": 2, "version_tag": null, "status": "draft", "tags": [ "onboarding" ], "session_id": "", "project_id": null, "visibility": "private", "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-02T09:30:00.000Z", "content": "graph TD; A[Sign up] --> B[Verify email]" } }, "updateArtifactResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "mermaid", "recharts", "chess", "python", "react", "html", "svg", "code", "quest", "file", "questmaster", "lattice", "blog-draft" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "version": { "type": "integer", "description": "The current version. Starts at 1; each content change adds one." }, "version_tag": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "review", "published", "archived" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "session_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "private", "project", "organization", "public" ] }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "content": { "type": [ "string", "null" ], "description": "The current version's content. `null` in a list (fetch the artifact by id for it), and in an update response to a caller who may edit the artifact but not read it, unless that update sent content." } }, "required": [ "id", "type", "title", "description", "version", "version_tag", "status", "tags", "session_id", "project_id", "visibility", "created_at", "updated_at", "content" ] }, "updateArtifactRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "content": { "type": "string", "minLength": 1, "description": "Changed content creates a new version." }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 } }, "additionalProperties": false, "example": { "content": "graph TD; A[Sign up] --> B[Verify email] --> C[Done]" } }, "listArtifactVersionsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "version_tag": { "type": [ "string", "null" ] }, "change_description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "content": { "type": [ "string", "null" ], "description": "This version's content. `null` in a list; fetch the version for it." } }, "required": [ "version", "version_tag", "change_description", "created_at", "content" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "example": { "data": [ { "version": 1, "version_tag": null, "change_description": "Created artifact", "created_at": "2026-10-01T12:00:00.000Z", "content": null } ], "next_cursor": null } }, "getArtifactVersionResponse200": { "type": "object", "properties": { "version": { "type": "integer" }, "version_tag": { "type": [ "string", "null" ] }, "change_description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "content": { "type": [ "string", "null" ], "description": "This version's content. `null` in a list; fetch the version for it." } }, "required": [ "version", "version_tag", "change_description", "created_at", "content" ], "example": { "version": 1, "version_tag": null, "change_description": "Created artifact", "created_at": "2026-10-01T12:00:00.000Z", "content": "graph TD; A[Sign up] --> B[Verify email]" } }, "createTranscriptionUploadResponse201": { "type": "object", "properties": { "upload_url": { "type": "string", "description": "POST the audio here as `multipart/form-data`. Send no `Authorization` header." }, "upload_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Form fields to send, unchanged and before the `file` field, with the upload." }, "file_key": { "type": "string", "description": "Pass this to `POST /api/v1/transcriptions` once the upload succeeds." }, "expires_at": { "type": "string", "description": "ISO 8601. The upload is refused after this; mint a new one to retry." } }, "required": [ "upload_url", "upload_fields", "file_key", "expires_at" ], "example": { "upload_url": "https://.s3.amazonaws.com/", "upload_fields": { "key": "transcribe-uploads//.mp3", "Content-Type": "audio/mpeg", "Policy": "..." }, "file_key": "transcribe-uploads//.mp3", "expires_at": "2026-10-09T12:05:00.000Z" } }, "createTranscriptionUploadResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] } }, "required": [ "error" ] }, "createTranscriptionUploadRequest": { "type": "object", "properties": { "mime_type": { "type": "string", "enum": [ "audio/mpeg", "audio/mp4", "audio/wav", "audio/webm", "audio/ogg", "audio/flac" ] }, "file_size": { "type": "integer", "minimum": 1, "maximum": 26214400, "description": "Size in bytes of the audio you will upload. At most 25 MiB." } }, "required": [ "mime_type", "file_size" ], "additionalProperties": false, "example": { "mime_type": "audio/mpeg", "file_size": 482133 } }, "createTranscriptionResponse200": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "example": { "text": "Thanks for calling. How can I help?" } }, "createTranscriptionResponse422": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "insufficient_credits", "spend_cap_exceeded" ] } }, "required": [ "error" ] }, "createTranscriptionResponse503": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" }, "name": { "type": "string", "deprecated": true, "description": "Deprecated, sunset 2026-12-01. The `name` of whatever the server threw - usually one of our own error classes (`NotFoundError`, `UnprocessableEntityError`, ...), but on an unhandled 500 it can be a library or driver class name instead. Unstable by nature: these are internal names we rename at will, and the set is open. Documented only so the wire and this spec agree for the deprecation window; it is removed on the sunset date. Branch on the HTTP status, not on this." }, "errorCode": { "type": "string", "enum": [ "provider_not_configured" ] } }, "required": [ "error" ] }, "createTranscriptionRequest": { "type": "object", "properties": { "file_key": { "type": "string", "minLength": 1, "description": "The `file_key` from `POST /api/v1/transcriptions/uploads`." } }, "required": [ "file_key" ], "additionalProperties": false, "example": { "file_key": "transcribe-uploads//.mp3" } }, "updateProjectResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "session_ids": { "type": "array", "items": { "type": "string" }, "description": "Sessions grouped in the project. Anyone the project is shared with can read them." }, "file_ids": { "type": "array", "items": { "type": "string" }, "description": "Files grouped in the project. Anyone the project is shared with can read them." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "description", "session_ids", "file_ids", "created_at", "updated_at" ] }, "updateProjectRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Unique among your live projects." }, "description": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "example": { "description": "Sources and notes for the Q4 market analysis." } }, "listAgentsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "system_prompt": { "type": [ "string", "null" ], "description": "The agent's system prompt. `null` unless the caller owns the agent." }, "preferred_model": { "type": [ "string", "null" ], "description": "Model id the agent answers with; `null` uses the default." }, "temperature": { "type": [ "number", "null" ] }, "max_tokens": { "type": [ "integer", "null" ] }, "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tools the agent may call. An empty list (or `null`) means the default tool policy applies." }, "denied_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tools the agent may never call. An empty list (or `null`) means the default tool policy applies." }, "trigger_words": { "type": "array", "items": { "type": "string" }, "description": "Mentions (for example `@research`) that invoke the agent in chat." }, "is_owner": { "type": "boolean", "description": "Whether the caller owns the agent, rather than having it shared with them." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "description", "system_prompt", "preferred_model", "temperature", "max_tokens", "allowed_tools", "denied_tools", "trigger_words", "is_owner", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "getAgentResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "system_prompt": { "type": [ "string", "null" ], "description": "The agent's system prompt. `null` unless the caller owns the agent." }, "preferred_model": { "type": [ "string", "null" ], "description": "Model id the agent answers with; `null` uses the default." }, "temperature": { "type": [ "number", "null" ] }, "max_tokens": { "type": [ "integer", "null" ] }, "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tools the agent may call. An empty list (or `null`) means the default tool policy applies." }, "denied_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tools the agent may never call. An empty list (or `null`) means the default tool policy applies." }, "trigger_words": { "type": "array", "items": { "type": "string" }, "description": "Mentions (for example `@research`) that invoke the agent in chat." }, "is_owner": { "type": "boolean", "description": "Whether the caller owns the agent, rather than having it shared with them." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "description", "system_prompt", "preferred_model", "temperature", "max_tokens", "allowed_tools", "denied_tools", "trigger_words", "is_owner", "created_at", "updated_at" ] }, "createAgentResponse201": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "system_prompt": { "type": [ "string", "null" ], "description": "The agent's system prompt. `null` unless the caller owns the agent." }, "preferred_model": { "type": [ "string", "null" ], "description": "Model id the agent answers with; `null` uses the default." }, "temperature": { "type": [ "number", "null" ] }, "max_tokens": { "type": [ "integer", "null" ] }, "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tools the agent may call. An empty list (or `null`) means the default tool policy applies." }, "denied_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tools the agent may never call. An empty list (or `null`) means the default tool policy applies." }, "trigger_words": { "type": "array", "items": { "type": "string" }, "description": "Mentions (for example `@research`) that invoke the agent in chat." }, "is_owner": { "type": "boolean", "description": "Whether the caller owns the agent, rather than having it shared with them." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "description", "system_prompt", "preferred_model", "temperature", "max_tokens", "allowed_tools", "denied_tools", "trigger_words", "is_owner", "created_at", "updated_at" ] }, "createAgentRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "system_prompt": { "type": "string" }, "preferred_model": { "type": "string", "minLength": 1, "description": "A chat model id. An unknown model is rejected with a 422." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 128000 }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools the agent may call. An empty list (or `null`) means the default tool policy applies." }, "denied_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools the agent may never call. An empty list (or `null`) means the default tool policy applies." }, "trigger_words": { "type": "array", "items": { "type": "string" }, "description": "Mentions (for example `@research`) that invoke the agent in chat." } }, "required": [ "name" ], "additionalProperties": false, "example": { "name": "Research assistant", "description": "Summarizes sources and cites them.", "system_prompt": "You are a careful research assistant. Always cite your sources.", "temperature": 0.3, "trigger_words": [ "@research" ] } }, "updateAgentResponse200": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "system_prompt": { "type": [ "string", "null" ], "description": "The agent's system prompt. `null` unless the caller owns the agent." }, "preferred_model": { "type": [ "string", "null" ], "description": "Model id the agent answers with; `null` uses the default." }, "temperature": { "type": [ "number", "null" ] }, "max_tokens": { "type": [ "integer", "null" ] }, "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tools the agent may call. An empty list (or `null`) means the default tool policy applies." }, "denied_tools": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tools the agent may never call. An empty list (or `null`) means the default tool policy applies." }, "trigger_words": { "type": "array", "items": { "type": "string" }, "description": "Mentions (for example `@research`) that invoke the agent in chat." }, "is_owner": { "type": "boolean", "description": "Whether the caller owns the agent, rather than having it shared with them." }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." } }, "required": [ "id", "name", "description", "system_prompt", "preferred_model", "temperature", "max_tokens", "allowed_tools", "denied_tools", "trigger_words", "is_owner", "created_at", "updated_at" ] }, "updateAgentRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "system_prompt": { "type": "string" }, "preferred_model": { "type": [ "string", "null" ], "minLength": 1, "description": "A chat model id. An unknown model is rejected with a 422." }, "temperature": { "type": [ "number", "null" ], "minimum": 0, "maximum": 2 }, "max_tokens": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 128000 }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools the agent may call. An empty list (or `null`) means the default tool policy applies." }, "denied_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools the agent may never call. An empty list (or `null`) means the default tool policy applies." }, "trigger_words": { "type": "array", "items": { "type": "string" }, "description": "Mentions (for example `@research`) that invoke the agent in chat." } }, "additionalProperties": false, "example": { "temperature": 0.7, "trigger_words": [ "@research", "@sources" ] } } }, "parameters": {} }, "paths": { "/api/chat": { "post": { "operationId": "sendChatMessage", "summary": "Send a chat message", "description": "Sends a message to the AI and creates a quest to process it. By default (async) the call returns immediately with a quest id; poll `GET /api/v1/quests/{id}` for the reply. Send `wait: true` to block until the reply is ready and receive it inline. A `wait: true` turn is bounded at about 45 seconds: one that runs longer is ended (unused credits refunded) and answered with a 504 naming the quest in `quest_id`. Send long or tool-heavy turns (large attachments, tool calls) in the default async mode and poll instead. A tool that produced machine-readable state reports it under `toolPayloads` - an array of `{ type, payload }` entries in emission order, alongside (never instead of) the prose reply - on the `wait: true` body and on the polled quest. A turn can FAIL after the ACK - reported on the polled quest as `type: \"error\"`, since the ACK was already sent. A terminal `status: \"stopped\"` (a missing session, a user-cancelled turn) is ALSO a failure even without `type: \"error\"` - it carries an explanatory string in `reply`/`replies` rather than an answer. `type` is the failure signal for the classified failure classes (an abort, a provider timeout, credit exhaustion); `errorCode` is an optional refinement present only when the failure is a classified billing reason. A recovered stuck quest is NOT in that list: one that still has renderable content resolves as a success by design. `QUEST_ERROR_CODES` has two members, but only `insufficient_credits` is raised as a quest errorCode by any current throw site on this endpoint - `spend_cap_exceeded` is thrown only by the embed chat route's pre-flight, which fires outside the process try/catch that would classify it onto a quest. A caller must treat `type: \"error\"` OR a terminal `status: \"stopped\"` as failure even when `errorCode` is absent, and must not read `reply` as an answer without checking those first. Authenticate with an API key (`b4m_live_`) or a JWT. Session resolution: pass `sessionId` to continue an existing notebook. An API-key caller that omits it gets a BRAND-NEW notebook rather than the notebook the human last had open, and `newConversation: true` forces a new notebook for any auth mode; both return the new id as `sessionId`, so the caller can continue the conversation by passing it back. A first-party JWT caller that omits `sessionId` keeps the last-opened-notebook fallback. Sending `sessionId` and `newConversation` together is a 422.", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendChatMessageRequest" } } } }, "responses": { "200": { "description": "Message accepted - NOT a completed turn. The default (async) path returns this queued ACK; the outcome arrives on `GET /api/v1/quests/{id}` (see the `sendChatMessage200PollResult` schema). With `wait: true` the body is instead the completed turn: the ACK fields plus the reply (`response`/`responses`), `toolPayloads`, `createdAt`, `performance` timings and, when requested, `promptDetails`/`promptText`. A turn that FAILS still resolves with `200`, never a 4xx, on both that `wait: true` body and the polled quest (`GET /api/v1/quests/{id}`) - the prose explaining why lands in `reply`/`response` like any other answer, so the reply text alone cannot tell a failure from an answer. `type` is the field that can: both surfaces carry it unconditionally, so match on `type: \"error\"` first - it covers credit exhaustion, a provider timeout or overload, and an in-process aborted turn; a real answer carries the turn's actual completion type instead (`\"message\"` for an ordinary reply). Two related states do NOT set `type: \"error\"`: a user-cancelled turn resolves as `status: \"stopped\"` with `type` left at `\"message\"`, and a recovered stuck quest that still has renderable content resolves as a success (`status: \"done\"`, no error) by design, to avoid destroying content to report a failure. `errorCode` then names the failure reason, but only for the billing failures that have one - `\"insufficient_credits\"` today; it is absent on every other `type: \"error\"` turn, so never use its absence to infer success. On a real answer `errorCode` is absent from the `wait: true` body. The body also carries `sessionId`, the notebook the turn was recorded in - for an API-key caller that sent none (or any caller sending `newConversation: true`), that is the freshly created notebook's id; pass it back as the request's `sessionId` to continue. Contrast the tts/music/soundEffects contracts, which reject synchronously with a 422 carrying the same `errorCode` vocabulary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendChatMessageResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "x-poll-result": { "schema": { "$ref": "#/components/schemas/sendChatMessage200PollResult" } } }, "400": { "description": "The request was rejected before a turn was created: a supplied `model` is unknown, disabled or not a chat model; or no usable default chat model is configured and none was supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "404": { "description": "No notebook/session exists to attach the message to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed schema validation, or `sessionId` and `newConversation: true` were sent together (they are mutually exclusive).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "504": { "description": "A `wait: true` turn ran past the request deadline. The turn is already ended: its quest (`quest_id`) is settled as timed out with any partial reply kept, and unused reserved credits are refunded. Retry in async mode for a long turn.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendChatMessageResponse504" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:chat", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/chat\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"message\": \"How do I reset my password?\",\n \"toolMode\": \"smart\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/chat\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"message\": \"How do I reset my password?\",\n \"toolMode\": \"smart\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/chat\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"message\": \"How do I reset my password?\",\n \"toolMode\": \"smart\"\n },\n)" } ] } }, "/api/v1/agent-executions": { "post": { "operationId": "startAgentExecution", "summary": "Start an agent execution", "description": "Runs the tool-using agent (ReAct) loop against a session - the same pipeline the product UI's Agent Mode toggle dispatches to, and the REST equivalent of the `agent_execute` WebSocket command. The run is asynchronous: this returns `202` with an execution id, and the caller polls `GET /api/v1/agent-executions/{id}` until `status` is terminal (`completed`, `failed`, or `aborted`). Nothing is streamed back over REST - for live iteration events, use the WebSocket route instead. Omit `agent_id` to get the profile the session's own surface resolves to, which is what reproduces the in-app toggle. The final reply is also written to the session as a normal chat message, so it appears in history. Naming a tool in `tools` also PRE-APPROVES it for the run: there is no interactive client to answer a permission prompt, so a run that calls an approval-gated tool you did not name fails with that tool named in `error` rather than hanging. Authenticate with an API key (`b4m_live_`) or a JWT.", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/startAgentExecutionRequest" } } } }, "responses": { "202": { "description": "Run accepted and dispatched. Poll `tracking_info.poll_url` for status and the answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/startAgentExecutionResponse202" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "No usable default chat model is configured and none was supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "404": { "description": "No session with the given `session_id` is owned by the caller, or `organization_id` names an organization the caller does not belong to. \"Exists but is not yours\" is reported as 404 too, so neither session ids nor org membership can be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The caller already has the maximum number of agent runs in flight - a per-user cap shared with runs started from the product UI. Wait for one to reach a terminal status before starting another; aborting a run is currently only possible over the WebSocket route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "502": { "description": "The executor could not be dispatched. The run did not start, so a retry is safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:chat", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/agent-executions\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"session_id\": \"\",\n \"message\": \"Audit this data set and summarize what stands out.\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agent-executions\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"session_id\": \"\",\n \"message\": \"Audit this data set and summarize what stands out.\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/agent-executions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"session_id\": \"\",\n \"message\": \"Audit this data set and summarize what stands out.\"\n },\n)" } ] } }, "/api/v1/agent-executions/{id}": { "get": { "operationId": "getAgentExecution", "summary": "Get an agent execution", "description": "Returns the status, reasoning trace, and (once terminal) the final answer of a run started by `POST /api/v1/agent-executions`. `steps` grows while the run is in flight, so polling this endpoint is also how a REST caller follows the loop. Safe (GET) requests on this route are exempt from the per-day API-key quota: a poll consumes no daily slot, and only the per-minute burst limit applies.", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The execution, its trace, and its answer if it has finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getAgentExecutionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "404": { "description": "No execution with that id is visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:chat", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/agent-executions/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agent-executions/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/agent-executions/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/sessions/{id}": { "get": { "operationId": "getSession", "summary": "Get a session", "description": "Reads a session you own or that was shared with you (called a \"notebook\" in the product UI): its name, attached knowledge files, tags, and retrieval settings. Use it to confirm what a `PUT` on the same path stored. A session not visible to you, or one that was deleted, is `404`. An API key needs `notebooks:read` or `notebooks:write`.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getSessionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "404": { "description": "No session with that id is visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:read", "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/sessions/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/sessions/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/sessions/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "put": { "operationId": "updateSession", "summary": "Update a session", "description": "Updates a session (called a \"notebook\" in the product UI): its name, attached knowledge files, tags, or retrieval settings. Set `knowledgeIds` and `forceKnowledgeRetrieval: true` together to enable grounded retrieval for `POST /api/chat` against this session - retrieval is gated by these session fields, not by the chat request. `lakeScope` narrows that retrieval to a chosen set of data lakes, and a non-empty list also turns forced retrieval on for a session that has never set it; omit it to leave the current choice unchanged, or send `null` to clear it so retrieval reaches every lake you can access. `includeLibraryFiles` sets whether the session grounds on your own library alongside its lakes; `false` confines it to lake content even when every lake is in scope (files attached to the session still reach the model and its knowledge-base tools), and is set aside (library included) while `forceKnowledgeRetrieval` is `false`. Authenticate with an API key (`b4m_live_`) or a JWT. Warning: adding to `knowledgeIds` shares those files with every member of every project containing this session by default (see `propagateToProjects`), and that sharing cannot be undone through the UI.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateSessionRequest" } } } }, "responses": { "200": { "description": "The updated session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateSessionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "404": { "description": "No session exists with the given id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X PUT \"https://your-deployment.example.com/api/sessions/\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"knowledgeIds\": [\n \"\"\n ],\n \"forceKnowledgeRetrieval\": true\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/sessions/\", {\n method: \"PUT\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"knowledgeIds\": [\n \"\"\n ],\n \"forceKnowledgeRetrieval\": true\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.put(\n \"https://your-deployment.example.com/api/sessions/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"knowledgeIds\": [\n \"\"\n ],\n \"forceKnowledgeRetrieval\": True\n },\n)" } ] }, "delete": { "operationId": "deleteSession", "summary": "Delete a session", "description": "Deletes one of your sessions (called a \"notebook\" in the product UI). This cannot be undone through the API. Files you uploaded into the session are deleted with it; files other people uploaded into it are kept, and every access grant this session gave out on a file is revoked. A session you do not own, or one already deleted, is `404`. A `409` means a concurrent change touched one of those files mid-delete; nothing was deleted, so retry. An API key needs `notebooks:write`.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The session was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deleteSessionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "404": { "description": "No session with that id is visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A concurrent change touched a file this session shares; nothing was deleted. Retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE \"https://your-deployment.example.com/api/sessions/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/sessions/\", {\n method: \"DELETE\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.delete(\n \"https://your-deployment.example.com/api/sessions/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/sessions/{id}/clone": { "post": { "operationId": "cloneSession", "summary": "Clone a session", "description": "Clones a session (called a \"notebook\" in the product UI), including its messages and attachments. Omit `targetSurface` to inherit the source workspace, send `null` for the main notebook list, or send a surface id for another workspace. An API key needs `notebooks:write`.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cloneSessionRequest" } } } }, "responses": { "200": { "description": "The cloned session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cloneSessionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The session id is missing or `targetSurface` is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `notebooks:write` or the caller is not allowed to clone sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No session with that id is visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The clone limit of 10 requests per minute per caller was exceeded.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until the caller can retry.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/sessions//clone\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/sessions//clone\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/sessions//clone\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={},\n)" } ] } }, "/api/ai/v1/tools": { "post": { "operationId": "executeTool", "summary": "Execute a server-side tool", "description": "Runs one of the built-in server-side tools (`weather_info`, `web_search`, `web_fetch`) and returns its result as JSON. Authenticate with a JWT access token only - API keys are NOT accepted on this endpoint. Rate-limited to 100 requests/hour per user, counted separately from other endpoints. `request_id` echoes the X-Request-ID response header.", "tags": [ "AI" ], "security": [ { "jwtAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/executeToolRequest" } } } }, "responses": { "200": { "description": "Tool executed successfully (`success` is always true here).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/executeToolResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid JWT (an API key is rejected here).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "Valid JWT, but the account is suspended or has a dispute pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded (100 requests/hour per user for this endpoint).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "500": { "description": "Tool execution failed (`success: false` with `error`) or an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/executeToolResponse500" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/ai/v1/tools\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"toolName\": \"web_search\",\n \"input\": {\n \"query\": \"how to reset a password\"\n }\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/ai/v1/tools\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"toolName\": \"web_search\",\n \"input\": {\n \"query\": \"how to reset a password\"\n }\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/ai/v1/tools\",\n headers={\"Authorization\": \"Bearer \"},\n json={\n \"toolName\": \"web_search\",\n \"input\": {\n \"query\": \"how to reset a password\"\n }\n },\n)" } ] } }, "/api/ai/v1/completions": { "post": { "operationId": "createCompletion", "summary": "Create a chat completion", "description": "OpenAI-compatible completion. A successful request is ALWAYS answered with an SSE stream (`text/event-stream`), regardless of the `stream` flag: a `meta` event, then `content`/`tool_use` events carrying `usage`/`credits`, terminated by `data: [DONE]`. The terminal event carries `stopReason`; treat `max_tokens` as a TRUNCATED reply rather than a complete one, and note that omitting `max_tokens` on the request lets the server size the output ceiling for the model (recommended for reasoning models, which spend thinking tokens inside that ceiling). A message `content` may be a string or an array of parts; image parts are accepted in OpenAI Chat (`image_url`), OpenAI Responses (`input_image`) or Anthropic (`image` with a `source`) form and are translated to whatever the target model speaks. Authenticate with an API key (`b4m_live_`) or a JWT.\n\nTOOL SEARCH. On a model whose `GET /api/v1/models` row has `supports_tool_search: true` and `backend: \"anthropic\"`, a `tools` entry may set `toolSchema.defer_loading: true`, and a `{ \"serverTool\": { \"type\": \"tool_search_tool_regex_20251119\", \"name\": \"tool_search_tool_regex\" } }` (or the `bm25` pair) entry adds Anthropic's tool search, so deferred definitions load only when the model searches for them. The stream then carries `provider_block` events (`{ type, provider: \"anthropic\", block }`) for the server-run search; echo each block back verbatim, in order, in the assistant `messages` content of the next request, and never answer one with a `tool_result`. When the server-run search loop hits its iteration limit the stream ends with `stopReason: \"pause_turn\"`; continue by re-sending the conversation with that assistant turn's provider blocks echoed. A client-side search may return `{ \"type\": \"tool_reference\", \"tool_name\": \"...\" }` blocks inside a `tool_result`'s content. On every other model, Bedrock-served Claude included, `defer_loading` is ignored (every tool is sent as usual) and a server tool, a `tool_reference` or an echoed tool search block is refused with a `400` rather than run without it.\n\nERRORS. Everything checked before the model provider is called fails with a JSON error body and a real HTTP status, before any stream opens: a malformed or otherwise invalid request or an unknown `model` `400` (`errorCode: \"unknown_model\"` for the latter), a bad credential `401`, a key without a required scope `403` (with `required_scopes`), a body over 25 MB `413`, a body that fails schema validation `422`, insufficient credits `422` with `errorCode: \"insufficient_credits\"` (personal or org balance, or an org per-member credit cap), a rate limit `429` with `Retry-After`, and a catalogued model whose provider is not configured on this deployment `503` with `errorCode: \"provider_not_configured\"` (retryable). Once the stream has opened the status stays `200` and a failure arrives as one terminal in-band `error` event. Branch on that event's `code`, never on `message`, which is prose and may change: `insufficient_credits` (buy credits) when credits run out mid-generation, `provider_rejected` when the model provider refused our credentials, `content_blocked` when the model declined the request (do not retry it unchanged), and `provider_error` for any other provider failure. Treat `code` as optional.", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createCompletionRequest" } } } }, "responses": { "200": { "description": "SSE stream of completion events (see the CompletionStreamEvent shape).", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/createCompletionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "400": { "description": "Malformed or otherwise invalid request (no `errorCode`), or a `model` the caller cannot use (`errorCode: \"unknown_model\"`): not in the catalog or not available to the caller. List valid ids with `GET /api/v1/models`. Tool search requests are refused with: `tool_search_unsupported` (a server tool, `tool_reference` or echoed tool search block on a model that cannot serve tool search here), `all_tools_deferred` (every tool deferred and no server tool), `deferred_tool_cache_control` (`cache_control` on a deferred tool), `unknown_tool_reference` (a `tool_reference` naming a tool not in `tools`, or carrying no string `tool_name`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createCompletionResponse400" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Request body over 25 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "422": { "description": "The body failed schema validation, or the caller cannot afford the request (`errorCode: \"insufficient_credits\"`: personal or org balance, or an org per-member credit cap).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createCompletionResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error before the stream opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "503": { "description": "Temporarily unavailable: the model's provider is not configured on this deployment (`errorCode: \"provider_not_configured\"`), or the database is unreachable (no `errorCode`). Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createCompletionResponse503" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } } }, "x-required-scopes": [ "ai:chat", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -sN -X POST \"https://your-deployment.example.com/api/ai/v1/completions\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"model\": \"claude-opus-4-8\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do I reset my password?\"\n }\n ],\n \"max_tokens\": 500\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/ai/v1/completions\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"model\": \"claude-opus-4-8\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do I reset my password?\"\n }\n ],\n \"max_tokens\": 500\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/ai/v1/completions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"model\": \"claude-opus-4-8\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do I reset my password?\"\n }\n ],\n \"max_tokens\": 500\n },\n stream=True,\n)" } ] } }, "/api/ai/tts": { "post": { "operationId": "synthesizeSpeech", "summary": "Synthesize speech from text", "description": "Generates speech from text using OpenAI or ElevenLabs. When the requested provider has no usable key (or the provider rejects it), another configured provider stands in and the substitution is reported via `provider`/`fallbackFrom` and the `X-B4M-Tts-Provider*` headers. Input length is capped per provider (OpenAI 4096 characters, ElevenLabs 10000), and an output `format` the chosen provider cannot produce is rejected with a 422 before any provider cost is incurred. `organization_id` picks the payer: an organization you belong to, or null for your personal credits; omitted bills your personal credits, as this endpoint always has. The default `encoding: \"binary\"` returns the raw audio bytes; `encoding: \"base64\"` returns JSON. Audio over the ~4MB response ceiling is returned by signed URL (a `303` for binary, the `delivery: \"url\"` variant for base64). Generated audio is saved to the file browser unless the call sets `preview`; the outcome is reported in the JSON save fields and the `X-B4M-Audio-*` headers - fetch the saved copy from `fileUrl` / `X-B4M-Audio-File-Url`, since `GET /api/files/{id}` fails closed until moderation completes. Authenticate with an API key (`b4m_live_`) or a JWT.", "tags": [ "Audio" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechRequest" } } } }, "responses": { "200": { "description": "Speech synthesized. Binary bodies carry a Content-Type that follows the requested `format` (`audio/mpeg` for mp3, else `audio/wav`, `audio/opus`, `audio/aac`, `audio/flac`, `audio/pcm`). The default `encoding: \"binary\"` returns the raw audio bytes; `encoding: \"base64\"` returns the JSON body. Audio over the ~4MB response ceiling cannot ride in the body: the binary encoding answers `303` instead, and the base64 encoding returns the `delivery: \"url\"` variant, whose `url` is a time-limited signed GET for the audio (`bytes` is its size).", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-B4M-Audio-Saved": { "description": "Whether a browsable copy was saved to the file browser (\"true\"/\"false\").", "schema": { "type": "string" } }, "X-B4M-Audio-Fab-File-Id": { "description": "Id of the saved file. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Name": { "description": "File name of the saved copy. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Url": { "description": "Signed URL for the saved copy, minted at creation. Use this rather than re-resolving the file via GET /api/files/{id}, which fails closed until the async moderation scan completes.", "schema": { "type": "string" } }, "X-B4M-Tts-Provider": { "description": "The provider that produced the audio. Present only when a fallback happened.", "schema": { "type": "string" } }, "X-B4M-Tts-Provider-Fallback-From": { "description": "The originally requested provider that could not serve the request. Present only on a fallback.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse200" } }, "audio/mpeg": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/wav": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/opus": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/aac": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/flac": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/pcm": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "303": { "description": "Binary encoding only: the audio exceeds the ~4MB response ceiling, so it was offloaded to storage and `Location` is a time-limited signed GET for it. HTTP clients that follow redirects receive the audio transparently (they drop the `Authorization` header on the cross-origin hop, as the signed URL requires); browser callers should use `encoding: \"base64\"`, since the storage origin sends no CORS headers. Carries the same `X-B4M-*` headers as the 200.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Location": { "description": "Signed URL of the offloaded audio.", "schema": { "type": "string" } }, "X-B4M-Audio-Saved": { "description": "Whether a browsable copy was saved to the file browser (\"true\"/\"false\").", "schema": { "type": "string" } }, "X-B4M-Audio-Fab-File-Id": { "description": "Id of the saved file. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Name": { "description": "File name of the saved copy. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Url": { "description": "Signed URL for the saved copy, minted at creation. Use this rather than re-resolving the file via GET /api/files/{id}, which fails closed until the async moderation scan completes.", "schema": { "type": "string" } }, "X-B4M-Tts-Provider": { "description": "The provider that produced the audio. Present only when a fallback happened.", "schema": { "type": "string" } }, "X-B4M-Tts-Provider-Fallback-From": { "description": "The originally requested provider that could not serve the request. Present only on a fallback.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The billing organization could not be resolved. An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse400" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing/invalid credentials, no provider has a usable key (`provider_not_configured`), or the provider refused the key we sent and no alternate could stand in (`provider_rejected`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse401" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope (`required_scopes` names it), or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse403" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "A nonexistent `organization_id`, for an admin caller; for anyone else it is `403`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse404" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The audio was generated (and billed) and exceeds the response ceiling, and offloading it to storage failed. Retry, or request shorter output.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse413" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "422": { "description": "Request body failed validation, the text exceeds the provider character limit, the provider cannot produce the requested `format`, the provider rejected the request (e.g. an unknown voice), or the caller cannot afford the synthesis - the last of those is the only one tagged `errorCode: \"insufficient_credits\"`, so match on the classifier rather than the status to tell a billing failure from a bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "The provider rate-limited the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse429" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "502": { "description": "The provider failed to generate speech.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/synthesizeSpeechResponse502" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/ai/tts\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"text\": \"Your password has been reset.\",\n \"provider\": \"openai\",\n \"voice\": \"alloy\",\n \"encoding\": \"base64\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/ai/tts\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"text\": \"Your password has been reset.\",\n \"provider\": \"openai\",\n \"voice\": \"alloy\",\n \"encoding\": \"base64\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/ai/tts\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"text\": \"Your password has been reset.\",\n \"provider\": \"openai\",\n \"voice\": \"alloy\",\n \"encoding\": \"base64\"\n },\n)" } ] } }, "/api/ai/music": { "post": { "operationId": "generateMusic", "summary": "Generate background music", "description": "**Deprecated, sunset 2027-01-15.** Use `/api/v1/music-generations` instead. Generates an instrumental or vocal background-music track from a text prompt. `lengthMs` (3000-120000, default 10000) is forced on the provider, so the generated track always matches the billed length; credits are reserved before generation and refunded if it fails. The default `encoding: \"binary\"` returns the raw audio bytes; `encoding: \"base64\"` returns JSON. Audio over the ~4MB response ceiling is returned by signed URL (a `303` for binary, the `delivery: \"url\"` variant for base64). Generated audio is saved to the file browser unless the call sets `preview`; the outcome is reported in the JSON save fields and the `X-B4M-Audio-*` headers - fetch the saved copy from `fileUrl` / `X-B4M-Audio-File-Url`, since `GET /api/files/{id}` fails closed until moderation completes. Authenticate with an API key (`b4m_live_`) or a JWT.", "deprecated": true, "tags": [ "Audio" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateMusicRequest" } } } }, "responses": { "200": { "description": "Music generated. Binary bodies carry a Content-Type that follows the requested `format` (mp3 by default). The default `encoding: \"binary\"` returns the raw audio bytes; `encoding: \"base64\"` returns the JSON body. Audio over the ~4MB response ceiling cannot ride in the body: the binary encoding answers `303` instead, and the base64 encoding returns the `delivery: \"url\"` variant, whose `url` is a time-limited signed GET for the audio (`bytes` is its size).", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-B4M-Audio-Saved": { "description": "Whether a browsable copy was saved to the file browser (\"true\"/\"false\").", "schema": { "type": "string" } }, "X-B4M-Audio-Fab-File-Id": { "description": "Id of the saved file. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Name": { "description": "File name of the saved copy. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Url": { "description": "Signed URL for the saved copy, minted at creation. Use this rather than re-resolving the file via GET /api/files/{id}, which fails closed until the async moderation scan completes.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: when this endpoint was deprecated. Always `@1792022400` on this endpoint.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the first day this endpoint may stop being served. Always `Fri, 15 Jan 2027 00:00:00 GMT` on this endpoint.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288: the replacement endpoint (`rel=\"successor-version\"`). Always `; rel=\"successor-version\"` on this endpoint.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateMusicResponse200" } }, "audio/mpeg": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/opus": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/L16": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/basic": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "303": { "description": "Binary encoding only: the audio exceeds the ~4MB response ceiling, so it was offloaded to storage and `Location` is a time-limited signed GET for it. HTTP clients that follow redirects receive the audio transparently (they drop the `Authorization` header on the cross-origin hop, as the signed URL requires); browser callers should use `encoding: \"base64\"`, since the storage origin sends no CORS headers. Carries the same `X-B4M-*` headers as the 200.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Location": { "description": "Signed URL of the offloaded audio.", "schema": { "type": "string" } }, "X-B4M-Audio-Saved": { "description": "Whether a browsable copy was saved to the file browser (\"true\"/\"false\").", "schema": { "type": "string" } }, "X-B4M-Audio-Fab-File-Id": { "description": "Id of the saved file. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Name": { "description": "File name of the saved copy. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Url": { "description": "Signed URL for the saved copy, minted at creation. Use this rather than re-resolving the file via GET /api/files/{id}, which fails closed until the async moderation scan completes.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: when this endpoint was deprecated. Always `@1792022400` on this endpoint.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the first day this endpoint may stop being served. Always `Fri, 15 Jan 2027 00:00:00 GMT` on this endpoint.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288: the replacement endpoint (`rel=\"successor-version\"`). Always `; rel=\"successor-version\"` on this endpoint.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The billing user or organization could not be resolved.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: when this endpoint was deprecated. Always `@1792022400` on this endpoint.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the first day this endpoint may stop being served. Always `Fri, 15 Jan 2027 00:00:00 GMT` on this endpoint.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288: the replacement endpoint (`rel=\"successor-version\"`). Always `; rel=\"successor-version\"` on this endpoint.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The audio was generated (and billed) and exceeds the response ceiling, and offloading it to storage failed. Retry, or request shorter output.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: when this endpoint was deprecated. Always `@1792022400` on this endpoint.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the first day this endpoint may stop being served. Always `Fri, 15 Jan 2027 00:00:00 GMT` on this endpoint.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288: the replacement endpoint (`rel=\"successor-version\"`). Always `; rel=\"successor-version\"` on this endpoint.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateMusicResponse413" } } } }, "422": { "description": "Request body failed validation (including a `format` whose codec the provider cannot produce), or the caller cannot afford the track - the latter is tagged `errorCode: \"insufficient_credits\"` (the balance is short, or the org member credit cap is exhausted).", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: when this endpoint was deprecated. Always `@1792022400` on this endpoint.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the first day this endpoint may stop being served. Always `Fri, 15 Jan 2027 00:00:00 GMT` on this endpoint.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288: the replacement endpoint (`rel=\"successor-version\"`). Always `; rel=\"successor-version\"` on this endpoint.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateMusicResponse422" } } } }, "502": { "description": "The provider failed to generate the track; reserved credits are refunded.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: when this endpoint was deprecated. Always `@1792022400` on this endpoint.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the first day this endpoint may stop being served. Always `Fri, 15 Jan 2027 00:00:00 GMT` on this endpoint.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288: the replacement endpoint (`rel=\"successor-version\"`). Always `; rel=\"successor-version\"` on this endpoint.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "No provider API key is configured for this deployment.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: when this endpoint was deprecated. Always `@1792022400` on this endpoint.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the first day this endpoint may stop being served. Always `Fri, 15 Jan 2027 00:00:00 GMT` on this endpoint.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288: the replacement endpoint (`rel=\"successor-version\"`). Always `; rel=\"successor-version\"` on this endpoint.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/ai/music\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"prompt\": \"calm lo-fi study beat with soft piano\",\n \"lengthMs\": 30000,\n \"forceInstrumental\": true\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/ai/music\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"prompt\": \"calm lo-fi study beat with soft piano\",\n \"lengthMs\": 30000,\n \"forceInstrumental\": true\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/ai/music\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"prompt\": \"calm lo-fi study beat with soft piano\",\n \"lengthMs\": 30000,\n \"forceInstrumental\": True\n },\n)" } ] } }, "/api/ai/sound-effects": { "post": { "operationId": "generateSoundEffect", "summary": "Generate a sound effect", "description": "Generates a short sound effect from a text description. Omitting `durationSeconds` lets the provider pick the length (and bills at its default); `promptInfluence` trades prompt fidelity (1) against variation (0). Credits are reserved before generation and refunded if it fails. `organization_id` picks the payer: an organization you belong to, or null for your personal credits; omitted bills your home organization (or personal credits if you have none). The default `encoding: \"binary\"` returns the raw audio bytes; `encoding: \"base64\"` returns JSON. Audio over the ~4MB response ceiling is returned by signed URL (a `303` for binary, the `delivery: \"url\"` variant for base64). Generated audio is saved to the file browser unless the call sets `preview`; the outcome is reported in the JSON save fields and the `X-B4M-Audio-*` headers - fetch the saved copy from `fileUrl` / `X-B4M-Audio-File-Url`, since `GET /api/files/{id}` fails closed until moderation completes. Authenticate with an API key (`b4m_live_`) or a JWT.", "tags": [ "Audio" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateSoundEffectRequest" } } } }, "responses": { "200": { "description": "Sound effect generated. Binary bodies carry a Content-Type that follows the requested `format` (mp3 by default). The default `encoding: \"binary\"` returns the raw audio bytes; `encoding: \"base64\"` returns the JSON body. Audio over the ~4MB response ceiling cannot ride in the body: the binary encoding answers `303` instead, and the base64 encoding returns the `delivery: \"url\"` variant, whose `url` is a time-limited signed GET for the audio (`bytes` is its size).", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-B4M-Audio-Saved": { "description": "Whether a browsable copy was saved to the file browser (\"true\"/\"false\").", "schema": { "type": "string" } }, "X-B4M-Audio-Fab-File-Id": { "description": "Id of the saved file. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Name": { "description": "File name of the saved copy. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Url": { "description": "Signed URL for the saved copy, minted at creation. Use this rather than re-resolving the file via GET /api/files/{id}, which fails closed until the async moderation scan completes.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateSoundEffectResponse200" } }, "audio/mpeg": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/opus": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/L16": { "schema": { "type": "string", "contentEncoding": "binary" } }, "audio/basic": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "303": { "description": "Binary encoding only: the audio exceeds the ~4MB response ceiling, so it was offloaded to storage and `Location` is a time-limited signed GET for it. HTTP clients that follow redirects receive the audio transparently (they drop the `Authorization` header on the cross-origin hop, as the signed URL requires); browser callers should use `encoding: \"base64\"`, since the storage origin sends no CORS headers. Carries the same `X-B4M-*` headers as the 200.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Location": { "description": "Signed URL of the offloaded audio.", "schema": { "type": "string" } }, "X-B4M-Audio-Saved": { "description": "Whether a browsable copy was saved to the file browser (\"true\"/\"false\").", "schema": { "type": "string" } }, "X-B4M-Audio-Fab-File-Id": { "description": "Id of the saved file. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Name": { "description": "File name of the saved copy. Present only when the copy was saved.", "schema": { "type": "string" } }, "X-B4M-Audio-File-Url": { "description": "Signed URL for the saved copy, minted at creation. Use this rather than re-resolving the file via GET /api/files/{id}, which fails closed until the async moderation scan completes.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The billing user or organization could not be resolved. An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope (`required_scopes` names it), or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateSoundEffectResponse403" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "A nonexistent `organization_id`, for an admin caller; for anyone else it is `403`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The audio was generated (and billed) and exceeds the response ceiling, and offloading it to storage failed. Retry, or request shorter output.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateSoundEffectResponse413" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "422": { "description": "Request body failed validation (including a `format` whose codec the provider cannot produce), or the caller cannot afford the effect - the latter is tagged `errorCode: \"insufficient_credits\"` (the balance is short, or the org member credit cap is exhausted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateSoundEffectResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "502": { "description": "The provider failed to generate the effect; reserved credits are refunded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "No provider API key is configured for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/ai/sound-effects\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"text\": \"heavy wooden door creaking open\",\n \"durationSeconds\": 3,\n \"promptInfluence\": 0.5\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/ai/sound-effects\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"text\": \"heavy wooden door creaking open\",\n \"durationSeconds\": 3,\n \"promptInfluence\": 0.5\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/ai/sound-effects\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"text\": \"heavy wooden door creaking open\",\n \"durationSeconds\": 3,\n \"promptInfluence\": 0.5\n },\n)" } ] } }, "/api/v1/me": { "get": { "operationId": "getMe", "summary": "Get the authenticated caller", "description": "Returns the authenticated caller: stable id, display name, plan tier, personal credit balance, and entitlement keys. The subject is always the credential holder - this endpoint accepts no user id, owner id, or impersonation parameter of any kind, so a key can only ever read its own owner. `credits.balance` is the caller's personal ledger; a call billed to an organization draws on a pool this number does not describe. Gate on `tier != \"free\"` for \"does this caller hold a paid plan (own or org seat)\" and on `subscription.price_id` for which product - the `basic`/`pro` rungs come from an internal plan ladder and do not track a plan's marketing name. An org seat (a Team plan held by the caller's organization) confers that org plan's tier and `subscription`, even when the caller pays nothing personally, so `tier != \"free\"` does not by itself mean the caller is billed. Responses are never cacheable. Authenticate with an API key (`b4m_live_`) carrying `me:read`, or a JWT.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "The caller, their tier, their personal credit balance, and their entitlement keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getMeResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "me:read" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/me\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/me\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/me\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/credits": { "get": { "operationId": "getCreditBalance", "summary": "Get the caller's credit balance", "description": "Returns the authenticated caller's spendable credit balance - the same number as `credits.balance` on `GET /api/v1/me`, without the identity and plan fields. Use it to check a key can afford a batch before starting one. The subject is always the credential holder; this endpoint accepts no user or owner id. `balance` is the caller's personal ledger; a call billed to an organization draws on a pool this number does not describe. Responses are never cacheable. Authenticate with an API key (`b4m_live_`) carrying any one of `me:read`, `ai:chat`, `ai:generate` or `ai:decide`, or a JWT.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "The caller's personal credit balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getCreditBalanceResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "me:read", "ai:chat", "ai:generate", "ai:decide" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/credits\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/credits\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/credits\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/models": { "get": { "operationId": "listModels", "summary": "List models", "description": "Lists the models the caller can use right now - the platform catalog filtered to the providers the caller has a key for, their own or the platform's. Use it to choose a `model` by capability before calling a generation endpoint: `context_window` and `max_output_tokens` for text models, and for image models the `image` block, which lists the accepted `size` values (or the rule they must meet) and whether `background`, `seed`, `quality`, `n` and reference images are honoured. To pick the cheapest text model, compare `credits_per_1m_tokens` - the rate a call is billed at. The list is cached for up to a minute per caller. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`. Sorted by `id` ascending. Authenticate with an API key (`b4m_live_`) carrying `ai:chat` or `ai:generate`, or a JWT.", "tags": [ "Models" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of models, ordered by `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listModelsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:chat", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/models\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/models\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/models\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/image-generations": { "post": { "operationId": "generateImage", "summary": "Generate an image", "description": "Queues an image generation and returns immediately with the quest that will carry the result - no image yet, and the call never blocks on the render. Poll `GET /api/v1/quests/{id}` until `status` is `\"done\"` (see the `generateImage200PollResult` schema). Omit `sessionId` to create a new session. The prompt is resolved against the session history first, so a follow-up such as \"make it darker\" binds to the previous image; `enhancedPrompt` reports the prompt actually sent to the model. Send `prompt_resolution: \"literal\"` to skip that step and have the prompt sent as written (apart from truncation to the model's prompt limit). `referenceImageFabFileIds` passes up to 15 already-uploaded images as style anchors, after the input image taken from `fabFileIds`. Only gpt-image models accept them: sending any with another model is rejected with a 400 rather than ignored. Which `size` values a model accepts, and whether it honours `background`, `seed`, `quality`, `n` and reference images, is listed per model in the `image` block of `GET /api/v1/models`. Credits are checked when the render runs, so insufficient credits arrive on the polled quest rather than as a 422. `organization_id` is accepted as an alias of `organizationId`, for callers used to the snake_case video and music bodies; `null` bills the personal account. `POST /api/ai/generate-image` is a legacy alias of this endpoint. Authenticate with an API key (`b4m_live_`) or a JWT.\n\nOptional `callbackUrl`: an https URL that receives a signed POST when the quest settles (success, failure, or a stop; a failed render is `type: \"error\"` in the body, same as the poll). The body is the `GET /api/v1/quests/{id}` response. Headers: `X-Webhook-Event-ID` (the same on every attempt for one settlement; delivery is at-least-once, so dedupe on it, and a retried quest settles again under a new one), `X-Webhook-Delivery-ID` (unique per attempt), `X-Webhook-Timestamp` (unix seconds), `X-Webhook-Signature-256` (`sha256=` + hex HMAC-SHA256 of `.` keyed with the API key's callback signing secret), and `X-Event-Type: quest.settled`. Delivery makes up to 5 attempts, retrying on a 5xx, 408, 429, timeout or network error - never on any other 4xx, and redirects are not followed; your endpoint must answer 2xx within 10 seconds. Requires API-key authentication and a signing secret on that key (returned once at key creation, or via `POST /api/user-api-keys/{id}/callback-secret`). A `callbackUrl` is rejected with a 400 when the request is not API-key authenticated, the key has no signing secret, the URL resolves to a private address, or the deployment does not deliver callbacks; a URL that is not https fails request validation with a 422. Polling still works whether or not `callbackUrl` is set.", "tags": [ "Images" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateImageRequest" } } } }, "responses": { "200": { "description": "Generation queued - NOT a finished render. `quest` has no images yet; its outcome arrives on `GET /api/v1/quests/{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateImageResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "x-poll-result": { "schema": { "$ref": "#/components/schemas/generateImage200PollResult" } } }, "400": { "description": "`referenceImageFabFileIds` is set for a non-gpt-image model, or the `callbackUrl` was rejected: the request is not API-key authenticated, the key has no callback signing secret, the URL resolves to a private address, or the deployment does not deliver callbacks. An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope, or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateImageResponse403" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "The session, or the quest being retried, does not exist or is not accessible to the caller. A nonexistent billing `organizationId` is `404` only for an admin caller; for anyone else, an invalid or inaccessible `organizationId` is `403` instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The body is malformed, or it names the billing organization ambiguously. Both `organizationId` and `organization_id` sent with different values is a `422`; so is an empty or blank value for either (a blank is never treated as an omission, which would bill a different payer), and so is any other billing-org-shaped key such as `billing_org_id` or `payerOrgId`, which would otherwise be stripped and silently bill the caller's home organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/image-generations\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"prompt\": \"a watercolor lighthouse at dusk\",\n \"model\": \"gpt-image-1\",\n \"size\": \"1024x1024\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/image-generations\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"prompt\": \"a watercolor lighthouse at dusk\",\n \"model\": \"gpt-image-1\",\n \"size\": \"1024x1024\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/image-generations\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"prompt\": \"a watercolor lighthouse at dusk\",\n \"model\": \"gpt-image-1\",\n \"size\": \"1024x1024\"\n },\n)" } ] } }, "/api/v1/image-edits": { "post": { "operationId": "editImage", "summary": "Edit an image", "description": "Queues an edit of an existing image and returns the quest that will carry the result, before the render runs. Poll `GET /api/v1/quests/{id}` until `status` is `\"done\"` (see the `editImage200PollResult` schema). `image` is the URL of the source image; `fabFileIds` must name at least one file, and the first is the inpainting mask. `referenceImageFabFileIds` adds up to 15 style anchors after the source image, so the mask always applies to the source; only gpt-image models accept them, and sending any with another model is rejected with a 400 rather than ignored. Both id fields take ids from `POST /api/v1/files`: upload each file, poll `GET /api/v1/files/{id}` until `moderation_status` is `clean`, then pass its `id`. An id that is not yet `clean` fails the edit on the polled quest. `image` takes a URL rather than an id, so a source uploaded the same way is passed as its `download_url`, which must still be unexpired when the render runs. The edited image is not a file id: read it from `files[].url` on the polled quest, not from `GET /api/v1/files/{id}`. `seed` makes an edit reproducible on BFL (FLUX) models only; gpt-image and Gemini models ignore it. Credits are checked when the render runs, so insufficient credits arrive on the polled quest rather than as a 422. `organization_id` is accepted as an alias of `organizationId`, for callers used to the snake_case video and music bodies; `null` bills the personal account. `POST /api/ai/edit-image` is a legacy alias of this endpoint. Authenticate with an API key (`b4m_live_`) or a JWT.\n\nOptional `callbackUrl`: an https URL that receives a signed POST when the quest settles (success, failure, or a stop; a failed render is `type: \"error\"` in the body, same as the poll). The body is the `GET /api/v1/quests/{id}` response. Headers: `X-Webhook-Event-ID` (the same on every attempt for one settlement; delivery is at-least-once, so dedupe on it, and a retried quest settles again under a new one), `X-Webhook-Delivery-ID` (unique per attempt), `X-Webhook-Timestamp` (unix seconds), `X-Webhook-Signature-256` (`sha256=` + hex HMAC-SHA256 of `.` keyed with the API key's callback signing secret), and `X-Event-Type: quest.settled`. Delivery makes up to 5 attempts, retrying on a 5xx, 408, 429, timeout or network error - never on any other 4xx, and redirects are not followed; your endpoint must answer 2xx within 10 seconds. Requires API-key authentication and a signing secret on that key (returned once at key creation, or via `POST /api/user-api-keys/{id}/callback-secret`). A `callbackUrl` is rejected with a 400 when the request is not API-key authenticated, the key has no signing secret, the URL resolves to a private address, or the deployment does not deliver callbacks; a URL that is not https fails request validation with a 422. Polling still works whether or not `callbackUrl` is set.", "tags": [ "Images" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editImageRequest" } } } }, "responses": { "200": { "description": "Edit queued - NOT a finished render. The body is the quest itself, with no images yet; its outcome arrives on `GET /api/v1/quests/{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editImageResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "x-poll-result": { "schema": { "$ref": "#/components/schemas/editImage200PollResult" } } }, "400": { "description": "`fabFileIds` is empty, `referenceImageFabFileIds` is set for a non-gpt-image model, or the `callbackUrl` was rejected: the request is not API-key authenticated, the key has no callback signing secret, the URL resolves to a private address, or the deployment does not deliver callbacks. An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope, or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/editImageResponse403" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "The session, or the quest being retried, does not exist or is not accessible to the caller. A nonexistent billing `organizationId` is `404` only for an admin caller; for anyone else, an invalid or inaccessible `organizationId` is `403` instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The body is malformed, or it names the billing organization ambiguously. Both `organizationId` and `organization_id` sent with different values is a `422`; so is an empty or blank value for either (a blank is never treated as an omission, which would bill a different payer), and so is any other billing-org-shaped key such as `billing_org_id` or `payerOrgId`, which would otherwise be stripped and silently bill the caller's home organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/image-edits\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"prompt\": \"replace the sky with a starry night\",\n \"model\": \"gpt-image-1\",\n \"sessionId\": \"664f1c2b9a1e4d0012ab34aa\",\n \"image\": \"https://example.com/source.png\",\n \"fabFileIds\": [\n \"664f1c2b9a1e4d0012ab34bb\"\n ]\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/image-edits\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"prompt\": \"replace the sky with a starry night\",\n \"model\": \"gpt-image-1\",\n \"sessionId\": \"664f1c2b9a1e4d0012ab34aa\",\n \"image\": \"https://example.com/source.png\",\n \"fabFileIds\": [\n \"664f1c2b9a1e4d0012ab34bb\"\n ]\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/image-edits\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"prompt\": \"replace the sky with a starry night\",\n \"model\": \"gpt-image-1\",\n \"sessionId\": \"664f1c2b9a1e4d0012ab34aa\",\n \"image\": \"https://example.com/source.png\",\n \"fabFileIds\": [\n \"664f1c2b9a1e4d0012ab34bb\"\n ]\n },\n)" } ] } }, "/api/v1/files": { "post": { "operationId": "createFileUpload", "summary": "Start a file upload", "description": "Registers a file and returns a presigned `upload_url`. Uploading is three steps: (1) call this endpoint with the file name, MIME type, and size in bytes; (2) `PUT` the raw bytes to `upload_url` before `upload_url_expires_at` - send no `Authorization` header, the URL signature is the credential, and do send a `Content-Type` matching `mime_type`; (3) poll `GET /api/v1/files/{id}` until `moderation_status` is `clean` (usually a few seconds after the PUT), then pass `id` wherever an endpoint takes a file id (for example `fabFileIds` and `referenceImageFabFileIds` on `POST /api/v1/image-edits`). Unsupported types, a size over the upload limit, or a size that would exceed your storage quota are rejected with 400 before any URL is issued. Authenticate with an API key (`b4m_live_`) carrying `files:write`, or a JWT.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createFileUploadRequest" } } } }, "responses": { "201": { "description": "The file is registered; PUT its bytes to `upload_url`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createFileUploadResponse201" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Unsupported file type, file larger than the upload limit, or storage quota exceeded. A size or quota refusal carries a stable `errorCode` plus `used_bytes`, `limit_bytes`, `requested_bytes` and `owner`, always together; an unsupported type carries none of them. This endpoint checks only the user quota and the per-file cap, so `org_storage_limit_exceeded` is never returned here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createFileUploadResponse400" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "files:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/files\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"file_name\": \"reference.png\",\n \"mime_type\": \"image/png\",\n \"file_size\": 482133\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/files\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"file_name\": \"reference.png\",\n \"mime_type\": \"image/png\",\n \"file_size\": 482133\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/files\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"file_name\": \"reference.png\",\n \"mime_type\": \"image/png\",\n \"file_size\": 482133\n },\n)" } ] }, "get": { "operationId": "listFiles", "summary": "List files", "description": "Lists the files you own, newest first, excluding archived and deleted ones. Files shared with you are not listed, though `GET /api/v1/files/{id}` resolves them by id: listing shares would need access checks that cannot be paged by cursor. Items carry no `download_url`; fetch a file by id for its bytes. `search` keeps only files whose name contains it, ignoring case; results stay newest first with no relevance ranking. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor`, with the same `search`, until it is `null`. Safe (GET) requests are exempt from the per-day API-key quota; only the per-minute burst limit applies. Authenticate with an API key (`b4m_live_`) carrying `files:read`, or a JWT.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "One page of files, newest first by `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listFilesResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `files:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` or `search` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "files:read" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/files\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/files\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/files\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/files/{id}": { "get": { "operationId": "getFile", "summary": "Get a file", "description": "Returns a file you own or that has been shared with you, with a short-lived signed `download_url` once it is downloadable. This is both the upload poll (after `POST /api/v1/files`) and the way to fetch any file id another endpoint hands back. `download_url` is `null` until `moderation_status` is `clean`; it expires at `download_url_expires_at`, so re-read this endpoint rather than storing it. Safe (GET) requests are exempt from the per-day API-key quota: a poll consumes no daily slot, and only the per-minute burst limit applies. Authenticate with an API key (`b4m_live_`) carrying `files:read`, or a JWT.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The file, and a download URL if it is downloadable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getFileResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `files:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No file with that id is visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "files:read" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/files/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/files/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/files/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "patch": { "operationId": "updateFile", "summary": "Update a file", "description": "Renames a file you can edit or changes its notes: a file you own, or one shared with you with edit (`update`) permission. Omitted fields are left unchanged. Unknown body fields are rejected. The response is the file summary, with no `download_url`: fetch the bytes from `GET /api/v1/files/{id}`, which requires `files:read`.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateFileRequest" } } } }, "responses": { "200": { "description": "The updated file summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateFileResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `files:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No file with that id is yours to edit. A file you cannot edit, one that does not exist and a malformed id are all reported as 404, so file ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "files:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X PATCH \"https://your-deployment.example.com/api/v1/files/\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"file_name\": \"q3-notes.pdf\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/files/\", {\n method: \"PATCH\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"file_name\": \"q3-notes.pdf\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.patch(\n \"https://your-deployment.example.com/api/v1/files/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"file_name\": \"q3-notes.pdf\"\n },\n)" } ] }, "delete": { "operationId": "deleteFile", "summary": "Delete a file", "description": "Deletes a file you own and frees its storage. On a file shared with you it removes only your access (an unshare): the owner's file is kept.", "tags": [ "Files" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "The file was deleted, or your access to it was removed.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `files:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No file with that id is yours or shared with you directly (a file you reach only through a group or a data lake cannot be deleted here). A file that does not exist and a malformed id are both reported as 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "files:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE \"https://your-deployment.example.com/api/v1/files/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/files/\", {\n method: \"DELETE\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.delete(\n \"https://your-deployment.example.com/api/v1/files/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/embeddings": { "post": { "operationId": "createEmbeddings", "summary": "Create embeddings", "description": "Returns one embedding vector per input string. The request and success bodies follow the OpenAI embeddings API shape; error bodies use the standard B4M error envelope. `model` is any embedding model this deployment supports (OpenAI, Voyage AI, Amazon Bedrock, or a self-hosted Ollama model); `input` is a string or up to 2048 strings, at most 300000 tokens in total and each within the model context window. The input count is further capped so inputs x output width stays within 196608 values (128 inputs at 1536 dimensions) - page larger jobs across requests. Pre-tokenized input (arrays of token ids) is not accepted; clients that send it by default, such as LangChain's Python `OpenAIEmbeddings`, must be set to send strings (`check_embedding_ctx_length=False`). `dimensions` shortens the vector on models that support it (OpenAI `text-embedding-3-*`, and Voyage models with several published widths). Billed in credits per input token from the per-model embedding rate, reserved before the provider call and refunded if it fails. Authenticate with an API key (`b4m_live_`) carrying `ai:generate`, or a JWT.", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createEmbeddingsRequest" } } } }, "responses": { "200": { "description": "One embedding per input, in input order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createEmbeddingsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The billing user or organization could not be resolved, or the API key bills an organization its owner is no longer a member of.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing/invalid credentials, or the embedding provider refused the configured key (`errorCode: \"provider_rejected\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createEmbeddingsResponse401" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation, an input exceeds the model context window, the request exceeds the token or response-size ceiling, the model has no published credit rate, the model cannot produce the requested `dimensions`, or the caller cannot afford the request - the last is tagged `errorCode: \"insufficient_credits\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createEmbeddingsResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-key rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "502": { "description": "The embedding provider failed; reserved credits are refunded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "This deployment has no credential for the requested model's provider (`errorCode: \"provider_not_configured\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createEmbeddingsResponse503" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/embeddings\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"model\": \"text-embedding-3-small\",\n \"input\": [\n \"The quick brown fox\",\n \"jumps over the lazy dog\"\n ],\n \"dimensions\": 1024\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/embeddings\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"model\": \"text-embedding-3-small\",\n \"input\": [\n \"The quick brown fox\",\n \"jumps over the lazy dog\"\n ],\n \"dimensions\": 1024\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/embeddings\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"model\": \"text-embedding-3-small\",\n \"input\": [\n \"The quick brown fox\",\n \"jumps over the lazy dog\"\n ],\n \"dimensions\": 1024\n },\n)" } ] } }, "/api/v1/decisions": { "post": { "operationId": "createDecision", "summary": "Answer typed questions with probabilities", "description": "Evaluates each question independently against the same `input` and returns calibrated probabilities - no generated text. Question types: `predicate` (probability a statement is true), `choice` (pick one value) and `score` (an ordered scale; `score` is the probability-weighted mean of 0-based level indices). `confidence` is computed by B4M with one published formula for every model. Answers come back in question order; a question the model declines is a `refusal` answer and does not fail the request. `input` is a string or a list of `text`, `json` and `image` parts; an image is a `file_id` you can read or a base64 `data:` URL (http(s) URLs are rejected). Platform ceilings: 50 questions, 64 choices, 2-10 levels and 8 images; each model's own caps are listed by `GET /api/v1/decision-models` and a request over one is a 422 naming the cap and `param`. Probabilities are not comparable across models: tune thresholds per model against labelled examples, and pin a versioned model id when you do. A busy provider is retried once on the same model, never another; after that the response is a 503 with `Retry-After`. Billed per input and output token at the model's rate, settled to the exact expected cost (most calls charge 0 credits, some 1). Authenticate with an API key (`b4m_live_`) carrying `ai:decide` or `ai:generate`, or a JWT.", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDecisionRequest" } } } }, "responses": { "200": { "description": "One answer per question, in question order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDecisionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The billing user or organization could not be resolved, or the API key bills an organization its owner is no longer a member of.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing/invalid credentials, or the provider refused the configured key (`errorCode: \"provider_rejected\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDecisionResponse401" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "The API key holds neither `ai:decide` nor `ai:generate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "An image `file_id` does not exist or is not readable by the caller. Reading one also needs the `files:read` scope; a key without it gets 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDecisionResponse404" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The body failed validation, or the request exceeds a per-model cap (`limit_exceeded`), sends an image to a text-only model (`unsupported_input`), repeats a question name or choice value (`invalid_request`), names a model this deployment does not serve (`model_unavailable`), overflows the model context (`context_length_exceeded`), or the caller cannot afford it (`insufficient_credits`). `param` names the offending field when there is one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDecisionResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-key or per-user decisions rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "502": { "description": "The provider failed or answered something that does not fit the questions (`provider_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDecisionResponse502" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "The provider stayed overloaded through one same-model retry (`errorCode: \"provider_overloaded\"`), or this deployment has no credential for the model (`errorCode: \"provider_not_configured\"`).", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying; sent with `provider_overloaded`.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createDecisionResponse503" } } } } }, "x-required-scopes": [ "ai:decide", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/decisions\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"model\": \"gpt-6-luna\",\n \"input\": [\n {\n \"type\": \"text\",\n \"text\": \"Help! My payouts have been failing for 3 days.\"\n },\n {\n \"type\": \"json\",\n \"json\": {\n \"plan\": \"pro\",\n \"open_tickets\": 2\n }\n }\n ],\n \"questions\": [\n {\n \"type\": \"predicate\",\n \"name\": \"is_urgent\",\n \"instructions\": \"The customer needs a reply within 24 hours.\"\n },\n {\n \"type\": \"choice\",\n \"name\": \"team\",\n \"instructions\": \"Which team should handle this?\",\n \"choices\": [\n {\n \"value\": \"billing\",\n \"description\": \"Payments, payouts, refunds\"\n },\n {\n \"value\": \"technical\",\n \"description\": \"Bugs, outages\"\n },\n {\n \"value\": \"sales\"\n }\n ]\n },\n {\n \"type\": \"score\",\n \"name\": \"frustration\",\n \"instructions\": \"How frustrated is the customer?\",\n \"levels\": [\n {\n \"label\": \"calm\"\n },\n {\n \"label\": \"frustrated\"\n },\n {\n \"label\": \"angry\",\n \"description\": \"Threatens to churn\"\n }\n ]\n }\n ]\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/decisions\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"model\": \"gpt-6-luna\",\n \"input\": [\n {\n \"type\": \"text\",\n \"text\": \"Help! My payouts have been failing for 3 days.\"\n },\n {\n \"type\": \"json\",\n \"json\": {\n \"plan\": \"pro\",\n \"open_tickets\": 2\n }\n }\n ],\n \"questions\": [\n {\n \"type\": \"predicate\",\n \"name\": \"is_urgent\",\n \"instructions\": \"The customer needs a reply within 24 hours.\"\n },\n {\n \"type\": \"choice\",\n \"name\": \"team\",\n \"instructions\": \"Which team should handle this?\",\n \"choices\": [\n {\n \"value\": \"billing\",\n \"description\": \"Payments, payouts, refunds\"\n },\n {\n \"value\": \"technical\",\n \"description\": \"Bugs, outages\"\n },\n {\n \"value\": \"sales\"\n }\n ]\n },\n {\n \"type\": \"score\",\n \"name\": \"frustration\",\n \"instructions\": \"How frustrated is the customer?\",\n \"levels\": [\n {\n \"label\": \"calm\"\n },\n {\n \"label\": \"frustrated\"\n },\n {\n \"label\": \"angry\",\n \"description\": \"Threatens to churn\"\n }\n ]\n }\n ]\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/decisions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"model\": \"gpt-6-luna\",\n \"input\": [\n {\n \"type\": \"text\",\n \"text\": \"Help! My payouts have been failing for 3 days.\"\n },\n {\n \"type\": \"json\",\n \"json\": {\n \"plan\": \"pro\",\n \"open_tickets\": 2\n }\n }\n ],\n \"questions\": [\n {\n \"type\": \"predicate\",\n \"name\": \"is_urgent\",\n \"instructions\": \"The customer needs a reply within 24 hours.\"\n },\n {\n \"type\": \"choice\",\n \"name\": \"team\",\n \"instructions\": \"Which team should handle this?\",\n \"choices\": [\n {\n \"value\": \"billing\",\n \"description\": \"Payments, payouts, refunds\"\n },\n {\n \"value\": \"technical\",\n \"description\": \"Bugs, outages\"\n },\n {\n \"value\": \"sales\"\n }\n ]\n },\n {\n \"type\": \"score\",\n \"name\": \"frustration\",\n \"instructions\": \"How frustrated is the customer?\",\n \"levels\": [\n {\n \"label\": \"calm\"\n },\n {\n \"label\": \"frustrated\"\n },\n {\n \"label\": \"angry\",\n \"description\": \"Threatens to churn\"\n }\n ]\n }\n ]\n },\n)" } ] } }, "/api/v1/decision-models": { "get": { "operationId": "listDecisionModels", "summary": "List the decision models you can use", "description": "Returns the decision models you can call right now, with their per-model caps and USD token prices. A model is listed only when a key for its provider is available to you (your own provider key or one the deployment configures), so the list can differ between callers and grows when a key is added. A floating alias carries `alias_of`; pin the versioned id when you tune thresholds, since a new version can shift probabilities. The catalog is a handful of entries, so it is returned whole, not paginated (as `GET /api/v1/video-models`).", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "The models you can call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listDecisionModelsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `ai:decide` nor `ai:generate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-key or per-user decisions rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:decide", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/decision-models\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/decision-models\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/decision-models\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/quests/{id}": { "get": { "operationId": "getQuest", "summary": "Get a quest", "description": "Polls the outcome of a turn started by `POST /api/chat` or an async generation route. `status` `done` and `stopped` are terminal; `pending` and `running` are not. A finished turn that failed has `type: \"error\"` and, where classified, an `errorCode`; a `stopped` turn is also a failure even without `type: \"error\"`, and its `reply` is an explanation rather than an answer. A `404` covers a quest that does not exist, one whose session was deleted, and one the caller cannot see, so polling after deleting the session returns `404`. Safe (GET) requests are exempt from the per-day API-key quota: a poll consumes no daily slot, and only the per-minute burst limit applies.", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The quest id returned by POST /api/chat or another async start." }, "required": true, "description": "The quest id returned by POST /api/chat or another async start.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The quest and its outcome so far.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getQuestResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "404": { "description": "No quest with that id is visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:read", "ai:chat", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/quests/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/quests/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/quests/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/quests/{id}/files": { "get": { "operationId": "listQuestFiles", "summary": "List quest files", "description": "Returns the files attached to one quest (one turn of a session): what was sent with the message and what the turn produced. Each carries a short-lived signed `download_url` once downloadable; re-read this endpoint rather than storing it. Not paginated: a quest holds a bounded set of files. A `404` covers a quest that does not exist and one in a session the caller cannot see.", "tags": [ "AI" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The quest id returned by POST /api/chat or another async start." }, "required": true, "description": "The quest id returned by POST /api/chat or another async start.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The quest's files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listQuestFilesResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds none of `notebooks:read`, `ai:chat` or `ai:generate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No quest with that id is visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:read", "ai:chat", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/quests//files\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/quests//files\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/quests//files\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/sessions": { "post": { "operationId": "createSession", "summary": "Create a session", "description": "Creates a session (called a \"notebook\" in the product UI). Pass the returned `id` as `sessionId` to `POST /api/chat`, then poll `GET /api/v1/quests/{id}` for the reply. An API key needs `notebooks:write` for this call, so a chat round trip needs that scope as well as `ai:chat`. A key holding `ai:generate` without `notebooks:write` may create a bare session only (`name`, `lastUsedModel`, `temperature`, `autoNamePlaceholder`); any other field is a 403. Unknown body fields are ignored. Naming a data lake with `dataLakeId` (ids come from `GET /api/v1/data-lakes`) seeds the session with that lake's retrieval defaults and turns on forced retrieval.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createSessionRequest" } } } }, "responses": { "200": { "description": "The created session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createSessionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The request could not be processed (for example a bad project id).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The key lacks `notebooks:write` (or holds only `ai:generate` and set a field beyond a bare session), is not bound to a requested data lake, or the caller is not entitled to the requested `surface`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "A named data lake or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:write", "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/sessions\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"name\": \"Quarterly analysis\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/sessions\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"name\": \"Quarterly analysis\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/sessions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"name\": \"Quarterly analysis\"\n },\n)" } ] }, "get": { "operationId": "listSessions", "summary": "List sessions", "description": "Lists the sessions you own (called \"notebooks\" in the product UI), newest first. Sessions shared with you are not included; read one of those by id with `GET /api/sessions/{id}`. Each item has the same shape `GET /api/sessions/{id}` returns. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`. Changing `search`, `surface` or `origin` starts a new listing, so drop the cursor when you do. An API key needs `notebooks:read` or `notebooks:write`.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match on the session name, its summary, or a tag name." }, "required": false, "description": "Case-insensitive substring match on the session name, its summary, or a tag name.", "name": "search", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Lists only sessions of this product surface. When omitted, only sessions with no surface are listed." }, "required": false, "description": "Lists only sessions of this product surface. When omitted, only sessions with no surface are listed.", "name": "surface", "in": "query" }, { "schema": { "type": "string", "enum": [ "web", "api", "slack", "cli", "agent" ], "description": "Lists only sessions created through this channel. `web` also matches sessions with no recorded origin." }, "required": false, "description": "Lists only sessions created through this channel. `web` also matches sessions with no recorded origin.", "name": "origin", "in": "query" } ], "responses": { "200": { "description": "One page of sessions, newest first by `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listSessionsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `notebooks:read` nor `notebooks:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` is out of range, a filter is malformed, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:read", "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/sessions\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/sessions\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/sessions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/data-lakes": { "get": { "operationId": "listDataLakes", "summary": "List data lakes", "description": "Lists the data lakes the caller can reach as a member: lakes they own, lakes shared with them through an organization or an access grant, public lakes, and the built-in lakes their plan entitles them to. Platform-administrator reach is deliberately NOT applied here, so an admin key lists its owner's own lakes rather than every lake on the platform. Only `draft` and `active` lakes are listed. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`.", "tags": [ "Data Lakes" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of lakes, ordered by `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listDataLakesResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds none of `datalake:read`, `datalake:write` or `datalake:query`, or Data Lakes are disabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "datalake:read", "datalake:write", "datalake:query" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/data-lakes\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/data-lakes\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/data-lakes\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/data-lakes/{id}": { "get": { "operationId": "getDataLake", "summary": "Get a data lake", "description": "Returns one data lake by id or slug. Every caller - owner and editor included - receives the same reader projection; management settings are not part of the public shape. `file_count` and `total_size_bytes` for a built-in lake are computed live.", "tags": [ "Data Lakes" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The lake.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getDataLakeResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds none of `datalake:read`, `datalake:write` or `datalake:query`, or Data Lakes are disabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No lake with that id or slug is visible to the caller. A lake that exists but is not yours to read is reported as 404 too, so lake ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "datalake:read", "datalake:write", "datalake:query" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/data-lakes/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/data-lakes/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/data-lakes/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/data-lakes/{id}/files/{file_id}": { "get": { "operationId": "getDataLakeFile", "summary": "Get a data lake file", "description": "Returns a lake member's ingestion status. Adding a file to a lake does NOT ingest it: a file only becomes searchable once it has been chunked and embedded, so poll this endpoint until `ingestion_status` is `ready`. `indexing` clears on its own; `paused` means re-processing was stopped partway and needs the file reprocessed (or background lake work resumed) before it returns; `failed` carries the reason in `error`. A `ready` file can also carry a non-null `error` when a later pass failed partway: its committed passages stay searchable, so branch on `ingestion_status`, not on `error`. `not_ingested` means the file has no searchable passages yet: ingestion has not started, a first pass has not committed its chunks, or the file has no extractable text (such a file never becomes `ready`). These agree with what search reports under `retrieval_unavailable`.", "tags": [ "Data Lakes" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "file_id", "in": "path" } ], "responses": { "200": { "description": "The member file and its ingestion state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getDataLakeFileResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds none of `datalake:read`, `datalake:write` or `datalake:query`, or Data Lakes are disabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "The lake is not visible to the caller, or the file does not exist, was deleted, or is not a current member of this lake. All of these are one 404, so neither lake nor file ids can be probed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "datalake:read", "datalake:write", "datalake:query" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/data-lakes//files/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/data-lakes//files/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/data-lakes//files/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "post": { "operationId": "addDataLakeFile", "summary": "Add a file to a data lake", "description": "Makes an existing file a member of the lake. Takes no body. Idempotent: adding a file that is already a member succeeds and changes nothing. Outside the restore window below, a caller can add only their own files (or, as the lake's owner, the owner's files); any other file is a 404. Membership alone does not ingest the file - poll `GET /api/v1/data-lakes/{id}/files/{file_id}` until it is `ready` before relying on it in search. Re-adding a file within about 30 minutes of removing it restores the membership it had.", "tags": [ "Data Lakes" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "file_id", "in": "path" } ], "responses": { "200": { "description": "The file is a member; the lake's updated totals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addDataLakeFileResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The file does not meet the lake's admission policy (for example, its passages were chunked to a size the lake does not accept). Reprocess the file to the required size, then add it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `datalake:write`, the caller can read this lake but may not change its membership (including every built-in lake, which is read-only), or Data Lakes are disabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "The lake is not visible to the caller, or the file does not exist, was deleted, or is not one the caller may add. Reported as one 404 so file ids cannot be probed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "datalake:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/data-lakes//files/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/data-lakes//files/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/data-lakes//files/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "delete": { "operationId": "removeDataLakeFile", "summary": "Remove a file from a data lake", "description": "Drops the file from the lake. Only membership changes: the file itself and its indexed passages are untouched, and the file's owner still finds it in their own library. Re-adding it within about 30 minutes (`POST` on the same path) restores the membership it had.", "tags": [ "Data Lakes" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "file_id", "in": "path" } ], "responses": { "200": { "description": "The file is no longer a member; the lake's updated totals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/removeDataLakeFileResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `datalake:write`, the caller can read this lake but may not change its membership (including every built-in lake, which is read-only), or Data Lakes are disabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "The lake is not visible to the caller, or the file is not a current member of it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "datalake:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE \"https://your-deployment.example.com/api/v1/data-lakes//files/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/data-lakes//files/\", {\n method: \"DELETE\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.delete(\n \"https://your-deployment.example.com/api/v1/data-lakes//files/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/data-lakes/{id}/search": { "post": { "operationId": "searchDataLake", "summary": "Search a data lake", "description": "Semantic (vector) search over one lake: the query is embedded with the model the corpus was indexed with and the top `top_k` passages at or above `min_score` are returned. Only members of this lake are searched - never the caller's other files. `tags` narrows to files carrying any of the listed tags. Files still being indexed or paused are withheld rather than searched stale: `partial_results` is then true and `retrieval_unavailable` counts them (poll `GET /api/v1/data-lakes/{id}/files/{file_id}` for a specific file). The query embedding is billed as credits. Limited to 10 searches per minute per caller, shared with the product UI.", "tags": [ "Data Lakes" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/searchDataLakeRequest" } } } }, "responses": { "200": { "description": "The ranked passages and what, if anything, was withheld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/searchDataLakeResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The API key bills an organization that no longer exists, or one its owner is no longer a member of.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `datalake:query`, or Data Lakes are disabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No lake with that id or slug is visible to the caller. A lake that exists but is not yours to read is reported as 404 too, so lake ids cannot be probed through this endpoint. A lake the caller can read but is not entitled to search is reported the same way, as is a lake that is not `active` yet (a draft lake is readable but not yet searchable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation, or the caller cannot afford the query embedding - the latter is tagged `errorCode: \"insufficient_credits\"` (the balance is short, or the org member credit cap is exhausted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/searchDataLakeResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Search rate limit (10 per minute) or per-user API rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "No usable key is configured on this deployment for the embedding provider the query needs (`errorCode: \"provider_not_configured\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/searchDataLakeResponse503" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "datalake:query" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/data-lakes//search\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"query\": \"What is our refund policy for annual plans?\",\n \"top_k\": 5\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/data-lakes//search\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"query\": \"What is our refund policy for annual plans?\",\n \"top_k\": 5\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/data-lakes//search\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"query\": \"What is our refund policy for annual plans?\",\n \"top_k\": 5\n },\n)" } ] } }, "/api/v1/video-generations/{id}/cancel": { "post": { "operationId": "cancelVideoGeneration", "summary": "Cancel a video generation", "description": "Requests cancellation and returns the job. A `pending` or `running` job moves to `cancelled` shortly after and its reserved credits are returned. A job already `storing` or finished is returned unchanged (the provider has already produced, and charged for, the video).", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The job after the cancel request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancelVideoGenerationResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No video generation with that id was requested by the caller (a malformed id is also a 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/video-generations//cancel\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/video-generations//cancel\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/video-generations//cancel\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/video-generations": { "post": { "operationId": "createVideoGeneration", "summary": "Start a video generation", "description": "Queues a video generation and returns `202` with the job. Poll `GET /api/v1/video-generations/{id}` until `state` is `succeeded`, `failed`, `blocked` or `cancelled`. On success, `output.availability` says whether the clip can be downloaded: `ready` means `output.url` is a signed download URL valid for 15 minutes (re-fetch the job for a fresh one); `pending_scan` means the saved file is still being scanned, so keep re-fetching the job (self-hosted installs can stay here for up to ~30 minutes); `unavailable` means the file was blocked or deleted and `output.url` will never be set, so stop polling. Credits for the requested duration are reserved up front and settled on completion; a failed or cancelled job is not charged. A `blocked` job is not charged either, unless the provider generated the clip before rejecting it and billed it: then the requested duration is charged and `credits.settled` shows it. Send an `Idempotency-Key` header (1-255 printable ASCII characters) to make retries safe: a repeat with the same key and body returns the original job, and the same key with a different body is a 422 `idempotency_key_reused`. Omitted fields take the model defaults from `GET /api/v1/video-models`. Set `organization_id` to bill an organization you belong to, or `null` to bill your personal credits; omitted, the job bills your home organization (or your personal credits if you have none). Keys are scoped to the billed account, so the same key sent for a different `organization_id` starts a new job. An organization-billed API key always bills its own organization (see `organization_id`).", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVideoGenerationRequest" } } } }, "responses": { "202": { "description": "Accepted; the job is queued (or replayed for a repeated Idempotency-Key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVideoGenerationResponse202" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope, or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVideoGenerationResponse403" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "`input_image_file_id` does not name an image you own (`errorCode: input_image_not_found`). A nonexistent `organization_id` is `404` only for an admin caller; for anyone else it is `403`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVideoGenerationResponse404" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request cannot run: a body or capability violation (`errorCode` names it, e.g. `unsupported_duration`), an unknown or unavailable model (`model_unavailable`), a model your administrator disabled (`model_disabled`), too few credits (`insufficient_credits`), or an Idempotency-Key problem (`invalid_idempotency_key`, `idempotency_key_reused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVideoGenerationResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/video-generations\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"A slow dolly shot of a red lighthouse at dusk\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/video-generations\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"A slow dolly shot of a red lighthouse at dusk\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/video-generations\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"A slow dolly shot of a red lighthouse at dusk\"\n },\n)" } ] }, "get": { "operationId": "listVideoGenerations", "summary": "List your video generations", "description": "Your jobs, newest first, optionally filtered by `state` and `source`. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "required": false, "name": "source", "in": "query" } ], "responses": { "200": { "description": "A page of jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listVideoGenerationsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "A malformed `cursor`, `limit`, `state` or `source`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/video-generations\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/video-generations\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/video-generations\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/video-generations/{id}": { "get": { "operationId": "getVideoGeneration", "summary": "Get a video generation", "description": "Returns one job you requested. Each read signs a fresh `output.url` (valid 15 minutes, see `expires_at`).", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getVideoGenerationResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No video generation with that id was requested by the caller (a malformed id is also a 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/video-generations/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/video-generations/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/video-generations/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/video-models": { "get": { "operationId": "listVideoModels", "summary": "List the video models you can use", "description": "Returns the video models that are enabled, available in this deployment and have a usable provider key for the caller, with their capabilities and per-second credit price. Validate requests against these capabilities: an unsupported duration, aspect ratio or resolution is a 422, never silently adjusted.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "The usable models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listVideoModelsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/video-models\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/video-models\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/video-models\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/music-generations/{id}/cancel": { "post": { "operationId": "cancelMusicGeneration", "summary": "Cancel a music generation", "description": "Requests cancellation and returns the job. A job still `pending` (waiting to start, or to retry) moves to `cancelled` shortly after and its reserved credits are returned. The provider renders a song in one call that cannot be interrupted and is billed once it starts, so a `running` job cannot be cancelled: the request is refused with a 409 (`not_cancellable`), and the job runs to its end, charged if the song is produced. A finished job is returned unchanged.", "tags": [ "Music" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The job after the cancel request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancelMusicGenerationResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No music generation with that id was requested by the caller (a malformed id is also a 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The song is already rendering (`running`); `errorCode` is `not_cancellable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancelMusicGenerationResponse409" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/music-generations//cancel\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/music-generations//cancel\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/music-generations//cancel\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/music-generations": { "post": { "operationId": "createMusicGeneration", "summary": "Start a music generation", "description": "Queues a song and returns `202` with the job. Poll `GET /api/v1/music-generations/{id}` until `state` is `succeeded`, `failed`, `blocked` or `cancelled`. A finished song is saved to your Files with the `generated` tag (if that save fails it is kept outside Files and `output.file_id` is null). On success, `output.availability` says whether it can be downloaded: `ready` means `output.url` is a signed download URL valid for 15 minutes (re-fetch the job for a fresh one); `pending_scan` means the saved file is still being scanned, so keep re-fetching the job (self-hosted installs can stay here for up to ~30 minutes); `unavailable` means the file was blocked or deleted and `output.url` will never be set, so stop polling. Credits for the model's price are reserved up front and settled on completion; a failed or cancelled job is not charged. A `blocked` job is not charged either, unless the provider generated the song before rejecting it and billed it: then the price is charged and `credits.settled` shows it. Send an `Idempotency-Key` header (1-255 printable ASCII characters) to make retries safe: a repeat with the same key and body returns the original job, and the same key with a different body is a 422 `idempotency_key_reused`. Omitted fields take the model defaults from `GET /api/v1/music-models`. Set `organization_id` to bill an organization you belong to, or `null` to bill your personal credits; omitted, the job bills your home organization (or your personal credits if you have none). Keys are scoped to the billed account, so the same key sent for a different `organization_id` starts a new job. An organization-billed API key always bills its own organization (see `organization_id`).", "tags": [ "Music" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createMusicGenerationRequest" } } } }, "responses": { "202": { "description": "Accepted; the job is queued (or replayed for a repeated Idempotency-Key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createMusicGenerationResponse202" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Your Files storage has no room for the song (`storage_limit_exceeded`, as on the Files upload routes). The body carries `used_bytes`, `limit_bytes`, `requested_bytes` and `owner`, always together; `requested_bytes` here is the most the song can take at the requested length, not its final size. This endpoint checks only the user quota, so `org_storage_limit_exceeded` is never returned here. An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createMusicGenerationResponse400" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope, or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createMusicGenerationResponse403" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "A nonexistent `organization_id`, for an admin caller; for anyone else it is `403`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request cannot run: a malformed body, a capability violation (`errorCode` names it, e.g. `unsupported_duration` or `lyrics_too_long`), an unknown or unavailable model (`model_unavailable`), a model your administrator disabled (`model_disabled`), too few credits (`insufficient_credits`), or an Idempotency-Key problem (`invalid_idempotency_key`, `idempotency_key_reused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createMusicGenerationResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/music-generations\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"model\": \"lyria-3.5\",\n \"prompt\": \"An upbeat synth-pop song about a road trip at sunrise\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/music-generations\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"model\": \"lyria-3.5\",\n \"prompt\": \"An upbeat synth-pop song about a road trip at sunrise\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/music-generations\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"model\": \"lyria-3.5\",\n \"prompt\": \"An upbeat synth-pop song about a road trip at sunrise\"\n },\n)" } ] }, "get": { "operationId": "listMusicGenerations", "summary": "List your music generations", "description": "Your jobs, newest first, optionally filtered by `state` and `source`. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`.", "tags": [ "Music" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "running", "storing", "succeeded", "failed", "blocked", "cancelled" ] }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string", "enum": [ "api", "studio", "agent" ] }, "required": false, "name": "source", "in": "query" } ], "responses": { "200": { "description": "A page of jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listMusicGenerationsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "A malformed `cursor`, `limit`, `state` or `source`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/music-generations\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/music-generations\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/music-generations\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/music-generations/{id}": { "get": { "operationId": "getMusicGeneration", "summary": "Get a music generation", "description": "Returns one job you requested. Each read signs a fresh `output.url` (valid 15 minutes, see `expires_at`).", "tags": [ "Music" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getMusicGenerationResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No music generation with that id was requested by the caller (a malformed id is also a 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/music-generations/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/music-generations/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/music-generations/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/music-models": { "get": { "operationId": "listMusicModels", "summary": "List the music models you can use", "description": "Returns the music models that are enabled, available in this deployment and have a usable provider key for the caller, with their capabilities and credit price. Validate requests against these capabilities: an unsupported duration, lyrics or vocals option is a 422, never silently adjusted. A few limits only show when the song is rendered (e.g. more lyrics than fit a very short song); such a job ends `failed`.", "tags": [ "Music" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "The usable models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listMusicModelsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks the `ai:generate` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/music-models\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/music-models\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/music-models\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/voice/voices": { "get": { "operationId": "listVoices", "summary": "List voices", "description": "Lists the voices available in the configured ElevenLabs workspace. The list is not paged: it is the whole workspace catalog, cached in memory per server instance for up to 15 minutes. `GET /api/voice/v2/voices` is a legacy alias of this endpoint. Authenticate with an API key (`b4m_live_`) or a JWT.", "tags": [ "Voice" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "The workspace voices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listVoicesResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold `ai:generate`, or Voice is not enabled on this deployment (`voiceV2Enabled` is off).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "ElevenLabs failed to return the voice list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "This deployment has no ElevenLabs server API key configured (`errorCode: \"provider_not_configured\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listVoicesResponse503" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/voice/voices\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/voice/voices\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/voice/voices\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/voice/sessions": { "post": { "operationId": "createVoiceSession", "summary": "Start a voice session", "description": "Opens a real-time voice conversation on the platform default voice agent, attached to an existing session (`sessionId`) or a new one, and returns the `clientBootstrap` to hand to the ElevenLabs Conversational AI SDK client-side (`Conversation.startSession`): connect with `signedUrl`, apply any overrides, and forward `sessionToken` as `custom_llm_extra_body.b4m_session`. Transcripts are appended to the session as the call runs. When credits are enforced, the maximum call length is reserved up front and reconciled down by `POST /api/v1/voice/sessions/{id}/end`, so always end the call. Pass `isReconnect: true` to re-attach a dropped transport without a second reservation. `POST /api/voice/v2/sessions` is a legacy alias of this endpoint. Authenticate with an API key (`b4m_live_`) or a JWT.", "tags": [ "Voice" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVoiceSessionRequest" } } } }, "responses": { "200": { "description": "The call is provisioned. `clientBootstrap` is consumed by the ElevenLabs Conversational AI SDK in the client; `signedUrl` is short-lived, so connect promptly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVoiceSessionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "No default voice agent is configured for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold `ai:generate`, Voice is not enabled on this deployment (`voiceV2Enabled` is off), or the caller already has the maximum number of concurrent voice sessions open (end one first).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "The `sessionId` does not exist or is not owned by the caller (a malformed id is also a 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Another call on the same session was provisioned concurrently and holds its reservation; this request's reservation is refunded. Retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "422": { "description": "Request body failed validation, or the caller cannot afford the up-front reservation - the latter is tagged `errorCode: \"insufficient_credits\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVoiceSessionResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "502": { "description": "ElevenLabs failed to provision the conversation; any reserved credits are refunded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "This deployment has no ElevenLabs server API key configured (`errorCode: \"provider_not_configured\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createVoiceSessionResponse503" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/voice/sessions\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"sessionId\": \"664f1c2b9a1e4d0012ab34aa\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/voice/sessions\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"sessionId\": \"664f1c2b9a1e4d0012ab34aa\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/voice/sessions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"sessionId\": \"664f1c2b9a1e4d0012ab34aa\"\n },\n)" } ] } }, "/api/v1/voice/sessions/{id}/end": { "post": { "operationId": "endVoiceSession", "summary": "End a voice session", "description": "Reconciles the credit reservation taken by `POST /api/v1/voice/sessions` down to the actual call duration and refunds the difference. Call it when the conversation ends. Idempotent: once the hold is cleared, a repeat call refunds nothing and reports `alreadyReconciled: true`. Only the session owner can end a call. `POST /api/voice/v2/sessions/{id}/end` is a legacy alias of this endpoint. Authenticate with an API key (`b4m_live_`) or a JWT.", "tags": [ "Voice" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The session id returned by `POST /api/v1/voice/sessions`." }, "required": true, "description": "The session id returned by `POST /api/v1/voice/sessions`.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The reservation is reconciled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/endVoiceSessionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key does not hold any of the required scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "404": { "description": "No session with that id is owned by the caller (a malformed id is also a 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/voice/sessions//end\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/voice/sessions//end\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/voice/sessions//end\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/whats-new": { "get": { "operationId": "listWhatsNew", "summary": "List release notes", "description": "Lists published release notes, newest first. Public: no credentials are needed, and the response is cacheable for up to about 15 minutes (5 fresh plus 10 stale-while-revalidate), so a newly published or withdrawn note can take that long to show. A deployment that proxies an upstream feed stacks its own caching on the upstream's, so there it can take about 31 minutes. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`. Rate limited per client IP.", "tags": [ "Release notes" ], "security": [], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of published release notes, newest first by `published_at`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listWhatsNewResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given. On a deployment that proxies an upstream feed, a cursor issued by that upstream which can no longer be served there ends the list (200 with empty `data`) rather than returning 422.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "429": { "description": "Per-IP rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } } } } }, "/api/v1/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "description": "Lists the projects the caller can read: projects they own and projects shared with them. A project's `file_ids` and `session_ids` are shared with it: anyone the project is shared with can read every file and session it groups. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of projects, ordered by `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listProjectsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `projects:read` nor `projects:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "projects:read", "projects:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/projects\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/projects\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/projects\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "post": { "operationId": "createProject", "summary": "Create a project", "description": "Creates a project owned by the caller, optionally grouping existing sessions and files in it. Every listed session and file must be readable by the caller. A project's `file_ids` and `session_ids` are shared with it: anyone the project is shared with can read every file and session it groups. Sharing the project later shares them too. Unknown body fields are rejected.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createProjectRequest" } } } }, "responses": { "201": { "description": "The created project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createProjectResponse201" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "A listed session or file does not exist or is not readable by the caller, or the body is not valid JSON. Nothing is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `projects:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation, or you already have a live project with this `name`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "projects:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/projects\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"name\": \"Market research\",\n \"description\": \"Sources and notes for the Q3 market analysis.\",\n \"session_ids\": [\n \"664f1c2b9a1e4d0012ab34aa\"\n ],\n \"file_ids\": [\n \"664f1c2b9a1e4d0012ab34bb\"\n ]\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/projects\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"name\": \"Market research\",\n \"description\": \"Sources and notes for the Q3 market analysis.\",\n \"session_ids\": [\n \"664f1c2b9a1e4d0012ab34aa\"\n ],\n \"file_ids\": [\n \"664f1c2b9a1e4d0012ab34bb\"\n ]\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/projects\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"name\": \"Market research\",\n \"description\": \"Sources and notes for the Q3 market analysis.\",\n \"session_ids\": [\n \"664f1c2b9a1e4d0012ab34aa\"\n ],\n \"file_ids\": [\n \"664f1c2b9a1e4d0012ab34bb\"\n ]\n },\n)" } ] } }, "/api/v1/projects/{id}": { "get": { "operationId": "getProject", "summary": "Get a project", "description": "Returns one project the caller can read. A project's `file_ids` and `session_ids` are shared with it: anyone the project is shared with can read every file and session it groups.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getProjectResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `projects:read` nor `projects:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No project with that id is visible to the caller. A project that exists but is not yours to read, a deleted project and a malformed id are all reported as 404, so project ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "projects:read", "projects:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/projects/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/projects/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/projects/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "patch": { "operationId": "updateProject", "summary": "Update a project", "description": "Renames a project you own or changes its description. Omitted fields are left unchanged, and an empty body changes nothing. Only the owner can update a project. Unknown body fields are rejected.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateProjectRequest" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateProjectResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `projects:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No project with that id is yours. A project shared with you, one that does not exist, a deleted project and a malformed id are all reported as 404, so project ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation, or you already have a live project with this `name`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "projects:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X PATCH \"https://your-deployment.example.com/api/v1/projects/\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"description\": \"Sources and notes for the Q4 market analysis.\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/projects/\", {\n method: \"PATCH\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"description\": \"Sources and notes for the Q4 market analysis.\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.patch(\n \"https://your-deployment.example.com/api/v1/projects/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"description\": \"Sources and notes for the Q4 market analysis.\"\n },\n)" } ] }, "delete": { "operationId": "deleteProject", "summary": "Delete a project", "description": "Deletes a project you own. The sessions and files it grouped are kept, but the access the project granted is revoked: members lose access to your content, and you lose access to sessions and files members added to it. Only the owner can delete a project.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "The project was deleted.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `projects:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No project with that id is yours. A project shared with you, one that does not exist, a deleted project and a malformed id are all reported as 404, so project ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "projects:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE \"https://your-deployment.example.com/api/v1/projects/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/projects/\", {\n method: \"DELETE\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.delete(\n \"https://your-deployment.example.com/api/v1/projects/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/artifacts": { "get": { "operationId": "listArtifacts", "summary": "List artifacts", "description": "Lists the artifacts you own, newest first, excluding deleted ones. Artifacts shared with you are not listed, though `GET /api/v1/artifacts/{id}` resolves them by id. Items carry `content: null`; fetch an artifact by id for its content. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`.", "tags": [ "Artifacts" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of artifacts, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listArtifactsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `notebooks:read` nor `notebooks:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:read", "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/artifacts\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/artifacts\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/artifacts\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "post": { "operationId": "createArtifact", "summary": "Create an artifact", "description": "Creates a private artifact at version 1. `session_id` files it under a session you can edit, and `project_id` under a project you can read. Unknown body fields are rejected.", "tags": [ "Artifacts" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createArtifactRequest" } } } }, "responses": { "201": { "description": "The new artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createArtifactResponse201" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `notebooks:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "The `session_id` or `project_id` does not exist or is not yours to file under.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/artifacts\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"type\": \"mermaid\",\n \"title\": \"Signup flow\",\n \"content\": \"graph TD; A[Sign up] --> B[Verify email]\",\n \"tags\": [\n \"onboarding\"\n ]\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/artifacts\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"type\": \"mermaid\",\n \"title\": \"Signup flow\",\n \"content\": \"graph TD; A[Sign up] --> B[Verify email]\",\n \"tags\": [\n \"onboarding\"\n ]\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/artifacts\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"type\": \"mermaid\",\n \"title\": \"Signup flow\",\n \"content\": \"graph TD; A[Sign up] --> B[Verify email]\",\n \"tags\": [\n \"onboarding\"\n ]\n },\n)" } ] } }, "/api/v1/artifacts/{id}": { "get": { "operationId": "getArtifact", "summary": "Get an artifact", "description": "Returns an artifact you own, one shared with you, or a public one, with its current version's content.", "tags": [ "Artifacts" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The artifact and its current content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getArtifactResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `notebooks:read` nor `notebooks:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No artifact with that id is visible to the caller. An artifact that does not exist, a deleted one and one you cannot read are all reported as 404, so artifact ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:read", "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/artifacts/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/artifacts/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/artifacts/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "patch": { "operationId": "updateArtifact", "summary": "Update an artifact", "description": "Updates an artifact you can edit: one you own, or one shared with you with write permission. Changed `content` creates a new version; the other fields change in place. Omitted fields are left unchanged. Unknown body fields are rejected.", "tags": [ "Artifacts" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateArtifactRequest" } } } }, "responses": { "200": { "description": "The updated artifact and its current content. `content` is `null` for a caller who may edit but not read the artifact, unless the request sent content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateArtifactResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `notebooks:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No artifact with that id is yours to edit. One you can only read (shared read-only, or public) is reported as 404 too, like one that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X PATCH \"https://your-deployment.example.com/api/v1/artifacts/\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"content\": \"graph TD; A[Sign up] --> B[Verify email] --> C[Done]\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/artifacts/\", {\n method: \"PATCH\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"content\": \"graph TD; A[Sign up] --> B[Verify email] --> C[Done]\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.patch(\n \"https://your-deployment.example.com/api/v1/artifacts/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"content\": \"graph TD; A[Sign up] --> B[Verify email] --> C[Done]\"\n },\n)" } ] }, "delete": { "operationId": "deleteArtifact", "summary": "Delete an artifact", "description": "Deletes an artifact you own, or one shared with you with delete permission.", "tags": [ "Artifacts" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "The artifact was deleted.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `notebooks:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No artifact with that id is yours to delete. One you cannot delete is reported as 404 too, like one that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE \"https://your-deployment.example.com/api/v1/artifacts/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/artifacts/\", {\n method: \"DELETE\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.delete(\n \"https://your-deployment.example.com/api/v1/artifacts/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/artifacts/{id}/versions": { "get": { "operationId": "listArtifactVersions", "summary": "List artifact versions", "description": "Lists an artifact's versions, oldest first. Items carry `content: null`; fetch a version for its content. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`.", "tags": [ "Artifacts" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of versions, in version order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listArtifactVersionsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `notebooks:read` nor `notebooks:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No artifact with that id is visible to the caller. An artifact that does not exist, a deleted one and one you cannot read are all reported as 404, so artifact ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:read", "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/artifacts//versions\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/artifacts//versions\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/artifacts//versions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/artifacts/{id}/versions/{version}": { "get": { "operationId": "getArtifactVersion", "summary": "Get an artifact version", "description": "Returns one version of an artifact you can read, with its content.", "tags": [ "Artifacts" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "A version number, starting at 1." }, "required": true, "description": "A version number, starting at 1.", "name": "version", "in": "path" } ], "responses": { "200": { "description": "The version and its content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getArtifactVersionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `notebooks:read` nor `notebooks:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No artifact with that id is visible to the caller. An artifact that does not exist, a deleted one and one you cannot read are all reported as 404, so artifact ids cannot be probed through this endpoint. A version that does not exist, or one that is not a positive integer, is also 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "notebooks:read", "notebooks:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/artifacts//versions/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/artifacts//versions/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/artifacts//versions/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/transcriptions/uploads": { "post": { "operationId": "createTranscriptionUpload", "summary": "Start a transcription upload", "description": "Returns a presigned upload for one audio file of at most 25 MiB. POST the audio to `upload_url` as `multipart/form-data`, with every `upload_fields` entry as a form field and the audio last as the `file` field, before `expires_at`. Send no `Authorization` header: the signature is the credential. Storage refuses a type other than `mime_type` or a size outside 1 byte to 25 MiB. Then call `POST /api/v1/transcriptions` with `file_key`.", "tags": [ "Transcriptions" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTranscriptionUploadRequest" } } } }, "responses": { "201": { "description": "The upload is ready; POST the audio to `upload_url`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTranscriptionUploadResponse201" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `ai:generate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation, or the balance cannot cover the estimated cost of transcribing `file_size` bytes (`errorCode: \"insufficient_credits\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTranscriptionUploadResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/transcriptions/uploads\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"mime_type\": \"audio/mpeg\",\n \"file_size\": 482133\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/transcriptions/uploads\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"mime_type\": \"audio/mpeg\",\n \"file_size\": 482133\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/transcriptions/uploads\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"mime_type\": \"audio/mpeg\",\n \"file_size\": 482133\n },\n)" } ] } }, "/api/v1/transcriptions": { "post": { "operationId": "createTranscription", "summary": "Transcribe audio", "description": "Transcribes an upload minted by `POST /api/v1/transcriptions/uploads` and returns the text. Call it within 5 minutes of minting the upload. Credits are charged by file size. The uploaded audio is deleted when the call returns, whether it succeeds or fails, so each upload can be transcribed once.\n\n**Limit:** this call is synchronous. The request times out after about 60 seconds, while the AWS speech backend can take up to about 5 minutes on long audio, so a long recording can fail with a gateway timeout (`504`) instead of returning text. A timed-out upload may not be deleted right away (it expires on its own), so do not retry with the same `file_key`: mint a new upload, or send shorter audio.", "tags": [ "Transcriptions" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTranscriptionRequest" } } } }, "responses": { "200": { "description": "The transcript.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTranscriptionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `ai:generate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "`file_key` is not one of your uploads, or the upload is missing or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation, the stored audio has an unsupported type or size, or the balance cannot cover its estimated cost (`errorCode: \"insufficient_credits\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTranscriptionResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "502": { "description": "The speech provider failed to transcribe the audio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "503": { "description": "This deployment has no speech model, or no credential for its provider, configured (`errorCode: \"provider_not_configured\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTranscriptionResponse503" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "ai:generate" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/transcriptions\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"file_key\": \"transcribe-uploads//.mp3\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/transcriptions\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"file_key\": \"transcribe-uploads//.mp3\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/transcriptions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"file_key\": \"transcribe-uploads//.mp3\"\n },\n)" } ] } }, "/api/v1/agents": { "get": { "operationId": "listAgents", "summary": "List agents", "description": "Lists the agents the caller can use: agents they own and agents shared with them. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of agents, ordered by `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listAgentsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `agents:read` nor `agents:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`limit` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "agents:read", "agents:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/agents\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agents\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/agents\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "post": { "operationId": "createAgent", "summary": "Create an agent", "description": "Creates an agent owned by the caller. The number of agents a user may own depends on their plan. Unknown body fields are rejected.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createAgentRequest" } } } }, "responses": { "201": { "description": "The created agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createAgentResponse201" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "400": { "description": "The caller already owns as many agents as their plan allows (`errorCode: agent_limit_reached`), or the body is not valid JSON. Nothing is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `agents:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation: an unknown field, an out-of-range value, an unknown `preferred_model`, or a malformed `trigger_words`/tool list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "agents:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/agents\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"name\": \"Research assistant\",\n \"description\": \"Summarizes sources and cites them.\",\n \"system_prompt\": \"You are a careful research assistant. Always cite your sources.\",\n \"temperature\": 0.3,\n \"trigger_words\": [\n \"@research\"\n ]\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agents\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"name\": \"Research assistant\",\n \"description\": \"Summarizes sources and cites them.\",\n \"system_prompt\": \"You are a careful research assistant. Always cite your sources.\",\n \"temperature\": 0.3,\n \"trigger_words\": [\n \"@research\"\n ]\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/agents\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"name\": \"Research assistant\",\n \"description\": \"Summarizes sources and cites them.\",\n \"system_prompt\": \"You are a careful research assistant. Always cite your sources.\",\n \"temperature\": 0.3,\n \"trigger_words\": [\n \"@research\"\n ]\n },\n)" } ] } }, "/api/v1/agents/{id}": { "get": { "operationId": "getAgent", "summary": "Get an agent", "description": "Returns one agent the caller owns or that is shared with them.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getAgentResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key holds neither `agents:read` nor `agents:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No agent with that id is visible to the caller. An agent that exists but is not yours to read, a deleted agent and a malformed id are all reported as 404, so agent ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "agents:read", "agents:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/agents/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agents/\", {\n method: \"GET\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.get(\n \"https://your-deployment.example.com/api/v1/agents/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "patch": { "operationId": "updateAgent", "summary": "Update an agent", "description": "Updates an agent you own. Omitted fields are left unchanged. Only the owner can update an agent. Unknown body fields are rejected.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateAgentRequest" } } } }, "responses": { "200": { "description": "The updated agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateAgentResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `agents:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No agent with that id is yours. An agent shared with you, one that does not exist, a deleted agent and a malformed id are all reported as 404, so agent ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation: an unknown field, an out-of-range value, an unknown `preferred_model`, or a malformed `trigger_words`/tool list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "agents:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X PATCH \"https://your-deployment.example.com/api/v1/agents/\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"temperature\": 0.7,\n \"trigger_words\": [\n \"@research\",\n \"@sources\"\n ]\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agents/\", {\n method: \"PATCH\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"temperature\": 0.7,\n \"trigger_words\": [\n \"@research\",\n \"@sources\"\n ]\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.patch(\n \"https://your-deployment.example.com/api/v1/agents/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"temperature\": 0.7,\n \"trigger_words\": [\n \"@research\",\n \"@sources\"\n ]\n },\n)" } ] }, "delete": { "operationId": "deleteAgent", "summary": "Delete an agent", "description": "Deletes an agent you own. Any credits held by the agent are returned to your balance. Only the owner can delete an agent.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "The agent was deleted.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } } } }, "403": { "description": "The API key lacks `agents:write`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeForbiddenResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "404": { "description": "No agent with that id is yours. An agent shared with you, one that does not exist, a deleted agent and a malformed id are all reported as 404, so agent ids cannot be probed through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "405": { "description": "The path does not serve this HTTP method.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "Allow": { "description": "The methods this path serves. GET implies HEAD.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "429": { "description": "Per-user rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } } }, "x-required-scopes": [ "agents:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE \"https://your-deployment.example.com/api/v1/agents/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agents/\", {\n method: \"DELETE\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n },\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.delete(\n \"https://your-deployment.example.com/api/v1/agents/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } } }, "webhooks": {}, "tags": [ { "name": "AI", "description": "Chat, completions, embeddings, and server-side tool execution." }, { "name": "Sessions", "description": "Sessions (called \"notebooks\" in the product UI) and their attached knowledge." }, { "name": "Release notes", "description": "Customer-facing notes on what changed in each release. Public." }, { "name": "Audio", "description": "Speech, music, and sound-effect generation. For music, use `POST /api/v1/music-generations`; `/api/ai/music` is deprecated." }, { "name": "Music", "description": "Song generation, queued with `202` and polled at `GET /api/v1/music-generations/{id}`." }, { "name": "Images", "description": "Image generation and editing, queued and polled as quests." }, { "name": "Transcriptions", "description": "Speech-to-text: upload an audio file, then transcribe it." }, { "name": "Artifacts", "description": "Diagrams, charts, code and documents kept in sessions, with their version history." }, { "name": "Files", "description": "Upload files and fetch any file by id, with short-lived signed download URLs." }, { "name": "Videos", "description": "Video generation, queued with `202` and polled at `GET /api/v1/video-generations/{id}`." }, { "name": "Voice", "description": "Real-time voice conversations: list voices, open a call, and reconcile its credits when it ends." }, { "name": "Models", "description": "The models the caller can use, and the parameters each one accepts." }, { "name": "Account", "description": "The caller's own identity, plan tier, credit balance, and entitlements." }, { "name": "Data Lakes", "description": "Curated document collections: list and inspect the lakes you can reach, manage which files belong to one, check each file's ingestion status, and run semantic search over a single lake." }, { "name": "Projects", "description": "Workspaces that group sessions and files: list and read the projects you can reach, and create new ones." }, { "name": "Agents", "description": "Custom agents with their own system prompt, model settings and tool access: list, read and manage them." } ] }