Download an artifact's bytes

The node side of artifact URLs. People and agents use the artifact's `url`, `https://usercontent.b3os.org/a/<artifact host id>/<name>?node=<node>&exp=<exp>&sig=<sig>`; the usercontent Worker checks the signature and serves the bytes from storage, or, until the upload has finished, from this route through the tunnel (with the same `node`, `exp` and `sig`). beta-api.b3os.org and beta.b3os.org never serve this route (`x-b3os-host: usercontent`). **Signature.** `sig` is the base64url (no padding) Ed25519 signature, made with the node key (the one that signs usage batches; the edge holds its public key), over the UTF-8 bytes of ``` "b3os-url-v1 " + node + " " + method + " " + path + " " + exp ``` `node` is the signing node's ID (`n1`, also the `node` query parameter), `method` is `GET` (a `HEAD` request is checked as `GET`), `path` is this route's path, `/v1/render/artifacts/<artifact_id>/content/<name>`, with the ID in `art_` form (not the host-safe `art-` form of the usercontent path), and `exp` is the expiry in Unix seconds, written in decimal without leading zeros. Other query parameters are not signed and are ignored. The Worker and the node both check the signature (`verify_strict`) and that `exp` has not passed; the node also checks that `node` is its own ID. A refused URL is `403 signed_url_invalid` with `reason`. `name` is the artifact's file name as it appears in `url`; any other name is `404 artifact_not_found`. **Response.** The artifact's bytes with its content type, `Content-Security-Policy: sandbox` (so a page or SVG never runs scripts or reads the origin) and `X-Content-Type-Options: nosniff`. One byte range per request (`Range: bytes=…`) is answered with `206`; an unsatisfiable or multi-part range is ignored and the whole artifact is returned. The response starts within 65 seconds; large videos then stream at the speed of the node's uplink.

GET /v1/render/artifacts/{artifact_id}/content/{name}

The node side of artifact URLs. People and agents use the artifact's `url`, `https://usercontent.b3os.org/a/<artifact host id>/<name>?node=<node>&exp=<exp>&sig=<sig>`; the usercontent Worker checks the signature and serves the bytes from storage, or, until the upload has finished, from this route through the tunnel (with the same `node`, `exp` and `sig`). beta-api.b3os.org and beta.b3os.org never serve this route (`x-b3os-host: usercontent`). **Signature.** `sig` is the base64url (no padding) Ed25519 signature, made with the node key (the one that signs usage batches; the edge holds its public key), over the UTF-8 bytes of ``` "b3os-url-v1\n" + node + "\n" + method + "\n" + path + "\n" + exp ``` `node` is the signing node's ID (`n1`, also the `node` query parameter), `method` is `GET` (a `HEAD` request is checked as `GET`), `path` is this route's path, `/v1/render/artifacts/<artifact_id>/content/<name>`, with the ID in `art_` form (not the host-safe `art-` form of the usercontent path), and `exp` is the expiry in Unix seconds, written in decimal without leading zeros. Other query parameters are not signed and are ignored. The Worker and the node both check the signature (`verify_strict`) and that `exp` has not passed; the node also checks that `node` is its own ID. A refused URL is `403 signed_url_invalid` with `reason`. `name` is the artifact's file name as it appears in `url`; any other name is `404 artifact_not_found`. **Response.** The artifact's bytes with its content type, `Content-Security-Policy: sandbox` (so a page or SVG never runs scripts or reads the origin) and `X-Content-Type-Options: nosniff`. One byte range per request (`Range: bytes=…`) is answered with `206`; an unsatisfiable or multi-part range is ignored and the whole artifact is returned. The response starts within 65 seconds; large videos then stream at the speed of the node's uplink.

Path Parameters

artifact_id string required path

The artifact ID (`art_…`).

Example: "art_01m5t41x77fg4pdnm2ryq73wgs"

name string required path

The artifact's file name, as in its `url`.

Example: "screenshot.webp"

Query Parameters

node string required query

ID of the node that signed the URL.

