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
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": [...]}'
| Feature | Anonymous | Authenticated |
|---|---|---|
| Site lifetime | 24 hours | Permanent |
| Max file size | 250 MB | 5 GB |
| Publish rate limit | 5/hour per IP | 60/hour per key |
| Custom slug | Allowed | Allowed |
| Auth header | None (or X-Claim-Token) | Authorization: Bearer <key> |
Publishing
Create a site
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
| Field | Type | Required | Description |
|---|---|---|---|
files | array | Yes | Array of file manifest entries |
files[].path | string | Yes | File path relative to site root (e.g. index.html, assets/style.css) |
files[].size | integer | Yes | File size in bytes |
files[].contentType | string | Yes | MIME type (e.g. text/html) |
files[].hash | string | Yes | SHA-256 hash in format sha256:<64 hex chars> |
slug | string | No | Custom slug for the subdomain. Auto-generated if omitted. |
expiresAt | string | No | RFC 3339 timestamp. Only for authenticated requests. |
Headers
| Header | Required | Description |
|---|---|---|
Authorization | No | Bearer <api-key> for authenticated requests |
Idempotency-Key | No | Unique 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-Secret | No | Anonymous 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
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
Returns all sites owned by the authenticated user. Requires Bearer auth.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Max results to return (max 100) |
offset | integer | 0 | Pagination 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
Update site metadata. All fields are optional — only included fields are updated. Set a field to null to clear it.
Request body
| Field | Type | Description |
|---|---|---|
title | string | null | Site title (used in Open Graph tags) |
description | string | null | Site description |
ogImagePath | string | null | Path to an image file in the site for Open Graph |
expiresAt | string | null | RFC 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
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
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
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
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
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
Returns all versions for a site, ordered by creation date (newest first).
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Max results to return |
offset | integer | 0 | Pagination 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
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
Regenerates expired presigned upload URLs for a pending version. Optionally pass a list of paths to refresh only specific files.
Request body (optional)
| Field | Type | Description |
|---|---|---|
paths | string[] | 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
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
| Field | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File path in the manifest |
uploadId | string | Yes | The upload ID from the create response |
parts | array | Yes | Array of completed parts |
parts[].partNumber | integer | Yes | Part number (1-based) |
parts[].etag | string | Yes | ETag 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
Creates a new worker and reserves a slug. The worker is not live until you deploy code to it.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
slug | string | No | Custom slug for the subdomain. Auto-generated if omitted. |
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <api-key> |
Idempotency-Key | No | Unique 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
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
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
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 name | Type | Required | Description |
|---|---|---|---|
metadata | JSON (form value) | Yes | Deployment metadata (see below) |
file | File upload(s) | Yes | One or more script files. Use field name file for each. |
<BINDING>/<NNNN_name>.sql | File upload(s) | No | A 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
| Field | Type | Required | Description |
|---|---|---|---|
entryPoint | string | Yes | Main module filename (e.g. index.js). Upload JavaScript; TypeScript is not compiled. |
compatibilityDate | string | No | Cloudflare 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. |
compatibilityFlags | string[] | No | Compatibility flags (e.g. ["nodejs_compat"]). nodejs_compat is added for you when a file imports node:* modules. |
crons | string[] | No | Cron triggers that run the worker's scheduled() handler, e.g. ["*/5 * * * *"]. See Cron triggers. |
storage | object | No | The 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. |
vars | object | No | Plain-text variables, {"MODE": "production"}, with Beacon Plus. |
confirm | object | No | Choices only the user makes, by binding name: detach, deleteStorage, newStorage and destructiveMigrations (lists of bindings), reapplyMigrations ({"DB": ["0002_x.sql"]}). Needs storage. |
skipBindingCheck | boolean | No | true 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
}
statusisdeployedwhen code or settings change,migratedwhen only database migrations run, orunchangedwhen files, settings and migrations were already live. An unchanged deploy uploads nothing and does not count toward the deploy limit. A migrated deploy uploads no code but counts toward that limit.- A deploy of code that is already live answers
unchangedonly when Beacon can confirm that the live script is the current deployment's own upload. Otherwise the same files and settings upload again, and the deploy answersdeployedand counts toward the deploy limit. Beacon can't confirm it on the first deploy of a worker whose current deployment predates Beacon Plus, or on the first deploy after the worker's per-request limits changed (with its plan, for example). Nor can it after an earlier deploy, rollback or delete of the worker ended without an answer from Cloudflare, or while it has replaced the script of a worker paused for a daily D1 limit because the worker's usage kept rising. warningsis always a list of{"code", "message", ...}objects:nodejs_compat_added,scheduled_handler_missing,crons_not_synced,resource_key_ignored,var_looks_secret,d1_location_ignored,migration_transaction_stripped,migration_empty_skipped,storage_size_warning(the account's D1 data is at 80% of its size limit or more), and on a rollbackschema_ahead_of_codeandrollback_target_uses_missing_binding.resumedistruewhen the deploy ended a pause of the worker, andliftedthen lists the reasons it lifted (["d1_rows_written"]). Any successful deploy or rollback,unchangedincluded, lifts a pause for a daily D1 limit or by an administrator; see Pauses and suspensions.operationIdnames this change in Beacon's logs; quote it when you report a problem.storagedescribes each binding and its deploy outcome; it is empty for workers without bindings.
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
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
| Parameter | Description |
|---|---|
deleteStorage | Repeat 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. |
erase | true skips the export kept of deleted storage. |
purgeNow | true 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
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
| Field | Type | Required | Description |
|---|---|---|---|
value | string | Yes | The 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
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
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
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
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)
| Field | Type | Required | Description |
|---|---|---|---|
deploymentId | string | No | Specific 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
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
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}]
}
typeisrequest,scheduled(a cron run, withcronandscheduledTime),dooralarm(Durable Objects),event(anything else), ordropped({"type": "dropped", "count": n}: a worker sending more than 50 events a second in a tail isolate has the rest counted instead of sent).- An invocation arrives well under a second after it ends, including what it logs in
ctx.waitUntil. Invocations in the first few seconds of a session can be missed. - Request headers are never sent. Each event carries at most 16 KB of log text.
- A session lasts up to an hour, then closes with code
4000: ask for a new URL and reconnect.1006or1012means the platform restarted: reconnect.4001means the worker was deleted or its account disabled: stop. - At most 5 sessions per worker are open at once, and each account can open 30 an hour (
429 rate_limited). A worker that was never deployed gets409 worker_not_deployed. - Until live logs are switched on, this endpoint answers
501 logs_unavailable.
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())
},
}
- Five fields in UTC: minute, hour, day of month, month, day of week. Each takes
*,n,a-b,*/s,a-b/sand comma lists; months also takeJAN–DEC. - Write the day of week as a name (
SUN–SAT, e.g.0 9 * * MON-FRI). Numbers are refused, because cron tools disagree on which day is 0 or 1.L,W,#and?are refused too. When both day fields are restricted, a day matching either one runs. Use ASCII characters, with spaces or tabs between fields and no surrounding whitespace. A positive step wider than the field selects its starting value only. - At most 5 crons per worker. An expression that doesn't parse gets
400 cron_invalid(naming it incron), and a sixth cron400 too_many_crons, before anything is uploaded. - A cron runs at most once per matching minute and usually starts within a minute of its time. There are no retries and no catch-up for a missed minute. A run may last up to 14 minutes.
- A run that throws is recorded with its error, and the stack appears in the log stream. Other crons are unaffected.
- A redeploy or rollback replaces the schedule with the new deployment's list, and deleting the worker stops it. Beacon generates the file
__beacon_entry.jsfor workers with crons, so an upload may not contain one (400 reserved_file_name). Beacon adds one module to every upload of a worker's code,__beacon_generation.js: a one-line comment naming the upload, so that two uploads of the same code are distinct versions. Nothing imports it, so your worker never runs it, and no Beacon answer lists it. A bundle that has its own file of that name keeps it, and the comment goes in the first of__beacon_generation-2.js,__beacon_generation-3.js, and so on, that the bundle doesn't have. - Until cron triggers are switched on, a deploy that declares crons is refused with
400 crons_not_supportedbefore anything is uploaded; call the worker's URL from an outside scheduler instead.
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
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"}
}
}
metadataVersion2:compatibilityDateis optional on deploy, and a worker delete takesdeleteStorage,eraseandpurgeNow.logsandcrons: live logs and cron triggers work on this server. While they arefalse, the logs endpoint answers501 logs_unavailableand a deploy with crons400 crons_not_supported.billing: this server sells Beacon Plus. While it isfalse, the billing endpoints answer503 billing_unavailable.storage: kinds this account can create.d1istruewith Beacon Plus, and without a key it isfalse. Durable Object provisioning is not available. Existing D1 bindings remain usable when creation is disabled.- With
Authorization: Bearer, the answer is for that account and addsaccount: theplan(freeorplus, ande2eorinternalfor Beacon's own accounts) and itsplanName,storageIncluded(D1 and plain-text vars;allowlistedsays the same, for older clients),storageAllowed(the account's D1 workers serve and its databases take writes; false is theplan_lapsedpause), the account'sstate(status,reason,until,pausedWorkers,strikes30d; see Pauses and suspensions), andupgradewhen the plan has no D1.upgrade.firstMonthPriceUsdis there while the account's first month of Beacon Plus would cost $1: it never had a Beacon Plus subscription.
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 answer | REST request |
|---|---|
beacon deploy | POST /v1/workers/:slug/deploy with the deploy's multipart body |
beacon deploy --dry-run, beacon storage plan | POST /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 DB | metadata "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-check | metadata "skipBindingCheck": true |
beacon storage | GET /v1/workers/:slug/storage |
beacon storage ops | GET /v1/workers/:slug/operations |
beacon storage restore DB | POST /v1/workers/:slug/storage/DB/restore |
beacon storage destroy DB | DELETE /v1/workers/:slug/storage/DB?confirm=DB |
beacon d1 export DB | POST /v1/workers/:slug/d1/DB/export |
beacon d1 migrations list DB | GET /v1/workers/:slug/d1/DB/migrations |
beacon d1 migrations resolve DB --mark-applied F | POST /v1/workers/:slug/d1/DB/migrations/resolve {"markApplied": "F"} (or markReverted) |
beacon d1 bookmarks DB | GET /v1/workers/:slug/d1/DB/bookmarks |
beacon d1 restore DB --before-op OP --yes | POST /v1/workers/:slug/d1/DB/restore?confirm=DB {"beforeOp": "OP"} |
beacon d1 restore DB --to BOOKMARK --yes | POST /v1/workers/:slug/d1/DB/restore?confirm=DB {"to": "BOOKMARK"} |
beacon secret ls, beacon secret set NAME | GET /v1/workers/:slug/secrets, PUT /v1/workers/:slug/secrets/NAME {"value": "..."} |
beacon list | GET /v1/workers |
beacon login | POST /v1/auth/send-otp, then POST /v1/auth/verify-otp |
Runtime notes
fetch()to a host whose DNS lookup fails does not throw. It resolves with status530and the bodyerror code: 1016. Treat a 530 whose body matches/^error code: \d+/as "no response from the endpoint".request.cfis undefined. The same data arrives as request headers that clients can't forge:x-beacon-colo(data center, e.g.SJC),x-beacon-country,x-beacon-region,x-beacon-city,x-beacon-timezone,x-beacon-asn. A header is missing when Cloudflare doesn't know the value.cf-connecting-ipis set too.- A worker can
fetch()another*.worker.beacon.hostworker, its own URL included. The call goes back through the edge like any outside request. - Scripted clients reach workers: Cloudflare's Browser Integrity Check is off for
*.worker.beacon.host, so Python'surllib, PycURL and Perl LWP are not blocked. - A request can use up to 1,000 ms of CPU and make 50 subrequests (200 with Beacon Plus); D1 queries are not subrequests. A request over either limit fails with
503(worker_cpu_limit,worker_subrequest_limit). See Plans and daily limits.
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.
| Free | Beacon Plus | |
|---|---|---|
| Price | $0 | $4 a month (your first month is $1) |
| D1 databases and plain-text vars | No | Yes |
| File storage, all sites together | Up to 10 GB | Up to 500 GB |
| Workers | 25 | 25 |
| New workers per 30 days | 30 | 100 |
| Worker requests per UTC day | 20,000 | 100,000 |
| D1 rows read per UTC day | No D1 | 25,000,000 |
| D1 rows written per UTC day | No D1 | 50,000 |
| D1 databases | No D1 | 5 per account, 3 per worker |
| D1 data, all databases together | No D1 | 2 GiB |
| Migration SQL per deploy | No D1 | 1 MiB |
| D1 queries through the API | No D1 | 12 a minute, bursts of 10 |
| D1 restores per hour | No D1 | 6 |
| CPU per request | 1,000 ms | 1,000 ms |
| Subrequests per request | 50 | 200 |
| Deploys, deploy requests, secret sets, secret deletes per hour | 60, 300, 60, 30 | 60, 300, 60, 30 |
| Worker creates, worker deletes per hour | 10, 10 | 10, 10 |
| Storage plans per hour | 120 | 120 |
| Cloudflare calls per 5 minutes | 60 | 60 |
"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:
| Reason | When | The worker's URL answers | Ends |
|---|---|---|---|
d1_rows_read, d1_rows_written | The account went over a daily D1 limit. One strike. | 503 worker_paused | A 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_pause | An administrator paused the worker. | 503 worker_paused | A deploy or rollback, a resume, or an administrator. |
metering_blind | Beacon couldn't measure D1 usage for 30 minutes, and the account's recent D1 use was heavy. | 503 worker_paused | On its own, when measuring recovers. |
d1_size | The account's D1 data reached twice its size limit. | 503 worker_paused | On its own, once the data is under twice the limit. |
plan_lapsed | Beacon Plus ended. | 503 worker_paused | Subscribing again, or a deploy without the D1 binding. |
request_cap | The account's workers reached the daily request limit. Every worker of the account, not a strike. | 429 daily_request_limit_reached | At 00:00 UTC, or when the limit rises above today's count. |
admin_suspend | An administrator suspended the worker, or the account and with it every worker. | 503 worker_suspended | An administrator. |
review | A second pause for a daily D1 limit within 30 days. Every worker of the account. | 503 worker_suspended | An administrator; write to support@beacon.host. |
disabled | An administrator disabled the account. Every worker of the account, and its keys get 401 account_disabled. | 503 worker_suspended | An 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
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
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 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):
- Exact match —
/style.cssserves the file at pathstyle.css - Trailing slash redirect —
/blogredirects (302) to/blog/if files exist under that prefix - Directory index —
/blog/servesblog/index.htmlif it exists - SPA fallback — only for sites that ship a shell page (see Single-page apps)
- Single-file auto-viewer — If the site has exactly one file, serves an HTML wrapper with appropriate viewer (image, video, PDF, or download link)
- Directory listing — If the path is a directory with files, renders an HTML file listing
- 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:
_shell.html— what TanStack Start writes in SPA mode.200.html— the Surge convention. For Vite, Create React App and other builds that only produceindex.html, copy it:cp dist/index.html dist/200.html.
How the fallback decides:
- A missing static asset (
.js,.mjs,.css,.map,.json,.wasm, images, fonts, audio and video,.pdf,.txt,.xml,.webmanifest,.zip,.gz,.csv) still returns 404, so a stale chunk fails loudly instead of receiving HTML. The exception is a browser navigation (Sec-Fetch-Mode: navigate, someone opening the link in a tab), which gets the shell. - Any other last segment is a route, dots included:
/u/jane.doe,/docs/v1.2,/sites/example.com. - A missing
/index.htmlor/<dir>/index.htmlredirects (302) to./with the query string kept, because your router knows/, not/index.html. - Unknown URLs get the shell with status 200, so render a not-found view for routes your router doesn't know, and give it
<meta name="robots" content="noindex">. 404.htmlis only used for requests the shell didn't answer.
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 type | Cache-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's | public, max-age=3600 |
| Password-protected sites | private, 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.
| Action | Limit | Scope |
|---|---|---|
| Publish (anonymous) | 5 per hour | Per IP address |
| Publish (authenticated) | 60 per hour | Per API key |
| Upload refresh | 10 per hour | Per site |
| Worker deploy (counted when it sends code or migrations to Cloudflare; rollbacks and migration applies too) | 60 per hour | Per account |
| Worker deploy and rollback requests | 300 per hour | Per 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 deletes | 60 / 30 per hour | Per account |
| Log sessions | 30 per hour | Per account |
| Worker analytics (counted when Beacon queries Cloudflare; answers from its 60-second cache are not) | 60 per hour | Per account |
| Cloudflare calls made for your workers (deploys, secrets, deletes, analytics) | 60 per 5 minutes | Per account (cf_budget_exhausted) |
| Worker resumes | 30 per hour | Per account |
| Checkouts / billing portal links / billing syncs | 10 / 20 / 360 per hour | Per 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
| Limit | Anonymous | Authenticated |
|---|---|---|
| Max file size | 250 MB | 5 GB |
| Max files per version | 10,000 | |
| Max total size per version | 10 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.
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"
}
| Field | Meaning |
|---|---|
error | One sentence saying what went wrong. |
code | Stable snake_case name of the error. Branch on it, not on error. |
hint | What to do about it. |
fix | run: 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. |
detail | Cloudflare's message, when there is one, with resource IDs removed. |
retryable | true only when the same request can succeed later. Otherwise change something first. |
retryAfter | Seconds to wait before retrying; the Retry-After header says the same. |
docs | This page's entry for the code, or Cloudflare's documentation for a script Cloudflare rejected. |
errors | Every 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
| Status | Meaning |
|---|---|
200 | Success |
400 | Bad request — invalid input, missing required fields, invalid hash format |
401 | Unauthorized — missing or invalid Bearer token / claim token, or a disabled account |
403 | Forbidden — the account's plan doesn't include this, or the worker or account is paused or suspended |
404 | Not found — site, worker or version does not exist, or isn't yours |
409 | Conflict — 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) |
413 | Payload too large — file or total site size exceeds limit |
422 | Unprocessable — 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 |
429 | Too many requests — rate limit exceeded |
500 | Internal server error |
501 | Not implemented — live logs aren't switched on for this server yet |
502 | Bad gateway — Cloudflare or Stripe unavailable (worker deployment failed, retry) |
503 | Service 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
| Error | Cause |
|---|---|
"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.
reasonsays 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, with403 worker_paused, and underreviewthe owner can't deploy or resume to end it. The account's workers answer503 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. - 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
retryAfterseconds (30); a checkout then answers with the account's one open link. - This server doesn't sell Beacon Plus: billing isn't set up on it (
GET /v1/capabilitiessays"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 lslists 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.cloudflareCallsPer5MinPerAccountinGET /v1/limits. Nothing was changed, unless the answer hasdeletedorstorageId: then the delete happened and only itspurgeNowpurge waits. WaitretryAfterseconds. content_blocked422- A published file is a native program (a Windows, Linux or macOS executable, under any name), or a
.zipor.tarthat holds one or a script which downloads and runs a program (a malware dropper);errornames 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.detailsays what was found:windows_executable,elf_executableormacho_executable(the file is a program),nested_executable(an archive holds one),script_dropper,windows_shortcut(a.lnk),encrypted_executableorunreadable_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) andscan_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:
cronholds it anderrorsays 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, whencronsin.beacon/config.jsonisn'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/capabilitiessays"crons": false). Nothing was uploaded. Removecronsand 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
retryAfterseconds. deployment_not_found404- The rollback's
deploymentIdisn't one of this worker's deployments.GET /v1/workers/:slug/deploymentslists 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.
erroranddetailcarry Cloudflare's message,cloudflareErrorsits error list, anddocsits 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
retryAfterseconds and send the request again. The CLI'sdeploy,delete,secret set,secret del,storage destroy,storage restoreandd1 migrations applydo this themselves, up to 3 times (10 s when there is noretryAfter), before they report it. They wait silently in JSON mode, so stderr still holds one JSON error;--prettyor--verboseprints 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) andafter(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 andupgradeoffer 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
operationIdwhen the response has one. Withdone, the change was made but Beacon couldn't record that its operation succeeded (Beacon marks the operationuncertainwhen it can);donesays 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'senv(env.DBisDB). Nothing was uploaded. The CLI answers the same code, before any request, for a--delete-storagename that isn't a binding name. invalid_metadata400- The deploy's
metadatapart is malformed or a value is out of range, and the message names the field: not JSON, noentryPoint, a badcompatibilityDate,location,jurisdictionor var, or arenamedFromthat 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:
metadatais 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.detailnames the file when it can. - Live logs aren't switched on for this server yet (
GET /v1/capabilitiessays"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.retryAfteris how many seconds until the next create fits. On Free, the hint andupgradeoffer 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 getting403 worker_paused, until you deploy it again or resume it. The worker'sstate.holds(GET /v1/workers/:slug) lists those pauses before and after subscribing. Carriesupgrade, asstorage_kind_not_enableddoes. 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
deletedorstorageId: then the delete happened and only itspurgeNowpurge waits (seepurgeNow). WaitretryAfterseconds. - Cloudflare failed or couldn't be reached. Send the request again, after
retryAfterwhen the answer has one; an export sent again sooner gets429 data_rate_limited. A secret set or delete right after a deploy gets it withretryAfter10 while Cloudflare catches up with the deploy, and a delete that gets it leaves the secret listed until a delete succeeds. The CLI'ssecret setandsecret delwait it out themselves, up to 3 times (5 s when there is noretryAfter), before they report it. They wait silently in JSON mode, so stderr still holds one JSON error;--prettyor--verboseprints 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
promotionCodematches 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);detailcarries 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_allowed403purgeNow=trueon 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;
errorsays which. WaitretryAfterseconds (theRetry-Afterheader says the same), when the hour turns over, then send the request again. Rate limits andGET /v1/limitslist 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
retryAfterseconds, or choose another slug. - 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 (
bindingsnames 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-leveldurableObjects, ...); the message names the key. Refused for every account insidestorage, and elsewhere where storage mode covers the account (otherwise ignored withresource_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 upgradeprints a checkout link). Or remove the binding (d1.<BINDING>) from the config and deploy again.upgradedescribes the plan:{"plan": "plus", "name": "Beacon Plus", "priceUsdMonthly": 4, "url": "https://beacon.host/pricing", "checkout": "https://beacon.host/dashboard?view=plan"}. It is never infix.run: subscribing is the user's decision, so tell them instead of opening it. AdurableObjectsdeclaration is refused the same way, withoutupgrade: 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.storagedescribes every binding and what deleting it would do, andnotNamedlists 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
retryAfterseconds 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;heldStoragelists both. With"detail": "d1_size", the account's D1 data is at its size limit (limitandused, in bytes): new databases, migrations and D1 API writes other thanDELETEandDROPwait. Delete rows or destroy a database; workers keep serving until the data reaches twice the limit (Pauses and suspensions). - 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 oncontroller.croninside onescheduled()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
fieldslists every unknown top-level key. The hint names the keys the server reads:entryPoint,compatibilityDate,compatibilityFlags,crons,vars,storage,confirmandskipBindingCheck. A key that names a Cloudflare resource is never unknown: wherestorage_field_not_allowedrefuses it, that answer comes first, and where it is only aresource_key_ignoredwarning, unknown keys beside it are still refused. A top-level"d1"is the config file's shape: in the metadata, D1 bindings go understorage.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
varson an account without Beacon Plus. The hint links https://beacon.host/pricing: only the account owner can subscribe (beacon upgradeprints a checkout link). Or move the values to secrets (beacon secret set NAME). Carriesupgrade, asstorage_kind_not_enableddoes. 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.runholdsbeacon deploy).beacon storage plangives it too before the first deploy (from the server's 404), since there is no storage to plan against:beacon deploy --dry-run(itsfix.run) previews the databases and migrations that deploy creates. worker_paused403- A pause refused the call.
reasonsays 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 runbeacon 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 runbeacon 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.
503 worker_pausedmeanwhile. 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 answers503 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 (torollbackTo, a deployment from before them, when there is one), then restore; or undo the restore with the command indetail. 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.
- From
GET /v1/workers/:slug/crons: the run history couldn't be read, sorunsis 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,
virtualTableslists the others, andappendSqlcreates 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
locationof 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 … COMMITwrapping 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 thenodejs_compatcompatibility 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.
lostWritesSincesays from when writes are gone;undoreverses 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 receivestorage_field_not_allowedinstead, and insidestorageevery 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
bindingkeeps 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.detailnames the restore that would undo them (beacon d1 restore DB --before-op OP --yes, RESTPOST /v1/workers/:slug/d1/DB/restore?confirm=DBwith{"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.", withusedBytesandlimitBytes). From deploys, and instorage.warningsofGET /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.configputs it back with its jurisdiction and location (the CLI adds the migrations folder of the last deploy), or suggestsrenamedFromwhen the same deploy adds one new binding;detailnames 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.runrestores it (beacon storage restore <BINDING>, RESTPOST /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 storageuntil 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 instorage.d1. Declare it there, or drop its files. confirm_mismatch400- The migrations request's
confirmnames something other than the binding in the URL.destructiveMigrationslists binding names, never files:{"confirm": {"destructiveMigrations": ["DB"]}};reapplyMigrationsmaps 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: truemeans 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_migrationsby something else; if no file ran as it, take it out withbeacon 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_migrationslacks, 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_unknown422resolve --mark-appliednamed a file Beacon has no record of: the database'sd1_migrationsdoesn't have it, and Beacon never sent it. Check the name withbeacon 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 bookmarkslists 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 bookmarksor a restore'spreviousBookmark. 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 DBin the CLI, or"confirm": {"destructiveMigrations": ["DB"]}(the binding's name, never the file's) in the deploy metadata or the body ofPOST /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.jsonhas a Cloudflare (wrangler) setting that Beacon doesn't read:kv,kv_namespaces,kvNamespaces,d1_databases,durable_objects,bindingsordatabase_id, named inkey.hintexplains it;fix.config, when present, is a merge patch with Beacon's form of the setting. Several such keys give one error with anerrorsentry each.storage_on_siteCLI- Storage and vars belong to workers. A static site cannot declare them.
invalid_compatibility_dateCLIcompatibilityDatein.beacon/config.jsonisn't aYYYY-MM-DDdate. 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-Aftergives the seconds until 00:00 UTC andresetsAtthe 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.