List your project's addresses

GET /v1/app-hosts
Every address of every application in your project, by application, then in claim order, each as List an application's addresses gives it (its state, the sandbox it serves, the cookies it dropped in the last 7 days). One bounded read: at most 100 addresses (an organization holds 20 unless B3 raised apps.hosts.max). The console's Applications list and home read it. Off by default: the platform.app_hosts flag must be on for your organization, or your organization must hold a serving address; without either this answers 404 feature_not_enabled (and b3os apply keeps each port's preview URL). 503 flags_unavailable when that cannot be read.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token)

Responses

200 Your project's addresses (an empty list when it has none).
application/json
object string REQUIRED
Values list
data object[] REQUIRED
Array of:
object string REQUIRED
Values app_host
label string REQUIRED
An address's label, the part before .b3os.io.
url string (uri) REQUIRED
https://<label>.b3os.io.
app string REQUIRED
An application's name, the name in its b3os.yaml.
environment string REQUIRED
The environment (production; environments are projects in this beta).
project_id string REQUIRED
service string REQUIRED
The service of the application whose port this is.
port integer REQUIRED
access string REQUIRED
link: people who hold a link from b3os app link. public: anyone on the internet.
Values link public
cookies object REQUIRED
mode string REQUIRED
isolated: the app's server gets only the cookies its own address set, plus the names in script. shared: the browser's cookies pass, except Cloudflare's and B3OS's own names and values that are not plain (a space, comma, quote or backslash).
Values isolated shared
script string[] REQUIRED
Cookies a page script writes and the app's server reads, by name.
state string REQUIRED
claimed: the label is the port's and no deploy has switched it yet. serving: it serves sandbox_id. stopped: it serves nothing (b3os app down, or the organization or project stopped). blocked: B3 took it down; it can be neither claimed nor routed.
Values claimed serving stopped blocked
sandbox_id string | null REQUIRED
The sandbox the address serves (serving only).
deploy_id string | null REQUIRED
The deploy that last switched the address.
base_label string | null REQUIRED
The application's own label this one is derived from (<base>--<service>), or null.
primary boolean
The address of the application's primary port, which holds its own label (the others derive from it). Set when that port is first claimed; a later primary in b3os.yaml does not move it. Every answer of the edge has it.
blocked_reason string | null
Why B3 blocked the address (blocked only; else null). Every answer of the edge has it.
claimed_at string (date-time) REQUIRED
updated_at string (date-time) REQUIRED
dropped_cookies object[] REQUIRED
Cookies a page script set that the address did not pass to the app in the last 7 days (cookies: isolated), by name, most requests first. List one under cookies.script to let it through.
Array of:
name string REQUIRED
requests integer REQUIRED
next_cursor string | null REQUIRED
401 Missing, malformed, expired or revoked credentials (unauthorized).
403 Authenticated but not allowed (forbidden, egress_denied).
404 Addresses are not on for your organization (feature_not_enabled: the platform.app_hosts flag). Nothing was read or claimed.
429 A rate, concurrency or quota limit applies (rate_limited, concurrency_limited, quota_exceeded).
500 Something failed inside B3OS (internal). Retry with backoff.
503 B3OS could not read whether addresses are on for your organization (flags_unavailable: the flag platform.app_hosts, or whether your organization holds a serving address). Nothing was read or changed; retry after Retry-After seconds. A caller must not read this as "no addresses". 
curl -X GET 'https://beta-api.b3os.org/v1/app-hosts' \  -H 'Authorization: Bearer YOUR_API_TOKEN'
const response = await fetch('https://beta-api.b3os.org/v1/app-hosts', {  method: 'GET',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN"  }});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.get('https://beta-api.b3os.org/v1/app-hosts', headers=headers)print(response.json())
200 Response 
{  "object": "list",  "data": [    {      "object": "app_host",      "label": "gpt-researcher",      "url": "https://gpt-researcher.b3os.io",      "app": "gpt-researcher",      "environment": "production",      "project_id": "prj_01m5t3pf8heewxt65ej3dm577y",      "service": "web",      "port": 8000,      "access": "link",      "cookies": {        "mode": "isolated",        "script": []      },      "state": "serving",      "sandbox_id": "sbx_01m5t68q1b590rj801nbzsqzkk",      "deploy_id": "dep_01m6a2zq8x9hkqd3n7c5b4v2tw",      "base_label": null,      "primary": true,      "blocked_reason": null,      "claimed_at": "2026-11-11T09:00:00.000Z",      "updated_at": "2026-11-11T09:02:00.000Z",      "dropped_cookies": []    }  ],  "next_cursor": null}
Previous Roll back to a deploy
Next List an application's addresses
Ask a question... ⌘I