Example: "n1"

exp integer required query

When the URL expires, in Unix seconds.

Example: 1793040000

sig string required query

Base64url (no padding) Ed25519 signature of the canonical string above.

Example: "qOxWOOryXIikfgvLdKZ3rjxZyxuO_eFCf-VXOHy2Zf5AEuXtOr-JsyyXTvIPP8joM4Rbp519aKjyAkMMxVAvAQ"

Header Parameters

Range string optional header

One byte range, such as `bytes=0-1048575`.

Responses

200 The artifact.

image/*

string (binary)

206 One byte range of the artifact.

400 The request failed validation (`invalid_request`, `invalid_url`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

403 The signed URL is missing parameters, malformed, expired, altered, or not signed by this node (`signed_url_invalid`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

404 No such artifact in this project (`artifact_not_found`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

410 The artifact was deleted at the end of its retention period (`artifact_expired`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

500 Something failed inside B3OS (`internal`). Retry with backoff.

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

curl -X GET 'https://beta-api.b3os.org/v1/render/artifacts/art_01m5t41x77fg4pdnm2ryq73wgs/content/screenshot.webp?node=n1&exp=1793040000&sig=qOxWOOryXIikfgvLdKZ3rjxZyxuO_eFCf-VXOHy2Zf5AEuXtOr-JsyyXTvIPP8joM4Rbp519aKjyAkMMxVAvAQ' \  -H 'Authorization: Bearer YOUR_API_TOKEN'

const response = await fetch('https://beta-api.b3os.org/v1/render/artifacts/art_01m5t41x77fg4pdnm2ryq73wgs/content/screenshot.webp?node=n1&exp=1793040000&sig=qOxWOOryXIikfgvLdKZ3rjxZyxuO_eFCf-VXOHy2Zf5AEuXtOr-JsyyXTvIPP8joM4Rbp519aKjyAkMMxVAvAQ', {  method: 'GET',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN"  }});const data = await response.json();console.log(data);

import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.get('https://beta-api.b3os.org/v1/render/artifacts/art_01m5t41x77fg4pdnm2ryq73wgs/content/screenshot.webp?node=n1&exp=1793040000&sig=qOxWOOryXIikfgvLdKZ3rjxZyxuO_eFCf-VXOHy2Zf5AEuXtOr-JsyyXTvIPP8joM4Rbp519aKjyAkMMxVAvAQ', headers=headers)print(response.json())

200 Response

"<binary>"

206 Response

"<binary>"

400 Response

{  "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 Response

{  "type": "https://docs.beta.b3os.org/errors#signed_url_invalid",  "title": "Invalid or expired signed URL",  "status": 403,  "code": "signed_url_invalid",  "detail": "The URL expired at 2026-10-26T18:40:00Z; get a fresh one with GET /v1/render/artifacts/art_01m5t41x77fg4pdnm2ryq73wgs",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "reason": "expired"}

404 Response

{  "type": "https://docs.beta.b3os.org/errors#artifact_not_found",  "title": "Artifact not found",  "status": 404,  "code": "artifact_not_found",  "detail": "No artifact art_01m5t41x77fg4pdnm2ryq73wgs in this project",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

410 Response

{  "type": "https://docs.beta.b3os.org/errors#artifact_expired",  "title": "Artifact expired",  "status": 410,  "code": "artifact_expired",  "detail": "art_01m5t41x77fg4pdnm2ryq73wgs expired on 2026-11-01T18:40:00Z",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

429 Response

{  "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 Response

{  "type": "https://docs.beta.b3os.org/errors#internal",  "title": "Internal error",  "status": 500,  "code": "internal",  "detail": "internal error",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

503 Response

{  "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}

GET /v1/render/artifacts/{artifact_id}/content/{name}

Base URL

Bearer Token

Path Parameters

artifact_id string required

name string required

Query Parameters

node string required

exp integer required

sig string required

Headers

Range string

Response

Was this page helpful?

Previous Get an artifact

Next List style presets