docs

beacon.host API

Static hosting and serverless backends built to be called by AI agents. Send the file in one request, or a manifest for big sites, and it's live on its own subdomain: curl -sS https://beacon.host/v1/publish -F file=@index.html

Using Claude Code or Codex? Start with publish HTML from Claude Code or Codex. Step-by-step without an account: Host a static site with no signup.

beacon.host is web hosting designed to be called by AI agents. Your agent sends a file manifest, uploads files to presigned URLs, and gets back a live URL at slug.beacon.host. There is also a one-file agent skill (install it with npx skills add beacon-host/skill -g), a zero-install Python publisher, the beacon CLI, an OpenAPI spec, a remote MCP server at https://beacon.host/mcp (add it with claude mcp add --transport http beacon https://beacon.host/mcp; setup for every client), and a dashboard where you can drop files to publish and manage sites. Step-by-step guides cover common jobs.

Every site gets its own subdomain. Updates are atomic and versioned. No account is required for one-off publishes (sites expire in 24 hours), or sign in for permanent hosting.

Base URL: https://beacon.host

Quick Start

One request

POST /v1/publish

Send the files themselves: a multipart form (-F file=@..., repeatable; -F archive=@site.zip for a zipped folder), the raw body with its Content-Type, or JSON in the MCP publish_site shape. A lone HTML file becomes index.html. Optional form fields or query parameters: slug, title, expires (2h, 7d or RFC 3339), and username plus password to put the site behind a login prompt.

curl -sS https://beacon.host/v1/publish -F file=@report.html

Response 201 Created (200 for an update with ?slug= and X-Claim-Token):

{
  "url": "https://autumn-river-42.beacon.host",
  "fileUrl": "https://autumn-river-42.beacon.host/",
  "slug": "autumn-river-42",
  "anonymous": true,
  "expiresAt": "2026-03-20T15:04:05Z",
  "claimUrl": "https://beacon.host/claim/autumn-river-42#ctk_abc123...",
  "claimToken": "ctk_abc123...",
  "passwordProtected": false
}

Up to 4 MB of files per request without an API key, 10 MB with one. POST /v1/upload is the same endpoint but prints only the link (handy for PDFs and images; see the file upload API), and PUT /v1/upload/<name> takes a raw body. Walkthrough for one HTML report: share an HTML file as a link.

Three calls, for big sites

Files up to 250 MB each (5 GB with an account), and only the files beacon.host doesn't already have are uploaded:

Step 1: Create a site with your file manifest

# Create a site with one HTML file
curl -X POST https://beacon.host/v1/sites \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "index.html",
        "size": 1024,
        "contentType": "text/html",
        "hash": "sha256:a1b2c3d4e5f6...64 hex chars"
      }
    ]
  }'

The response includes presigned upload URLs and a finalize URL:

{
  "site": {
    "id": "site_abc123",
    "slug": "autumn-river-42",
    "url": "https://autumn-river-42.beacon.host",
    "expiresAt": "2026-03-20T15:04:05Z",
    "createdAt": "2026-03-19T15:04:05Z"
  },
  "version": {
    "id": "ver_xyz789",
    "finalizeUrl": "/v1/sites/autumn-river-42/versions/ver_xyz789/finalize"
  },
  "uploads": {
    "pending": [
      {
        "path": "index.html",
        "uploadUrl": "https://storage.example.com/presigned-url...",
        "uploadMethod": "put"
      }
    ],
    "skipped": []
  },
  "claimToken": "ctk_abc123...",
  "claimUrl": "https://beacon.host/claim/autumn-river-42#ctk_abc123..."
}

Step 2: Upload each file to its presigned URL

curl -X PUT "https://storage.example.com/presigned-url..." \
  -H "Content-Type: text/html" \
  --data-binary @index.html

Step 3: Finalize the version to go live

curl -X POST https://beacon.host/v1/sites/autumn-river-42/versions/ver_xyz789/finalize \
  -H "X-Claim-Token: ctk_abc123..."

Response:

{
  "site": {
    "id": "site_abc123",
    "slug": "autumn-river-42",
    "url": "https://autumn-river-42.beacon.host",
    "currentVersionId": "ver_xyz789",
    "expiresAt": "2026-03-20T15:04:05Z",
    "createdAt": "2026-03-19T15:04:05Z",
    "updatedAt": "2026-03-19T15:04:10Z"
  },
  "version": {
    "id": "ver_xyz789",
    "status": "live",
    "fileCount": 1,
    "totalSize": 1024,
    "finalizedAt": "2026-03-19T15:04:10Z",
    "createdAt": "2026-03-19T15:04:05Z"
  }
}

Your site is now live at https://autumn-river-42.beacon.host.

Authentication

beacon.host supports two modes of operation:

Anonymous (no auth required)

Just call the API with no credentials. Your site will be assigned a random slug and will expire in 24 hours. Step-by-step: Host a static site with no signup. You receive a claimToken and claimUrl in the response that you can use to claim ownership later.

To manage an anonymous site (update it, delete it, etc.), include the claim token in the X-Claim-Token header:

curl -X PATCH https://beacon.host/v1/sites/autumn-river-42/metadata \
  -H "X-Claim-Token: ctk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"title": "My Site"}'

Authenticated (Bearer token)

Include your API key in the Authorization header. Authenticated sites are permanent (no expiry unless you set one). You get higher rate limits and larger file size allowances.

curl -X POST https://beacon.host/v1/sites \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"files": [...]}'
FeatureAnonymousAuthenticated
Site lifetime24 hoursPermanent
Max file size250 MB5 GB
Publish rate limit5/hour per IP60/hour per key
Custom slugAllowedAllowed
Auth headerNone (or X-Claim-Token)Authorization: Bearer <key>

Publishing

Create a site

POST /v1/sites

Creates a new site and its first version. Returns presigned upload URLs for each file in your manifest. With an API key, a manifest that would take the account's file storage over its plan's limit gets 409 file_storage_full and nothing is created.

Request body

FieldTypeRequiredDescription
filesarrayYesArray of file manifest entries
files[].pathstringYesFile path relative to site root (e.g. index.html, assets/style.css)
files[].sizeintegerYesFile size in bytes
files[].contentTypestringYesMIME type (e.g. text/html)
files[].hashstringYesSHA-256 hash in format sha256:<64 hex chars>
slugstringNoCustom slug for the subdomain. Auto-generated if omitted.
expiresAtstringNoRFC 3339 timestamp. Only for authenticated requests.

Headers

HeaderRequiredDescription
AuthorizationNoBearer <api-key> for authenticated requests
Idempotency-KeyNoUnique key to safely retry the request. If a site was already created with this key, the original response is replayed. Replay is scoped to the authenticated account; anonymous replay also needs X-Idempotency-Secret.
X-Idempotency-SecretNoAnonymous retries only: 32-128 random characters (A-Z a-z 0-9 - _), generated once per create and resent with every retry of it. Keep it private: it, not the key or your IP, proves the retry is yours. Without it an anonymous Idempotency-Key is ignored and every request creates a new site. Replay stops once the site is claimed.
curl -X POST https://beacon.host/v1/sites \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "slug": "my-project",
    "files": [
      {
        "path": "index.html",
        "size": 2048,
        "contentType": "text/html",
        "hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      {
        "path": "style.css",
        "size": 512,
        "contentType": "text/css",
        "hash": "sha256:d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592"
      }
    ]
  }'

Response 200 OK:

{
  "site": {
    "id": "site_abc123",
    "slug": "my-project",
    "url": "https://my-project.beacon.host",
    "expiresAt": null,
    "createdAt": "2026-03-19T15:04:05Z",
    "updatedAt": "2026-03-19T15:04:05Z"
  },
  "version": {
    "id": "ver_xyz789",
    "finalizeUrl": "/v1/sites/my-project/versions/ver_xyz789/finalize"
  },
  "uploads": {
    "pending": [
      {
        "path": "index.html",
        "uploadUrl": "https://storage.example.com/presigned-url-1...",
        "uploadMethod": "put"
      },
      {
        "path": "style.css",
        "uploadUrl": "https://storage.example.com/presigned-url-2...",
        "uploadMethod": "put"
      }
    ],
    "skipped": []
  }
}

Anonymous responses also include claimToken and claimUrl fields that let you claim ownership of the site later.

Upload files

Upload each file to its presigned URL using a PUT request. The Content-Type header must match the contentType from the manifest.

curl -X PUT "https://storage.example.com/presigned-url-1..." \
  -H "Content-Type: text/html" \
  --data-binary @index.html

Upload URLs expire after 1 hour. If they expire before you finish uploading, use the refresh uploads endpoint to get new ones.

Finalize a version

POST /v1/sites/:slug/versions/:versionId/finalize

Verifies all uploaded files match their declared hashes and sizes, then atomically makes the version live. The site is accessible immediately after a successful finalize.

Finalize also checks what each file is: a native program (a Windows, Linux or macOS executable, under any name), or a .zip or .tar that holds one or a malware dropper, is refused with 422 content_blocked and nothing goes live. See Content policy.

For an account's site, finalize checks its file storage again, in the same transaction that makes the version live, so two publishes can't pass the limit together: 409 file_storage_full, and the version stays pending.

To deploy with a new expiry, POST to version.finalizeExpiryUrl returned by create or create-version: /v1/sites/:slug/versions/:versionId/finalize-with-expiry, with Content-Type: application/json and {"expiresAt":"<RFC3339>"}. The expiry and live version commit together. Validation, storage verification, and conflict failures leave both unchanged; a concurrent version or expiry change returns 409. If the response is lost after commit, retry the same expiry endpoint to confirm current matching state; otherwise the outcome remains ambiguous. The time must remain in the future through commit. Anonymous sites are capped at creation plus 24 hours. Missing or null expiry is rejected; ordinary bodyless /finalize preserves expiry.

beacon deploy --expires requires this endpoint and its advertised finalizeExpiryUrl. Older servers fail closed without a metadata fallback. Replaying the expiry endpoint succeeds only while that version is current/live with the requested expiry; otherwise it returns 409 (expired sites return 404).

curl -X POST https://beacon.host/v1/sites/my-project/versions/ver_xyz789/finalize \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "site": {
    "id": "site_abc123",
    "slug": "my-project",
    "url": "https://my-project.beacon.host",
    "currentVersionId": "ver_xyz789",
    "expiresAt": null,
    "createdAt": "2026-03-19T15:04:05Z",
    "updatedAt": "2026-03-19T15:04:10Z"
  },
  "version": {
    "id": "ver_xyz789",
    "status": "live",
    "fileCount": 2,
    "totalSize": 2560,
    "finalizedAt": "2026-03-19T15:04:10Z",
    "createdAt": "2026-03-19T15:04:05Z"
  }
}

Multipart uploads

Files 250 MB and larger are automatically assigned multipart uploads. Instead of a single uploadUrl, you receive an uploadId and an array of partUrls.

// In the create site response, large files look like:
{
  "path": "large-video.mp4",
  "uploadMethod": "multipart",
  "uploadId": "mpu_abc123",
  "partUrls": [
    "https://storage.example.com/part-1-url...",
    "https://storage.example.com/part-2-url..."
  ]
}

Upload each part in order (8 MB per part), then call the complete multipart endpoint with the ETags returned by each part upload. After all multipart uploads are completed, call finalize as usual.

Content deduplication

beacon.host deduplicates files by their SHA-256 hash. If a file with the same hash was uploaded in a previous finalized version (on any site), it will appear in the skipped array instead of pending:

{
  "skipped": [
    {
      "path": "logo.png",
      "reason": "hash_match"
    }
  ]
}

You do not need to upload skipped files. They are already stored and will be served correctly.

Site Management

List sites

GET /v1/sites

Returns all sites owned by the authenticated user. Requires Bearer auth.

Query parameters

ParameterTypeDefaultDescription
limitinteger20Max results to return (max 100)
offsetinteger0Pagination offset
curl https://beacon.host/v1/sites?limit=20 \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "data": [
    {
      "id": "site_abc123",
      "slug": "my-project",
      "url": "https://my-project.beacon.host",
      "currentVersionId": "ver_xyz789",
      "ownerId": "usr_def456",
      "title": "My Project",
      "expiresAt": null,
      "createdAt": "2026-03-19T15:04:05Z",
      "updatedAt": "2026-03-19T15:04:10Z"
    }
  ],
  "totalCount": 1,
  "limit": 20,
  "offset": 0
}

Update metadata

PATCH /v1/sites/:slug/metadata

Update site metadata. All fields are optional — only included fields are updated. Set a field to null to clear it.

Request body

FieldTypeDescription
titlestring | nullSite title (used in Open Graph tags)
descriptionstring | nullSite description
ogImagePathstring | nullPath to an image file in the site for Open Graph
expiresAtstring | nullRFC 3339 expiry. Set to null to make permanent (authenticated only). Anonymous sites can only move it earlier, to at most 24 hours after creation. How expiry works.
curl -X PATCH https://beacon.host/v1/sites/my-project/metadata \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Project",
    "description": "A demo site published by my agent",
    "ogImagePath": "preview.png"
  }'

Response 200 OK:

{
  "site": {
    "id": "site_abc123",
    "slug": "my-project",
    "url": "https://my-project.beacon.host",
    "currentVersionId": "ver_xyz789",
    "title": "My Project",
    "description": "A demo site published by my agent",
    "ogImagePath": "preview.png",
    "expiresAt": null,
    "createdAt": "2026-03-19T15:04:05Z",
    "updatedAt": "2026-03-19T15:05:00Z"
  }
}

Set password protection

PUT /v1/sites/:slug/password

