Tham chiếu API REST

Mọi thao tác của API Belvador: đường gọi, quyền cần có, thao tác nào cần người duyệt, cách chống gửi lặp và khoá phiên bản; sinh từ cùng danh sách máy chủ dùng.

Bản Markdown

Trong bài này

Cơ bản
Duyệt thao tác
Các thao tác

Trạng thái: đang chạy (beta). REST API trả lời ở https://api.belvador.dev. Trang này sinh ra từ đúng danh sách thao tác mà cổng API chạy, nên chỉ thay đổi khi API thay đổi. Công cụ hỗ trợ OAuth có thể kết nối bằng cách đăng nhập thay vì dùng token. Coding agent dùng được đúng các thao tác này qua MCP server.

Cơ bản#

Địa chỉ gốc: https://api.belvador.dev/v1. JSON dùng snake_case, thời gian theo RFC 3339 giờ UTC, mã định danh là chuỗi.
Xác thực: gửi token cá nhân (blv_pat_…, tạo ở Tài khoản → API token) hoặc token service (blv_svc_…, tạo ở Cài đặt workspace → Service account) trong header Authorization dạng Bearer blv_… (các loại khoá). Token sống tối đa 365 ngày. Token chỉ dùng được trong workspace của nó, trong các project và môi trường được cấp, và không bao giờ vượt vai trò hiện tại của người hoặc service account đứng sau.
Đăng nhập bằng OAuth: công cụ hỗ trợ OAuth 2.1, ví dụ MCP client, tìm Belvador qua https://api.belvador.dev/.well-known/oauth-protected-resource và https://belvador.dev/.well-known/oauth-authorization-server. Công cụ tự đăng ký (RFC 7591, hoặc Client ID Metadata Document), đưa bạn tới belvador.dev để chọn workspace và quyền, và phải dùng PKCE với S256. Access token (blv_oat_…) sống 60 phút; refresh token (blv_ort_…) đổi sau mỗi lần dùng và dừng sau 30 ngày không dùng. Một mã hoặc refresh token bị dùng hai lần sẽ chấm dứt kết nối đó — hai lần refresh gửi cùng lúc cũng tính là dùng lại, nên hãy refresh lần lượt. Xem và ngắt kết nối ứng dụng ở Tài khoản → Ứng dụng đã kết nối.
Lỗi theo RFC 9457 (application/problem+json): code là mã lỗi cố định, request_id nhận diện lời gọi, errors[].pointer chỉ từng trường sai, ví dụ /name.
Tạo mới cần header Idempotency-Key. Gửi lại cùng khoá với cùng nội dung trong 24 giờ sẽ nhận lại đúng câu trả lời lần đầu, có Idempotent-Replayed: true, và không tạo thêm gì. Bí mật chỉ hiện một lần trong câu trả lời đó (ping token, khoá) không bao giờ được lặp lại: lần gửi lại trả null và ghi tên trường trong Belvador-Secret-Withheld. Cùng khoá nhưng nội dung khác bị từ chối với 422 IDEMPOTENCY_KEY_REUSED.
Sửa hoặc xoá monitor, uptime check, SLO, cấu hình project hay quy tắc cảnh báo cần If-Match với ETag bạn đọc gần nhất. Thiếu thì nhận 428; nếu ai đó đã sửa trong lúc đó thì 412 — đọc lại rồi thử lại.
Danh sách trả { "data": [...], "next_cursor": "...", "complete": true }. Gửi cursor cùng bộ lọc cũ để lấy trang sau; cursor dùng được 24 giờ và chỉ cho đúng danh sách đã tạo ra nó.
Thao tác nhạy cảm — khoá, thành viên, nơi nhận cảnh báo, thay đổi node — trả 403 APPROVAL_REQUIRED và chờ một người duyệt; xem Duyệt thao tác.
Dữ liệu nằm trên node của bạn (issue, event, trace, log, lượt chạy monitor) được đánh dấu dữ liệu node bên dưới. Cổng API đọc từ node của bạn bằng vé chỉ dùng được vài phút rồi chuyển nguyên câu trả lời; máy chủ của Belvador không lưu và không ghi log phần này. Node đang tắt thì nhận 503 NODE_OFFLINE — không có bản sao nào để trả thay. Tìm trace và log cần start và end, cách nhau tối đa 168 giờ.
Giới hạn tốc độ: 300 lời gọi mỗi phút cho mỗi token và 1200 cho cả workspace, tối đa 4 lời gọi dữ liệu node cùng lúc cho mỗi token. Mọi câu trả lời có header IETF RateLimit-Policy và RateLimit; vượt giới hạn thì nhận 429 RATE_LIMITED kèm Retry-After.
Tắt đi: thu hồi token thì token ngừng chạy trong khoảng 30 giây. Khi khẩn cấp, Belvador có thể tạm dừng API cho một workspace hoặc cho tất cả; lúc đó lời gọi nhận 503 PUBLIC_API_PAUSED, còn app vẫn chạy bình thường.

