> ## 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. # Proxy a request to a sandbox port The node side of sandbox port previews. People and agents do not call it directly: they open `https://usercontent.b3os.org/sbx////`, and the usercontent Worker checks the token, then forwards the request here (through the tunnel, like the edge) with the token in `x-b3os-port-token`. A path that ends at the token is redirected to the same path plus `/`, so relative URLs resolve under it. beta-api.b3os.org and beta.b3os.org never serve this route (`x-b3os-host: usercontent`). **Port token** (from `POST /v1/sandboxes/{sandbox_id}/ports/{port}/url`, or a public port's `ports[].url`): `pt1...`. `node` is the signing node's ID (`n1`), `exp` the expiry in Unix seconds (decimal, no leading zeros) and `sig` the base64url (no padding) Ed25519 signature, made with the node key (the one that signs usage batches) over the UTF-8 bytes of ``` "b3os-port-v1 " + node + " " + sandbox_id + " " + port + " " + exp ``` with `sandbox_id` in `sbx_` form (not the host-safe form) and `port` in decimal. A token is good for that sandbox and port only, until `exp`. The Worker checks the signature with the public key it holds for `node` (`verify_strict`) and the expiry before forwarding; the node checks both again, that `node` is its own ID, that the sandbox is running and that the port is declared, then connects to the port inside the sandbox over vsock. A refused token is `403 signed_url_invalid` with `reason`. **Forwarding.** The proxy forwards exactly seven methods, each declared here as its own operation: `GET` (WebSocket upgrades included), `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` and `OPTIONS` (`sandboxesProxyPortGet` … `sandboxesProxyPortOptions`). Every other method, `TRACE` and `CONNECT` included, is refused with `405 method_not_allowed` and an `Allow` header naming the seven. The app receives the request at `/`, without the `/sbx///` prefix; `rest` may be empty (`…/proxy/` reaches the app's root), and it and the query string are passed byte for byte. The request carries `X-Forwarded-Proto: https`, `X-Forwarded-Host: usercontent.b3os.org` and `X-Forwarded-Prefix: /sbx///`. The response comes back as the app sends it (status, headers, streamed body) minus hop-by-hop headers, `Set-Cookie`, and the two headers that would reach past the preview's own path on the shared origin, `Service-Worker-Allowed` and `Clear-Site-Data`; `Cookie` is removed from requests too (no cookies on usercontent in either direction). Unless the app sets `Referrer-Policy`, the proxy adds `Referrer-Policy: strict-origin`, so the token in the path is not sent to other sites. A response starts within 65 seconds; a WebSocket or a streamed body stays open up to an hour. **Base path.** All previews share the `usercontent.b3os.org` origin in v0.1 (per-port hostnames are planned): a page served from one port can send same-origin requests to any other usercontent URL it knows, so keep secrets out of previews. Apps should emit relative URLs. Two values describe the base path: - `X-Forwarded-Prefix` (on every forwarded request) is the request's full base path, `/sbx///`. Build absolute paths from it. - `B3OS_PORT_BASE_PATH` (in the sandbox's environment) is only the fixed start of that path, `/sbx/`, the same for every port and URL of the sandbox. It is not a full base path: the port and the token follow it, and the token differs per minted URL, so no value set when the sandbox starts can hold it. A public port's token lasts 7 days from sandbox creation, so its URL and base path (`ports[].url`) stay fixed; a sandbox that runs longer gets a new one. ` GET /v1/sandboxes/{sandbox_id}/ports/{port}/proxy/{rest} ` Proxy a request to a sandbox port The node side of sandbox port previews. People and agents do not call it directly: they open `https://usercontent.b3os.org/sbx////`, and the usercontent Worker checks the token, then forwards the request here (through the tunnel, like the edge) with the token in `x-b3os-port-token`. A path that ends at the token is redirected to the same path plus `/`, so relative URLs resolve under it. beta-api.b3os.org and beta.b3os.org never serve this route (`x-b3os-host: usercontent`). **Port token** (from `POST /v1/sandboxes/{sandbox_id}/ports/{port}/url`, or a public port's `ports[].url`): `pt1...`. `node` is the signing node's ID (`n1`), `exp` the expiry in Unix seconds (decimal, no leading zeros) and `sig` the base64url (no padding) Ed25519 signature, made with the node key (the one that signs usage batches) over the UTF-8 bytes of ``` "b3os-port-v1\n" + node + "\n" + sandbox_id + "\n" + port + "\n" + exp ``` with `sandbox_id` in `sbx_` form (not the host-safe form) and `port` in decimal. A token is good for that sandbox and port only, until `exp`. The Worker checks the signature with the public key it holds for `node` (`verify_strict`) and the expiry before forwarding; the node checks both again, that `node` is its own ID, that the sandbox is running and that the port is declared, then connects to the port inside the sandbox over vsock. A refused token is `403 signed_url_invalid` with `reason`. **Forwarding.** The proxy forwards exactly seven methods, each declared here as its own operation: `GET` (WebSocket upgrades included), `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` and `OPTIONS` (`sandboxesProxyPortGet` … `sandboxesProxyPortOptions`). Every other method, `TRACE` and `CONNECT` included, is refused with `405 method_not_allowed` and an `Allow` header naming the seven. The app receives the request at `/`, without the `/sbx///` prefix; `rest` may be empty (`…/proxy/` reaches the app's root), and it and the query string are passed byte for byte. The request carries `X-Forwarded-Proto: https`, `X-Forwarded-Host: usercontent.b3os.org` and `X-Forwarded-Prefix: /sbx///`. The response comes back as the app sends it (status, headers, streamed body) minus hop-by-hop headers, `Set-Cookie`, and the two headers that would reach past the preview's own path on the shared origin, `Service-Worker-Allowed` and `Clear-Site-Data`; `Cookie` is removed from requests too (no cookies on usercontent in either direction). Unless the app sets `Referrer-Policy`, the proxy adds `Referrer-Policy: strict-origin`, so the token in the path is not sent to other sites. A response starts within 65 seconds; a WebSocket or a streamed body stays open up to an hour. **Base path.** All previews share the `usercontent.b3os.org` origin in v0.1 (per-port hostnames are planned): a page served from one port can send same-origin requests to any other usercontent URL it knows, so keep secrets out of previews. Apps should emit relative URLs. Two values describe the base path: - `X-Forwarded-Prefix` (on every forwarded request) is the request's full base path, `/sbx///`. Build absolute paths from it. - `B3OS_PORT_BASE_PATH` (in the sandbox's environment) is only the fixed start of that path, `/sbx/`, the same for every port and URL of the sandbox. It is not a full base path: the port and the token follow it, and the token differs per minted URL, so no value set when the sandbox starts can hold it. A public port's token lasts 7 days from sandbox creation, so its URL and base path (`ports[].url`) stay fixed; a sandbox that runs longer gets a new one. ## Servers - ` https://beta-api.b3os.org ` — API (API keys and CLI tokens) - ` https://beta.b3os.org ` — Dashboard (session cookie and CSRF header; same paths) ## Parameters ### ` sandbox_id ` (path, required) The sandbox ID (`sbx_…`). - ` value `: type ` string ` - pattern: ` "^sbx_[0-9a-hjkmnp-tv-z]{26}$" ` Example: ```json "sbx_01m5t68q1b590rj801nbzsqzkk" ``` ### ` port ` (path, required) A port declared in the sandbox's `ports`. - ` value `: type ` integer ` - minimum: ` 1 ` - maximum: ` 65535 ` Example: ```json 3000 ``` ### ` rest ` (path, required) The rest of the path after the usercontent prefix, slashes included, possibly empty (the app's root). Passed to the app as `/` byte for byte. - ` value `: type ` string ` Example: ```json "assets/app.js" ``` ### ` x-b3os-port-token ` (header, required) The port token from the usercontent path (`pt1...`; see `sandboxesProxyPortGet`), set by the usercontent Worker. Missing, malformed, expired or not matching this sandbox and port: `403 signed_url_invalid`. - ` value `: type ` string ` - pattern: ` "^pt1\\.[a-z0-9-]{1,63}\\.(0|[1-9][0-9]{0,11})\\.[A-Za-z0-9_-]{86}$" ` Example: ```json "pt1.n1.1792955460.tjsgjiRC3sSYEwneW62TSvNqd-Jo_zzFI5zFYkB_YQBNl0CiBzI9xgoV6EJD_5YEmh3HbzSmb3acL8mY1LmYCg" ``` ## Responses ### ` 101 ` — Switching protocols; the WebSocket is connected to the app's WebSocket on the port. 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 ` ### ` 200 ` — The app's response, passed through (any status, headers and body; `Set-Cookie` removed). 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 ` ### ` 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" } ] } ``` ### ` 403 ` — The port token is missing, malformed, expired, for another sandbox or port, or not signed by this node (`signed_url_invalid`). 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#signed_url_invalid", "title": "Invalid or expired signed URL", "status": 403, "code": "signed_url_invalid", "detail": "The preview URL expired at 2026-10-25T19:11:00Z; request a new one with POST /v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/ports/3000/url", "instance": "req_01m5t4yg394wegr3j4y01qb363", "reason": "expired" } ``` ### ` 404 ` — No such sandbox, or the port is not declared in its `ports` (`sandbox_not_found`, `port_not_exposed`). 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#port_not_exposed", "title": "Port not exposed", "status": 404, "code": "port_not_exposed", "detail": "Port 8080 is not in the ports of sbx_01m5t68q1b590rj801nbzsqzkk", "instance": "req_01m5t4yg394wegr3j4y01qb363" } ``` ### ` 409 ` — The sandbox is paused or stopped (`sandbox_not_running`). 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#sandbox_not_running", "title": "Sandbox not running", "status": 409, "code": "sandbox_not_running", "detail": "sbx_01m5t68q1b590rj801nbzsqzkk is paused; resume it first", "instance": "req_01m5t4yg394wegr3j4y01qb363", "current_status": "paused" } ``` ### ` 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" } ``` ### ` 502 ` — Nothing in the sandbox accepted a connection on the port (`upstream_unreachable`), or the guest agent did not answer (`guest_unreachable`). 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#upstream_unreachable", "title": "Upstream unreachable", "status": 502, "code": "upstream_unreachable", "detail": "Nothing is listening on port 3000 in sbx_01m5t68q1b590rj801nbzsqzkk", "instance": "req_01m5t4yg394wegr3j4y01qb363", "reason": "connect" } ``` ### ` 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 GET 'https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/ports/3000/proxy/assets/app.js' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'x-b3os-port-token: pt1.n1.1792955460.tjsgjiRC3sSYEwneW62TSvNqd-Jo_zzFI5zFYkB_YQBNl0CiBzI9xgoV6EJD_5YEmh3HbzSmb3acL8mY1LmYCg' ``` ### JavaScript ```javascript const response = await fetch('https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/ports/3000/proxy/assets/app.js', { method: 'GET', headers: { "Authorization": "Bearer YOUR_API_TOKEN", "x-b3os-port-token": "pt1.n1.1792955460.tjsgjiRC3sSYEwneW62TSvNqd-Jo_zzFI5zFYkB_YQBNl0CiBzI9xgoV6EJD_5YEmh3HbzSmb3acL8mY1LmYCg" } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests headers = { 'Authorization': 'Bearer YOUR_API_TOKEN', 'x-b3os-port-token': 'pt1.n1.1792955460.tjsgjiRC3sSYEwneW62TSvNqd-Jo_zzFI5zFYkB_YQBNl0CiBzI9xgoV6EJD_5YEmh3HbzSmb3acL8mY1LmYCg' } response = requests.get('https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/ports/3000/proxy/assets/app.js', headers=headers) print(response.json()) ```