API Reference
PremiumREST API for config sync, server memory, AI proxy, and team management. Available on the Solo and Teams plans.
All endpoints are served from https://servonaut.dev.
Paths are grouped by prefix:
/api/v1/*— versioned REST API (configs, teams, memory, billing, health, usage)./api/oauth/*— OAuth 2.0 device flow (unversioned, stable)./api/ai/*— Servonaut AI proxy (unversioned)./api/cli/*— CLI relay endpoints (heartbeat, status, Mercure token)./api/entitlements— current user entitlements snapshot./mcp/*— MCP server (SSE transport for AI tool calls).
Authentication
Servonaut uses OAuth 2.0 Device Flow (RFC 8628) for authentication. This flow is designed for CLI tools and devices that cannot open a browser themselves.
Device flow steps
- The CLI requests a device code from
POST /api/oauth/device. - The user opens the verification URL in a browser and enters the user code.
- The CLI polls
POST /api/oauth/tokenuntil the user approves. - On approval, the CLI receives an access token and a refresh token.
While the user has not yet approved, the token endpoint returns
authorization_pending (HTTP 400). If the CLI polls faster than the
advertised interval, the server responds with slow_down
and a new minimum interval.
Refreshing an access token
Tokens can be revoked at any time via POST /api/oauth/revoke.
Using the access token
Include the token as a Bearer credential in the Authorization header on every API request.
Config Sync
Store, list, and restore versioned configuration snapshots from the Servonaut cloud.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/configs |
List your config snapshots (paginated). |
| GET | /api/v1/configs/latest |
Get the most recent snapshot. |
| GET | /api/v1/configs/{id} |
Get a specific snapshot by id. |
| POST | /api/v1/configs |
Push a new config snapshot. |
| POST | /api/v1/configs/{id}/restore |
Restore a specific snapshot as the active config. |
| PATCH | /api/v1/configs/{id} |
Update a snapshot's label. |
| DELETE | /api/v1/configs/{id} |
Delete a snapshot. |
Server Memory
Persisted snapshots of each managed server's OS, runtime, services, and configuration. Used by both the CLI and the AI proxy as ground-truth context.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/memory |
List your managed instances and their latest snapshot times. |
| POST | /api/v1/memory/instances |
Register or update an instance. |
| POST | /api/v1/memory/sync |
Push a batch of module snapshots collected by the CLI. |
| GET | /api/v1/memory/{instance_id} |
List modules available for an instance. |
| GET | /api/v1/memory/{instance_id}/{module} |
Latest snapshot of a single module. |
| GET | /api/v1/memory/{instance_id}/{module}/history |
Snapshot history for a module (paid plans). |
| POST | /api/v1/memory/{instance_id}/restore/{snapshot_id} |
Restore a prior snapshot as the active state. |
| GET | /api/v1/memory/drift |
List detected configuration drift events. |
| GET | /api/v1/memory/anomalies |
List detected anomalies awaiting acknowledgement. |
| GET | /api/v1/memory/fleet |
Fleet-wide rollup across all instances. |
Servonaut AI Solo & Teams
Hosted AI proxy — chat, log analysis, server triage, and tool-use via the CLI relay.
Requires an active Solo or Teams subscription. Requests are authenticated with your
Bearer token. Spend is metered against your monthly budget; query
GET /api/entitlements for current budget and usage.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/ai/chat |
Streaming AI chat (Server-Sent Events). JSON body with a messages array. |
| POST | /api/ai/chat/tool-result |
Return the result of a tool call back to an in-flight conversation. |
| GET | /api/ai/conversations |
List your AI conversation history (paginated). |
| GET | /api/ai/conversations/{id} |
Retrieve a single conversation with all messages. |
| PATCH | /api/ai/conversations/{id} |
Rename or tag a conversation. |
| DELETE | /api/ai/conversations/{id} |
Delete a conversation. |
| GET | /api/ai/conversations/{id}/export.json |
Export a conversation as JSON. |
| GET | /api/ai/conversations/{id}/export.md |
Export a conversation as Markdown. |
| POST | /api/ai/topup/checkout |
Create a Stripe Checkout session to purchase an AI top-up pack. |
Entitlements
A single read endpoint that returns the user's current plan, feature flags, quotas, and AI budget. The CLI caches this response and re-fetches it on demand. New fields are added over time without breaking existing consumers.
Teams
Team management endpoints are available on the Teams plan. Teams are addressed by slug.
Team lifecycle
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/teams |
List teams you belong to. |
| POST | /api/v1/teams |
Create a new team. |
| GET | /api/v1/teams/{slug} |
Get team details, members, and quotas. |
| PUT | /api/v1/teams/{slug} |
Update team name or settings. |
| DELETE | /api/v1/teams/{slug} |
Delete a team. |
| GET | /api/v1/teams/{slug}/audit |
Retrieve the team audit trail (paginated). |
Team members
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/teams/{slug}/members |
Invite a new member by email. |
| POST | /api/v1/teams/{slug}/members/{memberId}/resend |
Resend a pending invitation email. |
| PUT | /api/v1/teams/{slug}/members/{memberId} |
Update a member's role (owner, admin, member). |
| DELETE | /api/v1/teams/{slug}/members/{memberId} |
Remove a team member. |
Team-shared servers, configs, and memory
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/teams/{slug}/servers |
List servers shared with the team. |
| POST | /api/v1/teams/{slug}/servers |
Share a server with the team. |
| GET | /api/v1/teams/{slug}/configs |
List shared team config snapshots. |
| GET | /api/v1/teams/{slug}/memory |
List server-memory instances visible to the team. |
| PUT | /api/v1/teams/{slug}/ssh-config |
Update the team's shared SSH configuration. |
| GET | /api/v1/teams/{slug}/secrets-config |
Read the team's secrets-manager configuration. |
Health
GET /api/v1/health is a public, unauthenticated readiness probe.
Returns 200 OK with a JSON body when the application is serving traffic.
Rate limits and quotas
All authenticated endpoints are rate-limited per user, with a separate global
circuit breaker on the OAuth device-flow endpoints. The active buckets and
limits are defined in config/packages/rate_limiter.yaml and can
change between releases — always consult the response headers below for the
current state of your bucket.
Rate-limit headers are returned on every authenticated response:
Snapshot-count and AI-spend quotas are plan-specific and surfaced through
GET /api/entitlements. The pricing page lists the current per-plan limits.
Error responses
All errors use a consistent JSON envelope: an error code (machine-readable),
a human-readable message, and — where applicable — extra fields like
upgrade_url, required_tier, or retry_after.
Common error codes
| HTTP status | Error code | Description |
|---|---|---|
400 | invalid_request | Malformed request body or missing required field. |
401 | unauthorized | Missing or invalid access token. |
402 | payment_required | The endpoint requires a paid plan. Body includes upgrade_url. |
403 | forbidden | Token does not have permission for the requested resource. |
403 | forbidden_entitlement | Your plan does not include this feature. Body includes upgrade_url. |
404 | not_found | Resource does not exist. |
422 | validation_failed | Request body failed validation. Body may include a fields map. |
429 | rate_limited | Rate limit exceeded. Retry after Retry-After seconds. |
429 | quota_exceeded | Plan quota exhausted (snapshots, instances, AI spend, etc.). |
503 | feature_disabled | The feature is temporarily unavailable. Honor the Retry-After header. |
500 | internal_error | Server error. Report to support. |