> ## 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. # Scrape a list of URLs Starts a job that scrapes up to 1,000 URLs with the same options. Each page bills one `vision.page`. Results are listed with `GET /v1/vision/batches/{batch_id}/pages`; `?wait=`, the events stream and `webhook` report progress. ` POST /v1/vision/batches ` Scrape a list of URLs Starts a job that scrapes up to 1,000 URLs with the same options. Each page bills one `vision.page`. Results are listed with `GET /v1/vision/batches/{batch_id}/pages`; `?wait=`, the events stream and `webhook` report progress. ## 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 ### ` wait ` (query, optional) Seconds to wait for the job to finish before responding, from 0 to 60. If it finishes in time the response is `200` with the finished job; otherwise `202` with the job as it is, a `Location` to poll and `Retry-After`. `0` (the default) returns immediately. - ` value `: type ` integer ` - default: ` 0 ` - minimum: ` 0 ` - maximum: ` 60 ` ### ` Idempotency-Key ` (header, optional) A unique value (for example a UUID) that makes this request safe to retry. Scoped to your project for 24 hours: a retry with the same key, method, path and body returns the stored response with `Idempotent-Replayed: true`, and only to the same API key. Reusing the key for a different request returns `409 idempotency_key_conflict`. - ` value `: type ` string ` - minLength: ` 1 ` - maxLength: ` 255 ` ## Request body (required) Content type: ` application/json ` - ` value `: type ` object ` - Required fields: ` urls ` - ` urls `: type ` array ` - ` array item `: type ` string ` - maxLength: ` 8192 ` - ` scrape `: type ` object ` — Scrape options applied to every page. - ` formats `: type ` array ` - default: ` ["markdown"] ` - ` array item `: type ` string ` — `markdown` main content (or the whole page with `only_main_content: false`); `html` cleaned HTML; `raw_html` the HTML as received; `text` plain text; `links` absolute links; `metadata` title, description and Open Graph fields (always included, listed for compatibility); `screenshot` an image of the page (needs a browser); `json` structured data from `json.schema` (needs the node's model). - enum: ` ["markdown","html","raw_html","text","links","metadata","screenshot","json"] ` - ` only_main_content `: type ` boolean ` — Drop headers, navigation, footers and sidebars. - default: ` true ` - ` include_tags `: type ` array ` — CSS selectors to keep; everything else is dropped. - ` array item `: type ` string ` - maxLength: ` 200 ` - ` exclude_tags `: type ` array ` — CSS selectors to drop. - ` array item `: type ` string ` - maxLength: ` 200 ` - ` engine `: type ` string ` — Which tier may serve the page. `auto` (default): cache, then HTTP fetch, then a browser when the page needs JavaScript. `fetch`: never start a browser. `browser`: always render in Chrome (needed for `actions`, `screenshot` and profiles; implied by them). - enum: ` ["auto","fetch","browser"] ` - ` wait_for_ms `: type ` integer ` — Extra wait after the page is ready, before capture. - default: ` 0 ` - minimum: ` 0 ` - maximum: ` 30000 ` - ` timeout_ms `: type ` integer ` - default: ` 30000 ` - minimum: ` 1000 ` - maximum: ` 60000 ` - ` max_age_ms `: type ` integer ` — Accept a cached copy up to this old (default 2 days). `0` always fetches. - default: ` 172800000 ` - minimum: ` 0 ` - ` store_in_cache `: type ` boolean ` — Store the result in the cache. Requests with headers, a profile or actions are never shared across organizations. - default: ` true ` - ` headers `: type ` object ` — Extra request headers. A request with custom headers bypasses the shared cache. In a browser, a `Cookie` header becomes cookies for the page's host (path `/`), so it reaches the origin as on an HTTP fetch and is not sent to the other hosts the page loads from. - ` profile `: type ` string ` — A profile ID or name to load cookies and storage from. Implies `engine: browser`. The page renders in a browser of its own (never one shared with other organizations), which counts toward `vision.sessions.concurrent` while it runs. - ` actions `: type ` array ` — Browser actions to run before capture. Implies `engine: browser`. - ` array item `: type ` unknown ` — One browser action; `kind` selects it. The kinds and their fields match render timeline actions (`navigate`, `click`, `hover`, `type`, `key`, `scroll`, `select`, `wait`) plus `evaluate`, `screenshot` and `markdown`, which only `act` and scrape `actions` offer. - ` oneOf alternative 1 `: type ` object ` - Required fields: ` kind `, ` url ` - ` kind `: type ` string ` - enum: ` ["navigate"] ` - ` url `: type ` string `; format ` uri ` - maxLength: ` 4096 ` - ` wait_until `: type ` string ` - enum: ` ["load","domcontentloaded","networkidle"] ` - default: ` "load" ` - ` timeout_ms `: type ` integer ` - default: ` 10000 ` - minimum: ` 100 ` - maximum: ` 60000 ` - ` oneOf alternative 2 `: type ` object ` - Required fields: ` kind `, ` target ` - ` kind `: type ` string ` - enum: ` ["click"] ` - ` target `: type ` object ` — How an action finds its element (the same rules as render timelines, `timeline.schema.json#/$defs/target`): candidates match `selector` (CSS), `text` (visible text, case-insensitive substring unless `exact`) or `role` plus accessible `name`, limited to `within`; the best-scored candidate wins, or the `nth` match when set. An element that stays outside the viewport after scrolling it into view fails with `target_not_found`. - example: ` {"role":"button","name":"Continue"} ` - ` selector `: type ` string ` - minLength: ` 1 ` - maxLength: ` 1024 ` - ` text `: type ` string ` - minLength: ` 1 ` - maxLength: ` 500 ` - ` exact `: type ` boolean ` - default: ` false ` - ` role `: type ` string ` - pattern: ` "^[a-z]{2,32}$" ` - ` name `: type ` string ` - maxLength: ` 500 ` - ` within `: type ` string ` — CSS selector of the scope. - maxLength: ` 1024 ` - ` nth `: type ` integer ` - minimum: ` 0 ` - maximum: ` 1000 ` - ` anyOf alternative 1 `: type ` unknown ` - Required fields: ` selector ` - ` anyOf alternative 2 `: type ` unknown ` - Required fields: ` text ` - ` anyOf alternative 3 `: type ` unknown ` - Required fields: ` role ` - ` button `: type ` string ` - enum: ` ["left","right","middle"] ` - default: ` "left" ` - ` count `: type ` integer ` - default: ` 1 ` - minimum: ` 1 ` - maximum: ` 3 ` - ` modifiers `: type ` array ` — Modifier keys held during the action. - ` array item `: type ` string ` - enum: ` ["Alt","Control","Meta","Shift"] ` - ` timeout_ms `: type ` integer ` — How long to wait for the target to appear. - default: ` 10000 ` - minimum: ` 100 ` - maximum: ` 60000 ` - ` oneOf alternative 3 `: type ` object ` - Required fields: ` kind `, ` target ` - ` kind `: type ` string ` - enum: ` ["hover"] ` - ` target `: type ` object ` — How an action finds its element (the same rules as render timelines, `timeline.schema.json#/$defs/target`): candidates match `selector` (CSS), `text` (visible text, case-insensitive substring unless `exact`) or `role` plus accessible `name`, limited to `within`; the best-scored candidate wins, or the `nth` match when set. An element that stays outside the viewport after scrolling it into view fails with `target_not_found`. - example: ` {"role":"button","name":"Continue"} ` - ` selector `: type ` string ` - minLength: ` 1 ` - maxLength: ` 1024 ` - ` text `: type ` string ` - minLength: ` 1 ` - maxLength: ` 500 ` - ` exact `: type ` boolean ` - default: ` false ` - ` role `: type ` string ` - pattern: ` "^[a-z]{2,32}$" ` - ` name `: type ` string ` - maxLength: ` 500 ` - ` within `: type ` string ` — CSS selector of the scope. - maxLength: ` 1024 ` - ` nth `: type ` integer ` - minimum: ` 0 ` - maximum: ` 1000 ` - ` anyOf alternative 1 `: type ` unknown ` - Required fields: ` selector ` - ` anyOf alternative 2 `: type ` unknown ` - Required fields: ` text ` - ` anyOf alternative 3 `: type ` unknown ` - Required fields: ` role ` - ` timeout_ms `: type ` integer ` - default: ` 10000 ` - minimum: ` 100 ` - maximum: ` 60000 ` - ` oneOf alternative 4 `: type ` object ` - Required fields: ` kind `, ` text ` - ` kind `: type ` string ` - enum: ` ["type"] ` - ` target `: type ` object ` — How an action finds its element (the same rules as render timelines, `timeline.schema.json#/$defs/target`): candidates match `selector` (CSS), `text` (visible text, case-insensitive substring unless `exact`) or `role` plus accessible `name`, limited to `within`; the best-scored candidate wins, or the `nth` match when set. An element that stays outside the viewport after scrolling it into view fails with `target_not_found`. - example: ` {"role":"button","name":"Continue"} ` - ` selector `: type ` string ` - minLength: ` 1 ` - maxLength: ` 1024 ` - ` text `: type ` string ` - minLength: ` 1 ` - maxLength: ` 500 ` - ` exact `: type ` boolean ` - default: ` false ` - ` role `: type ` string ` - pattern: ` "^[a-z]{2,32}$" ` - ` name `: type ` string ` - maxLength: ` 500 ` - ` within `: type ` string ` — CSS selector of the scope. - maxLength: ` 1024 ` - ` nth `: type ` integer ` - minimum: ` 0 ` - maximum: ` 1000 ` - ` anyOf alternative 1 `: type ` unknown ` - Required fields: ` selector ` - ` anyOf alternative 2 `: type ` unknown ` - Required fields: ` text ` - ` anyOf alternative 3 `: type ` unknown ` - Required fields: ` role ` - ` text `: type ` string ` - maxLength: ` 10000 ` - ` clear `: type ` boolean ` — Clear the field before typing. - default: ` false ` - ` interval_ms `: type ` integer ` — Delay between characters. - default: ` 0 ` - minimum: ` 0 ` - maximum: ` 1000 ` - ` timeout_ms `: type ` integer ` - default: ` 10000 ` - minimum: ` 100 ` - maximum: ` 60000 ` - ` oneOf alternative 5 `: type ` object ` - Required fields: ` kind `, ` key ` - ` kind `: type ` string ` - enum: ` ["key"] ` - ` key `: type ` string ` — `KeyboardEvent.key`, such as `Enter`, `Tab` or `a`. - minLength: ` 1 ` - maxLength: ` 32 ` - ` modifiers `: type ` array ` — Modifier keys held during the action. - ` array item `: type ` string ` - enum: ` ["Alt","Control","Meta","Shift"] ` - ` oneOf alternative 6 `: type ` object ` — Scroll to an offset (`to`), by a delta (`by`), or until `target` is in view. - Required fields: ` kind ` - ` kind `: type ` string ` - enum: ` ["scroll"] ` - ` target `: type ` object ` — How an action finds its element (the same rules as render timelines, `timeline.schema.json#/$defs/target`): candidates match `selector` (CSS), `text` (visible text, case-insensitive substring unless `exact`) or `role` plus accessible `name`, limited to `within`; the best-scored candidate wins, or the `nth` match when set. An element that stays outside the viewport after scrolling it into view fails with `target_not_found`. - example: ` {"role":"button","name":"Continue"} ` - ` selector `: type ` string ` - minLength: ` 1 ` - maxLength: ` 1024 ` - ` text `: type ` string ` - minLength: ` 1 ` - maxLength: ` 500 ` - ` exact `: type ` boolean ` - default: ` false ` - ` role `: type ` string ` - pattern: ` "^[a-z]{2,32}$" ` - ` name `: type ` string ` - maxLength: ` 500 ` - ` within `: type ` string ` — CSS selector of the scope. - maxLength: ` 1024 ` - ` nth `: type ` integer ` - minimum: ` 0 ` - maximum: ` 1000 ` - ` anyOf alternative 1 `: type ` unknown ` - Required fields: ` selector ` - ` anyOf alternative 2 `: type ` unknown ` - Required fields: ` text ` - ` anyOf alternative 3 `: type ` unknown ` - Required fields: ` role ` - ` to `: type ` object ` — A position in CSS pixels. - Required fields: ` x `, ` y ` - ` x `: type ` number ` - ` y `: type ` number ` - ` by `: type ` object ` — A position in CSS pixels. - Required fields: ` x `, ` y ` - ` x `: type ` number ` - ` y `: type ` number ` - ` oneOf alternative 7 `: type ` object ` - Required fields: ` kind `, ` target `, ` value ` - ` kind `: type ` string ` - enum: ` ["select"] ` - ` target `: type ` object ` — How an action finds its element (the same rules as render timelines, `timeline.schema.json#/$defs/target`): candidates match `selector` (CSS), `text` (visible text, case-insensitive substring unless `exact`) or `role` plus accessible `name`, limited to `within`; the best-scored candidate wins, or the `nth` match when set. An element that stays outside the viewport after scrolling it into view fails with `target_not_found`. - example: ` {"role":"button","name":"Continue"} ` - ` selector `: type ` string ` - minLength: ` 1 ` - maxLength: ` 1024 ` - ` text `: type ` string ` - minLength: ` 1 ` - maxLength: ` 500 ` - ` exact `: type ` boolean ` - default: ` false ` - ` role `: type ` string ` - pattern: ` "^[a-z]{2,32}$" ` - ` name `: type ` string ` - maxLength: ` 500 ` - ` within `: type ` string ` — CSS selector of the scope. - maxLength: ` 1024 ` - ` nth `: type ` integer ` - minimum: ` 0 ` - maximum: ` 1000 ` - ` anyOf alternative 1 `: type ` unknown ` - Required fields: ` selector ` - ` anyOf alternative 2 `: type ` unknown ` - Required fields: ` text ` - ` anyOf alternative 3 `: type ` unknown ` - Required fields: ` role ` - ` value `: type ` string ` — The option value to select. - maxLength: ` 1000 ` - ` oneOf alternative 8 `: type ` object ` — Wait a fixed time (`ms`) or until a condition holds (`for`). - Required fields: ` kind ` - ` kind `: type ` string ` - enum: ` ["wait"] ` - ` ms `: type ` integer ` - minimum: ` 1 ` - maximum: ` 30000 ` - ` for `: type ` object ` — Exactly one condition to wait for (the same as a timeline `wait` action's `for`). - ` selector `: type ` string ` — An element matching this CSS selector is visible. - maxLength: ` 1024 ` - ` text `: type ` string ` — This text is visible. - maxLength: ` 500 ` - ` url `: type ` string ` — The page URL contains this substring. - maxLength: ` 4096 ` - ` network_idle `: type ` boolean ` — The network has been quiet. - enum: ` [true] ` - ` timeout_ms `: type ` integer ` - default: ` 10000 ` - minimum: ` 100 ` - maximum: ` 60000 ` - ` oneOf alternative 9 `: type ` object ` - Required fields: ` kind `, ` expression ` - ` kind `: type ` string ` - enum: ` ["evaluate"] ` - ` expression `: type ` string ` — JavaScript evaluated in the page; a returned promise is awaited and the JSON-serializable result is returned. - maxLength: ` 100000 ` - ` oneOf alternative 10 `: type ` object ` - Required fields: ` kind ` - ` kind `: type ` string ` - enum: ` ["screenshot"] ` - ` target `: type ` object ` — How an action finds its element (the same rules as render timelines, `timeline.schema.json#/$defs/target`): candidates match `selector` (CSS), `text` (visible text, case-insensitive substring unless `exact`) or `role` plus accessible `name`, limited to `within`; the best-scored candidate wins, or the `nth` match when set. An element that stays outside the viewport after scrolling it into view fails with `target_not_found`. - example: ` {"role":"button","name":"Continue"} ` - ` selector `: type ` string ` - minLength: ` 1 ` - maxLength: ` 1024 ` - ` text `: type ` string ` - minLength: ` 1 ` - maxLength: ` 500 ` - ` exact `: type ` boolean ` - default: ` false ` - ` role `: type ` string ` - pattern: ` "^[a-z]{2,32}$" ` - ` name `: type ` string ` - maxLength: ` 500 ` - ` within `: type ` string ` — CSS selector of the scope. - maxLength: ` 1024 ` - ` nth `: type ` integer ` - minimum: ` 0 ` - maximum: ` 1000 ` - ` anyOf alternative 1 `: type ` unknown ` - Required fields: ` selector ` - ` anyOf alternative 2 `: type ` unknown ` - Required fields: ` text ` - ` anyOf alternative 3 `: type ` unknown ` - Required fields: ` role ` - ` full_page `: type ` boolean ` - default: ` false ` - ` format `: type ` string ` - enum: ` ["jpeg","png","webp"] ` - default: ` "jpeg" ` - ` quality `: type ` integer ` - default: ` 80 ` - minimum: ` 1 ` - maximum: ` 100 ` - ` oneOf alternative 11 `: type ` object ` - Required fields: ` kind ` - ` kind `: type ` string ` - enum: ` ["markdown"] ` - ` only_main_content `: type ` boolean ` - default: ` true ` - ` locale `: type ` string ` — BCP 47 locale for `Accept-Language` and the browser. - default: ` "en-US" ` - ` timezone `: type ` string ` — IANA time zone for the browser, such as `America/Los_Angeles`. - ` mobile `: type ` boolean ` — Emulate a phone (viewport, user agent, touch). - default: ` false ` - ` viewport `: type ` object ` — Browser viewport in CSS pixels. - Required fields: ` width `, ` height ` - ` width `: type ` integer ` - minimum: ` 320 ` - maximum: ` 3840 ` - ` height `: type ` integer ` - minimum: ` 240 ` - maximum: ` 2160 ` - ` block_ads `: type ` boolean ` — Block ads, trackers and cookie banners. - default: ` true ` - ` block_resources `: type ` array ` — Resource types the browser does not download. Defaults to images, media and fonts unless a screenshot is requested. - ` array item `: type ` string ` - enum: ` ["image","media","font","stylesheet"] ` - ` screenshot `: type ` object ` — Options for the `screenshot` format. - ` full_page `: type ` boolean ` - default: ` false ` - ` format `: type ` string ` - enum: ` ["jpeg","png","webp"] ` - default: ` "jpeg" ` - ` quality `: type ` integer ` — JPEG and WebP quality. - default: ` 80 ` - minimum: ` 1 ` - maximum: ` 100 ` - ` json `: type ` object ` — Options for the `json` format. The node's model fills `schema` from the page. - ` schema `: type ` object ` — A JSON Schema the result must match. - ` prompt `: type ` string ` — Guidance for the model. - maxLength: ` 10000 ` - ` ignore_invalid_urls `: type ` boolean ` — Skip URLs that do not parse (listed in `result.invalid_urls`) instead of rejecting the request. - default: ` false ` - ` max_concurrency `: type ` integer ` — Pages scraped at once, capped by your concurrency limit. - minimum: ` 1 ` - ` webhook `: type ` object ` — Where to deliver this job's events. Deliveries are `POST`s of a `WebhookEvent` signed with `B3OS-Signature: t=,v1=.">` using the endpoint's secret (`POST /v1/webhooks/secret`). Failed deliveries are retried with backoff for 24 hours. Delivery goes through the egress guard, so private and loopback addresses are refused. - Required fields: ` url ` - ` url `: type ` string `; format ` uri ` — An `https://` URL. - example: ` "https://example.com/hooks/b3os" ` - maxLength: ` 2048 ` - ` events `: type ` array ` — Event types to deliver. Defaults to the terminal events (`job.succeeded`, `job.failed`, `job.canceled`); `["*"]` delivers every event. - example: ` ["job.succeeded","job.failed"] ` - ` array item `: type ` string ` - maxLength: ` 64 ` - ` 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 { "urls": [ "https://example.com/blog/a", "https://example.com/blog/b" ], "scrape": { "formats": [ "markdown" ] }, "webhook": { "url": "https://example.com/hooks/b3os" } } ``` ## Responses ### ` 200 ` — The batch finished within `wait` seconds, or the event stream when `Accept` is `text/event-stream`. Content type: ` application/json ` - ` value `: type ` object ` — A batch scrape job (`batch_…`). - Required fields: ` id `, ` object `, ` status `, ` created_at `, ` updated_at ` - ` id `: type ` string ` - pattern: ` "^batch_[0-9a-hjkmnp-tv-z]{26}$" ` - ` object `: type ` string ` - enum: ` ["batch_scrape"] ` - ` status `: type ` string ` — `queued` → `running` → one of the terminal statuses `succeeded`, `failed` or `canceled`. A job never leaves a terminal status. - enum: ` ["queued","running","succeeded","failed","canceled"] ` - ` created_at `: type ` string `; format ` date-time ` - ` updated_at `: type ` string `; format ` date-time ` - ` started_at `: type ` string `; nullable; format ` date-time ` - ` finished_at `: type ` string `; nullable; format ` date-time ` - ` progress `: type ` object ` — How far a job has got, in the job's own unit (pages, items, steps). - Required fields: ` completed `, ` unit ` - ` completed `: type ` integer ` — Units finished, successfully or not. - minimum: ` 0 ` - ` failed `: type ` integer ` — Units that failed (included in `completed`). - minimum: ` 0 ` - ` total `: type ` integer `; nullable — Units expected, when known. - minimum: ` 0 ` - ` unit `: type ` string ` — What is counted, such as `pages`, `items` or `steps`. - ` result `: type ` object ` - Required fields: ` pages_succeeded `, ` pages_failed `, ` invalid_urls ` - ` pages_succeeded `: type ` integer ` - ` pages_failed `: type ` integer ` - ` invalid_urls `: type ` array ` - ` array item `: type ` string ` - ` error `: 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 ` - ` timing `: type ` object ` — Server-side phase durations in milliseconds with microsecond resolution: the same phases as the `Server-Timing` header, keyed `_ms`. `total_ms` is always present. Phase names are product-specific and documented per operation. Example values in this reference are illustrative, not measurements. - example: ` {"claim_ms":1.1,"navigate_ms":31,"extract_ms":4.2,"total_ms":36.6} ` - Required fields: ` total_ms ` - ` total_ms `: type ` number ` - minimum: ` 0 ` - ` expires_at `: type ` string `; nullable; format ` date-time ` — When the job's results are deleted (retention); `null` while the job is not terminal. - ` 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"} ` - ` webhook `: type ` object ` — Where to deliver this job's events. Deliveries are `POST`s of a `WebhookEvent` signed with `B3OS-Signature: t=,v1=.">` using the endpoint's secret (`POST /v1/webhooks/secret`). Failed deliveries are retried with backoff for 24 hours. Delivery goes through the egress guard, so private and loopback addresses are refused. - Required fields: ` url ` - ` url `: type ` string `; format ` uri ` — An `https://` URL. - example: ` "https://example.com/hooks/b3os" ` - maxLength: ` 2048 ` - ` events `: type ` array ` — Event types to deliver. Defaults to the terminal events (`job.succeeded`, `job.failed`, `job.canceled`); `["*"]` delivers every event. - example: ` ["job.succeeded","job.failed"] ` - ` array item `: type ` string ` - maxLength: ` 64 ` 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 ` Idempotent-Replayed ` — Present with the value `true` when the response is a stored replay of an earlier request with the same `Idempotency-Key`. - ` value `: type ` string ` - enum: ` ["true"] ` Example: ```json { "id": "batch_01m5t3v176vrhf8a1mn570c5gd", "object": "batch_scrape", "status": "succeeded", "created_at": "2026-10-25T18:04:11.204Z", "updated_at": "2026-10-25T18:04:12.950Z", "started_at": "2026-10-25T18:04:11.210Z", "finished_at": "2026-10-25T18:04:12.950Z", "progress": { "completed": 2, "failed": 0, "total": 2, "unit": "pages" }, "result": { "pages_succeeded": 2, "pages_failed": 0, "invalid_urls": [] }, "timing": { "queue_ms": 0.3, "total_ms": 1746.2 }, "expires_at": "2026-11-01T18:04:12.950Z", "metadata": {} } ``` ### ` 202 ` — The batch was accepted and is still running. Poll `Location` or stream its events. Content type: ` application/json ` - ` value `: type ` object ` — A batch scrape job (`batch_…`). - Required fields: ` id `, ` object `, ` status `, ` created_at `, ` updated_at ` - ` id `: type ` string ` - pattern: ` "^batch_[0-9a-hjkmnp-tv-z]{26}$" ` - ` object `: type ` string ` - enum: ` ["batch_scrape"] ` - ` status `: type ` string ` — `queued` → `running` → one of the terminal statuses `succeeded`, `failed` or `canceled`. A job never leaves a terminal status. - enum: ` ["queued","running","succeeded","failed","canceled"] ` - ` created_at `: type ` string `; format ` date-time ` - ` updated_at `: type ` string `; format ` date-time ` - ` started_at `: type ` string `; nullable; format ` date-time ` - ` finished_at `: type ` string `; nullable; format ` date-time ` - ` progress `: type ` object ` — How far a job has got, in the job's own unit (pages, items, steps). - Required fields: ` completed `, ` unit ` - ` completed `: type ` integer ` — Units finished, successfully or not. - minimum: ` 0 ` - ` failed `: type ` integer ` — Units that failed (included in `completed`). - minimum: ` 0 ` - ` total `: type ` integer `; nullable — Units expected, when known. - minimum: ` 0 ` - ` unit `: type ` string ` — What is counted, such as `pages`, `items` or `steps`. - ` result `: type ` object ` - Required fields: ` pages_succeeded `, ` pages_failed `, ` invalid_urls ` - ` pages_succeeded `: type ` integer ` - ` pages_failed `: type ` integer ` - ` invalid_urls `: type ` array ` - ` array item `: type ` string ` - ` error `: 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 ` - ` timing `: type ` object ` — Server-side phase durations in milliseconds with microsecond resolution: the same phases as the `Server-Timing` header, keyed `_ms`. `total_ms` is always present. Phase names are product-specific and documented per operation. Example values in this reference are illustrative, not measurements. - example: ` {"claim_ms":1.1,"navigate_ms":31,"extract_ms":4.2,"total_ms":36.6} ` - Required fields: ` total_ms ` - ` total_ms `: type ` number ` - minimum: ` 0 ` - ` expires_at `: type ` string `; nullable; format ` date-time ` — When the job's results are deleted (retention); `null` while the job is not terminal. - ` 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"} ` - ` webhook `: type ` object ` — Where to deliver this job's events. Deliveries are `POST`s of a `WebhookEvent` signed with `B3OS-Signature: t=,v1=.">` using the endpoint's secret (`POST /v1/webhooks/secret`). Failed deliveries are retried with backoff for 24 hours. Delivery goes through the egress guard, so private and loopback addresses are refused. - Required fields: ` url ` - ` url `: type ` string `; format ` uri ` — An `https://` URL. - example: ` "https://example.com/hooks/b3os" ` - maxLength: ` 2048 ` - ` events `: type ` array ` — Event types to deliver. Defaults to the terminal events (`job.succeeded`, `job.failed`, `job.canceled`); `["*"]` delivers every event. - example: ` ["job.succeeded","job.failed"] ` - ` array item `: type ` string ` - maxLength: ` 64 ` 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 ` Location ` — URL of the created job or object; poll it with `GET`. - ` value `: type ` string `; format ` uri-reference ` Response header ` Retry-After ` — Seconds to wait before retrying or polling again. - ` value `: type ` integer ` - minimum: ` 0 ` Response header ` Idempotent-Replayed ` — Present with the value `true` when the response is a stored replay of an earlier request with the same `Idempotency-Key`. - ` value `: type ` string ` - enum: ` ["true"] ` Example: ```json { "id": "batch_01m5t3v176vrhf8a1mn570c5gd", "object": "batch_scrape", "status": "running", "created_at": "2026-10-25T18:04:11.204Z", "updated_at": "2026-10-25T18:04:11.210Z", "started_at": "2026-10-25T18:04:11.210Z", "finished_at": null, "progress": { "completed": 0, "failed": 0, "total": 2, "unit": "pages" }, "expires_at": null, "metadata": {}, "webhook": { "url": "https://example.com/hooks/b3os" } } ``` ### ` 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" } ``` ### ` 402 ` — The organization has no credits left, or the key reached its spend cap. 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#credits_exhausted", "title": "Credits exhausted", "status": 402, "code": "credits_exhausted", "detail": "Organization org_01m5t5hthd29mm5wpza5ndd6mm has no credits left", "instance": "req_01m5t4yg394wegr3j4y01qb363" } ``` ### ` 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" } ``` ### ` 409 ` — The object's state does not allow this operation, or the idempotency key conflicts. 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#idempotency_key_conflict", "title": "Idempotency key conflict", "status": 409, "code": "idempotency_key_conflict", "detail": "This Idempotency-Key was used with a different request body", "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" } ``` ### ` 422 ` — A parameter exceeds a plan limit (`limit_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 ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#limit_exceeded", "title": "Limit exceeded", "status": 422, "code": "limit_exceeded", "detail": "limit is 2000; crawls allow at most 500 pages", "instance": "req_01m5t4yg394wegr3j4y01qb363", "limit": { "id": "vision.crawl.pages_max", "limit": 500, "unit": "pages" } } ``` ### ` 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 POST 'https://beta-api.b3os.org/v1/vision/batches' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "urls": [ "https://example.com/blog/a", "https://example.com/blog/b" ], "scrape": { "formats": [ "markdown" ] }, "webhook": { "url": "https://example.com/hooks/b3os" } }' ``` ### JavaScript ```javascript const response = await fetch('https://beta-api.b3os.org/v1/vision/batches', { method: 'POST', headers: { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "urls": [ "https://example.com/blog/a", "https://example.com/blog/b" ], "scrape": { "formats": [ "markdown" ] }, "webhook": { "url": "https://example.com/hooks/b3os" } }) }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests headers = { 'Authorization': 'Bearer YOUR_API_TOKEN' } response = requests.post('https://beta-api.b3os.org/v1/vision/batches', headers=headers, json={ "urls": [ "https://example.com/blog/a", "https://example.com/blog/b" ], "scrape": { "formats": [ "markdown" ] }, "webhook": { "url": "https://example.com/hooks/b3os" } }) print(response.json()) ```