Protects the site with HTTP Basic authentication. Visitors will be prompted for credentials before seeing the site. Anonymous sites can be locked too, before anyone claims them: send X-Claim-Token: ctk_... instead of the Bearer key. Guide: password-protect an HTML page.

curl -X PUT https://beacon.host/v1/sites/autumn-river-42/password \
  -H "X-Claim-Token: ctk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"username": "client", "password": "s3cret"}'
curl -X PUT https://beacon.host/v1/sites/my-project/password \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "demo",
    "password": "s3cret"
  }'

Response 200 OK:

{
  "success": true
}

Remove password protection

DELETE /v1/sites/:slug/password
curl -X DELETE https://beacon.host/v1/sites/my-project/password \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "success": true
}

Delete a site

DELETE /v1/sites/:slug

Permanently deletes a site and all its versions. This action cannot be undone.

curl -X DELETE https://beacon.host/v1/sites/my-project \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "success": true
}

Claim an anonymous site

POST /v1/sites/:slug/claim

Transfer ownership of an anonymous site to your account. Requires both Bearer auth (to identify the new owner) and the claim token (to prove you created the site). Claiming a site removes its expiry and makes it permanent, and its files join the account's file storage: a claim they don't fit gets 409 file_storage_full and the site stays anonymous. How a person claims from the claim link, and what happens if nobody does: claim the site later.

curl -X POST https://beacon.host/v1/sites/autumn-river-42/claim \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"claimToken": "ctk_abc123..."}'

Response 200 OK:

{
  "site": {
    "id": "site_abc123",
    "slug": "autumn-river-42",
    "url": "https://autumn-river-42.beacon.host",
    "currentVersionId": "ver_xyz789",
    "ownerId": "usr_def456",
    "expiresAt": null,
    "createdAt": "2026-03-19T15:04:05Z",
    "updatedAt": "2026-03-19T15:10:00Z"
  }
}

Versions

Every publish creates a new version. Versions are immutable once finalized. You can update a site by creating a new version, or roll back to any previous version.

Create a new version

POST /v1/sites/:slug/versions

Creates a new version for an existing site. Works exactly like creating a site, but attaches to the existing slug. The new version does not go live until you finalize it. For an account's site, the new version replaces the live one in the account's file storage, and one that would take it over its limit gets 409 file_storage_full.

curl -X POST https://beacon.host/v1/sites/my-project/versions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "index.html",
        "size": 3072,
        "contentType": "text/html",
        "hash": "sha256:abc123..."
      }
    ]
  }'

Response 200 OK:

{
  "site": {
    "id": "site_abc123",
    "slug": "my-project",
    "url": "https://my-project.beacon.host",
    "currentVersionId": "ver_xyz789",
    "expiresAt": null,
    "createdAt": "2026-03-19T15:04:05Z",
    "updatedAt": "2026-03-19T15:04:10Z"
  },
  "version": {
    "id": "ver_new456",
    "finalizeUrl": "/v1/sites/my-project/versions/ver_new456/finalize"
  },
  "uploads": {
    "pending": [
      {
        "path": "index.html",
        "uploadUrl": "https://storage.example.com/presigned-url...",
        "uploadMethod": "put"
      }
    ],
    "skipped": []
  }
}

List versions

GET /v1/sites/:slug/versions

Returns all versions for a site, ordered by creation date (newest first).

Query parameters

ParameterTypeDefaultDescription
limitinteger20Max results to return
offsetinteger0Pagination offset
curl https://beacon.host/v1/sites/my-project/versions \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "data": [
    {
      "id": "ver_xyz789",
      "status": "live",
      "fileCount": 2,
      "totalSize": 2560,
      "finalizedAt": "2026-03-19T15:04:10Z",
      "createdAt": "2026-03-19T15:04:05Z"
    },
    {
      "id": "ver_old123",
      "status": "superseded",
      "fileCount": 1,
      "totalSize": 1024,
      "finalizedAt": "2026-03-18T10:00:00Z",
      "createdAt": "2026-03-18T09:59:55Z"
    }
  ],
  "totalCount": 2,
  "limit": 20,
  "offset": 0
}

Rollback to a version

POST /v1/sites/:slug/versions/:versionId/rollback

Instantly redeploys a previous version. Creates a new version by copying the file manifest from the target version, then atomically makes it live. The target version must be finalized (not pending). A rollback that would take the account's file storage over its limit gets 409 file_storage_full, like a publish.

curl -X POST https://beacon.host/v1/sites/my-project/versions/ver_old123/rollback \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "site": {
    "id": "site_abc123",
    "slug": "my-project",
    "url": "https://my-project.beacon.host",
    "currentVersionId": "ver_rolled789",
    "expiresAt": null,
    "createdAt": "2026-03-19T15:04:05Z",
    "updatedAt": "2026-03-19T16:00:00Z"
  },
  "version": {
    "id": "ver_rolled789",
    "status": "live",
    "fileCount": 1,
    "totalSize": 1024,
    "finalizedAt": "2026-03-19T16:00:00Z",
    "createdAt": "2026-03-19T16:00:00Z"
  }
}

Refresh upload URLs

POST /v1/sites/:slug/versions/:versionId/uploads/refresh

Regenerates expired presigned upload URLs for a pending version. Optionally pass a list of paths to refresh only specific files.

Request body (optional)

FieldTypeDescription
pathsstring[]Optional list of file paths to refresh. Omit to refresh all.
curl -X POST https://beacon.host/v1/sites/my-project/versions/ver_xyz789/uploads/refresh \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["index.html"]}'

Response 200 OK:

{
  "uploads": {
    "pending": [
      {
        "path": "index.html",
        "uploadUrl": "https://storage.example.com/new-presigned-url...",
        "uploadMethod": "put"
      }
    ],
    "skipped": []
  }
}

Complete multipart upload

POST /v1/sites/:slug/versions/:versionId/uploads/complete

Assembles a multipart upload after all parts have been uploaded. You must call this for each file that used multipart upload method before calling finalize.

Request body

FieldTypeRequiredDescription
pathstringYesFile path in the manifest
uploadIdstringYesThe upload ID from the create response
partsarrayYesArray of completed parts
parts[].partNumberintegerYesPart number (1-based)
parts[].etagstringYesETag returned by the part upload
curl -X POST https://beacon.host/v1/sites/my-project/versions/ver_xyz789/uploads/complete \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "large-video.mp4",
    "uploadId": "mpu_abc123",
    "parts": [
      {"partNumber": 1, "etag": "\"abc123...\""},
      {"partNumber": 2, "etag": "\"def456...\""}
    ]
  }'

Response 200 OK:

{
  "success": true
}

Workers

Workers are serverless JavaScript/TypeScript functions that run on Cloudflare's edge network. They are the compute layer for beacon.host — deploy an API backend alongside your static site.

The recommended pattern is to pair a static frontend with a Worker backend. A site and a worker can't share a slug, so give them two. For a walkthrough with working code, see Deploy an API without a Cloudflare account, and for webhooks, deploy a webhook receiver (GitHub, Stripe).

# Static frontend
my-app.beacon.host           → HTML/CSS/JS (Beacon)

# API backend (Hono recommended)
my-app-api.worker.beacon.host  → Serverless Worker (Cloudflare edge)

Workers require authentication. Anonymous workers are not supported. You must include a Bearer token with all Workers API requests.

Workers share a global slug namespace with static sites — a slug is unique across both. Upload JavaScript ES modules: the deploy endpoint takes files as-is, with no TypeScript compilation or bundling, and it does not resolve npm imports. A .wasm file goes up as a WebAssembly module (import wasm from "./query_compiler_bg.wasm"), which is how Prisma and other Wasm libraries load, since a Worker can't compile Wasm from bytes at runtime. Bundle first (for example npx esbuild index.ts --bundle --format=esm --outfile=index.js). beacon deploy does this for you: it runs your build script when package.json has one, otherwise it installs dependencies, compiles TypeScript and bundles every import with its built-in esbuild.

An account can have 25 workers (409 workers_quota_exceeded past that), and can add 30 new workers in any 30 days on Free, 100 on Beacon Plus (429 new_workers_limit_reached past that). A deployed worker that is deleted still counts for 30 days after the delete; deploys to existing workers never count. A deleted worker's slug can't be created again for 15 minutes (409 slug_cooling_down, with retryAfter). Changes to one worker run one at a time: a deploy, rollback, secret change or delete that overlaps another gets 409 deploy_in_progress, which is safe to retry; the CLI waits it out itself (deploy_in_progress). A deploy or rollback also gets 409 deploy_in_progress (retryable) when Cloudflare refused its upload because the worker's script changed after the deploy read it; nothing was uploaded, and sending it again reads the script again. If Beacon restarts during a change, that change's operation becomes uncertain (errorCode: op_interrupted), and the worker takes changes again about 2 minutes later. Workers API errors carry a code; Error codes explains each one.

Workers run on every plan, within daily request and per-request limits; D1 databases and plain-text vars come with Beacon Plus. A worker's URL answers with a short JSON error of its own when a limit or a pause stops a request (edge answers).

Live logs and cron triggers run through beacon.host's platform edge and work once it is switched on. Until then GET /v1/workers/:slug/logs/tail answers 501 with "code": "logs_unavailable", and a deploy that declares crons is refused with 400 and "code": "crons_not_supported" before anything is uploaded. GET /v1/capabilities says which: "logs": true and "crons": true once they work.

Create a worker

POST /v1/workers

Creates a new worker and reserves a slug. The worker is not live until you deploy code to it.

Request body

FieldTypeRequiredDescription
slugstringNoCustom slug for the subdomain. Auto-generated if omitted.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <api-key>
Idempotency-KeyNoUnique key to safely retry the request
curl -X POST https://beacon.host/v1/workers \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-api"}'

Response 200 OK:

{
  "slug": "my-api",
  "url": "https://my-api.worker.beacon.host",
  "createdAt": "2026-03-20T15:04:05Z"
}

Refusals: 409 slug_unavailable (a site or another worker has the slug), 409 slug_cooling_down (a worker with this slug was deleted in the last 15 minutes), 409 workers_quota_exceeded (the account already has 25 workers), 429 new_workers_limit_reached (the account added 30 workers in the last 30 days on Free, 100 on Beacon Plus), 403 account_suspended (the account is suspended) and 429 rate_limited (10 creates an hour, 100 on internal accounts).

List workers

GET /v1/workers

Returns all workers owned by the authenticated user.

curl https://beacon.host/v1/workers \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "data": [
    {
      "slug": "my-api",
      "url": "https://my-api.worker.beacon.host",
      "createdAt": "2026-03-20T15:04:05Z",
      "state": {"status": "active", "reason": null}
    }
  ],
  "totalCount": 1,
  "limit": 20,
  "offset": 0
}

Each worker's state is active, capped (its account reached the daily request limit), paused or suspended, with the reason (Pauses and suspensions).

Get worker details

GET /v1/workers/:slug

Returns a worker with its current deployment and that deployment's settings (bindings: entry point, compatibility date and flags, and crons). A worker that was never deployed has neither.

curl https://beacon.host/v1/workers/my-api \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "slug": "my-api",
  "url": "https://my-api.worker.beacon.host",
  "currentDeployment": {
    "id": "dep_abc123",
    "version": 3,
    "entryPoint": "index.js",
    "sizeBytes": 1234,
    "deployedAt": "2026-03-20T15:10:00Z"
  },
  "bindings": {
    "entryPoint": "index.js",
    "compatibilityDate": "2024-09-23",
    "compatibilityFlags": ["nodejs_compat"],
    "crons": ["0 * * * *"]
  },
  "createdAt": "2026-03-20T15:04:05Z",
  "state": {"status": "active", "reason": null, "since": null, "until": null, "canResume": false, "holds": []}
}

state says whether the worker serves. A paused worker's state names the reason, when it started, and every hold on it, with the usage that crossed a daily limit:

"state": {
  "status": "paused", "reason": "d1_rows_written", "since": "2026-10-22T12:03:00Z", "until": null, "canResume": true,
  "holds": [{"reason": "d1_rows_written", "scope": "worker", "placedAt": "2026-10-22T12:03:00Z", "placedBy": "system", "until": null, "metric": {"value": 50312, "cap": 50000}}]
}

canResume is true when the owner can lift the pause with a deploy or POST /v1/workers/:slug/resume. Pauses and suspensions lists every reason.

Deploy a worker

POST /v1/workers/:slug/deploy

Uploads and activates a worker script in a single request. The request body is multipart/form-data with a JSON metadata part and one or more file parts.

Multipart form fields

Field nameTypeRequiredDescription
metadataJSON (form value)YesDeployment metadata (see below)
fileFile upload(s)YesOne or more script files. Use field name file for each.
<BINDING>/<NNNN_name>.sqlFile upload(s)NoA D1 migration, one part per file, named for its binding (for example -F 'DB/0001_init.sql=@migrations/0001_init.sql'), with the binding's whole history on every deploy. The binding must be declared in storage.d1; parts for another binding are refused with 400 storage_not_declared.

Metadata fields

