Call the API
first API calls
curl https://api.blobyard.com/v1/health
curl -H "Authorization: Bearer $BLOBYARD_TOKEN" https://api.blobyard.com/v1/cli/whoamiThe base URL is https://api.blobyard.com/v1. Every response carries an X-Request-Id header and a matching requestId field. Rate-limited responses add Retry-After.
Read the response envelope
success and error envelopes
{
"ok": true,
"data": {},
"requestId": "req_9f2c4c8a"
}
{
"ok": false,
"error": { "code": "AUTH_REQUIRED", "message": "Sign in with blobyard login." },
"requestId": "req_9f2c4c8a"
}Successful responses wrap the payload in data. Failures return one stable error code and a redaction-safe message. Branch on ok and error.code, never on message text.
Choose an authentication mode
- CLI session tokens: opaque bearer tokens issued by the device flow, fifteen-minute access with rotating refresh.
- API tokens: byd_pat_ prefixed bearer tokens created in Settings or with blobyard tokens create, with explicit scopes and a bounded expiry.
- CI machine tokens: minted by posting a GitHub OIDC assertion to /v1/ci/github/oidc/exchange, valid for at most fifteen minutes.
- Capability tokens: high-entropy public tokens for shares and inboxes, passed as a token query parameter or request-body field.
Find the route
| Area | Routes |
|---|---|
| Device and session | POST /cli/device/start, POST /cli/device/poll, POST /cli/token/refresh, POST /cli/logout, GET /cli/whoami |
| Workspaces and projects | GET and POST /workspaces, GET and POST /projects |
| Uploads | POST /uploads/request, /uploads/parts/request, /uploads/complete, /uploads/abort, GET /uploads/status |
| Objects | GET and DELETE /objects, POST /downloads/request |
| Shares | POST and GET /shares, GET /shares/resolve, POST /shares/download, POST /shares/revoke |
| Previews | POST and GET /previews, POST /previews/revoke |
| Inboxes | POST and GET /inboxes, GET /inboxes/resolve, POST /inboxes/revoke |
| Retention | GET, PUT, and DELETE /retention |
| Web Yards | GET /yards, POST /yards/deploys/start, POST /yards/deploys/finalise, POST /yards/deploys/fail, GET /yards/deploys, POST /yards/rollback, POST /yards/delete |
| Automation | POST /ci/github/oidc/exchange |
| Workspace administration | GET /audit, GET /members, GET and POST /members/invites, POST /members/invites/revoke, POST /members/role, POST /members/remove |
| API tokens, CI trusts, and CLI sessions | GET and POST /api-tokens, POST /api-tokens/revoke, GET and POST /ci/trusts, POST /ci/trusts/revoke, GET /cli/sessions, POST /cli/sessions/revoke |
| Billing | GET /billing, POST /billing/checkout, POST /billing/portal, POST /billing/subscription/update, POST /billing/storage/checkout, POST /billing/storage/update |
| Account lifecycle | GET and POST /account/exports, POST /account/exports/download, GET /account/deletion, POST /account/deletion/prepare, POST /account/deletion/complete, POST /account/deletion/retry |
| One-time secrets | POST /secrets, POST /secrets/redeem |
This page summarizes the current 73-operation release candidate by workflow. The generated OpenAPI document is the complete method, path, schema, and surface inventory for this build. Production clients should compare it with the deployed document before assuming a release candidate route is live.