Previews

A preview exposes an HTTP service listening on a port inside a sandbox at a stable HTTPS URL. In v1, all previews are private: use API-key authenticated access by default, or token-mode browser links for handoff. There are no public preview URLs.

The Preview object

Create a preview

POST /v1/sandboxes/{sandboxId}/previews — requires scope preview:create.

Exposes a port on the sandbox. Creating a preview for the same sandbox and port returns the existing active preview instead of a duplicate. A sandbox can have at most 3 active previews, and an org at most 10.

curl -X POST https://api.crownest.dev/v1/sandboxes/sbx_abc123/previews \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "port": 3000 }'

Returns 201 with the preview creation envelope:

{
  "preview": {
    "id": "prv_abc123",
    "slug": "p-a1b2c3",
    "url": "https://p-a1b2c3.crownest.dev",
    "orgId": "org_abc123",
    "projectId": "prj_abc123",
    "sandboxId": "sbx_abc123",
    "port": 3000,
    "authMode": "authenticated",
    "createdAt": "2026-06-11T13:00:00.000Z"
  }
}

For a newly created token-mode preview, the response also includes previewToken as a sibling of preview. The token is returned only once; reads, lists, and deduped creates cannot recover it.

{
  "preview": {
    "id": "prv_abc123",
    "slug": "p-a1b2c3",
    "url": "https://p-a1b2c3.crownest.dev",
    "orgId": "org_abc123",
    "projectId": "prj_abc123",
    "sandboxId": "sbx_abc123",
    "port": 3000,
    "authMode": "token",
    "createdAt": "2026-06-11T13:00:00.000Z"
  },
  "previewToken": "pvt_..."
}

Errors: invalid_request, unsupported_preview_auth_mode, forbidden, not_found, sandbox_destroyed. If the port stops responding later, requests to the preview URL fail with preview_unavailable (502).

List previews

GET /v1/sandboxes/{sandboxId}/previews — requires scope preview:read.

Returns a paginated list of the sandbox's previews. This endpoint returns all active previews in a single page (hasMore is always false).

curl https://api.crownest.dev/v1/sandboxes/sbx_abc123/previews \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

{
  "data": [
    {
      "id": "prv_abc123",
      "url": "https://p-a1b2c3.crownest.dev",
      "port": 3000,
      "authMode": "authenticated"
    }
  ],
  "hasMore": false
}

Get a preview

GET /v1/previews/{previewId} — requires scope preview:read.

Returns one preview by ID.

curl https://api.crownest.dev/v1/previews/prv_abc123 \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

Returns 200 with { "preview": { ... } }. Errors: forbidden, not_found.

Revoke a preview

DELETE /v1/previews/{previewId} — requires scope preview:revoke.

Revokes the preview so its URL stops routing to the sandbox. The operation is idempotent — revoking an already-revoked preview returns the revoked record.

curl -X DELETE https://api.crownest.dev/v1/previews/prv_abc123 \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

Returns 200 with { "preview": { ... } } including revokedAt. Errors: forbidden, not_found.

Next steps

• Start the server behind your preview with a background request in Commands.
• Check what each scope allows in Authentication.