FieldTypeRequiredDescription
entryPointstringYesMain module filename (e.g. index.js). Upload JavaScript; TypeScript is not compiled.
compatibilityDatestringNoCloudflare compatibility date (YYYY-MM-DD). Without it, the worker's first deploy pins that day's date and later deploys keep it; sending a date moves the pin.
compatibilityFlagsstring[]NoCompatibility flags (e.g. ["nodejs_compat"]). nodejs_compat is added for you when a file imports node:* modules.
cronsstring[]NoCron triggers that run the worker's scheduled() handler, e.g. ["*/5 * * * *"]. See Cron triggers.
storageobjectNoThe worker's storage by binding name: {"d1": {"DB": {"location"?, "jurisdiction"?, "renamedFrom"?}}}. Not the config file's top-level "d1", which the metadata refuses (unknown_metadata_field). D1 comes with Beacon Plus. See Worker storage.
varsobjectNoPlain-text variables, {"MODE": "production"}, with Beacon Plus.
confirmobjectNoChoices only the user makes, by binding name: detach, deleteStorage, newStorage and destructiveMigrations (lists of bindings), reapplyMigrations ({"DB": ["0002_x.sql"]}). Needs storage.
skipBindingCheckbooleanNotrue deploys although the bundle names a binding the deploy doesn't declare (binding_undeclared_in_code).
# Deploy a simple worker
curl -X POST https://beacon.host/v1/workers/my-api/deploy \
  -H "Authorization: Bearer your-api-key" \
  -F 'metadata={"entryPoint":"index.js"}' \
  -F "file=@index.js"
# Deploy multiple files
curl -X POST https://beacon.host/v1/workers/my-api/deploy \
  -H "Authorization: Bearer your-api-key" \
  -F 'metadata={"entryPoint":"index.js"}' \
  -F "file=@index.js" \
  -F "file=@utils.js"

Response 200 OK:

{
  "slug": "my-api",
  "url": "https://my-api.worker.beacon.host",
  "deploymentId": "dep_abc123",
  "version": 3,
  "sizeBytes": 1234,
  "fileCount": 2,
  "entryPoint": "index.js",
  "compatibilityDate": "2026-09-30",
  "deployedAt": "2026-10-05T15:10:00Z",
  "status": "deployed",
  "warnings": [],
  "operationId": "op_abc123",
  "storage": {},
  "resumed": false
}

Deploy is idempotent. If files, settings and migrations match the current deployment, and Beacon can confirm that the live script is that deployment's own upload, it is returned with "status": "unchanged" without re-uploading to Cloudflare. Pending migrations run even when files and settings match; that response has "status": "migrated".

Each account has 60 deploys an hour and 300 deploy requests an hour (counted on every request); past either, 429 rate_limited with retryAfter. A deploy counts when it sends code or migrations to Cloudflare, and so does a migration apply (POST /v1/workers/:slug/d1/:binding/migrations, beacon d1 migrations apply) that sends migrations; migrations D1 refused, or answered with an error after which none of them had run, don't count. Beacon builds every binding itself. Metadata keys that name Cloudflare resources (binding lists, IDs) are refused with storage_field_not_allowed when storage mode covers the account; otherwise they are ignored with a resource_key_ignored warning. Inside storage (such as storage.d1.DB.id) they are refused for every account. Any other top-level key the server doesn't read is refused with 400 unknown_metadata_field, whose fields lists the keys. D1 storage and plain-text vars come with Beacon Plus: check storage.d1 in GET /v1/capabilities with your Bearer key before declaring storage (403 storage_kind_not_enabled and 403 vars_not_enabled otherwise). Keep credentials in secrets.

A deploy or rollback of a suspended worker is refused with 403 worker_suspended, and every change on a suspended account with 403 account_suspended. A deploy that creates a database or runs migrations is refused with 403 plan_lapsed after Beacon Plus ended, and with 409 storage_quota_exceeded while the account's D1 data is at its size limit.

curl sends only each file's base name, so keep extra modules next to index.js and import them as ./utils.js.

If Cloudflare refuses the script (it doesn't parse, imports a module that isn't in the upload, or throws while loading), the deploy fails with 422 and Cloudflare's own message. Nothing is recorded and the previous deployment keeps serving:

{
  "error": "Cloudflare rejected the script: Uncaught SyntaxError: Unexpected token ':' at index.js:1:23",
  "code": "deploy_failed",
  "hint": "fix the script and deploy again; retrying the same bundle fails the same way. The previous deployment is still live",
  "detail": "Uncaught SyntaxError: Unexpected token ':'\n  at index.js:1:23",
  "retryable": false,
  "docs": "https://developers.cloudflare.com/workers/observability/errors/#validation-errors-10021"
}

Fix the script before deploying again: the same bundle fails the same way, and every attempt counts toward the deploy rate limit. Only a Cloudflare outage or network failure returns 502 with "code": "platform_unavailable" and "retryable": true; retry those.

Here is an example Hono worker you can deploy as a backend for your static site. Hono is an npm package, so deploy it with beacon deploy, which installs and bundles it; the raw endpoint can't resolve import ... from 'hono', so with the raw API bundle it into one index.js first.

// index.ts (deploy with: beacon deploy)
import { Hono } from 'hono'

const app = new Hono()

app.get('/api/hello', (c) => {
  return c.json({ message: 'Hello from beacon.host!' })
})

app.post('/api/contact', async (c) => {
  const body = await c.req.json()
  return c.json({ ok: true })
})

export default app

Delete a worker

DELETE /v1/workers/:slug

Permanently deletes a worker, its deployments and secrets, and removes the script from Cloudflare's edge. This action cannot be undone. If the worker was ever deployed, its slug can't be used for a new worker for the next 15 minutes (slug_cooling_down). Open log sessions are closed, and its crons stop.

A worker an administrator suspended can't be deleted by its owner (403 worker_suspended), nor can any worker of an account an administrator suspended (403 account_suspended with "reason": "admin"). A paused worker, and a worker of an account suspended for review, can be deleted.

curl -X DELETE https://beacon.host/v1/workers/my-api \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "success": true,
  "deleted": "my-api",
  "operationId": "op_def456",
  "propagationNote": "The worker is deleted, but Cloudflare's edge can keep answering with the old script for a short while. ..."
}

Query parameters

ParameterDescription
deleteStorageRepeat once per storage binding the delete may destroy. A worker that has storage bindings must name every one of them, or the delete is refused with 409 storage_not_named, which lists each binding and what deleting it would do. Name a binding only when the user asked for its data to be deleted.
erasetrue skips the export kept of deleted storage.
purgeNowtrue deletes the storage at once instead of after its hold. Beacon's test and internal accounts only (403 purge_now_not_allowed). When the purge can't finish within the request, the worker is deleted all the same and its storage stays held: the answer is a retryable error with retryAfter (platform_busy, cf_budget_exhausted or data_rate_limited when Beacon held the purge's Cloudflare calls back, platform_unavailable when Cloudflare or R2 failed it) that also carries deleted, storage (each held binding with its purgeAfter) and propagationNote. Send the same request again after retryAfter to finish the purge; it answers the same way with alreadyDeleted: true, and 200 once the storage is gone (with no propagationNote: the answer that deleted the worker carried it). Left alone, the storage is purged when its hold ends.

A delete is not instant at the edge. Beacon replaces the deleted script with a stub that answers 404 Worker not found, which usually takes over within a minute or two; until then the old script can keep answering. Rotate any credentials a deleted worker had rather than relying on the delete to take it offline instantly.

Secrets

Secrets are environment variables encrypted at rest by Cloudflare. Secret values are never stored in Beacon's database — they go straight to Cloudflare. Beacon only tracks the secret name. Secrets stay set across redeploys and rollbacks.

Set a secret

PUT /v1/workers/:slug/secrets/:name

Sets or updates a secret. Secrets take effect immediately on the running worker (Cloudflare hot-reloads secrets without redeploying). They attach to the deployed script, so the worker must have been deployed at least once (409 worker_not_deployed before that); later deploys keep them. Right after a deploy, Cloudflare can take a few seconds to show the new script, and a secret set in that time gets 502 platform_unavailable (retryable, retryAfter 10). Send the same request again after retryAfter. beacon secret set does this itself, up to 3 times. A name one of the worker's bindings already uses gets 409 binding_name_conflict. Each account can set 60 secrets and delete 30 an hour. Secret changes to a suspended worker get 403 worker_suspended, and on a suspended account 403 account_suspended.

With the CLI, beacon deploy && beacon secret set SESSION_SECRET --generate sets a random 32-byte key (base64url) only if the secret does not exist yet, and never prints it. Until it is set, the first version runs without it, so make the app fail closed while the secret is missing.

Use POST on the same path with the same body to create only when absent. The response includes created: true when written or created: false when the existing value was preserved. Concurrent worker changes return 409; retry the request. PUT intentionally replaces the value. The CLI uses the create-only endpoint for --generate.

Request body

FieldTypeRequiredDescription
valuestringYesThe secret value
curl -X PUT https://beacon.host/v1/workers/my-api/secrets/DATABASE_URL \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"value": "postgres://user:pass@host/db"}'

Response 200 OK:

{
  "name": "DATABASE_URL",
  "createdAt": "2026-03-20T15:04:05Z"
}

Delete a secret

DELETE /v1/workers/:slug/secrets/:name
curl -X DELETE https://beacon.host/v1/workers/my-api/secrets/DATABASE_URL \
  -H "Authorization: Bearer your-api-key"

Response 204 No Content (empty body).

Right after a deploy, a delete can get the same retryable 502 platform_unavailable as a set (retryAfter 10), and the secret stays listed until a delete succeeds. Send the same request again after retryAfter. beacon secret del does this itself, up to 3 times.

List secrets

GET /v1/workers/:slug/secrets

Returns the names of all secrets set on the worker. Values are never returned.

curl https://beacon.host/v1/workers/my-api/secrets \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "data": [
    {"name": "API_KEY", "createdAt": "2026-03-19T12:00:00Z"},
    {"name": "DATABASE_URL", "createdAt": "2026-03-20T15:04:05Z"}
  ],
  "totalCount": 2,
  "limit": 20,
  "offset": 0
}

Deployment history

GET /v1/workers/:slug/deployments

Returns the deployment history for a worker, ordered by creation date (newest first).

curl https://beacon.host/v1/workers/my-api/deployments \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "data": [
    {
      "id": "dep_abc123",
      "version": 3,
      "entryPoint": "index.js",
      "sizeBytes": 1234,
      "deployedAt": "2026-03-20T15:10:00Z"
    },
    {
      "id": "dep_old789",
      "version": 2,
      "entryPoint": "index.js",
      "sizeBytes": 980,
      "deployedAt": "2026-03-19T12:00:00Z"
    }
  ],
  "totalCount": 2,
  "limit": 20,
  "offset": 0
}

Rollback

POST /v1/workers/:slug/rollback

Rolls back to a previous deployment. If no deploymentId is specified, rolls back to the immediately previous deployment. The previous script bundle is fetched from storage and re-deployed to Cloudflare's edge with that deployment's entry point, compatibility date and flags, and crons. Secrets and database contents stay as they are now. Saved plain-text vars are restored with the code; database migrations are not reversed. The response has the same fields as a deploy, with "status": "rolled_back" and rolledBackFrom; a rollback counts toward the hourly deploy limit.

Request body (optional)

FieldTypeRequiredDescription
deploymentIdstringNoSpecific deployment ID to roll back to. Defaults to previous deployment.
curl -X POST https://beacon.host/v1/workers/my-api/rollback \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"deploymentId": "dep_old789"}'

Response 200 OK:

{
  "slug": "my-api",
  "url": "https://my-api.worker.beacon.host",
  "deploymentId": "dep_rolled456",
  "version": 4,
  "sizeBytes": 1234,
  "fileCount": 2,
  "entryPoint": "index.js",
  "compatibilityDate": "2026-09-30",
  "deployedAt": "2026-03-20T16:00:00Z",
  "status": "rolled_back",
  "warnings": [],
  "operationId": "op_ghi789",
  "storage": {},
  "rolledBackFrom": "dep_old789",
  "resumed": false
}

Like a deploy, a rollback ends a pause for a daily D1 limit or by an administrator (resumed, lifted), and is refused for a suspended worker or account.

Resume a worker

POST /v1/workers/:slug/resume

Ends a pause without a deploy. It lifts the holds the owner may lift (a daily D1 limit, an administrator's pause) and the account's D1 hold of the same incident. When it ends a pause for a daily D1 limit, the account's D1 usage counts from that moment, so a fix gets the rest of the day's allowance. That happens once per pause. Resuming the account's other paused workers later doesn't restart the count, and ending an administrator's pause never does. beacon resume <slug> calls it. No body.

Agents: only when the user asks. A pause for a daily D1 limit usually means the worker ran away. Resuming it without a fix can cross the limit again, and a second pause within 30 days suspends the account for review. Deploy a fix instead, or ask the user.

curl -X POST https://beacon.host/v1/workers/notes/resume \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "slug": "notes",
  "resumed": true,
  "lifted": ["d1_rows_written"],
  "countedFrom": "2026-10-22T14:06:00Z",
  "state": {"status": "active", "reason": null, "since": null, "until": null, "canResume": false, "holds": []}
}

A worker with nothing to lift answers 200 with "resumed": false. countedFrom is when the account's D1 usage counts from now. Refusals: 403 worker_paused when the pause lifts on its own (reason metering_blind or d1_size), 403 plan_lapsed for a D1 worker after Beacon Plus ended, 403 worker_suspended, 403 account_suspended, 404 worker_not_found, and 429 rate_limited (30 resumes an hour per account).

Logs

GET /v1/workers/:slug/logs/tail

Returns a WebSocket URL that streams the worker's invocations as they happen: each request and cron run (and, for Durable Objects, each request and alarm), with its console.* output and any exceptions. beacon logs connects to it and prints one JSON object per line, or one readable line per invocation with --pretty, and reconnects when a session ends.

curl https://beacon.host/v1/workers/my-api/logs/tail \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "url": "wss://internal.worker.beacon.host/v1/tail/my-api?token=...",
  "expiresAt": "2026-10-05T15:11:00Z"
}