Duyệt thao tác#

Thao tác nhạy cảm không bao giờ chạy thẳng từ token: khoá DSN, khoá upload và ingest, ping token, thành viên và lời mời, token và service account, nơi nhận cảnh báo và thay đổi node. Trong danh sách bên dưới chúng được đánh dấu cần duyệt.

Lời gọi trả 403 APPROVAL_REQUIRED kèm approval_id, approval_url (một trang trên belvador.dev), expires_at và state, cùng header Link: <…>; rel="approval". Chưa có gì thay đổi.
Một người mở link, xem đúng những gì sẽ thay đổi, rồi duyệt bằng mã từ ứng dụng xác thực không cũ hơn 10 phút — hoặc từ chối. Đa số thao tác cần admin; xoá, dựng lại hay khôi phục node cần owner; token cá nhân mới chỉ chính người giữ token đó duyệt được. Yêu cầu từ service account và ứng dụng OAuth còn được gửi email cho owner và admin của workspace.
Gửi lại đúng lời gọi với cùng Idempotency-Key, hoặc hỏi GET /v1/approvals/{approval_id}, để biết kết quả: executed kèm các mã định danh vừa tạo (200), rejected, expired sau 15 phút (410), hoặc failed với lý do trong code.

Những điều luôn đúng:

Chỉ chạy đúng yêu cầu người duyệt đã xem, một lần, dưới tên người đó. Nếu yêu cầu đã lưu không còn khớp, hoặc token bị thu hồi hay mất quyền trong lúc chờ, thao tác thất bại và không có gì chạy.
Bí mật được tạo ra — khoá mới, token hay link mời — chỉ hiện một lần cho người duyệt, không bao giờ cho bên gọi.
Những gì người duyệt phải tự gõ — tên project hay node để xác nhận xoá, token bot, webhook URL hay mật khẩu mail — không bao giờ nhận từ bên gọi.
Mỗi workspace có tối đa 20 yêu cầu đang chờ; quá số đó nhận 429 RATE_LIMITED.
failed với APPROVAL_OUTCOME_UNKNOWN nghĩa là đã được duyệt nhưng kết quả chưa được ghi lại. Hãy kiểm tra lại tài nguyên trước khi yêu cầu lại.

Các thao tác#

`alert_deliveries`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/alert-deliveries/{delivery_id}/replay`	`alerts:write`	admin	—

`alert_rules`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/alert-rules`	`alerts:read`	viewer	phân trang
`POST /v1/alert-rules`	`alerts:write`	admin	—
`PUT /v1/alert-rules/{rule_id}/enabled`	`alerts:write`	admin	—
`DELETE /v1/alert-rules/{rule_id}`	`alerts:write`	admin	`If-Match`

`alerts`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/alerts`	`alerts:read`	viewer	phân trang

`approvals`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/approvals/{approval_id}`	`org:read`	viewer	—

`audit`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/audit-log`	`audit:read`	admin	phân trang

`coverage`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/coverage`	`coverage:read`	viewer	—
`PUT /v1/projects/{project_id}/coverage-expectations`	`coverage:write`	member	—

