API reference
REST · gRPC · WebSocket — same operations, three wire formats.
Everything Beacons does is in the API. The console is a client. The CLI is a client. The SDKs are clients. The API is versioned at /v1, OpenAPI 3.1 + protobuf published, and every request emits an audit event.
Authentication
/v1 — authentication.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/auth/challenge | Get an AEGIS challenge to sign |
| POST | /v1/auth/verify | Submit signed challenge + Arsenal ACT |
| POST | /v1/auth/refresh | Refresh session bound to your ACT |
Fleets
/v1 — fleets.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/fleets | List fleets your session can see |
| POST | /v1/fleets | Create a fleet (governance, trust roots) |
| GET | /v1/fleets/:id | Fleet detail incl. policy summary |
| PATCH | /v1/fleets/:id | Update governance |
| DELETE | /v1/fleets/:id | Tear down (drains peers, archives audit chain) |
Peers
/v1 — peers.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/fleets/:id/peers | Enroll a peer (composite verdict) |
| GET | /v1/fleets/:id/peers | List peers + states + transports |
| GET | /v1/peers/:id | Peer detail incl. lineage walk |
| PATCH | /v1/peers/:id | Rename, tag, restrict transports |
| DELETE | /v1/peers/:id | Revoke (chain teardown, audit event) |
Policy
/v1 — policy.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/fleets/:id/policy | Derived ACL snapshot |
| PUT | /v1/fleets/:id/governance | Replace governance manifest |
| POST | /v1/fleets/:id/policy/recompute | Force recomputation |
| GET | /v1/fleets/:id/policy/exceptions | Manual ACL overrides |
Audit
/v1 — audit.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/fleets/:id/audit | Stream of hash-chained events |
| GET | /v1/fleets/:id/audit/anchors | Sigil anchor history |
| GET | /v1/fleets/:id/audit/verify | Verify chain root vs Sigil |
Transports
/v1 — transports.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/transports | Available transports for the fleet |
| POST | /v1/peers/:id/transports | Negotiate a new transport (e.g. cellular fallback) |
Cellular
/v1 — cellular.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/cellular/sims | Order SIMs from a provider |
| GET | /v1/cellular/sims | Inventory + usage |
| POST | /v1/cellular/sims/:iccid/suspend | Suspend a SIM at the provider + drop routes |
| POST | /v1/cellular/esim/profiles | Mint an eSIM profile (internal API consumed by Locks) |
Realtime
/v1 — realtime.
| Method | Path | Purpose |
|---|---|---|
| WS | /v1/fleets/:id/events | Live audit + telemetry stream |
| gRPC | beacons.v1.PeerService | High-throughput agent enrollment |