Connect before expiresAt (60 seconds). Every text frame is one JSON object: first {"type": "connected"}, then one per invocation:

{
  "type": "request",
  "timestamp": "2026-10-05T07:27:41.672Z",
  "outcome": "exception",
  "method": "GET",
  "path": "/throw?m=L4",
  "status": 500,
  "duration": "3ms",
  "logs": [{"level": "warn", "message": ["about to throw"], "timestamp": 1791185261672}],
  "exceptions": [{"name": "Error", "message": "boom", "stack": "    at Object.fetch (index.js:9:41)", "timestamp": 1791185261672}]
}

Workers run on Cloudflare's edge, not on the Beacon server. If Beacon goes down, your deployed workers continue running. Only the management API (deploy, delete, secrets) is affected.

Cron triggers

Declare crons in the deploy metadata ("crons": ["*/5 * * * *"]), or in .beacon/config.json for beacon deploy, and export a scheduled() handler. Each matching minute, the worker's handler runs with controller.cron (the expression as written) and controller.scheduledTime (the start of the matched minute, in milliseconds):

export default {
  async fetch(request, env) { return new Response("ok") },
  async scheduled(controller, env, ctx) {
    console.log("cron", controller.cron, new Date(controller.scheduledTime).toISOString())
  },
}
GET /v1/workers/:slug/crons

The current deployment's crons, the next runs (UTC) and the last runs, newest first. beacon crons prints the same.

{
  "slug": "my-api",
  "enabled": true,
  "crons": ["*/5 * * * *"],
  "nextRuns": [{"cron": "*/5 * * * *", "at": "2026-10-05T15:15:00Z"}],
  "runs": [{
    "cron": "*/5 * * * *", "scheduledTime": "2026-10-05T15:10:00Z", "status": 200,
    "outcome": "ok", "durationMs": 12, "deploymentId": "dep_abc123", "recordedAt": "2026-10-05T15:10:01Z"
  }]
}

enabled is false while cron triggers aren't switched on; runs is then empty. A run's error holds the exception message when it failed.

Capabilities

GET /v1/capabilities

What this server supports, with no auth needed. Clients read it before relying on a feature; the beacon CLI does.

With a Free account's key:

{
  "metadataVersion": 2,
  "storage": {"d1": false, "durableObjects": false},
  "logs": true,
  "crons": true,
  "billing": true,
  "account": {
    "plan": "free",
    "planName": "Free",
    "storageIncluded": false,
    "allowlisted": false,
    "storageAllowed": false,
    "state": {"status": "active", "reason": null, "until": null, "pausedWorkers": [], "strikes30d": 0},
    "upgrade": {"plan": "plus", "name": "Beacon Plus", "priceUsdMonthly": 4, "firstMonthPriceUsd": 1, "url": "https://beacon.host/pricing", "checkout": "https://beacon.host/dashboard?view=plan"}
  }
}

Agents: if storage.d1 is false, tell the user D1 needs Beacon Plus; only they can subscribe (beacon upgrade prints a link). Never open or pay a checkout yourself, and never run beacon resume on your own: a second pause suspends the account.

Worker storage and plain-text variables

D1 databases come with Beacon Plus, $4 a month (your first month is $1), and are created by a worker deploy. Send your Bearer key to GET /v1/capabilities and check storage.d1 before creating one. Existing D1 bindings remain usable when new database creation is disabled. Durable Object provisioning is not available in this build. Legacy KV bindings can be preserved, but new KV namespaces cannot be declared.

The CLI reads D1 declarations and plain-text variables from .beacon/config.json:

{
  "type": "worker",
  "slug": "my-api",
  "d1": {"DB": {"migrations": "migrations"}},
  "vars": {"MODE": "production"}
}

beacon deploy creates env.DB, applies pending NNNN_name.sql files, and deploys the worker. A single D1 binding defaults to the migrations/ folder. With several bindings, each must name a separate folder. Optional location is a placement hint; jurisdiction: "eu" constrains the database to the EU. renamedFrom changes a binding name without copying or deleting its data. For a few seconds after a deploy that renames or detaches a binding returns, some requests can still see the old binding in env while Cloudflare's edge switches to the new version; code that no longer reads the old name is unaffected.

For the REST deploy, put storage: {"d1": {"DB": {}}} and vars in the metadata JSON. Send each migration as a separate multipart field named DB/0001_init.sql, with the file's SQL as its body. Send the binding's complete migration history on every deploy. Files already applied are only checksummed: the SQL not yet applied is at most 1 MB per deploy (migrations_too_large; send a long backlog over several deploys), the whole request at most 5 MB (deploy_too_large), with at most 10,000 migration files. Migrations must be UTF-8 text (migration_not_utf8). A part that is neither metadata, file nor <BINDING>/<NNNN_name>.sql is refused with 422 migration_bad_name. Beacon assigns Cloudflare IDs; do not supply them. Omitting storage preserves bindings. An explicit storage declaration is the desired set; removing a binding requires a matching confirm.detach or confirm.deleteStorage choice. Confirmations name bindings, never files: a destructive migration of DB runs with "confirm": {"destructiveMigrations": ["DB"]} (deploy metadata, or the body of POST .../d1/DB/migrations), and a file undone by a restore runs again with "confirm": {"reapplyMigrations": {"DB": ["0002_x.sql"]}}. Send either only once the user has agreed.

Plain-text vars are string values of up to 5 KB, stored with the deployment and restored by a code rollback. Their names must not conflict with bindings or secrets. Vars come with Beacon Plus too (403 vars_not_enabled without it). Use beacon secret set for credentials.

Migrations take a Time Travel bookmark before changing data. The deploy response describes each binding in storage and includes undo when data changed. status: "migrated" means migrations ran while the code and its settings were unchanged. status: "unchanged" means neither code nor migrations changed. A binding whose status is created got a new database with this deploy: a deploy refused after it created the database (platform_busy, a failed upload) keeps that database, and the next deploy binds it and reports created. A code rollback restores code and vars; it does not reverse database migrations. If code upload fails after migrations succeeded, the error includes the applied migrations and undo command. So does a deploy whose migrations fail on one database after another database's ran: the failing database is as it was, the others' migrations stay applied, the worker keeps its code, and the next deploy skips them. The failed operation records the same migrationsApplied and undo in its result (GET /v1/workers/:slug/operations/:id). Review that result before retrying or restoring.

Method Path Body or query Result
GET /v1/workers/:slug/storage None storage entries with binding, state, size, jurisdiction, migration and hold details; quota use
POST /v1/workers/:slug/storage/plan Deploy multipart body, or {"rollback":{"deploymentId":"..."}} Read-only plan with dryRun, ok, storage, warnings, and errors; refusals return 200 with ok: false
DELETE /v1/workers/:slug/storage/:binding ?confirm=DB; optional erase=true, purgeNow=true Hold a detached database for deletion; bound databases return storage_attached. A note says Beacon is still recording the destroy in its storage ledger; the destroy is committed either way
POST /v1/workers/:slug/storage/:binding/restore No body Cancel the hold and return the database to detached; the next deploy can reattach it
GET /v1/workers/:slug/operations ?limit=20 (1–100) Newest operations first, including kind, status, phase and redacted error
GET /v1/workers/:slug/operations/:id None One operation, including its redacted input and result
GET /v1/workers/:slug/d1/:binding/migrations None Migration ledger, checksums, applied and reverted states
POST /v1/workers/:slug/d1/:binding/migrations {"files":[{"name":"0001_init.sql","sql":"CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT);"}]}, plus "confirm": {"destructiveMigrations": ["DB"]} or {"reapplyMigrations": {"DB": ["0002_x.sql"]}} when the user agreed Apply pending files without deploying code. Send the binding's whole history: files already applied are only checksummed, and the rest is at most 1 MB of SQL per request. Returns migrationsApplied, operationId, and undo when changed. Counts toward the 60 deploys an hour when it sends migrations, unless D1 refused them or answered that none ran. A confirm that names anything but the binding is 400 confirm_mismatch
POST /v1/workers/:slug/d1/:binding/migrations/resolve Exactly one of {"markApplied":"0001_init.sql"} or {"markReverted":"0001_init.sql"} Settle a diverged migration ledger without running the migration SQL. markApplied records the database's version of the file when its d1_migrations row carries a checksum, and refuses a file Beacon has no record of (migration_unknown). markReverted also takes a name no migration file can have when d1_migrations or the ledger holds it
POST /v1/workers/:slug/d1/:binding/query {"sql":"SELECT * FROM notes WHERE id = ?1","params":[1]} or {"batch":[{"sql":"SELECT 1"}]} results and truncated; ?format=raw preserves column order and ?allowDdl=true permits DDL
GET /v1/workers/:slug/d1/:binding/schema None User schema entries and combined sql; internal tables are hidden
GET /v1/workers/:slug/d1/:binding/tables None User tables and views, with virtual tables marked
GET /v1/workers/:slug/d1/:binding/bookmarks None Bookmarks taken before migration operations, newest first
POST /v1/workers/:slug/d1/:binding/restore ?confirm=DB and exactly one of {"beforeOp":"..."}, {"beforeDeploy":"..."}, or {"to":"RFC3339 time or bookmark"} Rewrite the database in place; returns previousBookmark, undo, lostWritesSince, warnings, and migration reconciliation results
POST /v1/workers/:slug/d1/:binding/export Optional noData, noSchema, tables; poll with returned currentBookmark 202 with retryAfter while running, then 200 with signedUrl and expiresAt

All these endpoints require the owning account's Bearer key. Bindings are named like DB, never by a Cloudflare ID. The public config schema is GET /schema/beacon-config.json.

Rows read and written through query and migrations count toward the account's daily D1 limits as they happen. While the account is paused for a daily D1 limit, every query and standalone migration on any of its databases gets 403 worker_paused (with reason) until one of its storage workers is resumed or redeployed, or until 00:00 UTC if none is. After that, the databases of each worker still paused stay refused until that worker is resumed or redeployed, even past 00:00 UTC. After Beacon Plus ends, writes, migrations and restores get 403 plan_lapsed on every database the account holds, bound or not; reads keep working. From the D1 size limit on, writes other than DELETE and DROP, migrations and new databases get 409 storage_quota_exceeded. Exports work in every case.

Queries accept at most 100 batch entries, 100 parameters per entry and 1,000 statements, with 1 MB of SQL per request. Parameters are strings, numbers, booleans or null; a number binds as a REAL and a boolean as the number 1 or 0, which compares equal to the 1 a Worker's bind(true) binds. Every query counts against the data-plane rate limit, including one the guard refuses, but not one refused with platform_busy, cf_budget_exhausted or data_rate_limited, which never ran; a refusal lists at most 20 errors and counts the rest in errorsOmitted. Answers stop at 10,000 rows or 5 MB and set truncated. D1's own answer is read up to 10 MB and can't be cut past that: a bigger result is refused with d1_result_too_large, whose applied says whether the query's writes landed: true when it had a statement that can write and D1 ran it to the end, so don't run it again (it doesn't mean a row changed). Transaction control and ROLLBACK conflict resolutions (OR ROLLBACK, ON CONFLICT ROLLBACK, RAISE(ROLLBACK)) are refused (migration_has_transaction): D1 answers a ROLLBACK that fires with an internal error, as if it were down, so use ABORT, which undoes the same request and names the constraint. So are writes to internal tables: d1_migrations, sqlite_sequence, SQLite's schema table (sqlite_master, sqlite_schema) and _cf_ tables (d1_internal_table). Read and export commands work on detached databases too. An export blocks other database requests while it runs. Start at most one export per database per hour and ten per account per day; polling does not consume another export, and neither does sending the same body again: it polls the running export, or, while the hour is taken, returns the finished one again (reused, exportedAt, warning d1_export_reused). An export that D1 reports failed, or that Cloudflare refuses before it starts, doesn't count. One export request per database runs at a time: another sent meanwhile gets 429 data_rate_limited with retryAfter 5, and the same body sent after it polls the export. A start Cloudflare doesn't confirm (no answer, or no bookmark to poll) counts and can't be polled: it gets 502 platform_unavailable with "pollable": false and a retryAfter that runs to the end of the database's hour, and the same body sent sooner gets 429 data_rate_limited. A poll Cloudflare doesn't answer properly gets 502 platform_unavailable with retryAfter 5; the export keeps its charge, and the same body polls it again. A poll Cloudflare refuses outright gets 422 d1_query_failed with "pollable": false and a retryAfter that runs to the end of the database's hour: the export counts and can't be picked up, and the same body sent sooner gets 429 data_rate_limited. The download link expires after an hour. D1 can't export a database with virtual tables (FTS5) whole, nor a virtual table by name. Exported without tables, such a database gives its regular tables, and the answer adds virtualTables and appendSql: SQL to add at the end of the dump that creates the virtual tables, views, indexes and triggers and rebuilds each external-content FTS5 table from its content table (beacon d1 export appends it). Other virtual tables (a contentful or contentless FTS5 table) come back empty (warning d1_export_virtual_tables). A database with a virtual table whose CREATE statement Beacon can't read is refused with 422 d1_query_failed, which doesn't count toward the export limits: export its regular tables by name (tables, --table).

Deleting a D1 binding normally holds it for seven days. beacon storage restore DB cancels the hold until purge starts, including after recreating the worker under the same slug and account. At purge, eligible databases receive a final export retained for 30 days; a database with virtual tables gets the dump beacon d1 export gives, its regular tables and then the SQL that creates the rest. EU-jurisdiction databases and deletes with erase=true receive no final export. Export an EU database yourself before deleting it if you need a copy. An operator can also skip a final export, and an already missing database cannot be exported. If a required export fails, the database stays held. purgeNow=true skips the hold and is restricted to Beacon's test and internal accounts.

