# ByteBeacon

> Agent-first form backend: unlimited submissions on every tier. One API call
> gets you a working form endpoint. No human required to integrate.

Base URL: https://api.bytebeacon.com (locally http://localhost:8080). Every
API path — /v1, /s, /submit — is on that origin. https://app.bytebeacon.com is
the human dashboard and serves no API route; https://bytebeacon.com is the
marketing site. Where the docs write $BASE, they mean the API origin.

This file is served verbatim from TWO origins: https://bytebeacon.com/llms.txt
and https://api.bytebeacon.com/llms.txt. That is why the links below are
absolute — a relative link would resolve against whichever host answered, and
only one of the two serves raw markdown. They point at the raw .md on the API
because you are an agent and markdown is what you want; the same source
rendered for humans lives at https://bytebeacon.com/docs/ (no .md on those
URLs). Running it yourself: those links stay hosted, so read
http://localhost:8080/docs/quickstart.md from your own instance instead.

## Docs
- [Quickstart](https://api.bytebeacon.com/docs/quickstart.md): zero to receiving submissions in two curls
- [API reference](https://api.bytebeacon.com/docs/api.md): every endpoint, error code, and reserved field
- [OpenAPI](https://api.bytebeacon.com/openapi.json): machine-readable schema

## The short version
1. POST /v1/accounts {"email": "you@example.com"} → returns secret_key + form_id
2. Point an HTML form at POST /s/{form_id} (or POST /submit with a hidden
   access_key field). Submissions are stored; read them with the secret key.
3. GET /v1/submissions?form_id=... with "Authorization: Bearer <secret_key>"

## Your limits and usage
Unlimited by default, on every tier. GET /v1/me returns your organization's
`limits` — `rate_per_second`, `quota_per_day` (`null` means unlimited, never 0)
and `usage_last_24h`. GET /v1/forms returns the same per form, plus
`effective_rate_per_second` / `effective_quota_per_day`: the min() of the form's
lever and the organization's, which is the value that actually applies. Only
ByteBeacon can change a limit; there is no endpoint that raises your own.
Refusals are 429 `rate_limited` (too fast, retry in about a second) and 429
`quota_exhausted` (out for the rolling day), both with Retry-After.

There is a third: 429 `rate_restricted`, and it is the one you must NOT retry.
It means ByteBeacon is holding this account's rate below the published
`rate_per_second`, and it persists until a human at ByteBeacon lifts it — so it
carries no Retry-After, because no interval would make a retry succeed. Stop
sending and contact support. `GET /v1/me` publishes the same state up front as
`limits.rate_restricted` (boolean), so an agent can see it without being
refused first; if you are getting refused and the published `rate_per_second`
does not explain it, that field is the answer. The threshold behind it is
deliberately not published. Branch on `code`: wait a second, wait for the
window, or stop and talk to us — three different instructions.

## Lost or leaked your key?
The plaintext is never recoverable (only its hash is stored), but keys are
self-service: GET /v1/keys lists them, POST /v1/keys mints a replacement
(shown once), DELETE /v1/keys/{id} revokes one. Rotate by creating the new key
first, then revoking the old one — the API refuses to revoke your last active
key, so you cannot lock yourself out. None of this is tier-gated.