`deployments`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/projects/{project}/deployments`	`releases:write`	member	dữ liệu node

`destinations`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/destinations`	`alerts:read`	viewer	phân trang
`POST /v1/destinations`	`destinations:manage`	admin	cần duyệt · `Idempotency-Key`
`PATCH /v1/destinations/{destination_id}`	`destinations:manage`	admin	cần duyệt
`POST /v1/destinations/{destination_id}/connection`	`destinations:manage`	admin	cần duyệt
`DELETE /v1/destinations/{destination_id}`	`destinations:manage`	admin	cần duyệt
`PUT /v1/destinations/{destination_id}/recipients`	`destinations:manage`	admin	cần duyệt
`POST /v1/destination-recipients/{recipient_id}/resend`	`destinations:manage`	admin	—
`POST /v1/destinations/{destination_id}/test`	`notifications:write`	admin	—

`events`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/issues/{issue_id}/events`	`events:read`	viewer	dữ liệu node · phân trang
`GET /v1/issues/{issue_id}/events/{event_id}`	`events:read`	viewer	dữ liệu node

`incident_rules`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/incident-rules`	`alerts:read`	viewer	—
`POST /v1/incident-rules`	`alerts:write`	admin	—
`DELETE /v1/incident-rules/{rule_id}`	`alerts:write`	admin	—

`incidents`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/incidents`	`incidents:read`	viewer	phân trang
`GET /v1/incidents/{incident_id}`	`incidents:read`	viewer	—
`POST /v1/incidents/{incident_id}/ack`	`incidents:write`	member	—
`POST /v1/incidents/{incident_id}/resolve`	`incidents:write`	member	—
`POST /v1/incidents/{incident_id}/notes`	`incidents:write`	member	—
`PATCH /v1/incidents/{incident_id}`	`incidents:write`	member	—

`ingest_keys`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/projects/{project_id}/ingest-keys`	`keys:manage`	member	cần duyệt · `Idempotency-Key`
`DELETE /v1/ingest-keys/{key_id}`	`keys:manage`	member	cần duyệt

`invites`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/invites`	`members:manage`	admin	cần duyệt · `Idempotency-Key`
`DELETE /v1/invites/{invite_id}`	`members:manage`	admin	—

`issues`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/issues`	`issues:read`	viewer	dữ liệu node · phân trang
`GET /v1/issues/{issue_id}`	`issues:read`	viewer	dữ liệu node
`GET /v1/issues/{issue_id}/stats`	`issues:read`	viewer	dữ liệu node
`GET /v1/issues/{issue_id}/tags`	`issues:read`	viewer	dữ liệu node
`GET /v1/issues/{issue_id}/activity`	`issues:read`	viewer	dữ liệu node
`GET /v1/issues/{issue_id}/fix-status`	`releases:read`	viewer	dữ liệu node
`PATCH /v1/issues/{issue_id}`	`issues:write`	member	dữ liệu node
`POST /v1/issues/bulk`	`issues:write`	member	dữ liệu node

`logs`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/logs`	`logs:read`	viewer	dữ liệu node · `start`/`end` · phân trang
`GET /v1/logs/histogram`	`logs:read`	viewer	dữ liệu node · `start`/`end`
`GET /v1/logs/facets`	`logs:read`	viewer	dữ liệu node · `start`/`end`
`GET /v1/logs/{log_id}/around`	`logs:read`	viewer	dữ liệu node

`maintenance`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/maintenance-windows`	`monitors:read`	viewer	phân trang
`POST /v1/maintenance-windows`	`monitors:write`	member	`Idempotency-Key`
`PATCH /v1/maintenance-windows/{window_id}`	`monitors:write`	member	—
`DELETE /v1/maintenance-windows/{window_id}`	`monitors:write`	member	—

`members`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/members`	`members:read`	viewer	phân trang
`PATCH /v1/members/{user_id}`	`members:manage`	admin	cần duyệt
`DELETE /v1/members/{user_id}`	`members:manage`	admin	cần duyệt

`metrics`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/metrics/names`	`metrics:read`	viewer	dữ liệu node
`GET /v1/metrics/series`	`metrics:read`	viewer	dữ liệu node · phân trang
`GET /v1/metrics/query`	`metrics:read`	viewer	dữ liệu node · `start`/`end`