Data deletion, destructive migration confirmations, ledger resolution, and Time Travel restores require the user's explicit intent. The CLI equivalents are beacon storage, beacon storage plan, beacon storage ops, and beacon d1 commands. A Time Travel restore can return an error after Cloudflare changed the database; keep any operationId, previousBookmark, and undo in that response and inspect the operation before retrying.

A restore loses the writes made since lostWritesSince. For a restore to a time it is never after the time, and often earlier: Cloudflare resolves a time to the last batch of writes it closed by then, which can be a minute or more before it. After an undo, or a restore that took the database back past the point, it goes back to where the two histories parted, so it counts writes the undo brought back. Soon after a restore, Cloudflare places a time in the history that restore replaced; Beacon restores the latest point of the history the database had then that it recorded instead (warning replaced_history), or refuses (restore_time_ambiguous). A bookmark names a point of one database: another database's, or a made-up one, is restore_target_not_found and changes nothing. A restore past migrations the live code uses breaks that code: roll the code back to a deployment from before them first, then restore. A restore that undoes migrations the live deployment was deployed with warns code_ahead_of_schema.

undo, detail, hint and fix.run name beacon commands. Over REST, each is one request (:slug is the worker, DB the binding); fix.run stays safe as it is, and the rest wait for the user:

Command in an answerREST request
beacon deployPOST /v1/workers/:slug/deploy with the deploy's multipart body
beacon deploy --dry-run, beacon storage planPOST /v1/workers/:slug/storage/plan with the same body. While no worker has the slug (before its first deploy), the endpoint answers 404 worker_not_found, which beacon storage plan reports as worker_not_deployed; beacon deploy --dry-run then sends nothing and previews the declared databases and their migration files locally
--detach DB, --delete-storage DB, --new-storage DBmetadata "confirm": {"detach": ["DB"]}, {"deleteStorage": ["DB"]}, {"newStorage": ["DB"]}
--allow-destructive-migration DB"confirm": {"destructiveMigrations": ["DB"]} in the deploy metadata or the migrations body
--reapply-migration DB/0002_x.sql"confirm": {"reapplyMigrations": {"DB": ["0002_x.sql"]}}
--skip-binding-checkmetadata "skipBindingCheck": true
beacon storageGET /v1/workers/:slug/storage
beacon storage opsGET /v1/workers/:slug/operations
beacon storage restore DBPOST /v1/workers/:slug/storage/DB/restore
beacon storage destroy DBDELETE /v1/workers/:slug/storage/DB?confirm=DB
beacon d1 export DBPOST /v1/workers/:slug/d1/DB/export
beacon d1 migrations list DBGET /v1/workers/:slug/d1/DB/migrations
beacon d1 migrations resolve DB --mark-applied FPOST /v1/workers/:slug/d1/DB/migrations/resolve {"markApplied": "F"} (or markReverted)
beacon d1 bookmarks DBGET /v1/workers/:slug/d1/DB/bookmarks
beacon d1 restore DB --before-op OP --yesPOST /v1/workers/:slug/d1/DB/restore?confirm=DB {"beforeOp": "OP"}
beacon d1 restore DB --to BOOKMARK --yesPOST /v1/workers/:slug/d1/DB/restore?confirm=DB {"to": "BOOKMARK"}
beacon secret ls, beacon secret set NAMEGET /v1/workers/:slug/secrets, PUT /v1/workers/:slug/secrets/NAME {"value": "..."}
beacon listGET /v1/workers
beacon loginPOST /v1/auth/send-otp, then POST /v1/auth/verify-otp

Runtime notes

Plans and daily limits

Publishing sites and running workers is free. Beacon Plus is $4 a month (your first month is $1), billed monthly through Stripe. The $1 first month is for accounts that never had Beacon Plus. Cancel any time from beacon billing or the dashboard. Plus adds managed D1 databases: 5 per account and 3 per worker, 2 GiB of D1 data in total, migrations up to 1 MiB per deploy. Plain-text vars come with it too. Prices and the plan comparison are on the pricing page.

FreeBeacon Plus
Price$0$4 a month (your first month is $1)
D1 databases and plain-text varsNoYes
File storage, all sites togetherUp to 10 GBUp to 500 GB
Workers2525
New workers per 30 days30100
Worker requests per UTC day20,000100,000
D1 rows read per UTC dayNo D125,000,000
D1 rows written per UTC dayNo D150,000
D1 databasesNo D15 per account, 3 per worker
D1 data, all databases togetherNo D12 GiB
Migration SQL per deployNo D11 MiB
D1 queries through the APINo D112 a minute, bursts of 10
D1 restores per hourNo D16
CPU per request1,000 ms1,000 ms
Subrequests per request50200
Deploys, deploy requests, secret sets, secret deletes per hour60, 300, 60, 3060, 300, 60, 30
Worker creates, worker deletes per hour10, 1010, 10
Storage plans per hour120120
Cloudflare calls per 5 minutes6060

"No D1" means Free can't create D1 databases. Databases a Free account still holds, such as those kept when its Beacon Plus ended, are read-only and stay under Free's D1 limits: reads through the API count against 25,000,000 rows per UTC day, at most 12 queries a minute (bursts of 10), and the data against 2 GiB. Going over the daily read limit pauses the account's D1 queries through the API (exports keep working) and counts a strike, like any daily D1 limit (Pauses and suspensions).

A request can use up to 1,000 ms of CPU. Beacon measures requests over 50 ms; 50 ms will become the limit on Free and Plus together, announced in advance. 50 subrequests on Free and 200 on Plus. D1 queries are not subrequests. A request over its CPU or subrequest limit fails with 503. It is not a strike.

Daily limits count from 00:00 UTC. Past the daily request limit, workers answer 429 daily_request_limit_reached until 00:00 UTC. It is a quota, not a strike, and the API keeps working. GET /v1/limits returns these numbers for both plans (plans) and, with your key, your account's own (effective); GET /v1/usage shows today's usage against them.

Pauses and suspensions

Beacon checks D1 usage every minute and request counts every 15 seconds, and counts D1 queries made through the API as they happen. A storage worker whose account goes over a D1 cap is paused: its URL answers 503, and D1 queries and migrations through the API wait, until you deploy again or run beacon resume <slug>; the rest of the day's allowance counts from then. Exports keep working. Two such pauses within 30 days suspend the account for review.

A pause for a daily D1 limit, for D1 size, for unmeasured D1 usage or for an ended plan covers every worker of the account that has a D1 binding; workers without D1 keep serving. An administrator's pause covers one worker. Each worker's state (GET /v1/workers/:slug) and the account's (GET /v1/capabilities, GET /v1/usage) name the reason:

ReasonWhenThe worker's URL answersEnds
d1_rows_read, d1_rows_writtenThe account went over a daily D1 limit. One strike.503 worker_pausedA worker it paused serves again after a deploy or rollback, a resume, or an administrator, but not at 00:00 UTC, and D1 queries and migrations on its databases wait until then. Workers bound since the pause, and the API on the account's other databases, wait only until the first of these on any storage worker, or until 00:00 UTC.
admin_pauseAn administrator paused the worker.503 worker_pausedA deploy or rollback, a resume, or an administrator.
metering_blindBeacon couldn't measure D1 usage for 30 minutes, and the account's recent D1 use was heavy.503 worker_pausedOn its own, when measuring recovers.
d1_sizeThe account's D1 data reached twice its size limit.503 worker_pausedOn its own, once the data is under twice the limit.
plan_lapsedBeacon Plus ended.503 worker_pausedSubscribing again, or a deploy without the D1 binding.
request_capThe account's workers reached the daily request limit. Every worker of the account, not a strike.429 daily_request_limit_reachedAt 00:00 UTC, or when the limit rises above today's count.
admin_suspendAn administrator suspended the worker, or the account and with it every worker.503 worker_suspendedAn administrator.
reviewA second pause for a daily D1 limit within 30 days. Every worker of the account.503 worker_suspendedAn administrator; write to support@beacon.host.
disabledAn administrator disabled the account. Every worker of the account, and its keys get 401 account_disabled.503 worker_suspendedAn administrator enables the account; write to support@beacon.host.

A pause for a daily D1 limit is the only strike. Request limits, CPU and subrequest failures, an administrator's pause, a size pause, a pause while Beacon can't measure D1 usage and an ended plan never are. After a deploy or a resume ends a pause for a daily D1 limit, the account's D1 usage counts again from that moment (countedFrom), once per pause, so a fix gets the rest of the day. While the account is suspended, changes get 403 account_suspended (reason admin or review), and changes to a suspended worker get 403 worker_suspended. A suspension refuses no reads or exports. Under review, deleting a worker is still allowed. Destroying a database and deleting a secret get 403 account_suspended, and a D1 query that deletes rows is refused like any D1 write. A pause for a daily D1 limit still refuses D1 queries, reads included, with 403 worker_paused. Under review the owner can't deploy or resume to end that pause, so read the data with beacon d1 export meanwhile.

D1 size. At 80% of the D1 size limit deploys warn (storage_size_warning, also in GET /v1/usage). At 100% new databases, migrations and API writes other than deletes are refused (409 storage_quota_exceeded). At twice the limit the account's storage workers pause until the data shrinks. Bindings are never removed.

When Plus ends. The account returns to Free. Its storage workers are paused; the data is kept and becomes read-only, and reads and exports through the API keep working. Subscribing again resumes them. D1 data is never deleted automatically; sites over Free's file storage limit can be. Writes, migrations and restores get 403 plan_lapsed meanwhile. Subscribing again ends no other pause. A worker also paused for a daily D1 limit stays paused, and D1 queries and migrations on its databases keep getting 403 worker_paused, until you deploy it again or run beacon resume <slug>. The worker's state.holds (GET /v1/workers/:slug) lists those pauses before and after subscribing.

Agents: if storage.d1 is false, tell the user D1 needs Beacon Plus; only they can subscribe (beacon upgrade prints a link). Never open or pay a checkout yourself, and never run beacon resume on your own: a second pause suspends the account.

Today's usage

GET /v1/usage adds today's usage against each daily limit, the holds on the account's workers, its state and its strikes in the last 30 days. cap is a number or "unlimited"; percent is the floor of 100 × used / cap.

{
  "account": {"createdAt": "2026-09-01T10:00:00Z", "plan": "plus", "planName": "Beacon Plus"},
  "today": {
    "day": "2026-10-22", "resetsAt": "2026-10-23T00:00:00Z", "d1WindowStart": "2026-10-22T14:06:00Z",
    "metrics": [
      {"metric": "d1_rows_read", "used": 1200, "cap": 25000000, "percent": 0},
      {"metric": "d1_rows_written", "used": 412, "cap": 50000, "percent": 0},
      {"metric": "worker_requests", "used": 5310, "cap": 100000, "percent": 5},
      {"metric": "d1_size_bytes", "used": 1048576, "cap": 2147483648, "percent": 0}
    ]
  },
  "holds": [],
  "state": {"status": "active", "reason": null, "until": null, "pausedWorkers": [], "strikes30d": 0},
  "strikes30d": 0,
  "billing": {"status": "active", "currentPeriodEnd": "2026-11-22T12:00:00Z", "cancelAtPeriodEnd": false}
}

The rest of the answer (sites, workers, storage) is as before; storage.warnings can hold storage_size_warning. files is the account's file storage: {"used": 312345, "limit": 10737418240}, in bytes, with limit null for an account without one. d1WindowStart is when today's D1 usage started counting: 00:00 UTC, or the end of today's pause. A worker's own D1 queries reach Beacon's count a few minutes late, so a busy worker can go past a limit before it pauses; queries through the API count at once.

Billing API

Beacon Plus is bought and managed through Stripe. Only the account's owner subscribes: beacon upgrade prints a checkout link, and beacon billing a link to Stripe's billing portal (card, invoices, cancel). The links never appear in an error's fix.run; hints carry them as text. Every endpoint answers 503 billing_unavailable on a server that doesn't sell Plus (GET /v1/capabilities says "billing": false).

Start a checkout

POST /v1/billing/checkout

Returns the account's Stripe Checkout link for Beacon Plus and when it stops working (expiresAt). The body is optional: {"promotionCode": "CODE"} applies one of Beacon's Stripe promotion codes, which must be active, and Stripe enforces its own restrictions. Without a code, an account that never had a Beacon Plus subscription gets its first month for $1, then pays $4 a month; any other account can enter a promotion code on Stripe's page. Calling it again returns the same link while it has more than 10 minutes left and carries the same discount. Otherwise Beacon expires the old link and returns a new one, so an account has one open checkout at a time. Open the link in a browser; the payment page is Stripe's.

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "sessionId": "cs_test_...",
  "expiresAt": "2026-10-22T13:00:00Z"
}

Refusals, in this order: 503 billing_unavailable, 403 account_suspended, 409 plan_not_billable (a plan Beacon manages), 409 already_subscribed, 429 rate_limited (10 an hour per account), 400 promotion_code_invalid, 502 billing_provider_unavailable. A body that isn't JSON gets 400.

Open the billing portal

POST /v1/billing/portal

Returns a link to Stripe's billing portal for the account: change the card, see invoices, cancel. No body. It works while the account is suspended or disabled, so a subscription can always be canceled.

{"url": "https://billing.stripe.com/p/session/test_..."}

Refusals: 404 no_billing_account (the account never subscribed), 429 rate_limited (20 an hour), 502 billing_provider_unavailable, 503 billing_unavailable.

Billing status

GET /v1/billing
POST /v1/billing/sync

