{ "openapi": "3.1.0", "info": { "title": "Bike4Mind API", "version": "21.0.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**, **Skills** 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 documented scopes are:\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- `me:read`\n- `marketing-reports:read`\n- `marketing-reports:write`\n- `hearth:read`\n- `hearth:write`\n- `datalake:read`\n- `datalake:write`\n- `datalake:share`\n- `datalake:query`\n- `overwatch:read`\n- `skills:read`\n- `skills:write`\n- `skills:review`\n- `bob:read`\n- `bob:run`\n- `slack:post`\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, a reference image that is missing, not an image, or still in moderation, and the combined FLUX.2 input-image limit after attachments are resolved. 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, a reference image that is missing, not an image, or still in moderation, and the combined FLUX.2 input-image limit after attachments are resolved. 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": "object", "properties": { "blocks": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "hardcoded", "admin", "user", "project", "session", "org", "caller" ] }, "name": { "type": "string" }, "text": { "type": "string" }, "redacted": { "type": "boolean" }, "placement": { "type": "string", "enum": [ "system", "user_turn", "mixed" ] } }, "required": [ "source", "name", "redacted", "placement" ] } }, "sizeCapped": { "type": "boolean" } }, "required": [ "blocks", "sizeCapped" ] }, "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" ] }, "sendChatMessageResponse422": { "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": [ "output_budget_exhausted" ] }, "quest_id": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "error" ] }, "sendChatMessageResponse502": { "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." }, "quest_id": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "error", "quest_id" ] }, "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", "maxLength": 256 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "max_tokens": { "type": "integer", "minimum": 16 }, "maxTokens": { "type": "integer", "minimum": 16 }, "maxOutputTokens": { "type": "integer", "minimum": 16 }, "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" ] }, "startAgentExecutionResponse403": { "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" ] }, "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", "description": "The organization whose credit pool pays for this run. You must belong to it; a non-member gets 404. Omit it to bill your personal credits. An organization-billed API key always bills its own organization: omit this or set it to the key's; any other value is a 403 (`errorCode: billing_organization_mismatch`)." }, "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" }, "confidence_overrides": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "minItems": 1, "maxItems": 100, "description": "Admin only. Scripted per-iteration confidence scores (0 to 1) that replace the real score at the confidence gate: entry i scores iteration i + 1, and iterations past the end use the real score. The gate pauses the run for review on a streak of consecutive evaluated iterations below its threshold (currently 2), so script one low entry per iteration you want in the streak. Only iterations that ran tools are evaluated, scripted or not, and a finished run never pauses. A non-admin caller gets 403." } }, "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." }, "promptCacheTtl": { "type": "string", "enum": [ "5m", "1h" ], "description": "The chat's prompt-cache lifetime. Absent when never set, which follows your default." }, "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." }, "promptCacheTtl": { "type": "string", "enum": [ "5m", "1h" ], "description": "The chat's prompt-cache lifetime. Absent when never set, which follows your default." }, "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." }, "promptCacheTtl": { "type": "string", "enum": [ "5m", "1h" ], "description": "How long the prompt cache of this chat lives between messages: `5m` (the default) or `1h`. A 1-hour cache costs more to write and the same to read; it applies only on models that support it, and other models keep the 5-minute cache. Omit to leave it unchanged." }, "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." }, "promptCacheTtl": { "type": "string", "enum": [ "5m", "1h" ], "description": "The chat's prompt-cache lifetime. Absent when never set, which follows your default." }, "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", "decide" ] }, "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" }, "cacheWrite1hInputTokens": { "type": "number", "description": "The part of cacheCreationInputTokens written with the 1-hour TTL. Absent when there were none." } } }, "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", "invalid_request", "provider_error", "provider_rejected", "content_blocked", "output_budget_exhausted" ] } }, "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": [ "invalid_request", "unknown_model", "assistant_prefill_unsupported", "tool_search_unsupported", "all_tools_deferred", "deferred_tool_cache_control", "unknown_tool_reference", "tool_changes_unsupported", "invalid_tool_change" ] } }, "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", "minLength": 1, "maxLength": 256 }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "description": "A string, or an array of content blocks. A `system` message may instead hold only `tool_addition` / `tool_removal` blocks (`{ type, tool: { type: \"tool_reference\", name } }`) to load or unload a tool named in `tools` mid-conversation without invalidating the prompt cache. It must follow a user turn or an assistant turn ending in a tool search result, and be the last message or precede an assistant turn. Only on models whose `supports_tool_changes` is true and that are served by the direct Anthropic API; otherwise refused with `errorCode: \"tool_changes_unsupported\"` (or `invalid_tool_change` / `unknown_tool_reference` when malformed). A final non-blank assistant turn is an assistant prefill, except a server-tool continuation ending in `server_tool_use` or `tool_search_tool_result`. Plain system prompts and blank messages are ignored. It is accepted only when the selected model has `supports_assistant_prefill: true`; otherwise the request returns `400` with `errorCode: \"assistant_prefill_unsupported\"` without changing the message." }, "cache": { "type": "boolean" } }, "required": [ "role", "content" ] }, "minItems": 1 }, "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 Claude models (direct Anthropic or Bedrock) whose `supports_tool_search` is true; on every other model 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 Claude models (direct Anthropic or Bedrock) whose `supports_tool_search` is true; any other model is refused with `errorCode: \"tool_search_unsupported\"` rather than run without it." } }, "required": [ "serverTool" ] } ] } }, "temperature": { "type": "number" }, "max_tokens": { "type": "number" }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your own identifier for the conversation this request belongs to. Recorded with the request's credit usage so spend can be grouped by conversation. Not interpreted otherwise." }, "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 Claude models (direct Anthropic or Bedrock) whose `supports_tool_search` is true; on every other model 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 Claude models (direct Anthropic or Bedrock) whose `supports_tool_search` is true; any other model 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, "maximum": 32000 } }, "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, maximum 32000) 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." }, "cacheTtl": { "type": "string", "enum": [ "5m", "1h" ], "description": "Prompt-cache lifetime for this request, where the server places cache breakpoints (Claude on the direct Anthropic API or Bedrock, on requests the server caches: CLI and Desktop always, other callers once the conversation has a prior assistant turn). `5m` (the default) writes at 1.25x the input rate; `1h` writes at 2x and keeps the cached prefix for an hour between requests. Reads cost the same either way. Models without 1-hour caching ignore `1h` and keep `5m`. Every breakpoint in a request must share one TTL: with `1h`, set no `cache_control` of your own unless it also carries `ttl: \"1h\"`." } } } }, "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": 450 }, "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" }, "monthly_allowance": { "type": [ "number", "null" ], "minimum": 0 } }, "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, "monthly_allowance": 50000 }, "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", "openai-compatible", "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 for every model with this flag set, whether its `backend` is `anthropic` or `bedrock`." }, "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: `/api/ai/v1/completions` honours it only for models whose `backend` is `anthropic`; a `bedrock` model with this flag set is refused there with `errorCode: \"tool_changes_unsupported\"`." }, "supports_assistant_prefill": { "type": "boolean", "description": "Whether `/api/ai/v1/completions` accepts a final assistant message for the model to continue. When false, a text prefill returns `400` with `errorCode: \"assistant_prefill_unsupported\"`; server-tool continuations are allowed. On Claude models that accept assistant prefill, it cannot be combined with `thinking`." }, "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_assistant_prefill", "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_assistant_prefill": false, "supports_vision": true, "deprecation_date": null, "replaced_by": null, "image": null, "credits_per_1m_tokens": { "input": 4000, "output": 20000, "cached_input": 400 } }, { "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_assistant_prefill": true, "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" ], "additionalProperties": {} }, "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", "flux-2-max", "flux-2-pro", "flux-2-pro-preview", "flux-2-flex", "flux-2-klein-9b", "flux-2-klein-9b-preview", "flux-2-klein-4b", "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", "maxLength": 256, "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", "current_model_details", "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", "decide", "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", "default": false, "description": "Let the provider rewrite and expand the prompt before rendering. Applies to Black Forest Labs (FLUX) models only; other models ignore it. Defaults to false." }, "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", "flux-2-max", "flux-2-pro", "flux-2-pro-preview", "flux-2-flex", "flux-2-klein-9b", "flux-2-klein-9b-preview", "flux-2-klein-4b", "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", "maxLength": 256, "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 } }, "createTextRefinementResponse200": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "example": { "text": "A golden retriever running along a sunlit beach at sunset, waves breaking behind it." } }, "createTextRefinementResponse401": { "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", "provider_rejected" ] } }, "required": [ "error" ] }, "createTextRefinementResponse422": { "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" ] }, "createTextRefinementResponse503": { "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", "provider_rejected" ] } }, "required": [ "error" ] }, "createTextRefinementRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 10000 }, "context": { "type": "string", "maxLength": 10000 } }, "required": [ "text" ], "example": { "text": "a dog on a beach", "context": "prompt for an image generator" } }, "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": 256, "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": {} }, "turnTiming": { "type": "object", "properties": { "queueMs": { "type": "number" }, "contextBuildMs": { "type": "number" }, "semaphoreWaitMs": { "type": "number" }, "totalMs": { "type": "number" }, "fallbackHops": { "type": "number" }, "retries": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "stream_idle_timeout", "stream_truncated", "request_timeout", "rate_limit", "overloaded", "server_error", "transport", "tool_pairing", "other" ] }, "status": { "type": "number" }, "retryAfterMs": { "type": "number" }, "requestId": { "type": "string" }, "delayMs": { "type": "number" }, "model": { "type": "string" }, "at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ] } }, "required": [ "reason", "delayMs", "model", "at" ] } } }, "required": [ "queueMs", "semaphoreWaitMs", "fallbackHops", "retries" ] }, "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." }, "promptCacheTtl": { "type": "string", "enum": [ "5m", "1h" ], "description": "The chat's prompt-cache lifetime. Absent when never set, which follows your default." }, "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, "maximum": 50 }, "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." }, "promptCacheTtl": { "type": "string", "enum": [ "5m", "1h" ], "description": "The chat's prompt-cache lifetime. Absent when never set, which follows your default." }, "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_input_role", "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_input_role", "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, "maxLength": 256, "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 a first_frame input (or 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" ] }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "first_frame", "last_frame", "reference", "style" ] } }, "required": [ "file_id", "role" ], "additionalProperties": false }, "maxItems": 8, "description": "Image files you own, each tagged with what it is for. image_to_video needs a first_frame. The roles a model accepts, and how many of each, are its input_roles in GET /api/v1/video-models." }, "input_image_file_id": { "type": "string", "minLength": 1, "description": "Deprecated: send inputs with role first_frame instead. Cannot be combined with inputs." }, "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" ] } }, "input_roles": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "max": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "role", "max" ] }, "description": "The inputs[] roles this model accepts and the most of each one request may carry. Roles today: first_frame, last_frame, reference, style; ignore any you do not know." }, "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, "maxLength": 256, "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" ] } }, "video": { "type": [ "object", "null" ], "properties": { "landscape_url": { "type": [ "string", "null" ] }, "landscape_poster_url": { "type": [ "string", "null" ] }, "portrait_url": { "type": [ "string", "null" ] }, "portrait_poster_url": { "type": [ "string", "null" ] } } }, "image": { "type": [ "object", "null" ], "properties": { "landscape_url": { "type": [ "string", "null" ] }, "portrait_url": { "type": [ "string", "null" ] } } } }, "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, "maxLength": 256, "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, "maxLength": 256, "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" ] } }, "generateAgentAvatarResponse200": { "type": "object", "properties": { "portrait_url": { "type": "string", "description": "URL of the generated portrait: a signed storage URL valid for one hour, or the provider temporary URL if storage failed." }, "generation_prompt": { "type": "string", "description": "The visual prompt the portrait was generated from." } }, "required": [ "portrait_url", "generation_prompt" ] }, "generateAgentAvatarRequest": { "type": "object", "properties": { "image_model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "An image model id. Omit to use the deployment image model. An unknown or non-image model is rejected with a 400." } }, "additionalProperties": false, "example": {} }, "generateAgentDescriptionResponse200": { "type": "object", "properties": { "description": { "type": "string", "description": "The generated description. It is returned, not saved to the agent." } }, "required": [ "description" ] }, "generateAgentSystemPromptResponse200": { "type": "object", "properties": { "system_prompt": { "type": "string", "description": "The generated system prompt, already saved to the agent." } }, "required": [ "system_prompt" ] }, "enhanceAgentFieldResponse200": { "type": "object", "properties": { "enhanced_value": { "type": "string", "description": "The enhanced text. It is returned, not saved to the agent." } }, "required": [ "enhanced_value" ] }, "enhanceAgentFieldRequest": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The personality field being enhanced, for example `quirk` or `coreValues`. At most 100 characters." }, "current_value": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The text to enhance. It stays the basis of the result. At most 2000 characters." }, "agent_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Overrides the agent's stored name in the prompt. At most 200 characters." } }, "required": [ "field_name", "current_value" ], "additionalProperties": false, "example": { "field_name": "quirk", "current_value": "Hums while thinking" } }, "getClaudeMarketplaceResponse200": { "type": "object", "properties": { "name": { "type": "string" }, "owner": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "forceRemoveDeletedPlugins": { "type": "boolean" }, "plugins": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "source": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "archive" ] }, "url": { "type": "string" }, "sha256": { "type": "string" } }, "required": [ "source", "url", "sha256" ] } }, "required": [ "name", "description", "version", "source" ] } } }, "required": [ "name", "owner", "forceRemoveDeletedPlugins", "plugins" ], "example": { "name": "b4m-org-664f1c2b9a1e4d0012ab34cd", "owner": { "name": "Acme" }, "forceRemoveDeletedPlugins": true, "plugins": [ { "name": "review-pr", "description": "Review a pull request against the team checklist.", "version": "3", "source": { "source": "archive", "url": "https://app.bike4mind.com/api/v1/skills/market/664f1c2b9a1e4d0012ab34cd/claude-plugin.zip?version=3", "sha256": "a3f1c0de9b8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a392817060f5e" } } ] } }, "listSkillMarketListingsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "organization", "unlisted" ] }, "organization_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "in_review", "approved", "rejected", "delisted", "withdrawn" ] }, "author_name": { "type": [ "string", "null" ] }, "current_version": { "type": [ "integer", "null" ], "description": "The approved version importers receive." }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "uses_tools": { "type": "boolean" }, "auto_checked": { "type": "boolean", "description": "Whether the live version was approved without a human reviewer." }, "import_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "source_skill_id": { "type": "string", "description": "The skill the listing was published from. Present only for the listing author." }, "share_token": { "type": "string", "description": "Unlocks an unlisted listing. Present only for the listing author." }, "latest_version": { "type": "integer", "description": "The newest submitted version. Present only for the listing author." }, "pending_version": { "type": [ "integer", "null" ], "description": "A version awaiting review. Present only for the listing author." } }, "required": [ "id", "name", "description", "visibility", "organization_id", "tags", "status", "author_name", "current_version", "risk_tier", "uses_tools", "auto_checked", "import_count", "rating_avg", "rating_count", "published_at", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "getSkillMarketListingResponse200": { "type": "object", "properties": { "listing": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "organization", "unlisted" ] }, "organization_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "in_review", "approved", "rejected", "delisted", "withdrawn" ] }, "author_name": { "type": [ "string", "null" ] }, "current_version": { "type": [ "integer", "null" ], "description": "The approved version importers receive." }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "uses_tools": { "type": "boolean" }, "auto_checked": { "type": "boolean", "description": "Whether the live version was approved without a human reviewer." }, "import_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "source_skill_id": { "type": "string", "description": "The skill the listing was published from. Present only for the listing author." }, "share_token": { "type": "string", "description": "Unlocks an unlisted listing. Present only for the listing author." }, "latest_version": { "type": "integer", "description": "The newest submitted version. Present only for the listing author." }, "pending_version": { "type": [ "integer", "null" ], "description": "A version awaiting review. Present only for the listing author." } }, "required": [ "id", "name", "description", "visibility", "organization_id", "tags", "status", "author_name", "current_version", "risk_tier", "uses_tools", "auto_checked", "import_count", "rating_avg", "rating_count", "published_at", "created_at", "updated_at" ] }, "version": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string", "description": "The SKILL.md body. Omitted from marketplace list responses; included in the review queue." }, "argument_hint": { "type": [ "string", "null" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "claude_code_allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools pre-approved when the skill runs in Claude Code." }, "disable_model_invocation": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] }, "description": "Supporting files under scripts/ or references/, sorted by path. Present whenever `body` is, except on a review-queue `previous` version." } }, "required": [ "name", "description", "argument_hint", "allowed_tools", "claude_code_allowed_tools", "disable_model_invocation" ] }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "honest_summary": { "type": [ "object", "null" ], "properties": { "what_it_does": { "type": "string" }, "tools_used": { "type": "array", "items": { "type": "string" } }, "data_it_touches": { "type": "string" }, "risk_notes": { "type": "array", "items": { "type": "string" } }, "description_matches": { "type": "boolean" }, "mismatch_note": { "type": [ "string", "null" ] } }, "required": [ "what_it_does", "tools_used", "data_it_touches", "risk_notes", "description_matches", "mismatch_note" ], "description": "Generated from the skill body, not its description." }, "scan_status": { "type": "string", "enum": [ "scanning", "passed", "failed", "error" ], "description": "Present only for the listing author." }, "scan_findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "rules", "classifier" ] } }, "required": [ "rule", "severity", "message", "excerpt", "source" ] }, "description": "Present only for the listing author." }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "auto_approved", "approved", "rejected", "superseded" ], "description": "Present only for the listing author." }, "review_note": { "type": [ "string", "null" ], "description": "Present only for the listing author." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "version", "snapshot", "risk_tier", "honest_summary", "created_at" ], "description": "The current approved version, if any." }, "ratings": { "type": "array", "items": { "type": "object", "properties": { "stars": { "type": "integer" }, "review": { "type": [ "string", "null" ] }, "rated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "mine": { "type": "boolean" } }, "required": [ "stars", "review", "rated_at", "mine" ] } }, "my_import": { "type": [ "object", "null" ], "properties": { "version": { "type": "integer" }, "stars": { "type": [ "integer", "null" ] }, "review": { "type": [ "string", "null" ] }, "skill": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "Your imported copy, while it still exists." } }, "required": [ "version", "stars", "review", "skill" ] } }, "required": [ "listing", "version", "ratings", "my_import" ] }, "publishSkillMarketListingResponse201": { "type": "object", "properties": { "listing": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "organization", "unlisted" ] }, "organization_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "in_review", "approved", "rejected", "delisted", "withdrawn" ] }, "author_name": { "type": [ "string", "null" ] }, "current_version": { "type": [ "integer", "null" ], "description": "The approved version importers receive." }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "uses_tools": { "type": "boolean" }, "auto_checked": { "type": "boolean", "description": "Whether the live version was approved without a human reviewer." }, "import_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "source_skill_id": { "type": "string", "description": "The skill the listing was published from. Present only for the listing author." }, "share_token": { "type": "string", "description": "Unlocks an unlisted listing. Present only for the listing author." }, "latest_version": { "type": "integer", "description": "The newest submitted version. Present only for the listing author." }, "pending_version": { "type": [ "integer", "null" ], "description": "A version awaiting review. Present only for the listing author." } }, "required": [ "id", "name", "description", "visibility", "organization_id", "tags", "status", "author_name", "current_version", "risk_tier", "uses_tools", "auto_checked", "import_count", "rating_avg", "rating_count", "published_at", "created_at", "updated_at" ] }, "version": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string", "description": "The SKILL.md body. Omitted from marketplace list responses; included in the review queue." }, "argument_hint": { "type": [ "string", "null" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "claude_code_allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools pre-approved when the skill runs in Claude Code." }, "disable_model_invocation": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] }, "description": "Supporting files under scripts/ or references/, sorted by path. Present whenever `body` is, except on a review-queue `previous` version." } }, "required": [ "name", "description", "argument_hint", "allowed_tools", "claude_code_allowed_tools", "disable_model_invocation" ] }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "honest_summary": { "type": [ "object", "null" ], "properties": { "what_it_does": { "type": "string" }, "tools_used": { "type": "array", "items": { "type": "string" } }, "data_it_touches": { "type": "string" }, "risk_notes": { "type": "array", "items": { "type": "string" } }, "description_matches": { "type": "boolean" }, "mismatch_note": { "type": [ "string", "null" ] } }, "required": [ "what_it_does", "tools_used", "data_it_touches", "risk_notes", "description_matches", "mismatch_note" ], "description": "Generated from the skill body, not its description." }, "scan_status": { "type": "string", "enum": [ "scanning", "passed", "failed", "error" ], "description": "Present only for the listing author." }, "scan_findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "rules", "classifier" ] } }, "required": [ "rule", "severity", "message", "excerpt", "source" ] }, "description": "Present only for the listing author." }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "auto_approved", "approved", "rejected", "superseded" ], "description": "Present only for the listing author." }, "review_note": { "type": [ "string", "null" ], "description": "Present only for the listing author." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "version", "snapshot", "risk_tier", "honest_summary", "created_at" ] } }, "required": [ "listing", "version" ] }, "publishSkillMarketListingRequest": { "type": "object", "properties": { "skill_id": { "type": "string", "minLength": 1, "description": "A skill you own. Imported skills cannot be republished." }, "visibility": { "type": "string", "enum": [ "public", "organization", "unlisted" ] }, "organization_id": { "type": "string", "minLength": 1, "description": "Required for `organization` visibility, unless you belong to exactly one organization." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Up to 5 tags: 1-24 lowercase letters, digits or hyphens." } }, "required": [ "skill_id", "visibility" ], "additionalProperties": false, "example": { "skill_id": "664f1c2b9a1e4d0012ab34cd", "visibility": "organization", "tags": [ "review" ] } }, "listMySkillMarketListingsResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "organization", "unlisted" ] }, "organization_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "in_review", "approved", "rejected", "delisted", "withdrawn" ] }, "author_name": { "type": [ "string", "null" ] }, "current_version": { "type": [ "integer", "null" ], "description": "The approved version importers receive." }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "uses_tools": { "type": "boolean" }, "auto_checked": { "type": "boolean", "description": "Whether the live version was approved without a human reviewer." }, "import_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "source_skill_id": { "type": "string", "description": "The skill the listing was published from. Present only for the listing author." }, "share_token": { "type": "string", "description": "Unlocks an unlisted listing. Present only for the listing author." }, "latest_version": { "type": "integer", "description": "The newest submitted version. Present only for the listing author." }, "pending_version": { "type": [ "integer", "null" ], "description": "A version awaiting review. Present only for the listing author." }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string", "description": "The SKILL.md body. Omitted from marketplace list responses; included in the review queue." }, "argument_hint": { "type": [ "string", "null" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "claude_code_allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools pre-approved when the skill runs in Claude Code." }, "disable_model_invocation": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] }, "description": "Supporting files under scripts/ or references/, sorted by path. Present whenever `body` is, except on a review-queue `previous` version." } }, "required": [ "name", "description", "argument_hint", "allowed_tools", "claude_code_allowed_tools", "disable_model_invocation" ] }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "honest_summary": { "type": [ "object", "null" ], "properties": { "what_it_does": { "type": "string" }, "tools_used": { "type": "array", "items": { "type": "string" } }, "data_it_touches": { "type": "string" }, "risk_notes": { "type": "array", "items": { "type": "string" } }, "description_matches": { "type": "boolean" }, "mismatch_note": { "type": [ "string", "null" ] } }, "required": [ "what_it_does", "tools_used", "data_it_touches", "risk_notes", "description_matches", "mismatch_note" ], "description": "Generated from the skill body, not its description." }, "scan_status": { "type": "string", "enum": [ "scanning", "passed", "failed", "error" ], "description": "Present only for the listing author." }, "scan_findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "rules", "classifier" ] } }, "required": [ "rule", "severity", "message", "excerpt", "source" ] }, "description": "Present only for the listing author." }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "auto_approved", "approved", "rejected", "superseded" ], "description": "Present only for the listing author." }, "review_note": { "type": [ "string", "null" ], "description": "Present only for the listing author." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "version", "snapshot", "risk_tier", "honest_summary", "created_at" ] }, "description": "The 5 newest versions, newest first, without snapshot bodies." } }, "required": [ "id", "name", "description", "visibility", "organization_id", "tags", "status", "author_name", "current_version", "risk_tier", "uses_tools", "auto_checked", "import_count", "rating_avg", "rating_count", "published_at", "created_at", "updated_at", "versions" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "submitSkillMarketListingVersionResponse201": { "type": "object", "properties": { "listing": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "organization", "unlisted" ] }, "organization_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "in_review", "approved", "rejected", "delisted", "withdrawn" ] }, "author_name": { "type": [ "string", "null" ] }, "current_version": { "type": [ "integer", "null" ], "description": "The approved version importers receive." }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "uses_tools": { "type": "boolean" }, "auto_checked": { "type": "boolean", "description": "Whether the live version was approved without a human reviewer." }, "import_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "source_skill_id": { "type": "string", "description": "The skill the listing was published from. Present only for the listing author." }, "share_token": { "type": "string", "description": "Unlocks an unlisted listing. Present only for the listing author." }, "latest_version": { "type": "integer", "description": "The newest submitted version. Present only for the listing author." }, "pending_version": { "type": [ "integer", "null" ], "description": "A version awaiting review. Present only for the listing author." } }, "required": [ "id", "name", "description", "visibility", "organization_id", "tags", "status", "author_name", "current_version", "risk_tier", "uses_tools", "auto_checked", "import_count", "rating_avg", "rating_count", "published_at", "created_at", "updated_at" ] }, "version": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string", "description": "The SKILL.md body. Omitted from marketplace list responses; included in the review queue." }, "argument_hint": { "type": [ "string", "null" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "claude_code_allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools pre-approved when the skill runs in Claude Code." }, "disable_model_invocation": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] }, "description": "Supporting files under scripts/ or references/, sorted by path. Present whenever `body` is, except on a review-queue `previous` version." } }, "required": [ "name", "description", "argument_hint", "allowed_tools", "claude_code_allowed_tools", "disable_model_invocation" ] }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "honest_summary": { "type": [ "object", "null" ], "properties": { "what_it_does": { "type": "string" }, "tools_used": { "type": "array", "items": { "type": "string" } }, "data_it_touches": { "type": "string" }, "risk_notes": { "type": "array", "items": { "type": "string" } }, "description_matches": { "type": "boolean" }, "mismatch_note": { "type": [ "string", "null" ] } }, "required": [ "what_it_does", "tools_used", "data_it_touches", "risk_notes", "description_matches", "mismatch_note" ], "description": "Generated from the skill body, not its description." }, "scan_status": { "type": "string", "enum": [ "scanning", "passed", "failed", "error" ], "description": "Present only for the listing author." }, "scan_findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "rules", "classifier" ] } }, "required": [ "rule", "severity", "message", "excerpt", "source" ] }, "description": "Present only for the listing author." }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "auto_approved", "approved", "rejected", "superseded" ], "description": "Present only for the listing author." }, "review_note": { "type": [ "string", "null" ], "description": "Present only for the listing author." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "version", "snapshot", "risk_tier", "honest_summary", "created_at" ] } }, "required": [ "listing", "version" ] }, "submitSkillMarketListingVersionRequest": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "Replaces the listing tags once the version is accepted." } }, "default": {}, "additionalProperties": false, "example": {} }, "importSkillMarketListingResponse200": { "type": "object", "properties": { "skill": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "skill" ] }, "importSkillMarketListingResponse201": { "type": "object", "properties": { "skill": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "skill" ] }, "importSkillMarketListingResponse409": { "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": [ "version_changed", "local_changes", "name_taken" ] }, "suggested_name": { "type": "string", "description": "With `name_taken`: a free name to retry with." } }, "required": [ "error" ] }, "importSkillMarketListingRequest": { "type": "object", "properties": { "token": { "type": "string", "maxLength": 64, "description": "An unlisted listing's share token." }, "name": { "type": "string", "description": "A name for the copy, when the listing's name collides with one of yours." }, "target_skill_id": { "type": "string", "description": "Update this earlier imported copy in place instead." }, "overwrite": { "type": "boolean", "description": "Confirms overwriting a copy you edited since importing it." }, "expected_version_id": { "type": "string", "maxLength": 64, "description": "The version you reviewed; a 409 if a newer one was approved since." } }, "default": {}, "additionalProperties": false, "example": {} }, "rescanSkillMarketVersionResponse200": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string", "description": "The SKILL.md body. Omitted from marketplace list responses; included in the review queue." }, "argument_hint": { "type": [ "string", "null" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "claude_code_allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools pre-approved when the skill runs in Claude Code." }, "disable_model_invocation": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] }, "description": "Supporting files under scripts/ or references/, sorted by path. Present whenever `body` is, except on a review-queue `previous` version." } }, "required": [ "name", "description", "argument_hint", "allowed_tools", "claude_code_allowed_tools", "disable_model_invocation" ] }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "honest_summary": { "type": [ "object", "null" ], "properties": { "what_it_does": { "type": "string" }, "tools_used": { "type": "array", "items": { "type": "string" } }, "data_it_touches": { "type": "string" }, "risk_notes": { "type": "array", "items": { "type": "string" } }, "description_matches": { "type": "boolean" }, "mismatch_note": { "type": [ "string", "null" ] } }, "required": [ "what_it_does", "tools_used", "data_it_touches", "risk_notes", "description_matches", "mismatch_note" ], "description": "Generated from the skill body, not its description." }, "scan_status": { "type": "string", "enum": [ "scanning", "passed", "failed", "error" ], "description": "Present only for the listing author." }, "scan_findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "rules", "classifier" ] } }, "required": [ "rule", "severity", "message", "excerpt", "source" ] }, "description": "Present only for the listing author." }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "auto_approved", "approved", "rejected", "superseded" ], "description": "Present only for the listing author." }, "review_note": { "type": [ "string", "null" ], "description": "Present only for the listing author." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "version", "snapshot", "risk_tier", "honest_summary", "created_at" ] } }, "required": [ "version" ] }, "listSkillMarketReviewQueueResponse200": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string", "description": "The SKILL.md body. Omitted from marketplace list responses; included in the review queue." }, "argument_hint": { "type": [ "string", "null" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "claude_code_allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools pre-approved when the skill runs in Claude Code." }, "disable_model_invocation": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] }, "description": "Supporting files under scripts/ or references/, sorted by path. Present whenever `body` is, except on a review-queue `previous` version." } }, "required": [ "name", "description", "argument_hint", "allowed_tools", "claude_code_allowed_tools", "disable_model_invocation" ] }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "honest_summary": { "type": [ "object", "null" ], "properties": { "what_it_does": { "type": "string" }, "tools_used": { "type": "array", "items": { "type": "string" } }, "data_it_touches": { "type": "string" }, "risk_notes": { "type": "array", "items": { "type": "string" } }, "description_matches": { "type": "boolean" }, "mismatch_note": { "type": [ "string", "null" ] } }, "required": [ "what_it_does", "tools_used", "data_it_touches", "risk_notes", "description_matches", "mismatch_note" ], "description": "Generated from the skill body, not its description." }, "scan_status": { "type": "string", "enum": [ "scanning", "passed", "failed", "error" ], "description": "Present only for the listing author." }, "scan_findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "rules", "classifier" ] } }, "required": [ "rule", "severity", "message", "excerpt", "source" ] }, "description": "Present only for the listing author." }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "auto_approved", "approved", "rejected", "superseded" ], "description": "Present only for the listing author." }, "review_note": { "type": [ "string", "null" ], "description": "Present only for the listing author." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "version", "snapshot", "risk_tier", "honest_summary", "created_at" ] }, "listing": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "organization", "unlisted" ] }, "organization_id": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "in_review", "approved", "rejected", "delisted", "withdrawn" ] }, "author_name": { "type": [ "string", "null" ] }, "current_version": { "type": [ "integer", "null" ], "description": "The approved version importers receive." }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "uses_tools": { "type": "boolean" }, "auto_checked": { "type": "boolean", "description": "Whether the live version was approved without a human reviewer." }, "import_count": { "type": "integer" }, "rating_avg": { "type": "number" }, "rating_count": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp." }, "source_skill_id": { "type": "string", "description": "The skill the listing was published from. Present only for the listing author." }, "share_token": { "type": "string", "description": "Unlocks an unlisted listing. Present only for the listing author." }, "latest_version": { "type": "integer", "description": "The newest submitted version. Present only for the listing author." }, "pending_version": { "type": [ "integer", "null" ], "description": "A version awaiting review. Present only for the listing author." } }, "required": [ "id", "name", "description", "visibility", "organization_id", "tags", "status", "author_name", "current_version", "risk_tier", "uses_tools", "auto_checked", "import_count", "rating_avg", "rating_count", "published_at", "created_at", "updated_at" ] }, "previous": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string", "description": "The SKILL.md body. Omitted from marketplace list responses; included in the review queue." }, "argument_hint": { "type": [ "string", "null" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "claude_code_allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools pre-approved when the skill runs in Claude Code." }, "disable_model_invocation": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] }, "description": "Supporting files under scripts/ or references/, sorted by path. Present whenever `body` is, except on a review-queue `previous` version." } }, "required": [ "name", "description", "argument_hint", "allowed_tools", "claude_code_allowed_tools", "disable_model_invocation" ] } }, "required": [ "id", "version", "snapshot" ], "description": "The approved version this one would replace, for a diff." }, "can_decide": { "type": "boolean" } }, "required": [ "version", "listing", "previous", "can_decide" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] }, "reviewSkillMarketVersionResponse200": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "body": { "type": "string", "description": "The SKILL.md body. Omitted from marketplace list responses; included in the review queue." }, "argument_hint": { "type": [ "string", "null" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "claude_code_allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tools pre-approved when the skill runs in Claude Code." }, "disable_model_invocation": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] }, "description": "Supporting files under scripts/ or references/, sorted by path. Present whenever `body` is, except on a review-queue `previous` version." } }, "required": [ "name", "description", "argument_hint", "allowed_tools", "claude_code_allowed_tools", "disable_model_invocation" ] }, "risk_tier": { "type": [ "string", "null" ], "enum": [ "clean", "review", "high", null ] }, "honest_summary": { "type": [ "object", "null" ], "properties": { "what_it_does": { "type": "string" }, "tools_used": { "type": "array", "items": { "type": "string" } }, "data_it_touches": { "type": "string" }, "risk_notes": { "type": "array", "items": { "type": "string" } }, "description_matches": { "type": "boolean" }, "mismatch_note": { "type": [ "string", "null" ] } }, "required": [ "what_it_does", "tools_used", "data_it_touches", "risk_notes", "description_matches", "mismatch_note" ], "description": "Generated from the skill body, not its description." }, "scan_status": { "type": "string", "enum": [ "scanning", "passed", "failed", "error" ], "description": "Present only for the listing author." }, "scan_findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "message": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "rules", "classifier" ] } }, "required": [ "rule", "severity", "message", "excerpt", "source" ] }, "description": "Present only for the listing author." }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "auto_approved", "approved", "rejected", "superseded" ], "description": "Present only for the listing author." }, "review_note": { "type": [ "string", "null" ], "description": "Present only for the listing author." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." } }, "required": [ "id", "version", "snapshot", "risk_tier", "honest_summary", "created_at" ] } }, "required": [ "version" ] }, "reviewSkillMarketVersionRequest": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve" ] }, "ack_high_risk": { "type": "boolean", "description": "Required to approve a version whose `risk_tier` is `high`." }, "ack_mismatch": { "type": "boolean", "description": "Required when `honest_summary.description_matches` is false: the description understates the skill." }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "reject" ] }, "note": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Shown to the author." } }, "required": [ "action", "note" ], "additionalProperties": false } ], "example": { "action": "approve", "ack_high_risk": true } }, "postSlackMessageResponse200": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "channel_id": { "type": "string" }, "ts": { "type": "string" } }, "required": [ "ok", "channel_id", "ts" ], "example": { "ok": true, "channel_id": "C0123ABCDEF", "ts": "1730000000.123456" } }, "postSlackMessageResponse401": { "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": [ "slack_bot_not_in_channel", "slack_channel_archived", "slack_channel_restricted", "provider_rejected" ] } }, "required": [ "error" ] }, "postSlackMessageResponse409": { "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": [ "slack_bot_not_in_channel", "slack_channel_archived", "slack_channel_restricted", "provider_rejected" ] } }, "required": [ "error" ] }, "postSlackMessageRequest": { "type": "object", "properties": { "channel_id": { "type": "string", "pattern": "^[CG][A-Z0-9]{8,20}$" }, "text": { "type": "string", "maxLength": 3000, "pattern": "\\S" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "type" ], "additionalProperties": {} }, "minItems": 1, "maxItems": 49 }, "thread_ts": { "type": "string", "pattern": "^\\d{10}\\.\\d{6}$" } }, "required": [ "channel_id", "text" ], "additionalProperties": false, "example": { "channel_id": "C0123ABCDEF", "text": "Shipped v1.4.2 to production: 3 changes", "blocks": [ { "type": "section", "text": { "type": "mrkdwn", "text": "*Shipped v1.4.2 to production*\n- Faster export" } } ] } } }, "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`; one whose reasoning model spends its whole output budget thinking is answered with a 422 or 502 (see those responses). 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. The one exception is output-budget exhaustion: a `wait: true` request answers it with the 422 or 502 error envelope (plus `quest_id`) instead of this body. `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). A `wait: true` turn whose `max_tokens` a reasoning model spent entirely on thinking is `errorCode: output_budget_exhausted`; `quest_id` names the settled quest. Raise `max_tokens` or omit it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendChatMessageResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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. A free-tier daily credit cap hit is distinguished by `errorCode: daily_free_limit_reached` and a `Retry-After` header until the next UTC midnight.", "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": "A `wait: true` turn failed upstream: a reasoning model spent the whole server-chosen output budget thinking and produced no answer. The quest (`quest_id`) is settled as an error. An unchanged retry is likely to fail the same way; a shorter prompt or an explicit `max_tokens` may help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sendChatMessageResponse502" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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. 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 holds neither the `ai:chat` nor the `ai:generate` scope, or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`), or a non-admin caller sent `confidence_overrides`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/startAgentExecutionResponse403" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 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`, `decide`) 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. A final non-blank assistant message is an assistant prefill, except a server-tool continuation ending in `server_tool_use` or `tool_search_tool_result`. Plain system prompts and blank messages are ignored. Check the model's `supports_assistant_prefill` field from `GET /api/v1/models` before sending one. 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` (`backend` `\"anthropic\"` or `\"bedrock\"`), 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 `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: an empty `messages` array, a conversation with no non-empty user or assistant message (system-only, or only blank content), a malformed request, or an unknown `model` `400` (`errorCode: \"unknown_model\"` for an unknown model), a bad credential `401`, a key without a required scope `403` (with `required_scopes`), a free-tier account calling a model outside the free-tier allowlist `403` with `errorCode: \"model_requires_subscription\"` (upgrade the plan or pick a free-tier model), a body over 25 MB `413`, any other 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, or a model that could only come from a self-hosted model server (Ollama, local image) that is currently unreachable, `503` with `errorCode: \"provider_not_configured\"` (retryable). A provider rejection of caller input that happens before the stream opens is also a JSON `400`, with `errorCode: \"invalid_request\"` (do not retry it unchanged). 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, `invalid_request` when the provider rejects caller input (do not retry it unchanged), `provider_rejected` when the model provider refused our credentials, `content_blocked` when the model declined the request (do not retry it unchanged), `output_budget_exhausted` when a reasoning model spent your whole `max_tokens` thinking and wrote no answer (raise `max_tokens` or omit it; 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`), a model that rejects a final assistant message (`errorCode: \"assistant_prefill_unsupported\"`), provider-rejected caller input (`errorCode: \"invalid_request\"`), 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`). Mid-conversation tool changes are refused with: `tool_changes_unsupported` (a `tool_addition` / `tool_removal` system message on a model that cannot serve it here), `invalid_tool_change` (a malformed block, or one placed where the provider does not accept it), and `unknown_tool_reference` (a changed tool not in `tools`).", "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, or the self-hosted model server that lists it (Ollama, local image) is unreachable (`errorCode: \"provider_not_configured\"`), or the database is unreachable, including while verifying the plan of a free-tier model caller (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" } } } }, "429": { "description": "The API key exceeded its rate limit, or the provider stayed at its concurrency limit for longer than the request could wait. `Retry-After` says when to try again; 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" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "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" } } } }, "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" } } } }, "429": { "description": "The API key exceeded its rate limit, or the provider stayed at its concurrency limit for longer than the request could wait. `Retry-After` says when to try again; 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" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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" } } } }, "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. `credits.monthly_allowance` totals monthly personal plan grants, including custom grants; it is null when unavailable and may be omitted by older servers. 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": "Rate limit exceeded: the key's own limits, or this endpoint's per-key read limit.", "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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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": [ "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`. GPT-image accepts 15 references; FLUX.2 accepts 8 total input images (4 for Klein), including images attached through `fabFileIds`. Unsupported models and an oversized reference list are rejected with a 400. The combined FLUX.2 input limit is checked when the render resolves attachments; exceeding it fails the polled quest. 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 an unsupported model or its distinct ids alone exceed the model's reference limit, 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`; the URL is bound to `file_size`, so the body must be exactly that many bytes or storage refuses it with 403; (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/text-refinements": { "post": { "operationId": "createTextRefinement", "summary": "Refine text", "description": "Rewrites `text` to be more concise, clear and detailed while keeping its intent. `context` is optional background that steers the rewrite. `text` is at most 10000 characters and `context` at most 10000. Output is capped at about 800 tokens, and identical requests are served from a cache for about five minutes. A refinement the model runs is billed in credits for the tokens it used; a cached answer is free. 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/createTextRefinementRequest" } } } }, "responses": { "200": { "description": "The refined text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTextRefinementResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 text-refinement provider refused the configured key (`errorCode: \"provider_rejected\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTextRefinementResponse401" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 `ai:generate`, or AI features are disabled on this account by an administrator.", "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 caller cannot afford the refinement - 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/createTextRefinementResponse422" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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" } } } }, "500": { "description": "Unexpected server error (for example the refinement cache is unavailable).", "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 model call failed for a reason other than a rejected credential, or returned no refined text.", "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 operations model configured (`errorCode: \"provider_not_configured\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTextRefinementResponse503" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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/text-refinements\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"text\": \"a dog on a beach\",\n \"context\": \"prompt for an image generator\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/text-refinements\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"text\": \"a dog on a beach\",\n \"context\": \"prompt for an image generator\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/text-refinements\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"text\": \"a dog on a beach\",\n \"context\": \"prompt for an image generator\"\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": "An `inputs` file (or `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`, or `unsupported_input_role` for an input role the model does not take), an unknown, unavailable or retired model (`model_unavailable`; for a retired model the message names the model to use instead), 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" } } } }, "429": { "description": "Rate limit exceeded, or the account used up its tokens-per-minute allowance (`errorCode: \"token_rate_limit_exceeded\"`; `Retry-After` says when the window drains).", "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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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" } } } }, "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/whats-new/media/{id}/{asset}": { "get": { "operationId": "getWhatsNewMedia", "summary": "Get release note media", "description": "Redirects to one file of a published release note video or still image: `landscape` and `portrait` are the 16:9 and 9:16 MP4s, the `-poster` assets their still images, and `image-landscape` and `image-portrait` the 16:9 and 9:16 still images of the note's `image`. The `video` and `image` URLs that listWhatsNew returns for uploaded files point here, so a browser can use them as `src` and `poster` as they are. Public: no credentials are needed, and the note must be one listWhatsNew would show. The redirect is cacheable for up to 10 minutes and its target is signed for 1 hour, longer than that, so follow it rather than storing the target. Rate limited per client IP.", "tags": [ "Release notes" ], "security": [], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "landscape", "landscape-poster", "portrait", "portrait-poster", "image-landscape", "image-portrait" ] }, "required": true, "name": "asset", "in": "path" } ], "responses": { "303": { "description": "`Location` is a time-limited signed GET for the file.", "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 file.", "schema": { "type": "string" } } } }, "404": { "description": "No published note has this id, or the note has no such file, or the file is not an upload this deployment serves (a linked URL is listed as is, not through this 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" } } } }, "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": "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. Provider work stops being awaited after 45 seconds from request arrival, leaving time to return reserved credits and delete the upload before the hosted server stops at 60 seconds. A slow recording returns a gateway timeout (`504`) instead of text. AWS batch jobs cannot be cancelled remotely and may finish later; their output expires automatically. Do not retry with the same `file_key`: mint a new upload and send shorter audio. If cleanup fails, the upload may not be deleted right away (it expires on its own).", "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" } } } }, "504": { "description": "The transcription exceeded the request deadline; reserved credits are returned.", "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\" \\\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)" } ] } }, "/api/v1/agents/{id}/generate-avatar": { "post": { "operationId": "generateAgentAvatar", "summary": "Generate an agent avatar", "description": "Generates a portrait for an agent you own from its name, description and personality, stores it, and saves it as the agent portrait. Requires `agents:write`: the assistants run models on the deployment, which is management of the agent.", "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/generateAgentAvatarRequest" } } } }, "responses": { "200": { "description": "The stored portrait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateAgentAvatarResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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": "`image_model` is not an available image model (`errorCode: unknown_model`), no image model is configured, or the generated image would exceed the caller storage quota (`errorCode: storage_limit_exceeded`). Nothing is written.", "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`. The same status also answers a caller whose account has AI access revoked; that body carries only `error`, with no `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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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, or the account used up its tokens-per-minute or concurrent-request allowance (`errorCode: \"token_rate_limit_exceeded\"`, with a `Retry-After` for when the window drains, or `\"concurrency_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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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" } } } }, "502": { "description": "The image provider failed, refused the prompt, or the generated image was flagged by content moderation. Nothing is written; retry later.", "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//generate-avatar\" \\\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/agents//generate-avatar\", {\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/agents//generate-avatar\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={},\n)" } ] } }, "/api/v1/agents/{id}/generate-description": { "post": { "operationId": "generateAgentDescription", "summary": "Generate an agent description", "description": "Writes a description for an agent you own from its personality, identity and capabilities. The description is returned and not saved: send it back with `updateAgent` to keep it. Requires `agents:write`: the assistants run models on the deployment, which is management of the agent.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The generated description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateAgentDescriptionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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`. The same status also answers a caller whose account has AI access revoked; that body carries only `error`, with no `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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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, or the account used up its tokens-per-minute or concurrent-request allowance (`errorCode: \"token_rate_limit_exceeded\"`, with a `Retry-After` for when the window drains, or `\"concurrency_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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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" } } } }, "502": { "description": "The model or image provider failed to produce a result. Nothing is written; retry later.", "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//generate-description\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agents//generate-description\", {\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/agents//generate-description\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/agents/{id}/generate-system-prompt": { "post": { "operationId": "generateAgentSystemPrompt", "summary": "Generate an agent system prompt", "description": "Writes a system prompt for an agent you own from its metadata and saves it as the agent system prompt, replacing the current one. Generations for one agent are rate limited by an admin-set interval. Requires `agents:write`: the assistants run models on the deployment, which is management of the agent.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The saved system prompt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/generateAgentSystemPromptResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 assistant cannot run: the feature is disabled or not configured on this deployment. Nothing is written.", "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`. The same status also answers a caller whose account has AI access revoked; that body carries only `error`, with no `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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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, this agent system prompt was generated more recently than the admin-set interval allows, or the account used up its tokens-per-minute or concurrent-request allowance (`errorCode: \"token_rate_limit_exceeded\"`, with a `Retry-After` for when the window drains, or `\"concurrency_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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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" } } } }, "502": { "description": "The model or image provider failed to produce a result. Nothing is written; retry later.", "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//generate-system-prompt\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agents//generate-system-prompt\", {\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/agents//generate-system-prompt\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/agents/{id}/enhance-field": { "post": { "operationId": "enhanceAgentField", "summary": "Enhance an agent personality field", "description": "Rewrites one personality field of an agent you own into a richer version that keeps the original idea. The result is returned and not saved: send it back with `updateAgent` to keep it. Unknown body fields are rejected. Requires `agents:write`: the assistants run models on the deployment, which is management of the agent.", "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/enhanceAgentFieldRequest" } } } }, "responses": { "200": { "description": "The enhanced text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/enhanceAgentFieldResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 model is available to run the enhancement on 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 lacks `agents:write`. The same status also answers a caller whose account has AI access revoked; that body carries only `error`, with no `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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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, or the account used up its tokens-per-minute or concurrent-request allowance (`errorCode: \"token_rate_limit_exceeded\"`, with a `Retry-After` for when the window drains, or `\"concurrency_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" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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" } } } }, "502": { "description": "The model or image provider failed to produce a result. Nothing is written; retry later.", "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//enhance-field\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"field_name\": \"quirk\",\n \"current_value\": \"Hums while thinking\"\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/agents//enhance-field\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"field_name\": \"quirk\",\n \"current_value\": \"Hums while thinking\"\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/agents//enhance-field\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"field_name\": \"quirk\",\n \"current_value\": \"Hums while thinking\"\n },\n)" } ] } }, "/api/v1/skills/market/claude-marketplace.json": { "get": { "operationId": "getClaudeMarketplace", "summary": "Get an organization's Claude Code plugin marketplace", "description": "Returns a Claude Code `marketplace.json` listing the organization's approved Organization-visibility Skill Market listings, one `archive` plugin each, pinned by `sha256`, followed by one `archive` plugin per skill bundle whose `version` is a hash prefix, not a semantic version. Public and unlisted listings are not included. Responses are never cacheable. Authenticate with an API key (`b4m_live_`) carrying `skills:read`, sent as `Authorization: Bearer`. Claude Code sends that header when it is set as the marketplace source's `headers` in its settings, and forwards it to the same-origin plugin archives.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "orgId", "in": "query" } ], "responses": { "200": { "description": "The marketplace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getClaudeMarketplaceResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 `skills:read`, or the caller is not a member of the organization.", "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 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": [ "skills:read" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/skills/market/claude-marketplace.json\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/claude-marketplace.json\", {\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/skills/market/claude-marketplace.json\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/skills/market/{id}/claude-plugin.zip": { "get": { "operationId": "getClaudePluginZip", "summary": "Download a Skill Market listing as a Claude Code plugin", "description": "A zip holding an approved version as `skills//SKILL.md`, plus any supporting files the version ships under `skills//scripts/` and `skills//references/`. The optional `version` query pins the listing version advertised by the feed, so later approvals do not change its bytes or `sha256`. Without it, returns the current approved version. Authenticate with an API key (`b4m_live_`) carrying `skills:read`, sent as `Authorization: Bearer`. Claude Code sends that header when it is set as the marketplace source's `headers` in its settings, and forwards it to the same-origin plugin archives.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "exclusiveMinimum": 0 }, "required": false, "name": "version", "in": "query" } ], "responses": { "200": { "description": "The plugin archive.", "content": { "application/zip": { "schema": { "type": "string", "contentEncoding": "binary" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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": "Invalid version query.", "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 `skills: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 Organization listing with that id is visible to the caller. A listing in an org you are not in, a public or unlisted listing, and a malformed id are all 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" } } } }, "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": [ "skills:read" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/skills/market//claude-plugin.zip\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market//claude-plugin.zip\", {\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/skills/market//claude-plugin.zip\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/skills/market/bundles/{id}/claude-plugin.zip": { "get": { "operationId": "getClaudeBundleZip", "summary": "Download a Skill Market bundle as a Claude Code plugin", "description": "A zip holding the current approved version of each of an organization bundle's member listings, each as `skills//SKILL.md` plus its supporting files. Members that are no longer approved or visible are left out. Authenticate with an API key (`b4m_live_`) carrying `skills:read`, sent as `Authorization: Bearer`. Claude Code sends that header when it is set as the marketplace source's `headers` in its settings, and forwards it to the same-origin plugin archives.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The plugin archive.", "content": { "application/zip": { "schema": { "type": "string", "contentEncoding": "binary" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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": "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" } } } }, "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 `skills: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 bundle with that id is visible to the caller, or none of its members is approved. A bundle in an org you are not in 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" } } } }, "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": [ "skills:read" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/skills/market/bundles//claude-plugin.zip\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/bundles//claude-plugin.zip\", {\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/skills/market/bundles//claude-plugin.zip\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/skills/market/listings": { "get": { "operationId": "listSkillMarketListings", "summary": "Browse Skill Market listings", "description": "Lists the approved Public listings and the Organization listings of your organizations, with search and filters. Unlisted listings never appear. Cursor-paginated: pass `next_cursor` back as `cursor` until it is `null`, keeping the same filters.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 24 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "maxLength": 200, "description": "Full-text search over name, description and summary." }, "required": false, "description": "Full-text search over name, description and summary.", "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "public", "org" ] }, "required": false, "name": "scope", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated; matches listings carrying any of the first 5." }, "required": false, "description": "Comma-separated; matches listings carrying any of the first 5.", "name": "tags", "in": "query" }, { "schema": { "type": "string", "enum": [ "with", "without" ] }, "required": false, "name": "tools", "in": "query" }, { "schema": { "type": [ "number", "null" ], "minimum": 0, "maximum": 5 }, "required": false, "name": "min_rating", "in": "query" }, { "schema": { "type": "string", "enum": [ "relevance", "top", "imports", "new", "updated" ], "description": "Defaults to `relevance` with `q`, else `top`." }, "required": false, "description": "Defaults to `relevance` with `q`, else `top`.", "name": "sort", "in": "query" } ], "responses": { "200": { "description": "One page of listings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listSkillMarketListingsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 `skills:read` nor `skills: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": "A query value is out of range, or `cursor` is malformed or was issued for a different `limit`.", "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-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" } } } } }, "x-required-scopes": [ "skills:read", "skills:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/skills/market/listings\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/listings\", {\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/skills/market/listings\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "post": { "operationId": "publishSkillMarketListing", "summary": "Publish a skill to the Skill Market", "description": "Creates a listing from a skill you own and submits its first version. Every version is safety-scanned. A clean version goes live at once; one that needs a human waits in review, and importers keep receiving the previous approved version until it is approved. A skill has at most one live listing: to publish a change, submit a new version instead. Unknown body fields are rejected.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/publishSkillMarketListingRequest" } } } }, "responses": { "201": { "description": "The listing and its scanned first version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/publishSkillMarketListingResponse201" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 skill was imported from the market, no organization was chosen, a tag is invalid, or you have reached your active listing cap.", "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 `skills:write`, or the caller may not act on this listing. Also: you are not in the organization, your account is too new for a Public listing, or moderators removed this skill from the market.", "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 skill with that id is yours.", "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": "This skill already has a live listing.", "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": "Submission rate limit exceeded (10 scans per hour and an admin-set daily cap), or 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" } } } } }, "x-required-scopes": [ "skills:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/skills/market/listings\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"skill_id\": \"664f1c2b9a1e4d0012ab34cd\",\n \"visibility\": \"organization\",\n \"tags\": [\n \"review\"\n ]\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/listings\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"skill_id\": \"664f1c2b9a1e4d0012ab34cd\",\n \"visibility\": \"organization\",\n \"tags\": [\n \"review\"\n ]\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/skills/market/listings\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"skill_id\": \"664f1c2b9a1e4d0012ab34cd\",\n \"visibility\": \"organization\",\n \"tags\": [\n \"review\"\n ]\n },\n)" } ] } }, "/api/v1/skills/market/listings/{id}": { "get": { "operationId": "getSkillMarketListing", "summary": "Get a Skill Market listing", "description": "Returns a listing with its current approved version, recent ratings and your import of it. The author also sees a listing that is not live. `token` unlocks an unlisted listing. Author-only fields (`share_token`, `source_skill_id`, `pending_version`) need `skills:write` or a signed-in session.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "maxLength": 64, "description": "An unlisted listing's share token." }, "required": false, "description": "An unlisted listing's share token.", "name": "token", "in": "query" } ], "responses": { "200": { "description": "The listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getSkillMarketListingResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 `skills:read` nor `skills: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 listing with that id is visible to the caller. A listing you cannot see, a deleted listing and a malformed id are all 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-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" } } } } }, "x-required-scopes": [ "skills:read", "skills:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/skills/market/listings/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/listings/\", {\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/skills/market/listings/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] }, "delete": { "operationId": "withdrawSkillMarketListing", "summary": "Withdraw a Skill Market listing", "description": "Takes your listing off the market. Importers keep their copies; a version awaiting review is superseded. You can publish the skill again afterwards.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "The listing was withdrawn.", "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 `skills:write`, or the caller may not act on this listing. Only the author can withdraw.", "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 listing with that id exists.", "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 listing is already withdrawn or delisted.", "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-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" } } } } }, "x-required-scopes": [ "skills:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X DELETE \"https://your-deployment.example.com/api/v1/skills/market/listings/\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/listings/\", {\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/skills/market/listings/\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/skills/market/listings/mine": { "get": { "operationId": "listMySkillMarketListings", "summary": "List your Skill Market listings", "description": "Lists the listings you published, newest first, in any status, each with its 5 newest versions and their scan findings and review notes. Cursor-paginated.", "tags": [ "Skills" ], "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, "description": "Only the listing published from this skill." }, "required": false, "description": "Only the listing published from this skill.", "name": "source_skill_id", "in": "query" } ], "responses": { "200": { "description": "One page of your listings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listMySkillMarketListingsResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 `skills: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.", "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-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" } } } } }, "x-required-scopes": [ "skills:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/skills/market/listings/mine\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/listings/mine\", {\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/skills/market/listings/mine\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/skills/market/listings/{id}/versions": { "post": { "operationId": "submitSkillMarketListingVersion", "summary": "Submit a new version of a Skill Market listing", "description": "Submits the source skill's current content as the listing's next version. Every version is safety-scanned. A clean version goes live at once; one that needs a human waits in review, and importers keep receiving the previous approved version until it is approved. The body is optional.", "tags": [ "Skills" ], "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/submitSkillMarketListingVersionRequest" } } } }, "responses": { "201": { "description": "The listing and the scanned version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submitSkillMarketListingVersionResponse201" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 tag is invalid, or the content is unchanged since the last version.", "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 `skills:write`, or the caller may not act on this listing. Only the author can submit, and only while still in the organization.", "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 listing, or the skill it was published from, no longer exists.", "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 listing is withdrawn or delisted.", "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": "Submission rate limit exceeded (10 scans per hour and an admin-set daily cap), or 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" } } } } }, "x-required-scopes": [ "skills:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/skills/market/listings//versions\" \\\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/skills/market/listings//versions\", {\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/skills/market/listings//versions\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={},\n)" } ] } }, "/api/v1/skills/market/listings/{id}/import": { "post": { "operationId": "importSkillMarketListing", "summary": "Import a Skill Market listing", "description": "Copies the listing's current approved version into your skills, or with `target_skill_id` refreshes an earlier copy. Pending or rejected content is never imported. The body is optional.", "tags": [ "Skills" ], "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/importSkillMarketListingRequest" } } } }, "responses": { "200": { "description": "The earlier copy was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/importSkillMarketListingResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests remaining in the current day.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Unix epoch (seconds) when the day window resets.", "schema": { "type": "integer" } } } }, "201": { "description": "A new copy was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/importSkillMarketListingResponse201" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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": "This is your own listing, the new name is invalid, or the target copy is shared with everyone.", "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 `skills: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 listing with that id is visible to the caller. A listing you cannot see, a deleted listing and a malformed id are all reported as 404. Also: `target_skill_id` is not your copy 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" } } } }, "409": { "description": "`version_changed`: a newer version was approved since `expected_version_id`. `local_changes`: you edited the target copy; retry with `overwrite: true`. `name_taken`: retry with `name`. With no `errorCode`: a concurrent write raced the import; retry it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/importSkillMarketListingResponse409" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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": "Import rate limit exceeded (60 per hour), or 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" } } } } }, "x-required-scopes": [ "skills:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/skills/market/listings//import\" \\\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/skills/market/listings//import\", {\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/skills/market/listings//import\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={},\n)" } ] } }, "/api/v1/skills/market/versions/{vid}/rescan": { "post": { "operationId": "rescanSkillMarketVersion", "summary": "Rescan a Skill Market version", "description": "Retries the safety scan of one of your versions whose scan errored or stalled.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "vid", "in": "path" } ], "responses": { "200": { "description": "The rescanned version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rescanSkillMarketVersionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 `skills:write`, or the caller may not act on this listing. Only the author can rescan.", "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 version with that id exists.", "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 version is not waiting for a rescan: its scan finished, or another one is running.", "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": "Submission rate limit exceeded (10 scans per hour and an admin-set daily cap), or 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" } } } } }, "x-required-scopes": [ "skills:write" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/skills/market/versions//rescan\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/versions//rescan\", {\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/skills/market/versions//rescan\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/skills/market/review-queue": { "get": { "operationId": "listSkillMarketReviewQueue", "summary": "List Skill Market versions awaiting review", "description": "Lists the held versions you can review, oldest first, each with its listing and the approved version it would replace. Under an API key without `admin:*` this is the Organization listings of the organizations you administer. Cursor-paginated, but a page can be shorter than `limit`, even empty, while `next_cursor` is non-null: keep passing `next_cursor` back as `cursor` until it is `null`. A version that finishes scanning after you paged past its creation time shows up on the next pass that starts without a cursor.", "tags": [ "Skills" ], "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 the review queue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listSkillMarketReviewQueueResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 `skills:review`, or you administer no organization.", "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.", "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-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" } } } } }, "x-required-scopes": [ "skills:review" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X GET \"https://your-deployment.example.com/api/v1/skills/market/review-queue\" \\\n -H \"Authorization: Bearer b4m_live_\"" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/review-queue\", {\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/skills/market/review-queue\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n)" } ] } }, "/api/v1/skills/market/versions/{vid}/review": { "post": { "operationId": "reviewSkillMarketVersion", "summary": "Approve or reject a held Skill Market version", "description": "Approving puts the version live for importers; rejecting keeps the earlier approved version live and needs a `note` for the author.", "tags": [ "Skills" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "vid", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reviewSkillMarketVersionRequest" } } } }, "responses": { "200": { "description": "The decided version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reviewSkillMarketVersionResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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": "Approval needs `ack_high_risk` or `ack_mismatch`.", "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 `skills:review`, or you may not review this listing: it is not an Organization listing of an organization you administer, or it is your own Public listing.", "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 version with that id exists, or its listing is gone.", "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 version is no longer awaiting review: it was decided or superseded.", "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": "The body is invalid, e.g. a reject without a `note`.", "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-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" } } } } }, "x-required-scopes": [ "skills:review" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/skills/market/versions//review\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"action\": \"approve\",\n \"ack_high_risk\": true\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/skills/market/versions//review\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"action\": \"approve\",\n \"ack_high_risk\": true\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/skills/market/versions//review\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"action\": \"approve\",\n \"ack_high_risk\": True\n },\n)" } ] } }, "/api/v1/slack/messages": { "post": { "operationId": "postSlackMessage", "summary": "Post a Slack message", "description": "Posts a message to a Slack channel, or a reply in a thread with `thread_ts`, as the Bike4Mind bot. Returns the message `ts`; pass it back as `thread_ts` to reply in that thread. Three things must hold: the key carries `slack:post`; the channel is in a Slack workspace connected to an organization the key's owner belongs to (an organization-billed key must bill that same organization); and an owner of that same organization (or a platform admin) has enabled the channel for API posting, optionally limited to listed key ids. Disconnecting the workspace turns every opt-in off. `slack:post` is a confined scope: a posting key carries no other scope and reaches no other route. Mint one from the organization's Slack integration settings. The bot must also be a member of the channel: invite it with `/invite @`. `text` is at most 3000 characters and is the notification fallback when `blocks` (Block Kit, at most 49 blocks and 40000 serialized characters) is sent. Blocks are limited to section, header, divider, context, image, rich_text; nothing a reader can act on is accepted: no interactive elements, `action_id`, `confirm`, or `url` outside a rich_text link, and a section `accessory` must be an image. Broadcast mentions (``, ``, ``, user groups, and bare `@channel` / `@here` / `@everyone`) are posted as plain text that notifies nobody; `<@U...>` user mentions are kept. Every post ends with a context block naming the posting user and key, and carries message metadata marking it as an API post; Slack actions on it are ignored. A block Slack rejects as malformed answers 422. Rate limited to 30 messages a minute and 1,000 a day per key and per user, and 60 a minute per channel, on top of the key's own limits. Authenticate with an API key (`b4m_live_`) carrying `slack:post`.", "tags": [ "Slack" ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSlackMessageRequest" } } } }, "responses": { "200": { "description": "The message was posted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSlackMessageResponse200" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 Slack refused the connected workspace credentials (`errorCode: \"provider_rejected\"`; an organization owner must reconnect the workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSlackMessageResponse401" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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 key lacks `slack:post`, the request was not made with an API key, or the channel is not enabled for API posting by an organization the key's owner belongs to (or not for this key).", "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" } } } }, "409": { "description": "The bot is not a member of the channel (`errorCode: \"slack_bot_not_in_channel\"`; invite it), or the channel is archived (`errorCode: \"slack_channel_archived\"`), or the channel restricts posting, such as announcement-only or thread-only (`errorCode: \"slack_channel_restricted\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSlackMessageResponse409" } } }, "headers": { "X-Request-ID": { "description": "Correlation id for this request; safe to log and quote in support requests.", "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "description": "Request quota per minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Minute": { "description": "Unix epoch (seconds) when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Request quota per day.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests 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-key rate limit exceeded, or Slack is rate limiting the bot. Honor `Retry-After`.", "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": "Slack failed to post the message.", "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": [ "slack:post" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s -X POST \"https://your-deployment.example.com/api/v1/slack/messages\" \\\n -H \"Authorization: Bearer b4m_live_\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'B4M_REQUEST_BODY'\n{\n \"channel_id\": \"C0123ABCDEF\",\n \"text\": \"Shipped v1.4.2 to production: 3 changes\",\n \"blocks\": [\n {\n \"type\": \"section\",\n \"text\": {\n \"type\": \"mrkdwn\",\n \"text\": \"*Shipped v1.4.2 to production*\\n- Faster export\"\n }\n }\n ]\n}\nB4M_REQUEST_BODY" }, { "lang": "JavaScript", "label": "fetch", "source": "const res = await fetch(\"https://your-deployment.example.com/api/v1/slack/messages\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer b4m_live_\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"channel_id\": \"C0123ABCDEF\",\n \"text\": \"Shipped v1.4.2 to production: 3 changes\",\n \"blocks\": [\n {\n \"type\": \"section\",\n \"text\": {\n \"type\": \"mrkdwn\",\n \"text\": \"*Shipped v1.4.2 to production*\\n- Faster export\"\n }\n }\n ]\n}),\n});" }, { "lang": "Python", "label": "requests", "source": "import requests\n\nres = requests.post(\n \"https://your-deployment.example.com/api/v1/slack/messages\",\n headers={\"Authorization\": \"Bearer b4m_live_\"},\n json={\n \"channel_id\": \"C0123ABCDEF\",\n \"text\": \"Shipped v1.4.2 to production: 3 changes\",\n \"blocks\": [\n {\n \"type\": \"section\",\n \"text\": {\n \"type\": \"mrkdwn\",\n \"text\": \"*Shipped v1.4.2 to production*\\n- Faster export\"\n }\n }\n ]\n },\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." }, { "name": "Skills", "description": "Your organization's approved Skill Market listings, served as a Claude Code plugin marketplace." }, { "name": "Slack", "description": "Post status messages and thread replies to Slack channels through the Bike4Mind bot, without holding a Slack token." } ] }