REST API

Rivetr 1.0.0 exposes a JSON REST API built with Axum. Resource routes sit under /api on the API port, which defaults to 8080; /health, /metrics, and /mcp sit at the root. The dashboard and CLI call this API, and MCP uses the same token model on its own endpoint.

The 1.0 release changed dashboard URLs (/settings, /account, /team, /integrations, /keys, /monitoring), but not API paths. Old dashboard URLs redirect; API clients keep the same routes.

Base URL and content type

Archive uploads (/api/apps/{id}/deploy/upload, /api/projects/{id}/apps/upload, /api/build/detect) accept up to 100 MB.

Authentication

X-API-Key: <token> works in place of Authorization. SSE and WebSocket clients that cannot set headers can use ?token=<token>. Admin tokens and API tokens are subject to the API access policy; dashboard sessions are not.

API token scopes

Scopes do not imply each other except admin. A CI token usually needs read,deploy. A token never exceeds its owner's account and team permissions; the role check runs after the scope check. A missing scope returns 403 with {"error":{"code":"insufficient_scope", ...}}.

Optional restrictions narrow a token: team_id limits it to one team, and resources limits it to listed projects, apps, databases, or services. Restricted tokens cannot call admin routes or use MCP. Tokens support expires_at, pause and resume, and roll with a grace period. A paused token gets 401. Omitting scopes on creation grants every scope.

API access policy

Admins can turn token authentication on or off and allow only listed source addresses under Settings > Advanced. The settings are api_access_enabled and api_allowed_ips (IPs or CIDRs; an empty list allows every source). The policy applies to the admin token and API tokens, not dashboard sessions, so an admin cannot lock themselves out of the dashboard.

{"error":{"code":"api_access_denied","message":"API access is not allowed from this IP address"}}

Rate limits

Defaults, configurable under [rate_limit] in rivetr.toml:

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceeding a limit returns 429 with Retry-After. Login and 2FA validation also lock an account after 5 failures in 15 minutes, with exponential backoff up to 15 minutes.

Pagination and errors

Most collection routes return a JSON array of every visible row: /api/apps, /api/databases, /api/services, /api/projects, and similar. Three log routes paginate with page (1-indexed) and per_page: /api/audit (default 50, max 100), /api/webhook-events (default 50, max 200), and /api/proxy/logs (default 100, max 1000). Paginated responses use {"items": [], "total": 0, "page": 1, "per_page": 50, "total_pages": 0}; proxy logs also include total_capped.

Errors use one envelope, with optional field-level details:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed for 1 field",
    "details": {"name": ["Name cannot be empty"]}
  }
}

Common codes: bad_request, unauthorized, forbidden, not_found, conflict, validation_error, too_many_requests, two_factor_required, internal_error, service_unavailable, insufficient_scope, api_access_denied.

Streaming

App logs stream over SSE at GET /api/apps/{id}/logs/stream with Accept: text/event-stream. Events are connected, log, end, and error; a keep-alive comment is sent while idle. WebSocket routes authenticate with ?token=:

Endpoint catalog

Core resources

Platform resources

Operations

Examples

Create a scoped token. The secret is returned once as token:

curl -X POST https://rivetr.example.com/api/tokens \
  -H "Authorization: Bearer $RIVETR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy","scopes":["read","deploy"],"expires_at":"2027-01-01T00:00:00Z"}'

List apps, deploy, and stream logs:

curl -H "Authorization: Bearer $RIVETR_TOKEN" \
  https://rivetr.example.com/api/apps

curl -X POST -H "Authorization: Bearer $RIVETR_TOKEN" \
  https://rivetr.example.com/api/apps/$APP_ID/deploy

curl -N -H "Accept: text/event-stream" \
  "https://rivetr.example.com/api/apps/$APP_ID/logs/stream?token=$RIVETR_TOKEN"

Open a container terminal over WebSocket:

websocat "wss://rivetr.example.com/api/apps/$APP_ID/terminal?token=$RIVETR_TOKEN"

Related pages

• CLI for status, apps, deploy, and logs against the same API.
• MCP Server for the 11 tools exposed at POST /mcp.