{ "openapi": "3.1.0", "info": { "title": "Aetherin API", "version": "1.0.0-rc.4", "summary": "Shared REST contract for the Aetherin server side.", "description": "OpenAPI 3.1 specification that is the source of truth for all Aetherin server\nprojects (core runtime, middleware, frontend). Generated clients (TS via\nopenapi-typescript/orval, Go via oapi-codegen) must be regenerated whenever\nthis spec changes; CI fails on drift.\n", "license": { "name": "Proprietary", "url": "https://aetherin.com" }, "contact": { "name": "Aetherin", "url": "https://aetherin.com" } }, "servers": [ { "url": "https://api.{host}/v1", "description": "Production (behind Vercel middleware in practice)", "variables": { "host": { "default": "aetherin.com" } } }, { "url": "http://127.0.0.1:8080/v1", "description": "Local development" } ], "tags": [ { "name": "Health", "description": "Liveness, readiness, and build information." }, { "name": "Auth", "description": "Operator authentication and session management." }, { "name": "Orgs", "description": "Organization management." }, { "name": "Workspaces", "description": "Workspace management within an organization." }, { "name": "Keys", "description": "API key lifecycle management." }, { "name": "Providers", "description": "Upstream provider configuration and health." }, { "name": "Models", "description": "Model catalog." }, { "name": "Chat", "description": "Chat completions (OpenAI-compatible)." }, { "name": "Embeddings", "description": "Embedding generation." }, { "name": "Usage", "description": "Usage reporting and raw events." }, { "name": "Budgets", "description": "Spend budgets and limits." }, { "name": "Billing", "description": "Subscription billing, invoices, checkout, and Stripe webhooks." }, { "name": "Plugins", "description": "Plugin lifecycle and configuration." }, { "name": "Admin", "description": "Administrative operations." }, { "name": "Team", "description": "Organization members and email invitations." } ], "security": [ { "cookieSession": [], "csrfToken": [] } ], "paths": { "/healthz": { "get": { "tags": [ "Health" ], "summary": "Liveness probe", "operationId": "getHealthz", "security": [], "responses": { "200": { "description": "Service is alive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "status": "ok", "version": "1.0.0-rc.2", "uptime_seconds": 3600 } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/readyz": { "get": { "tags": [ "Health" ], "summary": "Readiness probe (db, redis, providers)", "operationId": "getReadyz", "security": [], "responses": { "200": { "description": "All dependencies ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" }, "example": { "status": "ready", "checks": { "db": { "status": "ok" }, "redis": { "status": "ok" }, "providers": { "status": "ok" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "description": "Not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_error", "message": "database is not reachable", "type": "server_error" } } } } } } } }, "/version": { "get": { "tags": [ "Health" ], "summary": "Build info", "operationId": "getVersion", "security": [], "responses": { "200": { "description": "Build information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" }, "example": { "version": "1.0.0-rc.2", "commit": "3f2b1c9", "build_time": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Create an account", "description": "Creates a user with the `member` role, a default organisation and a\ndefault workspace. Self-service registration can be closed by the\ndeployment (an account can then only be created by an administrator\nwith `POST /admin/users`).\n", "operationId": "register", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" }, "example": { "email": "new@example.com", "password": "a-strong-passphrase" } } } }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" }, "example": { "user": { "id": "usr_01HXYZ", "email": "new@example.com", "role": "member" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Operator login (sets session cookie)", "operationId": "login", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "example": { "email": "admin@example.com", "password": "********" } } } }, "responses": { "200": { "description": "Logged in", "headers": { "Set-Cookie": { "description": "Session cookie", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" }, "example": { "user": { "id": "usr_01HXYZ", "email": "admin@example.com", "role": "owner" }, "csrf_token": "csrf_01HXYZ", "orgs": [ { "id": "org_01HXYZ", "name": "Acme", "slug": "acme", "owner_id": "usr_01HXYZ", "created_at": "2026-10-19T12:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Logout (clears session cookie)", "operationId": "logout", "responses": { "204": { "description": "Logged out" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Current user + orgs", "operationId": "getMe", "responses": { "200": { "description": "Current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" }, "example": { "user": { "id": "usr_01HXYZ", "email": "admin@example.com", "role": "owner" }, "orgs": [ { "id": "org_01HXYZ", "name": "Acme", "slug": "acme", "owner_id": "usr_01HXYZ", "created_at": "2026-10-19T12:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Refresh session", "operationId": "refreshSession", "responses": { "200": { "description": "Refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshResponse" }, "example": { "csrf_token": "csrf_01HXYZ" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/orgs": { "get": { "tags": [ "Orgs" ], "summary": "List organizations", "operationId": "listOrgs", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated orgs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgListResponse" }, "example": { "data": [ { "id": "org_01HXYZ", "name": "Acme", "slug": "acme", "owner_id": "usr_01HXYZ", "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "tags": [ "Orgs" ], "summary": "Create organization", "operationId": "createOrg", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCreate" }, "example": { "name": "Acme", "slug": "acme" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Org" }, "example": { "id": "org_01HXYZ", "name": "Acme", "slug": "acme", "owner_id": "usr_01HXYZ", "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/orgs/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Orgs" ], "summary": "Get organization", "operationId": "getOrg", "responses": { "200": { "description": "Organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Org" }, "example": { "id": "org_01HXYZ", "name": "Acme", "slug": "acme", "owner_id": "usr_01HXYZ", "created_at": "2026-10-19T12:00:00Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Orgs" ], "summary": "Update organization", "operationId": "updateOrg", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgUpdate" }, "example": { "name": "Acme Inc" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Org" }, "example": { "id": "org_01HXYZ", "name": "Acme Inc", "slug": "acme", "owner_id": "usr_01HXYZ", "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "tags": [ "Orgs" ], "summary": "Delete organization", "operationId": "deleteOrg", "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/orgs/{id}/workspaces": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Workspaces" ], "summary": "List workspaces in org", "operationId": "listWorkspaces", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated workspaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListResponse" }, "example": { "data": [ { "id": "wsp_01HXYZ", "org_id": "org_01HXYZ", "name": "Production", "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create workspace", "operationId": "createWorkspace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreate" }, "example": { "name": "Production" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" }, "example": { "id": "wsp_01HXYZ", "org_id": "org_01HXYZ", "name": "Production", "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/orgs/{id}/workspaces/{workspaceId}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Workspaces" ], "summary": "Get workspace", "operationId": "getWorkspace", "responses": { "200": { "description": "Workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" }, "example": { "id": "wsp_01HXYZ", "org_id": "org_01HXYZ", "name": "Production", "created_at": "2026-10-19T12:00:00Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Workspaces" ], "summary": "Update workspace", "operationId": "updateWorkspace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUpdate" }, "example": { "name": "Staging" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" }, "example": { "id": "wsp_01HXYZ", "org_id": "org_01HXYZ", "name": "Staging", "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete workspace", "operationId": "deleteWorkspace", "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/keys": { "get": { "tags": [ "Keys" ], "summary": "List API keys (scoped to workspace)", "operationId": "listKeys", "parameters": [ { "name": "workspace_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" }, "example": { "data": [ { "id": "key_01HXYZ", "workspace_id": "wsp_01HXYZ", "name": "Backend", "prefix": "sk-aetherin-abc", "budget_usd_monthly": 100, "rpm_limit": 600, "created_at": "2026-10-19T12:00:00Z", "revoked_at": null } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "tags": [ "Keys" ], "summary": "Create API key (key shown once)", "operationId": "createKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreate" }, "example": { "workspace_id": "wsp_01HXYZ", "name": "Backend", "budget_usd_monthly": 100, "rpm_limit": 600 } } } }, "responses": { "201": { "description": "Created (includes plaintext key once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" }, "example": { "id": "key_01HXYZ", "workspace_id": "wsp_01HXYZ", "name": "Backend", "prefix": "sk-aetherin-abc", "budget_usd_monthly": 100, "rpm_limit": 600, "created_at": "2026-10-19T12:00:00Z", "revoked_at": null, "key": "sk-aetherin-abc.DEFGHIJKLMNOPQRSTUVWXYZ" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/keys/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Keys" ], "summary": "Get API key", "operationId": "getKey", "responses": { "200": { "description": "Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" }, "example": { "id": "key_01HXYZ", "workspace_id": "wsp_01HXYZ", "name": "Backend", "prefix": "sk-aetherin-abc", "budget_usd_monthly": 100, "rpm_limit": 600, "created_at": "2026-10-19T12:00:00Z", "revoked_at": null } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Keys" ], "summary": "Update API key", "operationId": "updateKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyUpdate" }, "example": { "budget_usd_monthly": 250 } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" }, "example": { "id": "key_01HXYZ", "workspace_id": "wsp_01HXYZ", "name": "Backend", "prefix": "sk-aetherin-abc", "budget_usd_monthly": 250, "rpm_limit": 600, "created_at": "2026-10-19T12:00:00Z", "revoked_at": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "tags": [ "Keys" ], "summary": "Revoke/delete API key", "operationId": "deleteKey", "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/keys/{id}/rotate": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "post": { "tags": [ "Keys" ], "summary": "Rotate API key (new key shown once)", "operationId": "rotateKey", "responses": { "200": { "description": "Rotated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" }, "example": { "id": "key_01HXYZ", "workspace_id": "wsp_01HXYZ", "name": "Backend", "prefix": "sk-aetherin-xyz", "budget_usd_monthly": 250, "rpm_limit": 600, "created_at": "2026-10-19T12:00:00Z", "revoked_at": null, "key": "sk-aetherin-xyz.ABCDEFGHIJKLMNOPQRSTUVWXYZ" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/providers": { "get": { "tags": [ "Providers" ], "summary": "List providers (catalog + status)", "operationId": "listProviders", "parameters": [ { "name": "workspace_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderListResponse" }, "example": { "data": [ { "id": "prv_01HXYZ", "workspace_id": "wsp_01HXYZ", "type": "openai", "base_url": "https://api.openai.com/v1", "enabled": true, "source": "manual", "has_credentials": true, "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "tags": [ "Providers" ], "summary": "Configure upstream provider credentials", "operationId": "createProvider", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCreate" }, "example": { "workspace_id": "wsp_01HXYZ", "type": "openai", "base_url": "https://api.openai.com/v1", "credentials": { "api_key": "sk-upstream-xxxxxxxx" }, "enabled": true } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" }, "example": { "id": "prv_01HXYZ", "workspace_id": "wsp_01HXYZ", "type": "openai", "base_url": "https://api.openai.com/v1", "enabled": true, "source": "manual", "has_credentials": true, "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/providers/{id}/health": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Providers" ], "summary": "Provider health check", "operationId": "getProviderHealth", "responses": { "200": { "description": "Health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderHealth" }, "example": { "status": "ok", "latency_ms": 42, "message": "OpenAI reachable" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/providers/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "patch": { "tags": [ "Providers" ], "summary": "Update a provider (enable/disable, base URL, rotate key)", "operationId": "updateProvider", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderUpdate" }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "Updated provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Providers" ], "summary": "Disable a provider (soft delete)", "operationId": "deleteProvider", "responses": { "204": { "description": "Provider disabled" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/models": { "get": { "tags": [ "Models" ], "summary": "List models (OpenAI-compatible)", "operationId": "listModels", "security": [ { "bearerAuth": [] }, { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "provider", "in": "query", "schema": { "type": "string" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Model list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelListResponse" }, "example": { "object": "list", "data": [ { "id": "gpt-4o-mini", "provider_id": "prv_01HXYZ", "upstream_id": "gpt-4o-mini", "display_name": "GPT-4o mini", "pricing": { "prompt_per_1m": 0.15, "completion_per_1m": 0.6 }, "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "tags": [ "Models" ], "summary": "Register a model for a provider", "description": "Makes an upstream model available under a stable id. Requires the\n`admin` role for the provider's organisation.\n", "operationId": "createModel", "security": [ { "bearerAuth": [] }, { "cookieSession": [], "csrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCreate" }, "example": { "provider_id": "prv_01HXYZ", "upstream_id": "gpt-4o-mini", "display_name": "GPT-4o mini", "price_in": 0.15, "price_out": 0.6 } } } }, "responses": { "201": { "description": "Model registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/models/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Models" ], "summary": "Get model", "operationId": "getModel", "security": [ { "bearerAuth": [] }, { "cookieSession": [], "csrfToken": [] } ], "responses": { "200": { "description": "Model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" }, "example": { "id": "gpt-4o-mini", "provider_id": "prv_01HXYZ", "upstream_id": "gpt-4o-mini", "display_name": "GPT-4o mini", "pricing": { "prompt_per_1m": 0.15, "completion_per_1m": 0.6 }, "created_at": "2026-10-19T12:00:00Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/models/{id}/routes": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Models" ], "summary": "List fallback routes for a model", "operationId": "listModelRoutes", "security": [ { "bearerAuth": [] }, { "cookieSession": [], "csrfToken": [] } ], "responses": { "200": { "description": "Ordered fallback targets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelRouteListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Models" ], "summary": "Add or update a fallback route for a model", "operationId": "upsertModelRoute", "security": [ { "bearerAuth": [] }, { "cookieSession": [], "csrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelRouteCreate" } } } }, "responses": { "201": { "description": "Route created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelRoute" }, "example": { "id": "mrt_01HXYZ", "model_id": "gpt-4o", "target_model_id": "gpt-4o-mini", "position": 0, "enabled": true, "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/models/{id}/routes/{routeID}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "routeID", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Models" ], "summary": "Delete a fallback route", "operationId": "deleteModelRoute", "security": [ { "bearerAuth": [] }, { "cookieSession": [], "csrfToken": [] } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "example": "deleted" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/chat/completions": { "post": { "tags": [ "Chat" ], "summary": "Chat completions (streaming + non-streaming)", "operationId": "createChatCompletion", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }, "example": { "model": "gpt-4o-mini", "messages": [ { "role": "user", "content": "Hello!" } ], "stream": false } } } }, "responses": { "200": { "description": "Completion or SSE stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" }, "example": { "id": "chatcmpl-01HXYZ", "object": "chat.completion", "created": 1760875200, "model": "gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help?" }, "finish_reason": "stop", "logprobs": null } ], "usage": { "prompt_tokens": 9, "completion_tokens": 8, "total_tokens": 17 } } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ChatCompletionChunk" }, "example": { "id": "chatcmpl-01HXYZ", "object": "chat.completion.chunk", "created": 1760875200, "model": "gpt-4o-mini", "choices": [ { "index": 0, "delta": { "role": "assistant", "content": "Hello" }, "finish_reason": null } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/embeddings": { "post": { "tags": [ "Embeddings" ], "summary": "Create embeddings", "operationId": "createEmbedding", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" }, "example": { "model": "text-embedding-3-small", "input": "The quick brown fox", "encoding_format": "float", "dimensions": 1536 } } } }, "responses": { "200": { "description": "Embeddings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" }, "example": { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.0023, -0.0142, 0.0089 ], "index": 0 } ], "model": "text-embedding-3-small", "usage": { "prompt_tokens": 4, "total_tokens": 4 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/usage": { "get": { "tags": [ "Usage" ], "summary": "Usage summary (by key/model/day)", "operationId": "getUsage", "parameters": [ { "name": "workspace_id", "in": "query", "schema": { "type": "string" } }, { "name": "key_id", "in": "query", "schema": { "type": "string" } }, { "name": "model", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "group_by", "in": "query", "description": "Which breakdown the summary populates. Without it all three are\nreported. The others are present but empty.\n", "schema": { "type": "string", "enum": [ "key", "model", "day" ] } } ], "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" }, "example": { "totals": { "requests": 1280, "prompt_tokens": 512000, "completion_tokens": 128000, "cost_usd": 42.17 }, "by_key": [ { "key_id": "key_01HXYZ", "requests": 800, "cost_usd": 31.02 } ], "by_model": [ { "model": "gpt-4o-mini", "requests": 1280, "cost_usd": 42.17 } ], "by_day": [ { "day": "2026-10-19", "requests": 96, "cost_usd": 3.14 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/usage/export.csv": { "get": { "tags": [ "Usage" ], "summary": "Export usage events as CSV", "operationId": "exportUsageCsv", "parameters": [ { "name": "workspace_id", "in": "query", "schema": { "type": "string" } }, { "name": "key_id", "in": "query", "schema": { "type": "string" } }, { "name": "model", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Usage events as a CSV stream (defaults to the current month)", "content": { "text/csv": { "schema": { "type": "string" }, "example": "id,created_at,key_id,model,prompt_tokens,completion_tokens,cost_usd\nevt_01HXYZ,2026-10-19T12:00:00Z,key_01HXYZ,gpt-4o-mini,120,48,0.000042\n" } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/usage/events": { "get": { "tags": [ "Usage" ], "summary": "Paginated raw usage events", "operationId": "listUsageEvents", "parameters": [ { "name": "workspace_id", "in": "query", "schema": { "type": "string" } }, { "name": "key_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventListResponse" }, "example": { "data": [ { "id": "evt_01HXYZ", "api_key_id": "key_01HXYZ", "model_id": "gpt-4o-mini", "prompt_tokens": 9, "completion_tokens": 8, "cost_usd": 0.00062, "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/budgets": { "get": { "tags": [ "Budgets" ], "summary": "List budgets", "operationId": "listBudgets", "parameters": [ { "name": "workspace_id", "in": "query", "schema": { "type": "string" } }, { "name": "key_id", "in": "query", "description": "Restrict to one client key.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated budgets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetListResponse" }, "example": { "data": [ { "id": "bdg_01HXYZ", "api_key_id": "key_01HXYZ", "period": "monthly", "limit_usd": 100, "spent_usd": 12.34, "reset_at": "2026-11-01T00:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "tags": [ "Budgets" ], "summary": "Create budget", "operationId": "createBudget", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetCreate" }, "example": { "api_key_id": "key_01HXYZ", "period": "monthly", "limit_usd": 100, "rpm_limit": 600 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" }, "example": { "id": "bdg_01HXYZ", "api_key_id": "key_01HXYZ", "period": "monthly", "limit_usd": 100, "spent_usd": 0, "reset_at": "2026-11-01T00:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/budgets/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "patch": { "tags": [ "Budgets" ], "summary": "Update budget", "operationId": "updateBudget", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetUpdate" }, "example": { "limit_usd": 250, "rpm_limit": 600 } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" }, "example": { "id": "bdg_01HXYZ", "api_key_id": "key_01HXYZ", "period": "monthly", "limit_usd": 250, "spent_usd": 12.34, "reset_at": "2026-11-01T00:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/plugins": { "get": { "tags": [ "Plugins" ], "summary": "List plugins", "operationId": "listPlugins", "responses": { "200": { "description": "Plugins", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginListResponse" }, "example": { "data": [ { "id": "plg_01HXYZ", "name": "usage-alert", "version": "1.2.0", "ring": 1, "enabled": true, "config_json": { "threshold_usd": 80 }, "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/plugins/install": { "post": { "tags": [ "Plugins" ], "summary": "Install plugin", "operationId": "installPlugin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginInstall" }, "example": { "id": "usage-alert", "name": "usage-alert", "version": "1.2.0", "config": { "threshold_usd": 80 } } } } }, "responses": { "201": { "description": "Installed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plugin" }, "example": { "id": "plg_01HXYZ", "name": "usage-alert", "version": "1.2.0", "ring": 1, "enabled": true, "config_json": { "threshold_usd": 80 }, "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/plugins/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "delete": { "tags": [ "Plugins" ], "summary": "Uninstall plugin", "operationId": "uninstallPlugin", "responses": { "204": { "description": "Uninstalled" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/plugins/{id}/config": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Plugins" ], "summary": "Get plugin config", "operationId": "getPluginConfig", "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginConfigResponse" }, "example": { "id": "plg_01HXYZ", "config": { "threshold_usd": 80 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Plugins" ], "summary": "Update plugin config", "operationId": "updatePluginConfig", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginConfigUpdate" }, "example": { "config": { "threshold_usd": 120 } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginConfigResponse" }, "example": { "id": "plg_01HXYZ", "config": { "threshold_usd": 120 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/admin/users": { "get": { "tags": [ "Admin" ], "summary": "List all users", "operationId": "adminListUsers", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponse" }, "example": { "data": [ { "id": "usr_01HXYZ", "email": "admin@example.com", "role": "owner", "status": "active", "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Admin" ], "summary": "Create a user", "operationId": "adminCreateUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" }, "example": { "email": "newuser@example.com", "role": "member", "send_invite": true } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": "usr_01HABC", "email": "newuser@example.com", "role": "member", "status": "invited", "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/admin/users/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "patch": { "tags": [ "Admin" ], "summary": "Update a user", "operationId": "adminUpdateUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" }, "example": { "role": "admin" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": "usr_01HXYZ", "email": "admin@example.com", "role": "admin", "status": "active", "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Admin" ], "summary": "Soft-delete a user", "description": "Marks the user as `deleted` and revokes their sessions. The record is\nretained for audit and referential integrity.\n", "operationId": "adminDeleteUser", "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/admin/audit-log": { "get": { "tags": [ "Admin" ], "summary": "Audit log", "operationId": "adminAuditLog", "parameters": [ { "name": "actor", "in": "query", "schema": { "type": "string" }, "description": "Filter by actor user id." }, { "name": "action", "in": "query", "schema": { "type": "string" }, "description": "Filter by action (e.g. key.create)." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only include entries created at or after this time." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only include entries created at or before this time." }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated audit log", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogListResponse" }, "example": { "data": [ { "id": "aud_01HXYZ", "actor": "usr_01HXYZ", "action": "key.create", "target": "key_01HXYZ", "metadata": { "name": "Backend" }, "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/admin/system": { "get": { "tags": [ "Admin" ], "summary": "System info", "operationId": "adminSystem", "responses": { "200": { "description": "System info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemInfo" }, "example": { "version": "1.0.0-rc.2", "uptime_seconds": 3600, "go_version": "go1.23.2", "db_status": "ok", "redis_status": "ok" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/billing/plans": { "get": { "tags": [ "Billing" ], "summary": "List the plan catalog", "operationId": "listBillingPlans", "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string", "default": "eur" }, "description": "ISO 4217 currency code; defaults to the platform currency." } ], "responses": { "200": { "description": "Available plans (pay-as-you-go, monthly/annual, setup)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPlanListResponse" }, "example": { "data": [ { "plan": "payg", "name": "Pay as you go", "currency": "eur", "interval": "usage", "unit_amount": 0, "included_requests": 0, "payment_methods": [ "card", "klarna", "bancontact" ] }, { "plan": "managed_29", "name": "Managed 29", "currency": "eur", "interval": "monthly", "unit_amount": 29, "included_requests": 100000, "payment_methods": [ "card", "klarna", "bancontact" ] }, { "plan": "setup_300", "name": "Setup Standard", "currency": "eur", "interval": "one_time", "unit_amount": 300, "included_requests": 0, "payment_methods": [ "card", "klarna", "bancontact" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/ProviderError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/billing/subscription": { "get": { "tags": [ "Billing" ], "summary": "Get the current subscription", "operationId": "getBillingSubscription", "parameters": [ { "name": "org_id", "in": "query", "schema": { "type": "string" }, "description": "Organization to bill; defaults to the caller's active org." } ], "responses": { "200": { "description": "Current subscription (the implicit `free` plan when none exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "id": "sub_01HXYZ", "org_id": "org_01HXYZ", "plan": "managed_29", "interval": "monthly", "status": "active", "seats": 5, "currency": "eur", "payment_method": "sepa_debit", "current_period_start": "2026-10-01T00:00:00Z", "current_period_end": "2026-11-01T00:00:00Z", "cancel_at_period_end": false, "trial_end": null, "created_at": "2026-09-15T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/ProviderError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/billing/checkout-session": { "post": { "tags": [ "Billing" ], "summary": "Start a subscription checkout", "operationId": "createCheckoutSession", "parameters": [ { "name": "org_id", "in": "query", "schema": { "type": "string" }, "description": "Organization to bill; defaults to the caller's active org." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionRequest" }, "example": { "plan": "managed_29", "success_url": "https://app.aetherin.com/billing/success", "cancel_url": "https://app.aetherin.com/billing/cancel", "email": "admin@example.com" } } } }, "responses": { "201": { "description": "Checkout session created; redirect the browser to `url`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" }, "example": { "id": "cs_test_01HXYZ", "plan": "managed_29", "url": "https://checkout.stripe.com/c/pay/cs_test_01HXYZ", "expires_at": "2026-10-19T13:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/ProviderError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/billing/portal-session": { "post": { "tags": [ "Billing" ], "summary": "Open the customer billing portal", "operationId": "createPortalSession", "parameters": [ { "name": "org_id", "in": "query", "schema": { "type": "string" }, "description": "Organization to bill; defaults to the caller's active org." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalSessionRequest" }, "example": { "return_url": "https://app.aetherin.com/billing" } } } }, "responses": { "200": { "description": "Portal session created; redirect the browser to `url`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalSession" }, "example": { "url": "https://billing.stripe.com/p/session/01HXYZ", "expires_at": "2026-10-19T13:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/ProviderError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/billing/invoices": { "get": { "tags": [ "Billing" ], "summary": "List invoices", "operationId": "listInvoices", "parameters": [ { "name": "org_id", "in": "query", "schema": { "type": "string" }, "description": "Organization to bill; defaults to the caller's active org." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated invoices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" }, "example": { "data": [ { "id": "in_01HXYZ", "org_id": "org_01HXYZ", "number": "AETH-0007", "status": "paid", "currency": "eur", "subtotal": 29, "tax": 2.32, "total": 31.32, "amount_due": 0, "amount_paid": 31.32, "hosted_invoice_url": "https://invoice.stripe.com/i/in_01HXYZ", "invoice_pdf": "https://invoice.stripe.com/i/in_01HXYZ.pdf", "period_start": "2026-09-01T00:00:00Z", "period_end": "2026-10-01T00:00:00Z", "created_at": "2026-10-01T00:05:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/ProviderError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/stripe": { "post": { "tags": [ "Billing" ], "summary": "Stripe webhook receiver", "description": "Receives asynchronous billing events from Stripe (subscription and\ninvoice lifecycle). Authenticated by verifying the `Stripe-Signature`\nheader against the configured webhook signing secret, not by a session\nor API key. Returns `400` when the signature is missing or invalid.\n", "operationId": "stripeWebhook", "security": [], "parameters": [ { "name": "Stripe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stripe signature header (`t=...,v1=...`)." } ], "requestBody": { "required": true, "description": "Raw Stripe event payload (opaque; not modelled here).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "evt_01HXYZ", "type": "invoice.paid", "created": 1760875200, "data": { "object": { "id": "in_01HXYZ" } } } } } }, "responses": { "200": { "description": "Event received and handled", "content": { "application/json": { "schema": { "type": "object", "required": [ "received" ], "properties": { "received": { "type": "boolean" } } }, "example": { "received": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "502": { "$ref": "#/components/responses/ProviderError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orgs/{id}/invites": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Team" ], "summary": "List invitations for an org", "operationId": "listInvites", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated invitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteListResponse" }, "example": { "data": [ { "id": "inv_01HXYZ", "org_id": "org_01HXYZ", "email": "teammate@example.com", "role": "member", "status": "pending", "invited_by": "usr_01HXYZ", "expires_at": "2026-10-26T12:00:00Z", "accepted_at": null, "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Team" ], "summary": "Invite an email address to an org", "operationId": "createInvite", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteCreate" }, "example": { "email": "teammate@example.com", "role": "member" } } } }, "responses": { "201": { "description": "Invitation created. The single-use `token` is returned once so an\noperator can deliver the link when no mailer is configured.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteCreated" }, "example": { "id": "inv_01HXYZ", "org_id": "org_01HXYZ", "email": "teammate@example.com", "role": "member", "status": "pending", "invited_by": "usr_01HXYZ", "expires_at": "2026-10-26T12:00:00Z", "accepted_at": null, "created_at": "2026-10-19T12:00:00Z", "token": "invt_7f3c2a9e", "accept_url": "https://app.aetherin.dev/invites/invt_7f3c2a9e/accept" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/orgs/{id}/invites/{inviteId}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "inviteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Team" ], "summary": "Revoke a pending invitation", "operationId": "revokeInvite", "responses": { "204": { "description": "Invitation revoked" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/invites/{token}/accept": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Team" ], "summary": "Accept an invitation", "description": "Redeems an invitation token. May be called anonymously (the invite email\nmust match an existing account) or by an authenticated user (the session\nuser's email must match the invite). On success the caller becomes an\norg member.\n", "operationId": "acceptInvite", "security": [ {}, { "cookieSession": [], "csrfToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteAcceptRequest" }, "example": { "email": "teammate@example.com" } } } }, "responses": { "200": { "description": "Invitation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" }, "example": { "id": "inv_01HXYZ", "org_id": "org_01HXYZ", "email": "teammate@example.com", "role": "member", "status": "accepted", "invited_by": "usr_01HXYZ", "expires_at": "2026-10-26T12:00:00Z", "accepted_at": "2026-10-19T12:30:00Z", "created_at": "2026-10-19T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/orgs/{id}/members": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Team" ], "summary": "List members of an org", "operationId": "listMembers", "parameters": [ { "name": "role", "in": "query", "schema": { "$ref": "#/components/schemas/Role" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberListResponse" }, "example": { "data": [ { "id": "mem_01HXYZ", "org_id": "org_01HXYZ", "user_id": "usr_01HXYZ", "email": "admin@example.com", "role": "owner", "status": "active", "created_at": "2026-10-19T12:00:00Z" } ], "next_cursor": null, "has_more": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/orgs/{id}/members/{memberId}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Team" ], "summary": "Change a member's role", "operationId": "updateMember", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberUpdate" }, "example": { "role": "admin" } } } }, "responses": { "200": { "description": "Updated member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Team" ], "summary": "Remove a member from an org", "operationId": "removeMember", "responses": { "204": { "description": "Removed" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "webhooks": { "usageAlert": { "post": { "summary": "Usage alert event (webhook)", "operationId": "usageAlertWebhook", "tags": [ "Usage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageAlertEvent" }, "example": { "event": "usage.alert", "api_key_id": "key_01HXYZ", "threshold_usd": 80, "spent_usd": 84.5, "occurred_at": "2026-10-19T12:00:00Z", "request_id": "req_01HXYZ" } } } }, "responses": { "204": { "description": "Acknowledged" } } } } }, "components": { "securitySchemes": { "cookieSession": { "type": "apiKey", "in": "cookie", "name": "session", "description": "Operator session cookie (HttpOnly, Secure, SameSite)." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk-aetherin", "description": "Client API key as Bearer token." }, "csrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "CSRF token of the session, required **in addition to** the session\ncookie on mutating requests (POST, PUT, PATCH, DELETE). The value is the\n`csrf_token` returned by `POST /auth/login` and `POST /auth/refresh`\n(and by `GET /auth/me`). Requests that authenticate with a client API\nkey (`bearerAuth`) do not need it — they are not browser-driven and\ncannot be cross-site forged.\n" } }, "parameters": { "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "invalid_request", "message": "model is required", "type": "invalid_request_error", "param": "model", "request_id": "req_01HXYZ" } } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "missing or invalid credentials", "type": "authentication_error", "param": null, "request_id": "req_01HXYZ" } } } } }, "PaymentRequired": { "description": "Budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "budget_exceeded", "message": "monthly budget exceeded for this key", "type": "budget_error", "param": "api_key_id", "request_id": "req_01HXYZ" } } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "resource not found", "type": "not_found_error", "param": "id", "request_id": "req_01HXYZ" } } } } }, "RateLimited": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limit_exceeded", "message": "too many requests", "type": "rate_limit_error", "param": null, "request_id": "req_01HXYZ" } } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "forbidden", "message": "admin role required", "type": "permission_error", "param": null, "request_id": "req_01HXYZ" } } } } }, "Conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "conflict", "message": "a user with this email already exists", "type": "conflict_error", "param": "email", "request_id": "req_01HXYZ" } } } } }, "ServiceUnavailable": { "description": "A required dependency (secrets, database, or upstream) is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "secrets_unavailable", "message": "cannot seal credentials without a secrets key", "type": "server_error", "param": null, "request_id": "req_01HXYZ" } } } } }, "ProviderError": { "description": "The upstream provider (for example Stripe) failed or is unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "provider_error", "message": "the payment provider could not be reached", "type": "provider_error", "param": null, "request_id": "req_01HXYZ" } } } } } }, "schemas": { "HealthResponse": { "type": "object", "required": [ "status", "version", "uptime_seconds" ], "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string" }, "uptime_seconds": { "type": "integer" } } }, "ReadyResponse": { "type": "object", "required": [ "status", "checks" ], "properties": { "status": { "type": "string", "enum": [ "ready", "not_ready" ] }, "checks": { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "fail" ] }, "message": { "type": "string" } } } } } }, "VersionResponse": { "type": "object", "required": [ "version", "commit", "build_time" ], "properties": { "version": { "type": "string" }, "commit": { "type": "string" }, "build_time": { "type": "string", "format": "date-time" } } }, "LoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } } }, "RegisterRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password", "minLength": 12, "description": "At least 12 characters." } } }, "RegisterResponse": { "type": "object", "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/AuthUser" } } }, "LoginResponse": { "type": "object", "required": [ "user", "csrf_token" ], "properties": { "user": { "$ref": "#/components/schemas/AuthUser" }, "csrf_token": { "type": "string", "description": "CSRF token for the new session." }, "orgs": { "type": "array", "items": { "$ref": "#/components/schemas/Org" } } } }, "MeResponse": { "type": "object", "required": [ "user", "orgs" ], "properties": { "user": { "$ref": "#/components/schemas/AuthUser" }, "csrf_token": { "type": "string", "description": "The current session's CSRF token. Always present, so a client that\nlost it (new tab, cleared storage) can recover without rotating the\nsession.\n" }, "orgs": { "type": "array", "items": { "$ref": "#/components/schemas/Org" } } } }, "RefreshResponse": { "type": "object", "required": [ "csrf_token" ], "properties": { "csrf_token": { "type": "string", "description": "CSRF token of the rotated session." } } }, "User": { "type": "object", "required": [ "id", "email", "role", "created_at" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/Role" }, "status": { "$ref": "#/components/schemas/UserStatus" }, "created_at": { "type": "string", "format": "date-time" } } }, "AuthUser": { "type": "object", "description": "The user as returned by the auth endpoints. The account's `status` and\n`created_at` are admin data and are not exposed to the user themself.\n", "required": [ "id", "email", "role" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/Role" } } }, "UserListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "Org": { "type": "object", "required": [ "id", "name", "slug", "owner_id", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "owner_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "OrgCreate": { "type": "object", "required": [ "name", "slug" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "OrgUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "OrgListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Org" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "Workspace": { "type": "object", "description": "The wire format of this resource (the server's internal model is not exposed).", "required": [ "id", "org_id", "name", "created_at" ], "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkspaceCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "WorkspaceUpdate": { "type": "object", "properties": { "name": { "type": "string" } } }, "WorkspaceListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "ApiKey": { "type": "object", "required": [ "id", "workspace_id", "name", "prefix", "created_at" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "Public prefix of the key (e.g. sk-aetherin-abc)." }, "budget_usd_monthly": { "type": [ "number", "null" ], "format": "double" }, "rpm_limit": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApiKeyCreate": { "type": "object", "description": "A negative `budget_usd_monthly` or `rpm_limit`, or a missing\n`workspace_id`, is rejected with `400`.\n", "required": [ "workspace_id", "name" ], "properties": { "workspace_id": { "type": "string" }, "name": { "type": "string" }, "budget_usd_monthly": { "type": "number", "format": "double" }, "rpm_limit": { "type": "integer" } } }, "ApiKeyUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "budget_usd_monthly": { "type": "number", "format": "double" }, "rpm_limit": { "type": "integer" } } }, "ApiKeyCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Full plaintext key, shown once." } } } ] }, "ApiKeyListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "Provider": { "type": "object", "required": [ "id", "type", "enabled", "source", "has_credentials", "created_at" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ], "description": "Null for providers seeded from server env (global scope)." }, "type": { "type": "string", "description": "Provider type. Supported values: openai, anthropic, google/gemini,\ngroq, mistral, xai, deepseek, cohere, together, fireworks, perplexity,\nopenrouter, ollama, azure, nvidia, moonshot, siliconflow, nanogpt,\nhuggingface, singularityapi.\n" }, "base_url": { "type": [ "string", "null" ], "format": "uri" }, "enabled": { "type": "boolean" }, "source": { "type": "string", "enum": [ "seeded", "manual" ], "description": "`seeded` = created automatically from server env at boot;\n`manual` = added through the API.\n" }, "has_credentials": { "type": "boolean", "description": "Whether a sealed upstream credential is stored. The credential itself\nis never returned.\n" }, "created_at": { "type": "string", "format": "date-time" } } }, "ProviderCreate": { "type": "object", "required": [ "workspace_id", "type" ], "properties": { "workspace_id": { "type": "string" }, "type": { "type": "string" }, "base_url": { "type": "string", "format": "uri" }, "credentials": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string" } ], "description": "Upstream credentials, encrypted at rest. Prefer an object\n`{api_key: \"...\"}`; a raw string is accepted for legacy clients and\ntreated as the API key.\n" }, "enabled": { "type": "boolean", "default": true } } }, "ProviderUpdate": { "type": "object", "properties": { "base_url": { "type": [ "string", "null" ], "format": "uri" }, "credentials": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "string" } ], "description": "Rotate upstream credentials (same shape as create)." }, "enabled": { "type": "boolean" } } }, "ProviderHealth": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "down" ] }, "latency_ms": { "type": "integer" }, "message": { "type": "string" } } }, "ProviderListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "Model": { "type": "object", "required": [ "id", "provider_id", "upstream_id", "display_name" ], "properties": { "id": { "type": "string" }, "provider_id": { "type": "string" }, "upstream_id": { "type": "string" }, "display_name": { "type": "string" }, "pricing": { "type": "object", "properties": { "prompt_per_1m": { "type": "number", "format": "double" }, "completion_per_1m": { "type": "number", "format": "double" } } }, "created_at": { "type": "string", "format": "date-time" } } }, "ModelCreate": { "type": "object", "required": [ "provider_id", "upstream_id", "display_name" ], "properties": { "provider_id": { "type": "string" }, "upstream_id": { "type": "string", "description": "The model id as the upstream provider knows it." }, "display_name": { "type": "string" }, "price_in": { "type": "number", "format": "double", "description": "Price per 1M prompt tokens." }, "price_out": { "type": "number", "format": "double", "description": "Price per 1M completion tokens." } } }, "ModelListResponse": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "ModelRoute": { "type": "object", "required": [ "id", "model_id", "target_model_id", "position", "enabled" ], "properties": { "id": { "type": "string" }, "model_id": { "type": "string" }, "target_model_id": { "type": "string" }, "position": { "type": "integer", "minimum": 0 }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "ModelRouteCreate": { "type": "object", "required": [ "target_model_id" ], "properties": { "target_model_id": { "type": "string" }, "position": { "type": "integer", "minimum": 0, "default": 0 }, "enabled": { "type": "boolean", "default": true } } }, "ModelRouteListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelRoute" } } } }, "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "temperature": { "type": "number", "format": "double" }, "top_p": { "type": "number", "format": "double" }, "n": { "type": "integer" }, "stream": { "type": "boolean", "default": false }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "max_tokens": { "type": "integer" }, "presence_penalty": { "type": "number", "format": "double" }, "frequency_penalty": { "type": "number", "format": "double" }, "user": { "type": "string" }, "seed": { "type": "integer" }, "response_format": { "type": "object", "additionalProperties": true }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_choice": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "stream_options": { "type": "object", "properties": { "include_usage": { "type": "boolean" } } } } }, "ChatMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool", "function" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_call_id": { "type": "string" } } }, "ChatCompletion": { "type": "object", "required": [ "id", "object", "created", "model", "choices" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/ChatMessage" }, "finish_reason": { "type": [ "string", "null" ] }, "logprobs": { "type": [ "object", "null" ], "additionalProperties": true } } } }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "ChatCompletionChunk": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "example": "chat.completion.chunk" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "delta": { "type": "object", "additionalProperties": true }, "finish_reason": { "type": [ "string", "null" ] } } } }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "EmbeddingRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] }, "dimensions": { "type": "integer" }, "user": { "type": "string" } } }, "EmbeddingResponse": { "type": "object", "required": [ "object", "data", "model", "usage" ], "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "required": [ "object", "embedding", "index" ], "properties": { "object": { "type": "string", "example": "embedding" }, "embedding": { "oneOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] }, "index": { "type": "integer" } } } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } }, "UsageEvent": { "type": "object", "description": "The wire format of this resource (the server's internal model is not exposed).", "required": [ "id", "api_key_id", "model_id", "prompt_tokens", "completion_tokens", "cost_usd", "created_at" ], "properties": { "id": { "type": "string" }, "api_key_id": { "type": "string" }, "model_id": { "type": "string" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "cost_usd": { "type": "number", "format": "double" }, "created_at": { "type": "string", "format": "date-time" } } }, "UsageEventListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEvent" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "UsageSummary": { "type": "object", "description": "The wire format of this resource (the server's internal model is not exposed).", "properties": { "totals": { "type": "object", "properties": { "requests": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "cost_usd": { "type": "number", "format": "double" } } }, "by_key": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "by_model": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "by_day": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Budget": { "type": "object", "description": "The wire format of this resource (the server's internal model is not exposed).", "required": [ "id", "api_key_id", "period", "limit_usd", "spent_usd", "reset_at" ], "properties": { "id": { "type": "string" }, "api_key_id": { "type": "string" }, "period": { "type": "string", "enum": [ "monthly" ] }, "limit_usd": { "type": "number", "format": "double" }, "spent_usd": { "type": "number", "format": "double" }, "reset_at": { "type": "string", "format": "date-time" } } }, "BudgetCreate": { "type": "object", "required": [ "api_key_id", "limit_usd" ], "properties": { "api_key_id": { "type": "string" }, "period": { "type": "string", "enum": [ "monthly" ], "default": "monthly" }, "limit_usd": { "type": "number", "format": "double" }, "rpm_limit": { "type": "integer" } } }, "BudgetUpdate": { "type": "object", "description": "`limit_usd` sets the budget for the key. `rpm_limit` sets the key's\nrequest rate limit. Both are optional; a body with neither (or with a\nnegative value) is rejected with `400`. Changing a limit never resets\nthe period — the spend and the reset date are preserved.\n", "properties": { "limit_usd": { "type": "number", "format": "double", "description": "Monthly budget in the billing currency." }, "rpm_limit": { "type": "integer", "description": "Requests per minute allowed for the key." } } }, "BudgetListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Budget" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "Plugin": { "type": "object", "required": [ "id", "name", "version", "ring", "enabled" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "ring": { "type": "integer", "description": "The plugin ring the plugin belongs to (0 = kernel, 1 = feature)." }, "enabled": { "type": "boolean" }, "config_json": { "type": "object", "additionalProperties": true, "description": "The plugin's configuration, as stored." }, "created_at": { "type": "string", "format": "date-time" } } }, "PluginInstall": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "The registry key of the plugin. Re-installing the same id updates it." }, "name": { "type": "string" }, "version": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } } }, "PluginConfigResponse": { "type": "object", "properties": { "id": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } } }, "PluginConfigUpdate": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": true } } }, "PluginListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plugin" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "AuditLog": { "type": "object", "required": [ "id", "actor", "action", "target", "created_at" ], "properties": { "id": { "type": "string" }, "actor": { "type": "string" }, "action": { "type": "string" }, "target": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "AuditLogListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "SystemInfo": { "type": "object", "properties": { "version": { "type": "string" }, "uptime_seconds": { "type": "integer" }, "go_version": { "type": "string" }, "db_status": { "type": "string" }, "redis_status": { "type": "string" } } }, "Role": { "type": "string", "description": "Role of a user or organization member. `owner` is the org creator,\n`admin` can manage org resources and members, `billing` can manage the\nsubscription and invoices, `member` has standard access.\n", "enum": [ "owner", "admin", "member", "billing" ] }, "UserStatus": { "type": "string", "description": "Account / membership lifecycle state.", "enum": [ "active", "invited", "suspended", "deleted" ] }, "Plan": { "type": "string", "description": "Billing plan identifier. `payg` is usage-based pay-as-you-go with no\nrecurring fee. Numeric suffixes (29/59/99) are list prices in the billing\ncurrency; the currency is reported per subscription and invoice\n(`currency`, ISO 4217) and is deliberately not hardcoded. `setup_300`\nand `setup_600` are one-time setup packages (interval `one_time`,\npurchased with checkout `mode: payment`). `custom` denotes a\nnegotiated/enterprise agreement.\n", "enum": [ "free", "payg", "managed_29", "managed_59", "managed_99", "setup_300", "setup_600", "custom" ] }, "BillingInterval": { "type": "string", "description": "Recurring interval; `usage` for pay-as-you-go, `one_time` for a\nnon-recurring purchase (for example a setup package).\n", "enum": [ "monthly", "annual", "usage", "one_time" ] }, "BillingPlan": { "type": "object", "description": "A purchasable plan from the catalog.", "required": [ "plan", "name", "currency", "interval" ], "properties": { "plan": { "$ref": "#/components/schemas/Plan" }, "name": { "type": "string", "example": "Managed 29" }, "description": { "type": "string" }, "currency": { "type": "string", "example": "eur" }, "interval": { "$ref": "#/components/schemas/BillingInterval" }, "unit_amount": { "type": "number", "format": "double", "description": "Price per interval in major units; `0` for pay-as-you-go." }, "included_requests": { "type": "integer", "description": "Requests included per period (pay-as-you-go: 0)." }, "payment_methods": { "type": "array", "description": "Stripe payment method types enabled for this plan.", "items": { "type": "string" }, "example": [ "card", "klarna", "bancontact" ] } } }, "BillingPlanListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillingPlan" } } } }, "Subscription": { "type": "object", "required": [ "id", "org_id", "plan", "status", "seats", "currency", "current_period_start", "current_period_end", "created_at" ], "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "plan": { "$ref": "#/components/schemas/Plan" }, "interval": { "$ref": "#/components/schemas/BillingInterval" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "incomplete", "incomplete_expired", "paused" ] }, "seats": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "description": "ISO 4217 currency code (lowercase), e.g. `eur`, `usd`, `gbp`.", "example": "eur" }, "payment_method": { "type": [ "string", "null" ], "description": "Stripe payment method type used, e.g. `card`, `sepa_debit`.", "example": "sepa_debit" }, "current_period_start": { "type": "string", "format": "date-time" }, "current_period_end": { "type": "string", "format": "date-time" }, "cancel_at_period_end": { "type": "boolean", "default": false }, "trial_end": { "type": [ "string", "null" ], "format": "date-time" }, "stripe_customer_id": { "type": [ "string", "null" ] }, "stripe_subscription_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Invoice": { "type": "object", "required": [ "id", "org_id", "status", "currency", "total", "amount_due", "amount_paid", "created_at" ], "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "number": { "type": [ "string", "null" ], "description": "Human-readable invoice number." }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code (lowercase).", "example": "eur" }, "subtotal": { "type": "number", "format": "double" }, "tax": { "type": "number", "format": "double", "description": "Tax amount computed by Stripe; Aetherin does not calculate tax." }, "total": { "type": "number", "format": "double" }, "amount_due": { "type": "number", "format": "double" }, "amount_paid": { "type": "number", "format": "double" }, "hosted_invoice_url": { "type": [ "string", "null" ], "format": "uri" }, "invoice_pdf": { "type": [ "string", "null" ], "format": "uri" }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "InvoiceListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "Invite": { "type": "object", "required": [ "id", "org_id", "email", "role", "status", "created_at" ], "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/Role" }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired" ] }, "invited_by": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "InviteCreate": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/Role" } } }, "InviteCreated": { "allOf": [ { "$ref": "#/components/schemas/Invite" }, { "type": "object", "required": [ "token", "accept_url" ], "properties": { "token": { "type": "string", "description": "Single-use redemption token; returned only on creation." }, "accept_url": { "type": "string", "format": "uri", "description": "Link an operator can send to the invitee." } } } ] }, "InviteAcceptRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Required for anonymous redemption and must match the invited email.\nOmit when calling with a session cookie.\n" } } }, "InviteListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "Member": { "type": "object", "required": [ "id", "org_id", "user_id", "email", "role", "status", "created_at" ], "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/Role" }, "status": { "$ref": "#/components/schemas/UserStatus" }, "created_at": { "type": "string", "format": "date-time" } } }, "MemberUpdate": { "type": "object", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/Role" } } }, "MemberListResponse": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "CreateUserRequest": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/Role" }, "send_invite": { "type": "boolean", "default": true, "description": "Send an invitation email so the user can set a password." } } }, "UpdateUserRequest": { "type": "object", "minProperties": 1, "properties": { "role": { "$ref": "#/components/schemas/Role" }, "status": { "$ref": "#/components/schemas/UserStatus" } } }, "CheckoutSessionRequest": { "type": "object", "required": [ "plan", "success_url", "cancel_url" ], "properties": { "plan": { "$ref": "#/components/schemas/Plan" }, "mode": { "type": "string", "enum": [ "subscription", "payment", "setup" ], "default": "subscription", "description": "`subscription` for recurring plans, `payment` for one-time setup invoices, `setup` to save a payment method for pay-as-you-go.\n" }, "interval": { "$ref": "#/components/schemas/BillingInterval" }, "success_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" }, "email": { "type": "string", "format": "email", "description": "Optional email to prefill at checkout." }, "payment_methods": { "type": "array", "description": "Optional subset of Stripe payment method types to enable (must be supported by the account); omitted means the plan's default set.\n", "items": { "type": "string" }, "example": [ "card", "sepa_debit", "paypal" ] } } }, "CheckoutSession": { "type": "object", "required": [ "id", "plan", "url" ], "properties": { "id": { "type": "string" }, "plan": { "$ref": "#/components/schemas/Plan" }, "mode": { "type": "string", "enum": [ "subscription", "payment", "setup" ] }, "interval": { "$ref": "#/components/schemas/BillingInterval" }, "url": { "type": "string", "format": "uri", "description": "Stripe-hosted checkout URL to redirect the browser to." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PortalSessionRequest": { "type": "object", "required": [ "return_url" ], "properties": { "return_url": { "type": "string", "format": "uri" } } }, "PortalSession": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Stripe-hosted customer portal URL." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ErrorCode": { "type": "string", "description": "Standard error codes returned in `ErrorResponse.error.code`. The full\nmapping of codes to HTTP statuses and meanings is documented in\n`openapi/ERROR_CODES.md`.\n", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "conflict", "rate_limit_exceeded", "budget_exceeded", "provider_error", "secrets_unavailable", "csrf_invalid", "internal_error", "validation_error" ] }, "UsageAlertEvent": { "type": "object", "required": [ "event", "api_key_id", "threshold_usd", "spent_usd", "occurred_at" ], "properties": { "event": { "type": "string", "enum": [ "usage.alert" ], "description": "Event type." }, "api_key_id": { "type": "string" }, "threshold_usd": { "type": "number", "format": "double" }, "spent_usd": { "type": "number", "format": "double" }, "occurred_at": { "type": "string", "format": "date-time" }, "request_id": { "type": [ "string", "null" ] } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "type" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" }, "type": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] } } } }, "example": { "error": { "code": "invalid_request", "message": "model is required", "type": "invalid_request_error", "param": "model", "request_id": "req_01HXYZ" } } } } } }