> ## Documentation Index > Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt > Use this file to discover all available pages before exploring further. # Update an API key Renames a key or changes its spend cap, expiry or metadata. Scopes cannot change; create a new key instead. A caller with a spend cap or an expiry cannot set a larger cap or a later (or no) expiry than its own (`forbidden`, reason `scope_escalation`). ` PATCH /v1/keys/{key_id} ` Update an API key Renames a key or changes its spend cap, expiry or metadata. Scopes cannot change; create a new key instead. A caller with a spend cap or an expiry cannot set a larger cap or a later (or no) expiry than its own (`forbidden`, reason `scope_escalation`). ## Servers - ` https://beta-api.b3os.org ` — API (API keys and CLI tokens) - ` https://beta.b3os.org ` — Dashboard (session cookie and CSRF header; same paths) ## Authentication The operation accepts these alternatives. Schemes within one alternative are required together. ### Alternative 1 - ` apiKey `: ` http ` - HTTP scheme: ` bearer ` (b3os_sk_ API key or b3os_pat_ token) - `Authorization: Bearer `. Two credential kinds are accepted: - **API keys** `b3os_sk_<32 base32>_`, created in the dashboard or with `POST /v1/keys`. A key belongs to one project, has scopes, an optional spend cap and expiry, and is shown only once. - **CLI tokens** `b3os_pat_<32 base32>_`, issued by the device login (`b3os login`). They act for one user in the organization and project chosen at approval. Keys are stored as SHA-256 hashes. The edge exchanges them for a 60-second node token before forwarding a request to a node, so nodes never see your key. ### Alternative 2 - ` session `: ` apiKey ` - Credential: ` __Host-b3os_session ` in ` cookie ` - The dashboard session cookie on `beta.b3os.org` (host-only, `Secure`, `HttpOnly`). Requests other than `GET`/`HEAD` must also send `x-b3os-csrf: ` from `GET /v1/auth/session`; SameSite is not relied on. The cookie is never sent to `beta-api.b3os.org` or `usercontent.b3os.org`. ## Parameters ### ` key_id ` (path, required) - ` value `: type ` string ` - pattern: ` "^key_[0-9a-hjkmnp-tv-z]{26}$" ` Example: ```json "key_01m5t5csy2wt4e3er052chyf1x" ``` ## Request body (required) Content type: ` application/json ` - ` value `: type ` object ` - ` name `: type ` string ` - minLength: ` 1 ` - maxLength: ` 100 ` - ` spend_cap_usd `: type ` number `; nullable - minimum: ` 0 ` - ` expires_at `: type ` string `; nullable; format ` date-time ` - ` metadata `: type ` object ` — Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them. - example: ` {"customer":"acme","ticket":"ENG-1423"} ` Example: ```json { "spend_cap_usd": 50 } ``` ## Responses ### ` 200 ` — The updated key. Content type: ` application/json ` - ` value `: type ` object ` - Required fields: ` id `, ` object `, ` kind `, ` client_id `, ` name `, ` redacted `, ` org_id `, ` project_id `, ` scopes `, ` spend_cap_usd `, ` spent_usd `, ` status `, ` expires_at `, ` created_at `, ` created_by `, ` last_used_at `, ` revoked_at `, ` metadata ` - ` id `: type ` string ` - pattern: ` "^key_[0-9a-hjkmnp-tv-z]{26}$" ` - ` object `: type ` string ` - enum: ` ["api_key"] ` - ` kind `: type ` string ` — `api_key` (`b3os_sk_…`, made with `POST /v1/keys`) or `cli_token` (`b3os_pat_…`, from the device login; `created_by` is the user who approved it). - enum: ` ["api_key","cli_token"] ` - ` client_id `: type ` string `; nullable — The device-login client a CLI token was issued to (`b3os-cli`); null for API keys. - ` name `: type ` string ` - ` redacted `: type ` string ` — The start and end of the secret, for recognizing it. - ` org_id `: type ` string ` - ` project_id `: type ` string ` - ` scopes `: type ` array ` - ` array item `: type ` string ` — A scope from the catalog (`vision:run`; `x-b3os-scopes`), `:*` for every scope of one product, or `*` for every scope. The build generates `enum` from the catalog, the same list as `dist/scopes.json` plus `:*` and `*`. - enum: ` ["vision:read","vision:write","vision:run","render:read","render:write","render:run","sandboxes:read","sandboxes:write","sandboxes:run","routines:read","routines:write","routines:run","actions:read","actions:write","actions:run","infer:read","infer:write","infer:run","vault:read","vault:write","vault:run","platform:read","platform:write","vision:*","render:*","sandboxes:*","routines:*","actions:*","infer:*","vault:*","platform:*","*"] ` - ` spend_cap_usd `: type ` number `; nullable - ` spent_usd `: type ` number ` — Spend in the current billing period. - ` status `: type ` string ` - enum: ` ["active","revoked","expired"] ` - ` expires_at `: type ` string `; nullable; format ` date-time ` - ` created_at `: type ` string `; format ` date-time ` - ` created_by `: type ` object ` - Required fields: ` type `, ` id ` - ` type `: type ` string ` - enum: ` ["user","api_key"] ` - ` id `: type ` string ` - ` last_used_at `: type ` string `; nullable; format ` date-time ` - ` revoked_at `: type ` string `; nullable; format ` date-time ` - ` metadata `: type ` object ` — Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them. - example: ` {"customer":"acme","ticket":"ENG-1423"} ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "id": "key_01m5t5csy2wt4e3er052chyf1x", "object": "api_key", "kind": "api_key", "client_id": null, "name": "research agent", "redacted": "b3os_sk_ex4m…2321", "org_id": "org_01m5t5hthd29mm5wpza5ndd6mm", "project_id": "prj_01m5t3pf8heewxt65ej3dm577y", "scopes": [ "vision:run", "sandboxes:write", "sandboxes:run", "infer:run" ], "spend_cap_usd": 50, "spent_usd": 1.42, "status": "active", "expires_at": "2026-12-31T00:00:00.000Z", "created_at": "2026-10-25T21:00:00.000Z", "created_by": { "type": "user", "id": "usr_01m5t3jv4b5sappg7vzv1rwx6x" }, "last_used_at": "2026-10-25T21:30:00.000Z", "revoked_at": null, "metadata": {} } ``` ### ` 400 ` — The request failed validation (`invalid_request`, `invalid_url`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#invalid_request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "1 field failed validation", "instance": "req_01m5t4yg394wegr3j4y01qb363", "errors": [ { "pointer": "/url", "detail": "must be an absolute http or https URL" } ] } ``` ### ` 401 ` — Missing, malformed, expired or revoked credentials (`unauthorized`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#unauthorized", "title": "Unauthorized", "status": 401, "code": "unauthorized", "detail": "API key checksum does not match; check that the whole key was copied", "instance": "req_01m5t4yg394wegr3j4y01qb363", "reason": "malformed" } ``` ### ` 403 ` — Authenticated but not allowed (`forbidden`, `egress_denied`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden", "detail": "This key lacks the scope sandboxes:write", "instance": "req_01m5t4yg394wegr3j4y01qb363", "reason": "scope", "required_scope": "sandboxes:write" } ``` ### ` 404 ` — No such key in your organization (`api_key_not_found`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#api_key_not_found", "title": "API key not found", "status": 404, "code": "api_key_not_found", "detail": "No API key key_01m5t5csy2wt4e3er052chyf1x in this organization", "instance": "req_01m5t4yg394wegr3j4y01qb363" } ``` ### ` 413 ` — The request body exceeds this operation's limit. Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#payload_too_large", "title": "Payload too large", "status": 413, "code": "payload_too_large", "detail": "Request body is 1572864 bytes; this operation accepts at most 1048576", "instance": "req_01m5t4yg394wegr3j4y01qb363" } ``` ### ` 415 ` — The Content-Type is not accepted by this operation. Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#unsupported_media_type", "title": "Unsupported media type", "status": 415, "code": "unsupported_media_type", "detail": "Expected Content-Type application/json", "instance": "req_01m5t4yg394wegr3j4y01qb363" } ``` ### ` 429 ` — A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Response header ` Retry-After ` — Seconds to wait before retrying or polling again. - ` value `: type ` integer ` - minimum: ` 0 ` Response header ` RateLimit-Limit ` — Requests allowed in the current window for the limit that applies to this operation. - ` value `: type ` integer ` Response header ` RateLimit-Remaining ` — Requests left in the current window. - ` value `: type ` integer ` Response header ` RateLimit-Reset ` — Seconds until the current window resets. - ` value `: type ` integer ` Response header ` RateLimit-Policy ` — The applied policy as `;w=;name=""` (limit IDs are listed by `GET /v1/limits`). - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#rate_limited", "title": "Rate limited", "status": 429, "code": "rate_limited", "detail": "60 scrapes per minute allowed; retry in 12 seconds", "instance": "req_01m5t4yg394wegr3j4y01qb363", "retry_after_s": 12, "limit": { "id": "vision.scrape.rpm", "limit": 60, "unit": "requests", "window_s": 60, "current": 60 } } ``` ### ` 500 ` — Something failed inside B3OS (`internal`). Retry with backoff. Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#internal", "title": "Internal error", "status": 500, "code": "internal", "detail": "internal error", "instance": "req_01m5t4yg394wegr3j4y01qb363" } ``` ### ` 503 ` — The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`. - ` value `: type ` string ` Response header ` Retry-After ` — Seconds to wait before retrying or polling again. - ` value `: type ` integer ` - minimum: ` 0 ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#node_unavailable", "title": "Node unavailable", "status": 503, "code": "node_unavailable", "detail": "Node n1 is not reachable; retry in 5 seconds", "instance": "req_01m5t4yg394wegr3j4y01qb363", "retry_after_s": 5 } ``` ## Request examples ### cURL ```curl curl -X PATCH 'https://beta-api.b3os.org/v1/keys/key_01m5t5csy2wt4e3er052chyf1x' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "spend_cap_usd": 50 }' ``` ### JavaScript ```javascript const response = await fetch('https://beta-api.b3os.org/v1/keys/key_01m5t5csy2wt4e3er052chyf1x', { method: 'PATCH', headers: { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "spend_cap_usd": 50 }) }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests headers = { 'Authorization': 'Bearer YOUR_API_TOKEN' } response = requests.patch('https://beta-api.b3os.org/v1/keys/key_01m5t5csy2wt4e3er052chyf1x', headers=headers, json={ "spend_cap_usd": 50 }) print(response.json()) ```