REST API reference

Status: live (beta). The REST API answers at https://api.belvador.dev. This page is generated from the same list of operations the gateway runs, so it changes only when the API does. Tools that support OAuth can connect by sign-in instead of a token. Coding agents can use the same operations through the MCP server.

Basics#

• Base URL: https://api.belvador.dev/v1. JSON uses snake_case, times are RFC 3339 in UTC, ids are strings.

• Authentication: send a personal token (blv_pat_…, from Account → API tokens) or a service token (blv_svc_…, from Workspace settings → Service accounts) in the Authorization header as Bearer blv_… (credentials). Tokens last at most 365 days. A token works only inside its workspace and the projects and environments it was given, and never above the current role of the person or service account behind it.

• Sign in with OAuth: tools that support OAuth 2.1, such as MCP clients, find Belvador from https://api.belvador.dev/.well-known/oauth-protected-resource and https://belvador.dev/.well-known/oauth-authorization-server. They register themselves (RFC 7591, or a Client ID Metadata Document), send you to belvador.dev to pick a workspace and permissions, and must use PKCE with S256. Access tokens (blv_oat_…) last 60 minutes; refresh tokens (blv_ort_…) change on every use and stop after 30 days without use. A code or refresh token used twice ends that connection — two refreshes sent at the same moment count as reuse, so refresh one at a time. See and disconnect apps under Account → Connected apps.

• Errors follow RFC 9457 (application/problem+json): code is the stable error code, request_id identifies the call, and errors[].pointer names each invalid field, for example /name.

• Creating something needs an Idempotency-Key header. Sending the same key with the same body within 24 hours returns the first answer again, marked Idempotent-Replayed: true, and creates nothing new. A one-time secret in that answer (a ping token, a key) is never repeated: the replay shows null and names the field in Belvador-Secret-Withheld. The same key with a different body is refused with 422 IDEMPOTENCY_KEY_REUSED.

• Changing or deleting a monitor, uptime check, SLO, project setting or alert rule needs If-Match with the ETag you last read. Without it the answer is 428; if someone changed it since, 412 — read it again and retry.

• Lists return { "data": [...], "next_cursor": "...", "complete": true }. Pass cursor with the same filters for the next page; a cursor lasts 24 hours and only works for the list that made it.

• Sensitive operations — keys, members, alert destinations, node changes — answer 403 APPROVAL_REQUIRED and wait for a person; see Approvals.

• Data stored on your node (issues, events, traces, logs, monitor runs) is marked node data below. The gateway reads it from your node with a ticket that lasts a few minutes and passes the answer through; Belvador's servers neither store nor log it. If your node is offline the answer is 503 NODE_OFFLINE — nothing is served from a copy. Trace and log searches need start and end, at most 168 hours apart.

• Rate limits: 300 calls per minute per token and 1200 per workspace, and 4 node-data calls in flight per token. Every answer carries the IETF RateLimit-Policy and RateLimit headers; over the limit the answer is 429 RATE_LIMITED with Retry-After.

• Turning it off: revoking a token stops it within about 30 seconds. In an emergency Belvador can pause the API for one workspace or for everyone; calls then answer 503 PUBLIC_API_PAUSED and the app keeps working.

Approvals#

Sensitive operations never run straight from a token: DSN, upload and ingest keys, ping tokens, members and invites, tokens and service accounts, alert destinations and node changes. They are marked approval in the list below.

1. The call answers 403 APPROVAL_REQUIRED with approval_id, approval_url (a page on belvador.dev), expires_at and state, and a Link: <…>; rel="approval" header. Nothing has changed yet.

2. A person opens the link, sees exactly what will change, and approves with a code from their authenticator app no older than 10 minutes — or rejects. Most operations need an admin; deleting, rebuilding or recovering the node needs the owner; a new personal token can only be approved by the token's own holder. Requests from service accounts and OAuth apps are also emailed to the workspace's owners and admins.

3. Send the same request again with the same Idempotency-Key, or poll GET /v1/approvals/{approval_id}, to read the outcome: executed with the ids it produced (200), rejected, expired after 15 minutes (410), or failed with the reason in code.

What always holds:

• It runs exactly the request the person saw, once, as that person. If the stored request no longer matches, or the token was revoked or lost its rights meanwhile, it fails and nothing runs.

• Secrets it creates — a new key, token or invite link — are shown once to the approving person, never to the caller.

• What a person types themselves — the project or node name that confirms a deletion, a bot token, webhook URL or mail password — is never accepted from the caller.

• At most 20 requests wait per workspace; more answer 429 RATE_LIMITED.

• failed with APPROVAL_OUTCOME_UNKNOWN means it was approved but its result was never recorded. Check the resource before asking again.

Operations#

alert_deliveries#

alert_rules#

alerts#

approvals#

audit#

coverage#

destinations#

events#

incident_rules#

incidents#

ingest_keys#

invites#

issues#

logs#

maintenance#

members#

metrics#

monitors#

node#

notification_policies#

occurrences#

ping_tokens#

privacy#

project_keys#

projects#

service_principals#

slos#

spans#

telemetry#

tickets#

tokens#

traces#

upload_tokens#

uptime#

usage#

workspace#