Create a profile

Stores cookies and storage as a named profile, encrypted in the node's vault. `state` is Playwright's `storageState` JSON (`context.storageState({indexedDB: true})`) uploaded as is. Every cookie domain and origin must belong to `domains` (derived from the state when omitted). The API returns counts and domains, never cookie values; `GET /v1/vision/profiles/{profile_id}/state` exports the state.

POST /v1/vision/profiles
Stores cookies and storage as a named profile, encrypted in the node's vault. `state` is Playwright's `storageState` JSON (`context.storageState({indexedDB: true})`) uploaded as is. Every cookie domain and origin must belong to `domains` (derived from the state when omitted). The API returns counts and domains, never cookie values; `GET /v1/vision/profiles/{profile_id}/state` exports the state.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)

Header Parameters

Idempotency-Key string optional header
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`.

Request Body required

application/json
name string REQUIRED
Unique per project.
state object REQUIRED
Playwright storageState JSON (context.storageState({indexedDB: true})). Upload it as is; exports return the same shape. Sensitive: it is encrypted at rest, decrypted only inside the session or recorder that loads it, never logged and never sent to a model.
cookies object[] REQUIRED
Array of:
name string REQUIRED
value string REQUIRED
domain string REQUIRED
Host or .domain the cookie belongs to.
path string REQUIRED
expires number REQUIRED
Unix time in seconds; -1 for a session cookie.
httpOnly boolean REQUIRED
secure boolean REQUIRED
sameSite unknown REQUIRED
Enum: Strict, Lax, None
partitionKey string
CHIPS partition (top-level site, e.g. https://example.com) for partitioned cookies.
_crHasCrossSiteAncestor boolean
Chromium partition detail Playwright emits for partitioned cookies; preserved as is.
origins object[] REQUIRED
Array of:
origin string REQUIRED
Serialized origin: scheme://host[:port], no path.
localStorage object[] REQUIRED
Array of:
name string REQUIRED
value string REQUIRED
indexedDB object[]
Array of:
name string REQUIRED
version integer REQUIRED
stores object[] REQUIRED
Array of: ...
opfs object[]
Array of:
path string REQUIRED
type unknown REQUIRED
Enum: file, directory
base64 string (byte)
domains string[]
Registrable domains the profile may hold state for. Derived from `state` when omitted.
Array of: string
expires_at string (date-time)
Delete the profile automatically at this time.
metadata 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.

Responses

201 The profile.
application/json
id string REQUIRED
object unknown REQUIRED
Enum: profile
created_at string (date-time) REQUIRED
RFC 3339, UTC, e.g. 2026-10-25T17:00:00Z.
updated_at string (date-time) REQUIRED
Last time the storage state was replaced or saved back.
last_used_at string (date-time) | null REQUIRED
Last time a session or render job loaded the profile; null if never.
expires_at string (date-time) | null
When the profile is deleted automatically; null for no expiry.
metadata object REQUIRED
Customer string map, at most 16 keys (ARCHITECTURE 4.1).
name string REQUIRED
org string
Owning org. Returned to the owner only; tenancy is checked on every access.
project string
domains string[] REQUIRED
Registrable domains the profile may hold state for. Every cookie domain and every origin host in the storage state must equal one of these or be a subdomain of one; an import that breaks this fails with profile_domain_mismatch. When omitted at creation, it is derived from the uploaded state.
Array of: string
revision integer REQUIRED
Increments on every save. A session that loaded revision n and saves back while the profile is at revision m > n fails with profile_conflict unless it asked to overwrite.
status unknown REQUIRED
active: loadable. locked: a session with persist is writing it back; loads still see the last revision. expired: past expires_at, about to be deleted.
Enum: active, locked, expired
source unknown
How the current revision was produced: uploaded storage state, saved back from a vision session, or imported from a render or CLI login.
Enum: upload, session, login
stats object REQUIRED
Counts over the current revision, so clients can show what a profile holds without decrypting it.
cookies integer REQUIRED
origins integer REQUIRED
indexeddb_databases integer
bytes integer REQUIRED
Size of the serialized storage state before encryption.
earliest_cookie_expiry string (date-time) | null
Earliest expires among persistent cookies; null when there are none. Lets clients warn before a login lapses.
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
409 Another profile already has this name (`profile_name_taken`).
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
422 A cookie or origin falls outside the profile's domains (`profile_domain_mismatch`).
429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500 Something failed inside B3OS (`internal`). Retry with backoff.
503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). 
curl -X POST 'https://beta-api.b3os.org/v1/vision/profiles' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "name": "acme-staging",  "state": {    "cookies": [      {        "name": "session",        "value": "<cookie value>",        "domain": "app.example.com",        "path": "/",        "expires": 1793000000,        "httpOnly": true,        "secure": true,        "sameSite": "Lax"      }    ],    "origins": []  }}'
const response = await fetch('https://beta-api.b3os.org/v1/vision/profiles', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "name": "acme-staging",    "state": {      "cookies": [        {          "name": "session",          "value": "<cookie value>",          "domain": "app.example.com",          "path": "/",          "expires": 1793000000,          "httpOnly": true,          "secure": true,          "sameSite": "Lax"        }      ],      "origins": []    }  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/v1/vision/profiles', headers=headers, json={  "name": "acme-staging",  "state": {    "cookies": [      {        "name": "session",        "value": "<cookie value>",        "domain": "app.example.com",        "path": "/",        "expires": 1793000000,        "httpOnly": true,        "secure": true,        "sameSite": "Lax"      }    ],    "origins": []  }})print(response.json())
201 Response 
{  "id": "prof_01m5t3v4507bhcb5jqrgzfvfsk",  "object": "profile",  "created_at": "2026-10-25T18:00:00.000Z",  "updated_at": "2026-10-25T18:00:00.000Z",  "last_used_at": null,  "expires_at": null,  "metadata": {},  "name": "acme-staging",  "domains": [    "example.com"  ],  "revision": 1,  "status": "active",  "source": "upload",  "stats": {    "cookies": 1,    "origins": 0,    "bytes": 214  }}
Previous List profiles
Next Get a profile
Ask a question... ⌘I