`monitors`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/monitors`	`monitors:read`	viewer	phân trang
`GET /v1/monitors/{monitor_id}`	`monitors:read`	viewer	—
`POST /v1/monitors`	`monitors:write`	member	`Idempotency-Key`
`PATCH /v1/monitors/{monitor_id}`	`monitors:write`	member	`If-Match`
`DELETE /v1/monitors/{monitor_id}`	`monitors:write`	member	`If-Match`
`PUT /v1/monitors/{monitor_id}/pause`	`monitors:write`	member	—
`PUT /v1/monitors/{monitor_id}/mute`	`monitors:write`	member	—
`DELETE /v1/monitor-discoveries/{discovery_id}`	`monitors:write`	member	—
`GET /v1/monitors/{monitor_id}/signal`	`monitors:read`	viewer	dữ liệu node
`GET /v1/monitors/{monitor_id}/occurrences`	`monitors:read`	viewer	dữ liệu node · phân trang
`POST /v1/monitors/backtest`	`monitors:read`	viewer	dữ liệu node

`node`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/node`	`org:read`	viewer	—
`POST /v1/node`	`node:operate`	admin	cần duyệt · `Idempotency-Key`
`POST /v1/node/jobs/{job_id}/retry`	`node:operate`	admin	—
`POST /v1/node/{node_id}/resize`	`node:operate`	admin	cần duyệt
`POST /v1/node/{node_id}/upgrade`	`node:operate`	admin	—
`DELETE /v1/node/{node_id}`	`node:operate`	admin	cần duyệt
`POST /v1/node/{node_id}/restore`	`node:operate`	admin	—
`POST /v1/node/backups`	`node:operate`	admin	—
`PUT /v1/node/backup-custody`	`node:operate`	admin	cần duyệt
`POST /v1/node/{node_id}/rebuild`	`node:operate`	admin	cần duyệt · `Idempotency-Key`
`POST /v1/node/jobs/{job_id}/recovery-kit`	`node:operate`	admin	cần duyệt

`notification_policies`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/notification-policies`	`alerts:read`	viewer	—
`POST /v1/notification-policies`	`alerts:write`	admin	—
`DELETE /v1/notification-policies/{policy_id}`	`alerts:write`	admin	—

`occurrences`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/occurrences`	`monitors:write`	member	dữ liệu node
`DELETE /v1/occurrences/{monitor_slug}/{occurrence_id}`	`monitors:write`	member	dữ liệu node

`ping_tokens`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/monitors/{monitor_id}/ping-tokens/rotate`	`keys:manage`	member	cần duyệt
`POST /v1/monitors/{monitor_id}/ping-tokens/revoke-previous`	`keys:manage`	member	cần duyệt
`POST /v1/monitors/{monitor_id}/ping-tokens/reset`	`keys:manage`	member	cần duyệt

`privacy`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/projects/{project_id}/privacy`	`projects:read`	viewer	—
`PUT /v1/projects/{project_id}/privacy`	`privacy:write`	admin	cần duyệt

`project_keys`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/projects/{project_id}/keys`	`keys:manage`	member	cần duyệt · `Idempotency-Key`
`POST /v1/keys/{key_id}/rotate`	`keys:manage`	member	cần duyệt
`DELETE /v1/keys/{key_id}`	`keys:manage`	member	cần duyệt

`projects`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/projects`	`projects:read`	viewer	phân trang
`GET /v1/projects/{project_id}`	`projects:read`	viewer	—
`POST /v1/projects`	`projects:write`	member	`Idempotency-Key`
`PATCH /v1/projects/{project_id}`	`projects:write`	member	`If-Match`
`PATCH /v1/projects/{project_id}/intake`	`projects:write`	member	`If-Match`
`PATCH /v1/projects/{project_id}/observability`	`projects:write`	member	`If-Match`
`PUT /v1/projects/{project_id}/scrub/{group}`	`privacy:write`	admin	cần duyệt
`PUT /v1/projects/{project_id}/checkin-auth`	`keys:manage`	member	cần duyệt
`PUT /v1/projects/{project_id}/environments/{name}/hidden`	`projects:write`	member	—
`DELETE /v1/projects/{project_id}`	`projects:delete`	admin	cần duyệt
`POST /v1/projects/{project_id}/restore`	`projects:write`	member	—
`POST /v1/projects/{project_id}/test-event`	`projects:write`	member	—