GET reads the account's plan and subscription as Beacon has them. POST /v1/billing/sync first asks Stripe (at most once every 5 seconds per account) and answers the same way, so a client that just paid can poll it until the plan is plus; beacon upgrade --wait does. Sync allows 360 calls an hour (429 rate_limited).

{
  "plan": "plus",
  "planName": "Beacon Plus",
  "planSource": "billing",
  "priceUsdMonthly": 4,
  "introOffer": {"eligible": false, "firstMonthPriceUsd": 1},
  "checkoutAvailable": false,
  "portalAvailable": true,
  "subscription": {"id": "sub_...", "status": "active", "currentPeriodEnd": "2026-11-22T12:00:00Z", "cancelAtPeriodEnd": false}
}

planSource is billing for a plan bought through Stripe, admin for one Beacon set, and null on Free. checkoutAvailable says whether POST /v1/billing/checkout would start a checkout now. introOffer.eligible is true while the account never had a Beacon Plus subscription, so its first month would cost introOffer.firstMonthPriceUsd dollars. subscription is null for an account that never subscribed. A subscription whose payment is past_due keeps Plus while Stripe retries the card.

Stripe's endpoints

Two more routes are Stripe's, not a client's. POST /v1/billing/webhook receives Stripe's events, signed with Stripe-Signature: 200 {"received": true}, 400 {"error": "invalid signature"}, or 500 {"error": "retry"}, which Stripe retries. GET /billing/return?session_id= is where Stripe Checkout sends the browser after a payment: it confirms the session with Stripe and redirects to the dashboard's Plan view (?billing=success, or ?billing=pending while the payment settles). Neither needs an API key.

Serving

Once a site is finalized, it is served at https://<slug>.beacon.host. Files are stored on Cloudflare R2 and served over HTTPS by beacon.host. Workers are different: they run on Cloudflare's edge network. Sites are read-only: GET and HEAD serve files, OPTIONS answers CORS preflights, and any other method returns 405. Every response carries Access-Control-Allow-Origin: *, so other sites can fetch() your files (JSON, fonts, images). Credentials are never allowed cross-origin, so a password-protected site stays unreadable from other origins.

URL resolution

When a request arrives, beacon.host resolves the file to serve using this chain (in order):

  1. Exact match — /style.css serves the file at path style.css
  2. Trailing slash redirect — /blog redirects (302) to /blog/ if files exist under that prefix
  3. Directory index — /blog/ serves blog/index.html if it exists
  4. SPA fallback — only for sites that ship a shell page (see Single-page apps)
  5. Single-file auto-viewer — If the site has exactly one file, serves an HTML wrapper with appropriate viewer (image, video, PDF, or download link)
  6. Directory listing — If the path is a directory with files, renders an HTML file listing
  7. 404 — the site's own 404.html (served with status 404) if it has one, otherwise the beacon.host 404 page

There is no automatic fallback to index.html. A single-page app that only ships index.html returns 404 on deep links and reloads until it opts in to the SPA fallback.

Single-page apps

Ship a shell page at the root of the site and every path that has no file of its own is answered with it (status 200), so deep links and reloads such as /projects/42, /u/jane.doe or /invite/<token> reach your client-side router. Either file opts in; _shell.html wins if both exist:

How the fallback decides:

TanStack Start: the default build renders on a server, which beacon.host doesn't run. Turn on SPA mode in vite.config.ts and deploy the client output in dist/client, which contains _shell.html. Routes you prerender (prerender: { enabled: true }) are served as real HTML files and the shell handles the rest.

tanstackStart({ spa: { enabled: true } })

Custom 404 page

Put a 404.html at the root of the site to replace the beacon.host 404 page. It is served with status 404 for any path that resolves to nothing.

Cache headers

Content typeCache-Control
HTML files (.html, .htm)public, max-age=60, must-revalidate
Files named with the first 8+ hex characters of their own SHA-256 (e.g. app.<sha256[:8]>.js)public, max-age=31536000, immutable
Everything else, including other bundler hashes such as Vite'spublic, max-age=3600
Password-protected sitesprivate, no-store

Conditional requests

Every file response includes an ETag header derived from the file's SHA-256 hash. Clients can use If-None-Match to receive 304 Not Modified responses for unchanged files.

Range requests

All file responses include Accept-Ranges: bytes. Clients can use the Range header to request partial content, which is useful for streaming large media files. A single byte range (bytes=0-1023, bytes=1024-, bytes=-500) returns 206. A range that starts past the end of the file returns 416 with Content-Range: bytes */<size>. Multi-range requests, other units and malformed headers are ignored and the whole file is returned with 200. If-Range is honoured with the file's ETag.

Rate Limits

Rate limits are applied per endpoint category. When a limit is exceeded, the API returns 429 Too Many Requests; Workers API limits answer with "code": "rate_limited". GET /v1/limits returns the numbers the server enforces, for your account's plan when you send your key.

ActionLimitScope
Publish (anonymous)5 per hourPer IP address
Publish (authenticated)60 per hourPer API key
Upload refresh10 per hourPer site
Worker deploy (counted when it sends code or migrations to Cloudflare; rollbacks and migration applies too)60 per hourPer account
Worker deploy and rollback requests300 per hourPer account
New workers / worker deletes (counted only when a worker is created or deleted, not for a refusal or a 404)10 per hour each (100 on internal accounts)Per account
Secret sets / secret deletes60 / 30 per hourPer account
Log sessions30 per hourPer account
Worker analytics (counted when Beacon queries Cloudflare; answers from its 60-second cache are not)60 per hourPer account
Cloudflare calls made for your workers (deploys, secrets, deletes, analytics)60 per 5 minutesPer account (cf_budget_exhausted)
Worker resumes30 per hourPer account
Checkouts / billing portal links / billing syncs10 / 20 / 360 per hourPer account

An account can have 25 workers, and can add 30 new workers in any 30 days on Free and 100 on Beacon Plus (new_workers_limit_reached). Daily limits on worker requests and D1 usage are in Plans and daily limits.

File and size limits

LimitAnonymousAuthenticated
Max file size250 MB5 GB
Max files per version10,000
Max total size per version10 GB

File storage. The files of an account's live sites together can take up to 10 GB on Free and up to 500 GB on Beacon Plus. Each site counts the version it serves, so a file two sites share counts twice; pending and older versions and expired sites don't count, and deleting a site frees its space at once. A publish that would take the account over its limit is refused with 409 file_storage_full: when the site or version is created, before anything is uploaded, and again at finalize and rollback. Claiming an anonymous site adds its files and is refused the same way. An account already over its limit can still publish changes that don't grow its total. Anonymous sites don't count until claimed; they have their own limits and last 24 hours. GET /v1/usage shows the account's files (used and limit, in bytes; limit is null for an account without one), and GET /v1/limits each plan's storage.fileBytes.

If Beacon Plus ends while an account stores more than Free's 10 GB, Beacon emails the owner and, after 30 days, deletes the largest sites until the account is within 10 GB.

Presigned URLs expire after 1 hour. If your uploads take longer, use the refresh uploads endpoint to get new URLs.

Content policy

beacon.host hosts websites and the files they link to. Publishing refuses native programs (Windows PE, Linux ELF and macOS Mach-O executables) under any file name, uploaded as they are or inside a .zip or .tar (.tar.gz), and archives that hold a script which downloads and runs a program (a malware dropper). The answer is 422 content_blocked, from finalize and from every other way of publishing, and nothing goes live. App packages (.apk, .aab, .ipa, .jar), including the native libraries inside them, game packs (.mcpack, .mcaddon), Office documents, WebAssembly and ordinary JavaScript publish as usual; a Windows program (.exe, .scr, .msi, ...) is refused even inside an app package. File names with a program or script extension (.exe, .msi, .bat, .ps1, .hta, .vbs, .jar, ...) are refused by name when the site or version is created (400).

The terms of use forbid phishing, malware and spam, and live sites found serving malware are taken down. Report a site to abuse@beacon.host.

Errors

Errors are JSON objects with an error field, usually with a hint that says what to do and a docs link:

{
  "error": "slug is already taken"
}

Workers API errors also carry a stable code, listed under Error codes, and say whether retrying can help:

{
  "error": "the slug \"my-api\" belonged to a worker deleted in the last 15 minutes",
  "code": "slug_cooling_down",
  "hint": "wait and try again, or choose another slug",
  "retryable": true,
  "retryAfter": 600,
  "docs": "https://beacon.host/docs#error-slug_cooling_down"
}
FieldMeaning
errorOne sentence saying what went wrong.
codeStable snake_case name of the error. Branch on it, not on error.
hintWhat to do about it.
fixrun: commands that are safe to run as they are, such as beacon deploy or beacon secret ls. A command that deletes data is never in it. config: an RFC 7396 merge patch for .beacon/config.json.
detailCloudflare's message, when there is one, with resource IDs removed.
retryabletrue only when the same request can succeed later. Otherwise change something first.
retryAfterSeconds to wait before retrying; the Retry-After header says the same.
docsThis page's entry for the code, or Cloudflare's documentation for a script Cloudflare rejected.
errorsEvery refusal, when a request has several.

One Workers refusal has no code: a missing or invalid API key gets 401 with only {"error": "unauthorized"}, and the CLI exits with code 2 on it. A disabled account's key gets the coded 401 account_disabled. Most coded errors also carry a hint.

Some refusals add fields of their own, named in their entries below. The beacon CLI prints the server's error fields unchanged, and reports problems it finds itself (a bad config or flag, before any request) in the same shape.

Common status codes

StatusMeaning
200Success
400Bad request — invalid input, missing required fields, invalid hash format
401Unauthorized — missing or invalid Bearer token / claim token, or a disabled account
403Forbidden — the account's plan doesn't include this, or the worker or account is paused or suspended
404Not found — site, worker or version does not exist, or isn't yours
409Conflict — slug taken or cooling down, version not pending, another change to the same worker in progress, or the account's file storage is full (file_storage_full)
413Payload too large — file or total site size exceeds limit
422Unprocessable — entry point file not found in uploaded worker bundle, Cloudflare rejected the worker script, or a published file is a program or holds a malware dropper (content_blocked); not retryable
429Too many requests — rate limit exceeded
500Internal server error
501Not implemented — live logs aren't switched on for this server yet
502Bad gateway — Cloudflare or Stripe unavailable (worker deployment failed, retry)
503Service unavailable — Beacon paused its Cloudflare calls for a moment (retry after retryAfter), or workers or billing aren't configured on this server

Common error messages

ErrorCause
"files are required"Empty file manifest
"too many files (max 10000)"Manifest exceeds file count limit
"slug is already taken"Custom slug conflicts with an existing site
"file "x" must have hash in sha256:<hex> format"Missing or malformed hash
"version is not pending"Trying to finalize or refresh an already-finalized version
"file "x": not uploaded"Finalize called before all files were uploaded
"file "x": hash mismatch"Uploaded file content does not match declared hash
"Cloudflare rejected the script: ..."The worker script failed Cloudflare's validation (syntax error, missing module, a throw at startup); see detail
"rate limit exceeded"Too many requests in the time window

Error codes

Every code the API and the beacon CLI return, with its HTTP status. Retry the request unchanged only where an entry says retryable; the response then has "retryable": true and a retryAfter.

