// api reference

API Reference

All routes are under https://api.aetherin.app/v1. Operator routes use a session cookie; client routes use Authorization: Bearer sk-aetherin-….

Health

Method	Path	Description
GET	/healthz	Liveness probe
GET	/readyz	Readiness probe (db, redis, providers)
GET	/version	Build info

Auth

Method	Path	Description
POST	/auth/register	Create an account
POST	/auth/activate	Activate an invited account
POST	/auth/activate/{token}	Activate an invited account (token in path)
POST	/auth/login	Operator login (sets session cookie)
POST	/auth/logout	Logout (clears session cookie)
GET	/auth/me	Current user + orgs
POST	/auth/refresh	Refresh session

Orgs & Workspaces

Method	Path	Description
GET	/orgs	List organizations
POST	/orgs	Create organization
GET	/orgs/{id}	Get organization
PATCH	/orgs/{id}	Update organization
DELETE	/orgs/{id}	Delete organization
GET	/orgs/{id}/workspaces	List workspaces in org
POST	/orgs/{id}/workspaces	Create workspace
GET	/orgs/{id}/workspaces/{workspaceId}	Get workspace
PATCH	/orgs/{id}/workspaces/{workspaceId}	Update workspace
DELETE	/orgs/{id}/workspaces/{workspaceId}	Delete workspace
GET	/orgs/{id}/invites	List invitations for an org
POST	/orgs/{id}/invites	Invite an email address to an org
DELETE	/orgs/{id}/invites/{inviteId}	Revoke a pending invitation
POST	/invites/{token}/accept	Accept an invitation
GET	/orgs/{id}/members	List members of an org
PATCH	/orgs/{id}/members/{memberId}	Change a member's role
DELETE	/orgs/{id}/members/{memberId}	Remove a member from an org

Keys

Method	Path	Description
GET	/keys	List API keys (scoped to workspace)
POST	/keys	Create API key (key shown once)
GET	/keys/{id}	Get API key
PATCH	/keys/{id}	Update API key
DELETE	/keys/{id}	Revoke/delete API key
POST	/keys/{id}/rotate	Rotate API key (new key shown once)

Models & Providers

Method	Path	Description
GET	/models	List models (OpenAI-compatible)
POST	/models	Register a model for a provider
GET	/models/{id}	Get model
GET	/models/{id}/routes	List fallback routes for a model
POST	/models/{id}/routes	Add or update a fallback route for a model
DELETE	/models/{id}/routes/{routeID}	Delete a fallback route
GET	/providers	List providers (catalog + status)
POST	/providers	Configure upstream provider credentials
GET	/providers/{id}/health	Provider health check
PATCH	/providers/{id}	Update a provider (enable/disable, base URL, rotate key)
DELETE	/providers/{id}	Disable a provider (soft delete)

Chat & Embeddings

Method	Path	Description
POST	/chat/completions	Chat completions (streaming + non-streaming)
POST	/embeddings	Create embeddings

Usage & Budgets

Method	Path	Description
GET	/usage	Usage summary (by key/model/day)
GET	/usage/export.csv	Export usage events as CSV
GET	/usage/events	Paginated raw usage events
GET	/budgets	List budgets
POST	/budgets	Create budget
PATCH	/budgets/{id}	Update budget

Plugins

Method	Path	Description
GET	/plugins	List plugins
POST	/plugins/install	Install plugin
GET	/plugins/{id}/config	Get plugin config
PATCH	/plugins/{id}/config	Update plugin config
DELETE	/plugins/{id}	Uninstall plugin

Billing

Method	Path	Description
GET	/billing/plans	List the plan catalog
GET	/billing/subscription	Get the current subscription
POST	/billing/checkout-session	Start a subscription checkout
POST	/billing/portal-session	Open the customer billing portal
GET	/billing/invoices	List invoices
POST	/webhooks/stripe	Stripe webhook receiver

Admin

Method	Path	Description
GET	/admin/users	List all users
POST	/admin/users	Create a user
PATCH	/admin/users/{id}	Update a user
DELETE	/admin/users/{id}	Soft-delete a user
GET	/admin/audit-log	Audit log
GET	/admin/system	System info
GET	/admin/models/pricing	List models with governance prices (default, recommended, effective)
PATCH	/admin/models/{id}/pricing	Set a model's catalogue price and provenance
GET	/admin/price-policies	List margin policies
POST	/admin/price-policies	Set the margin for a scope (upsert)
DELETE	/admin/price-policies/{id}	Delete a margin policy
GET	/admin/notifications	List the operator's discovery notifications
PATCH	/admin/notifications/{id}	Resolve a notification (applied or dismissed)
GET	/admin/feeds	List provider catalogue feeds
POST	/admin/feeds	Register a feed (upsert by adapter + label)
GET	/admin/feeds/{id}	Read a feed
POST	/admin/feeds/{id}/run	Run a feed now

Error codes

Every error uses the same envelope — branch on error.code, never on message.

{
  "error": {
    "code": "invalid_request",
    "message": "model is required",
    "type": "invalid_request_error",
    "param": "model",
    "request_id": "req_01HXYZ"
  }
}

Code	HTTP	Meaning
invalid_request	400	The request is malformed or missing required data.
validation_error	400	The request failed schema/semantic validation.
unauthorized	401	Authentication is missing or invalid.
forbidden	403	Authenticated but not allowed to perform the action.
not_found	404	The referenced resource does not exist.
conflict	409	The request conflicts with current state.
budget_exceeded	402	The key or workspace budget is exhausted.
rate_limit_exceeded	429	Per-key request/token rate limit hit.
provider_error	502	The upstream provider failed or is unreachable.
secrets_unavailable	503	A required dependency is not available to serve the request.
csrf_invalid	403	The CSRF proof was missing or did not match the session.
internal_error	500	Unexpected server-side failure.

Error codes are stable: existing codes are never renamed or repurposed, and new codes may be added in a minor release. Consumers must tolerate unknown codes.