`releases`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/projects/{project}/releases`	`releases:read`	viewer	dữ liệu node
`GET /v1/projects/{project}/releases/{version}/health`	`releases:read`	viewer	dữ liệu node

`service_principals`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/service-accounts`	`tokens:manage`	admin	cần duyệt · `Idempotency-Key`
`PATCH /v1/service-accounts/{id}`	`tokens:manage`	admin	cần duyệt

`slos`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/slos`	`monitors:read`	viewer	phân trang
`GET /v1/slos/{slo_id}`	`monitors:read`	viewer	—
`POST /v1/slos`	`monitors:write`	member	`Idempotency-Key`
`PATCH /v1/slos/{slo_id}`	`monitors:write`	member	`If-Match`
`DELETE /v1/slos/{slo_id}`	`monitors:write`	member	`If-Match`
`PUT /v1/slos/{slo_id}/hold`	`monitors:write`	member	—
`POST /v1/slos/import`	`monitors:write`	member	—

`spans`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/spans`	`traces:read`	viewer	dữ liệu node · `start`/`end` · phân trang
`GET /v1/spans/histogram`	`traces:read`	viewer	dữ liệu node · `start`/`end`

`telemetry`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/telemetry/usage`	`usage:read`	viewer	dữ liệu node

`tickets`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/tickets`	`issues:read`	viewer	dữ liệu node

`tokens`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/tokens`	`tokens:manage`	admin	cần duyệt · `Idempotency-Key`
`POST /v1/service-accounts/{service_principal_id}/tokens`	`tokens:manage`	admin	cần duyệt · `Idempotency-Key`
`DELETE /v1/tokens/{id}`	`tokens:manage`	admin	—
`PUT /v1/token-policy`	`tokens:manage`	admin	cần duyệt

`traces`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/traces/{trace_id}`	`traces:read`	viewer	dữ liệu node
`GET /v1/traces/{trace_id}/spans`	`traces:read`	viewer	dữ liệu node
`GET /v1/traces/{trace_id}/spans/{span_id}`	`traces:read`	viewer	dữ liệu node

`upload_tokens`#

Gọi	Quyền	Vai trò	Ghi chú
`POST /v1/projects/{project_id}/upload-tokens`	`keys:manage`	member	cần duyệt · `Idempotency-Key`
`DELETE /v1/upload-tokens/{token_id}`	`keys:manage`	member	cần duyệt

`uptime`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/uptime-checks`	`monitors:read`	viewer	phân trang
`GET /v1/uptime-checks/{check_id}`	`monitors:read`	viewer	—
`POST /v1/uptime-checks`	`monitors:write`	member	`Idempotency-Key`
`PATCH /v1/uptime-checks/{check_id}`	`monitors:write`	member	`If-Match`
`DELETE /v1/uptime-checks/{check_id}`	`monitors:write`	member	`If-Match`
`PUT /v1/uptime-checks/{check_id}/hold`	`monitors:write`	member	—
`POST /v1/uptime-checks/{check_id}/runs`	`monitors:write`	member	—

`usage`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/usage`	`usage:read`	viewer	—

`workspace`#

Gọi	Quyền	Vai trò	Ghi chú
`GET /v1/workspace`	`org:read`	viewer	—

Thấy chỗ sai hoặc thiếu? Gửi cho chúng tôi: hello@belvador.dev

Tham chiếu API REST

Cơ bản#

Duyệt thao tác#

Các thao tác#

alert_deliveries#

alert_rules#

alerts#

approvals#

audit#

coverage#

deployments#

destinations#

events#

incident_rules#

incidents#

ingest_keys#

invites#

issues#

logs#

maintenance#

members#

metrics#

monitors#

node#

notification_policies#

occurrences#

ping_tokens#

privacy#

project_keys#

projects#

releases#

service_principals#

slos#

spans#

telemetry#

tickets#

tokens#

traces#

upload_tokens#

uptime#

usage#

workspace#