account_disabled401
An administrator disabled the account, so its API keys are refused on every request, except POST /v1/billing/portal, which still opens so a subscription can be canceled. Logging in again doesn't help; write to support@beacon.host. The CLI exits with code 2, as for any failed login.
account_suspended403
The account is suspended, so its changes are refused: deploys and rollbacks, secrets, new workers, storage changes, D1 writes, migrations and restores, resumes and checkouts. reason says why. admin: an administrator suspended it, and deleting a worker is refused too. review: a second pause for a daily D1 limit within 30 days suspended it for review (Pauses and suspensions); deleting a worker is still allowed. The suspension itself refuses no reads or exports. A pause for a daily D1 limit still refuses D1 queries, reads included, with 403 worker_paused, and under review the owner can't deploy or resume to end it. The account's workers answer 503 worker_suspended. Only an administrator lifts a suspension: write to support@beacon.host.
already_subscribed409
The account already has Beacon Plus, so there is nothing to check out. beacon billing (POST /v1/billing/portal) opens the billing portal to manage the subscription.
billing_provider_unavailable502 · retryable
Stripe didn't answer or failed, or another change to the account's billing was still running. Part of the request may have happened anyway: a checkout may already have expired the account's previous link. Send the same request again after retryAfter seconds (30); a checkout then answers with the account's one open link.
billing_unavailable503
This server doesn't sell Beacon Plus: billing isn't set up on it (GET /v1/capabilities says "billing": false), or its billing portal isn't. Retrying doesn't help.
binding_name_conflict409
The secret's name is already used by another of the worker's bindings. Secrets and bindings share the worker's env, so their names must differ. Choose another name; beacon secret ls lists the secrets.
cf_budget_exhausted429 · retryable
Your account made too many Cloudflare calls in the last 5 minutes. Deploys, rollbacks, secret changes, deletes and analytics all make them; the limit is workers.cloudflareCallsPer5MinPerAccount in GET /v1/limits. Nothing was changed, unless the answer has deleted or storageId: then the delete happened and only its purgeNow purge waits. Wait retryAfter seconds.
content_blocked422
A published file is a native program (a Windows, Linux or macOS executable, under any name), or a .zip or .tar that holds one or a script which downloads and runs a program (a malware dropper); error names the file, and the file inside an archive. Nothing went live, and a site's previous version keeps serving. Sending the same files fails the same way, so leave the file out. App packages (.apk, .ipa, .jar), game packs, WebAssembly and JavaScript are fine. detail says what was found: windows_executable, elf_executable or macho_executable (the file is a program), nested_executable (an archive holds one), script_dropper, windows_shortcut (a .lnk), encrypted_executable or unreadable_executable (a program in an archive that can't be opened to check it: password-protected, or packed with an unusual compression method), archive_bomb (more than 100,000 files in one archive) large_archive_unscanned (an archive over 64 MiB that couldn't be fully read: damaged, or using a compression method the check doesn't read) and scan_budget_spent (an archive that unpacks to more than 4 GiB, more than can be checked). See Content policy.
cron_invalid400
A cron expression doesn't parse: cron holds it and error says why. Crons have 5 fields in UTC and write the day of week as a name (MON-FRI), never a number; see Cron triggers. Nothing was uploaded. The CLI answers the same code, before any request, when crons in .beacon/config.json isn't a list of strings.
crons_not_supported400
The deploy declares crons, and cron triggers aren't switched on for this server yet (GET /v1/capabilities says "crons": false). Nothing was uploaded. Remove crons and deploy again, and call the worker's URL from an outside scheduler in the meantime.
data_rate_limited429 · retryable
Cloudflare is rate-limiting one resource this request used, or a database export limit is taken (another export request for the database is in flight, or its hour or the account's day is used up). Other requests are unaffected. Wait retryAfter seconds.
deployment_not_found404
The rollback's deploymentId isn't one of this worker's deployments. GET /v1/workers/:slug/deployments lists them.
deploy_failed422
Cloudflare rejected the script: it doesn't parse, imports a module that isn't in the upload, or throws while it loads. error and detail carry Cloudflare's message, cloudflareErrors its error list, and docs its documentation. Retrying the same bundle fails the same way and counts toward the deploy limit, so fix the script first. Nothing is recorded and the previous deployment keeps serving. A rollback whose target Cloudflare refuses fails the same way.
deploy_in_progress409 · retryable
Another deploy, rollback, secret change or delete of this worker is running, or Cloudflare refused a deploy's or rollback's upload because the worker's script changed after the deploy read it; nothing was uploaded. Wait retryAfter seconds and send the request again. The CLI's deploy, delete, secret set, secret del, storage destroy, storage restore and d1 migrations apply do this themselves, up to 3 times (10 s when there is no retryAfter), before they report it. They wait silently in JSON mode, so stderr still holds one JSON error; --pretty or --verbose prints one line on stderr per wait.
do_class_not_exported422
A declared Durable Object class is not exported by the bundle.
do_class_still_exported422
The bundle still exports a Durable Object class whose namespace would be removed.
do_delete_unconfirmed409
The delete would destroy Durable Object classes (classes) with all their objects at once, which can't be undone. A person must confirm by typing the class name; never confirm on their behalf.
file_storage_full409
The publish or claim would take the account's file storage, the files of all its live sites together, over its limit (File storage). limit, used (now) and after (with this publish) are in bytes. Nothing went live, and a site's previous version keeps serving. Creating a site or a version answers it before anything is uploaded; finalize and rollback answer it too, since publishes to two sites can race, and so does a claim of an anonymous site whose files don't fit. Delete sites you no longer need, then publish again. On Free, the hint and upgrade offer Beacon Plus, with up to 500 GB. An account already over its limit can still publish changes that don't grow its total.
internal_error500
Something failed inside Beacon. Try again; if it keeps failing, write to support@beacon.host with the operationId when the response has one. With done, the change was made but Beacon couldn't record that its operation succeeded (Beacon marks the operation uncertain when it can); done says what was done, and sending the same request again is safe.
invalid_binding_name400
A binding name in the deploy metadata (storage.d1.<NAME>) isn't one: upper-case letters, digits and _, starting with a letter, as in the worker's env (env.DB is DB). Nothing was uploaded. The CLI answers the same code, before any request, for a --delete-storage name that isn't a binding name.
invalid_metadata400
The deploy's metadata part is malformed or a value is out of range, and the message names the field: not JSON, no entryPoint, a bad compatibilityDate, location, jurisdiction or var, or a renamedFrom that isn't the binding's previous name. Nothing was uploaded. Deploy a worker lists the fields.
invalid_request400, 413, 422
A Workers API request is malformed and has no code of its own; the message says what to change (a body that isn't JSON, a missing multipart part, a bundle over 3 MB compressed, an entry point that isn't in the upload). Nothing was changed.
invalid_bundle400, 409
An uploaded file has a name Beacon can't upload: metadata is reserved for the upload's own metadata, and names can't contain control characters. On a rollback, the target deployment's bundle has such a name (400), or its stored bundle is missing (409): roll back to another deployment, or deploy the code again. detail names the file when it can.
logs_unavailable501
Live logs aren't switched on for this server yet (GET /v1/capabilities says "logs": false). In the meantime, log from the worker to a service you control, or return diagnostics in a response.
new_workers_limit_reached429
The account added the most new workers its plan allows in 30 days (30 on Free, 100 on Beacon Plus, in limit). A worker counts from its create while it exists, and a deployed worker that is deleted counts for 30 days after the delete, because the 404 page left at its address stays. Deploy to one of the account's existing workers instead: deploys never count. retryAfter is how many seconds until the next create fits. On Free, the hint and upgrade offer Beacon Plus.
no_billing_account404
The account has never subscribed, so it has no billing portal. beacon upgrade (POST /v1/billing/checkout) starts a subscription; only the account owner can.
plan_lapsed403
Beacon Plus ended for this account, so its D1 workers are paused and its D1 data is read-only. Writes to any of its databases (bound to a worker or not), standalone migrations, deploys that create a database or run migrations, D1 restores and resuming a D1 worker are refused. The data is kept, and reads and exports still work. The hint links https://beacon.host/pricing: the account owner resubscribes (beacon upgrade), which ends this pause and these refusals with no other step. Or deploy the worker without its D1 binding to serve it on Free. Subscribing again ends no other pause. A worker also paused for a daily D1 limit stays paused, and D1 queries and migrations on its databases keep getting 403 worker_paused, until you deploy it again or resume it. The worker's state.holds (GET /v1/workers/:slug) lists those pauses before and after subscribing. Carries upgrade, as storage_kind_not_enabled does.
plan_not_billable409
Beacon manages this account's plan (one an administrator set, or a test or internal account), or the account is being deleted, so it can't start a checkout. Write to support@beacon.host to change it.
platform_busy503 · retryable
Beacon stopped calling Cloudflare for a moment because Cloudflare asked it to slow down. Nothing was changed, unless the answer has deleted or storageId: then the delete happened and only its purgeNow purge waits (see purgeNow). Wait retryAfter seconds.
platform_unavailable502, 503 · retryable
Cloudflare failed or couldn't be reached. Send the request again, after retryAfter when the answer has one; an export sent again sooner gets 429 data_rate_limited. A secret set or delete right after a deploy gets it with retryAfter 10 while Cloudflare catches up with the deploy, and a delete that gets it leaves the secret listed until a delete succeeds. The CLI's secret set and secret del wait it out themselves, up to 3 times (5 s when there is no retryAfter), before they report it. They wait silently in JSON mode, so stderr still holds one JSON error; --pretty or --verbose prints one line on stderr per wait. It is 503 when a purge's final export can't be written because the server has no R2 configured; the storage stays held.
promotion_code_invalid400
The checkout's promotionCode matches none of Beacon's active Stripe promotion codes, or Stripe refused it for this checkout (it expired, ran out, or its minimum or customer restriction doesn't fit); detail carries Stripe's reason. No new link was made, though the account's previous link may already have been expired. Check the code and try again, or check out without one.
purge_now_not_allowed403
purgeNow=true on a worker delete is only for Beacon's test and internal accounts. Delete without it.
request_too_large413
The request body is over the endpoint's limit, which the message gives in bytes. Nothing was changed. Send a smaller body.
rollback_bundle_missing409
The rollback target's stored bundle is gone. Roll back to another deployment, or deploy the code again.
rollback_crosses_do_change409
The rollback crosses a Durable Object class change. Choose a compatible deployment.
rollback_target_missing409
The worker has no earlier deployment to roll back to.
rollback_var_conflicts_secret409
The rollback target sets a var that is now a secret of this worker, and rolling back would delete the secret. Roll back to another deployment, or deploy the current code.
rate_limited429 · retryable
An hourly limit of your account is used up: deploys, deploy or rollback requests, new workers, worker deletes, secret sets or deletes, log sessions, or analytics requests; error says which. Wait retryAfter seconds (the Retry-After header says the same), when the hour turns over, then send the request again. Rate limits and GET /v1/limits list them.
reserved_file_name400
An uploaded file is named __beacon_entry.js, which Beacon generates for workers that declare crons. Rename the file.
slug_cooling_down409 · retryable
A worker with this slug was deleted less than 15 minutes ago, so a new worker can't take the slug yet. Wait retryAfter seconds, or choose another slug.
slug_unavailable409
A site or another worker has the slug, or another request took it first. Choose another slug.
storage_binding_unknown409
The live script binds storage Beacon has no record of (bindings names it). Nothing was changed and the operator has been alerted; write to support@beacon.host.
storage_field_not_allowed400
The deploy metadata names a Cloudflare resource (id, database_id, namespace_id, bindings, kvNamespaces, a top-level durableObjects, ...); the message names the key. Refused for every account inside storage, and elsewhere where storage mode covers the account (otherwise ignored with resource_key_ignored). Remove it: Beacon builds every binding from storage declared by binding name.
storage_kind_not_enabled403
The deploy declares D1 on an account without Beacon Plus. Nothing was created. The hint says so and links https://beacon.host/pricing: only the account owner can subscribe (beacon upgrade prints a checkout link). Or remove the binding (d1.<BINDING>) from the config and deploy again. upgrade describes the plan: {"plan": "plus", "name": "Beacon Plus", "priceUsdMonthly": 4, "url": "https://beacon.host/pricing", "checkout": "https://beacon.host/dashboard?view=plan"}. It is never in fix.run: subscribing is the user's decision, so tell them instead of opening it. A durableObjects declaration is refused the same way, without upgrade: Durable Object provisioning isn't available.
storage_missing409
A storage binding of this worker points at a resource that no longer exists, so the change was stopped instead of leaving the worker bound to nothing. Write to support@beacon.host.
storage_not_adopted409
The worker's script still has a storage binding from an earlier beacon.host feature that Beacon hasn't taken over yet. A deploy would remove it, so it was refused. Write to support@beacon.host.
storage_not_named409
The worker has storage bindings, and the delete doesn't name each of them in deleteStorage, or names one the worker doesn't have. storage describes every binding and what deleting it would do, and notNamed lists the missing names. Deleting the worker deletes that data: name a binding only if the user asked for its data to be deleted. A binding whose last create waits on support (storage_unresolved) can't be named: the delete leaves it, and it keeps counting toward the quota.
storage_provisioning503 · retryable
Storage for this worker is still being set up. Try again after retryAfter.
storage_purge_in_progress409 · retryable
The storage the request names is already being deleted. Wait retryAfter seconds before checking again.
storage_quota_exceeded409
The deploy would exceed the worker or account storage quota. Held databases count until purged, and unresolved ones (failed, create_mismatch) until support settles them; heldStorage lists both. With "detail": "d1_size", the account's D1 data is at its size limit (limit and used, in bytes): new databases, migrations and D1 API writes other than DELETE and DROP wait. Delete rows or destroy a database; workers keep serving until the data reaches twice the limit (Pauses and suspensions).
storage_unavailable_in_dev_mode503
A Beacon server in dev mode doesn't call Cloudflare, so it can't run D1 queries, exports or purges. Use the API URL of a server that calls Cloudflare.
too_many_crons400
The deploy declares more than 5 crons (limit). Combine schedules, or branch on controller.cron inside one scheduled() handler.
unknown_metadata_field400
The deploy metadata, or a strict storage or confirmation object in it, has a field Beacon doesn't know; the message names it, and fields lists every unknown top-level key. The hint names the keys the server reads: entryPoint, compatibilityDate, compatibilityFlags, crons, vars, storage, confirm and skipBindingCheck. A key that names a Cloudflare resource is never unknown: where storage_field_not_allowed refuses it, that answer comes first, and where it is only a resource_key_ignored warning, unknown keys beside it are still refused. A top-level "d1" is the config file's shape: in the metadata, D1 bindings go under storage.d1 ({"storage": {"d1": {"DB": {}}}}). Nothing was uploaded.
usage_ceiling_reached403
No longer returned. Older servers answered it when an account reached a daily storage usage ceiling; the daily limits now pause the account's storage workers instead (worker_paused, Pauses and suspensions).
vars_not_enabled403
The deploy sends plain-text vars on an account without Beacon Plus. The hint links https://beacon.host/pricing: only the account owner can subscribe (beacon upgrade prints a checkout link). Or move the values to secrets (beacon secret set NAME). Carries upgrade, as storage_kind_not_enabled does.
worker_not_found404
No worker of yours has this slug (someone else's answers the same), or it was deleted while the request ran. GET /v1/workers (beacon list) lists yours; a worker is created by its first deploy.
worker_not_deployed409
The worker has no deployment yet. Secrets attach to the deployed script, and its logs start with the first deployment: deploy it first (fix.run holds beacon deploy). beacon storage plan gives it too before the first deploy (from the server's 404), since there is no storage to plan against: beacon deploy --dry-run (its fix.run) previews the databases and migrations that deploy creates.
worker_paused403
A pause refused the call. reason says which, and the hint how the pause ends (Pauses and suspensions):
  • d1_rows_read, d1_rows_written: the account went over a daily D1 limit, so its storage workers are paused and D1 queries and migrations through the API wait, on every database of the account. Deploy a fix (beacon deploy) or run beacon resume <slug>; D1 usage then counts from that moment. With no worker to resume, the API is free again at 00:00 UTC. Exports still work.
  • admin_pause: An administrator paused this worker, and D1 writes to its databases wait. Deploy (beacon deploy) or run beacon resume <slug> to start it again. Reads and exports still work.
  • metering_blind: Beacon can't measure D1 usage right now, so storage workers with heavy recent D1 use are paused, and a resume is refused. The pause lifts on its own when measuring recovers.
  • d1_size: the account's D1 data is at twice its size limit, so its storage workers are paused, and a resume is refused. Delete rows or destroy a database; the pause lifts on its own once the data is under twice the limit.
An agent should deploy a fix, or ask the user, rather than resume on its own: a second pause within 30 days suspends the account for review. The worker's URL answers 503 worker_paused meanwhile.
worker_suspended403
An administrator suspended this worker ("reason": "admin"), so changes to it and deleting it are refused. Reads and exports still work; write to support@beacon.host. Its URL answers 503 worker_suspended.
workers_quota_exceeded409
The account already has the most workers it can have (25, in limit). Delete one it no longer needs.

Warnings

A deploy, rollback, restore or export that succeeds can still report problems in warnings, a list of {"code", "message", ...} objects.

code_ahead_of_schemawarning
From a restore: it undid migrations (files) the live deployment (deploymentId) was deployed with, so its code may fail where it uses them. Roll the code back first (to rollbackTo, a deployment from before them, when there is one), then restore; or undo the restore with the command in detail.
crons_not_syncedwarning
The deployment is live, but its cron schedule couldn't be updated yet. Beacon retries within 10 minutes. Until then, crons the deployment added may not run yet, and crons it dropped don't run.
cron_runs_unavailablewarning
From GET /v1/workers/:slug/crons: the run history couldn't be read, so runs is empty. Try again shortly.
d1_export_reusedwarning
From an export: the database's export for the hour is taken, so the answer is the finished export again (reused, exportedAt), without the changes made since. The message says when a new export can start.
d1_export_virtual_tableswarning
From an export of a database with virtual tables (FTS5), which D1 can't export whole: the dump has the regular tables, virtualTables lists the others, and appendSql creates them with the views, indexes and triggers and rebuilds each external-content FTS5 table. The rows of other virtual tables aren't in it.
d1_location_ignoredwarning
The location of a D1 binding (binding) changed, but a location is used only when the database is created; the database stays where it is.
migration_empty_skippedwarning
A migration file (binding, file) has no statements, only comments or a wrapper; it isn't run or recorded.
migration_transaction_strippedwarning
A BEGIN … COMMIT wrapping a whole migration file (binding, file) was removed before it ran; the checksum covers the file as written.
nodejs_compat_addedwarning
A file imports node:* modules, which Cloudflare runs only with the nodejs_compat compatibility flag, so the flag was added.
replaced_historywarning
From a restore to a time: Cloudflare placed the time in a history a later restore replaced, so the database went to the latest point of the history it had then that Beacon recorded. lostWritesSince says from when writes are gone; undo reverses the restore.
resource_key_ignoredwarning
The deploy metadata names a Cloudflare resource (an ID or a list of bindings) at key. It was ignored because storage mode does not cover this account. Storage-enabled accounts receive storage_field_not_allowed instead, and inside storage every account does. Remove the resource field.
rollback_target_uses_missing_bindingwarning
The rollback target used storage (bindings) that isn't bound now; its code may fail where it uses it.
scheduled_handler_missingwarning
Crons are declared, but no uploaded file mentions a scheduled() handler, so every run would fail. Add one to the worker's default export.
schema_ahead_of_codewarning
After a rollback: the database binding keeps the migrations applied since the target deployment (files), and the older code may not expect them. Data and schema are kept; a rollback never reverses migrations. detail names the restore that would undo them (beacon d1 restore DB --before-op OP --yes, REST POST /v1/workers/:slug/d1/DB/restore?confirm=DB with {"beforeOp": "OP"}), which also discards data written since: only with the user's approval. Otherwise deploy code that works with the newer schema.
storage_size_warningwarning
The account's D1 data is at 80% of its size limit or more ("message": "D1 data is at 85% of this account's 2.0 GiB limit.", with usedBytes and limitBytes). From deploys, and in storage.warnings of GET /v1/usage. At the limit, new databases, migrations and D1 API writes other than deletes are refused (storage_quota_exceeded), so delete rows or destroy a database you don't need.
var_looks_secretwarning
A var (var) is named like a credential. Vars are stored in plain text, so set it as a secret instead (beacon secret set NAME).

Storage and D1 errors

storage_binding_removed409
A declared binding was removed without an explicit detach or delete choice. fix.config puts it back with its jurisdiction and location (the CLI adds the migrations folder of the last deploy), or suggests renamedFrom when the same deploy adds one new binding; detail names the detach and delete choices, which are the user's.
storage_kind_changed409
An existing binding cannot change storage kind. Use a new binding name.
storage_in_grace409
The binding has a database held for deletion, also when its declaration still says renamedFrom. fix.run restores it (beacon storage restore <BINDING>, REST POST /v1/workers/:slug/storage/<BINDING>/restore); a new, empty database instead needs the user's approval (--new-storage).
storage_rename_source_unknown409
renamedFrom names no storage this worker owns. Check the binding name.
storage_attached409
The database is still bound to the worker. Detach it before destroying it.
storage_not_found404
This worker has no accessible storage of the requested kind under that binding name.
storage_not_ready404
The resource is still being created. Follow the hint to finish provisioning.
storage_not_in_grace409
The database has no deletion hold to cancel.
storage_unresolved409
Cloudflare answered the binding's last create under another name, so a database Beacon can't verify may exist for it. It counts toward the quota and is listed by beacon storage until support settles it. Nothing was changed and the operator has been alerted; write to support@beacon.host. A new, empty database instead needs the user's approval (--new-storage).
d1_jurisdiction_immutable409
A database jurisdiction cannot change after creation.
do_class_removed409
A Durable Object class was removed without a matching explicit deletion choice.
binding_undeclared_in_code422
The bundle references a binding absent from the declared environment. Correct the config or code.
platform_capacity503
Beacon cannot create more D1 databases now. Existing bindings keep working; honor retryAfter.
storage_paused503
Storage changes are paused for recovery. Retry after the operator resumes them.
storage_not_declared400
The deploy has migration parts (BINDING/NNNN_name.sql) for a binding that isn't in storage.d1. Declare it there, or drop its files.
confirm_mismatch400
The migrations request's confirm names something other than the binding in the URL. destructiveMigrations lists binding names, never files: {"confirm": {"destructiveMigrations": ["DB"]}}; reapplyMigrations maps the binding to file names: {"reapplyMigrations": {"DB": ["0002_x.sql"]}}.
operation_not_found404
The operation does not belong to this worker and account.
d1_query_failed422
D1 rejected the query or export. Inspect the redacted detail.
d1_result_too_large422
D1 ran the query, but its result is over 10 MB, so nothing is returned. applied: true means the query had a statement that can write and D1 ran it to the end, so don't run it again; it doesn't mean a row changed.
migration_failed422
The failed database migration batch applied nothing. Earlier successful bindings in the same deploy can remain changed; inspect migrationsApplied and undo.
migration_modified422
An applied migration has a different checksum. Restore the original file and add a new migration.
migration_missing422
The submitted history omits an applied migration. Send the full history. A name no migration file can have was written to d1_migrations by something else; if no file ran as it, take it out with beacon d1 migrations resolve <BINDING> --mark-reverted <name>.
migration_out_of_order422
A pending migration sorts before the last applied file. Give it a later number.
migration_reverted_pending422
A restored migration is still present locally. It does not rerun without an explicit reapply choice.
migration_ledger_diverged422
Beacon and the database disagree about migration history: Beacon's ledger has a file applied that the database's d1_migrations lacks, or holds with another version's checksum, or Beacon can't tell which version a row is. Nothing ran. Inspect both before explicitly resolving the ledger.
migration_unknown422
resolve --mark-applied named a file Beacon has no record of: the database's d1_migrations doesn't have it, and Beacon never sent it. Check the name with beacon d1 migrations list; a new file runs at the next deploy.
restore_too_early422
The requested restore time is less than 60 seconds after database creation.
restore_target_not_found404
The operation or deployment has no bookmark for this database, or belongs to another worker; or the bookmark isn't a point of this database (another database's, or made up). Nothing changed. beacon d1 bookmarks lists the database's bookmarks.
restore_time_ambiguous422
Beacon can't tell which history the database had at the restore time: it falls during a restore or after one whose outcome Beacon doesn't know, or Cloudflare places it in a history a later restore replaced and Beacon recorded no point of the one the database had then. Nothing changed. Name another time, or a bookmark from beacon d1 bookmarks or a restore's previousBookmark.
invalid_bookmark400
The target is neither a valid D1 bookmark nor a supported RFC3339 time.
migration_unterminated422
SQL ends inside an unfinished statement, quoted value, comment or trigger.
migration_not_utf8422
A migration file isn't UTF-8 text. Nothing ran. Save it as UTF-8 (or write the bytes as a blob literal such as X'E9'); Beacon never rewrites it.
migration_has_transaction422
Transaction control is not allowed inside the SQL batch, nor a ROLLBACK conflict resolution (OR ROLLBACK, ON CONFLICT ROLLBACK, RAISE(ROLLBACK)) in a query or a pending migration: D1 answers one that fires with an internal error. Use ABORT.
migration_forbidden_statement422
The SQL uses a forbidden statement or PRAGMA.
d1_internal_table422
The SQL writes to a protected internal table or reserved object.
migration_destructive422
The migration may delete data and needs the user's explicit confirmation. Once they agree: --allow-destructive-migration DB in the CLI, or "confirm": {"destructiveMigrations": ["DB"]} (the binding's name, never the file's) in the deploy metadata or the body of POST /v1/workers/:slug/d1/DB/migrations.
migration_bad_name422
Migration names must follow NNNN_name.sql, and a deploy's migration parts BINDING/NNNN_name.sql: any other part is refused, never dropped, and so is a file sent twice. Follow the suggested rename.
migrations_too_large413
Over 1 MB of migration SQL not yet applied in one request (files already applied are only checksummed and don't count), more files not yet applied than one request records (a few thousand), over 10,000 migration files, or an apply request over 5 MB. Send new files over several deploys, a few at a time, and keep large data out of migrations.
deploy_too_large413
The deploy request is over 5 MB: the bundle (at most 3 MB compressed), the metadata and each D1 binding's whole migration history together. Keep large data out of migrations.
ddl_requires_migration422
Put the schema change in a migration, or explicitly use allowDdl=true for a query.
d1_params_multi_statement400
Bound parameters require one SQL statement per query entry.

From the CLI

The CLI finds these itself, before it sends anything.

config_unknown_keyCLI
.beacon/config.json has a Cloudflare (wrangler) setting that Beacon doesn't read: kv, kv_namespaces, kvNamespaces, d1_databases, durable_objects, bindings or database_id, named in key. hint explains it; fix.config, when present, is a merge patch with Beacon's form of the setting. Several such keys give one error with an errors entry each.
storage_on_siteCLI
Storage and vars belong to workers. A static site cannot declare them.
invalid_compatibility_dateCLI
compatibilityDate in .beacon/config.json isn't a YYYY-MM-DD date. Fix it, or remove it to keep the date the server pinned.
server_too_oldCLI
A deploy or storage command needs an API feature the server does not provide. Metadata version 2 is required for storage-aware deploy and delete. Use a current server; do not remove a data-safety confirmation to bypass this error.

Edge answers

A request to a worker's URL (https://<slug>.worker.beacon.host) gets one of these answers instead of the worker's own when a daily limit, a per-request limit or a pause stops it. They are written for the worker's visitors, so they never name the account. Each is JSON with Content-Type: application/json, Cache-Control: no-store and Access-Control-Allow-Origin: *, and links to its entry below:

{
  "error": "worker_paused",
  "message": "This worker is paused because its account went over a daily D1 limit.",
  "docs": "https://beacon.host/docs#edge-worker_paused"
}
daily_request_limit_reached429
"This worker's account reached its daily request limit. It resets at 00:00 UTC." The account's workers made the day's requests its plan allows (20,000 on Free, 100,000 on Beacon Plus). Retry-After gives the seconds until 00:00 UTC and resetsAt the time. It is a quota, not a strike, and the API keeps working. Refused requests aren't counted. If the edge hasn't heard from Beacon for 30 minutes, it applies the lower of Free's limit and the account's own.
worker_paused503
"This worker is paused because its account went over a daily D1 limit." when the account went over a daily D1 limit, and "This worker is paused." for any other pause: an administrator's, the D1 size limit, Beacon Plus ending, or D1 usage Beacon can't measure. The owner sees the reason in the worker's state (GET /v1/workers/:slug) and ends the pause as Pauses and suspensions says.
worker_suspended503
"This worker is suspended." An administrator suspended the worker or its account, the account is suspended for review, or it was disabled. Only an administrator lifts it; the owner writes to support@beacon.host.
worker_cpu_limit503
"This request used more CPU time than this worker's plan allows." Only this request failed; the worker keeps serving others. The limit is 1,000 ms of CPU per request for now (Plans and daily limits). It is not a strike.
worker_subrequest_limit503
"This request made more subrequests than this worker's plan allows." Only this request failed. The limit is 50 subrequests per request on Free and 200 on Beacon Plus; D1 queries aren't subrequests. It is not a strike.