Preview an application's addresses

POST /v1/apps/{app}/hosts/preview
What Claim an application's addresses would give each port, without claiming anything: the port's stored label (yours) or the label that is free now (free; another organization may claim it first). A port that could get no label answers the error the claim would. b3os plan and --dry-run call this. 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)

Path Parameters

app string required path
The application's name (name in its b3os.yaml).
Min length 1Max length 63Pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
Example: "research-agent"

Request Body required

application/json
hosts object[] REQUIRED
The application's addressed ports, the primary one first.
Min items 1Max items 32
Array of:
service string REQUIRED
Min length 1Max length 63Pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
port integer REQUIRED
Min 1Max 65535
access string
link: people who hold a link from b3os app link. public: anyone on the internet.
Values link public
cookies object
mode string
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[]
Max items 20Unique itemsItem pattern ^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,64}$
host string
Ask for this label instead of the default; read when the port is first claimed.
Min length 1Max length 63Pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
primary boolean
This port gets the application's own label; read when the port is first claimed.
deploy_id string
The deploy this claim is part of: a b3os apply id (<yyyymmdd>T<hhmmss>Z-<8 hex>) or a GitHub App deploy's dep_<ulid>. The claim is refused when a newer deploy, or a change without deploy_id, set an address after this deploy began. Leave it out for your own change. The preview takes it and ignores it.
Max length 64

Responses

200 The label each port has or would get.
application/json
object string REQUIRED
Values app_host_preview
hosts object[] REQUIRED
Array of:
service string REQUIRED
port integer REQUIRED
label string REQUIRED
An address's label, the part before .b3os.io.
url string (uri) REQUIRED
status string REQUIRED
yours: the port's stored label. free: free now; another organization may claim it first.
Values yours free
400 The request failed validation (invalid_request, invalid_url).
401 Missing, malformed, expired or revoked credentials (unauthorized).
403 B3 blocked the address; it can be neither claimed nor routed (app_host_blocked).
404 Addresses are not on for your organization (feature_not_enabled: the platform.app_hosts flag). Nothing was read or claimed.
409 Every candidate label is held by another application or organization (app_host_label_taken), the port already has another label than host asks for (app_host_conflict, reason label_fixed), or a newer deploy, or a change outside a deploy, set the address after the deploy deploy_id names began (app_host_route_conflict, reason newer_deploy; nothing is written).
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
422 The label is one B3OS refuses (app_host_label_reserved, with reason), the claim is over apps.hosts.max or apps.hosts.public_max (limit_exceeded), it would make a serving address public while the sandbox it serves has no spend_cap_usd (app_host_public_needs_spend_cap), or it would make a serving address link while the sandbox it serves has that port public (app_host_port_public). Nothing is written.
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 POST 'https://beta-api.b3os.org/v1/apps/research-agent/hosts/preview' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "hosts": [    {      "service": "web",      "port": 8000,      "primary": true    }  ]}'
const response = await fetch('https://beta-api.b3os.org/v1/apps/research-agent/hosts/preview', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "hosts": [      {        "service": "web",        "port": 8000,        "primary": true      }    ]  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/v1/apps/research-agent/hosts/preview', headers=headers, json={  "hosts": [    {      "service": "web",      "port": 8000,      "primary": true    }  ]})print(response.json())
200 Response 
{  "object": "app_host_preview",  "hosts": [    {      "service": "web",      "port": 8000,      "label": "gpt-researcher",      "url": "https://gpt-researcher.b3os.io",      "status": "free"    }  ]}
Previous Claim an application's addresses
Next Switch an application's addresses
Ask a question... ⌘I