{ "openapi": "3.1.0", "info": { "title": "SeaOtter API", "description": "SeaOtter control plane API \u2014 managed Hermes Agent hosting. Authenticate with a Clerk session JWT (web) or an org-scoped API key (`Authorization: Bearer so_\u2026` from POST /api/v1/api-keys). Public developer docs: https://docs.seaotter.dev", "version": "1.0.0" }, "servers": [ { "url": "https://seaotter-api-bpenevambq-uc.a.run.app", "description": "Production" }, { "url": "http://localhost:8000", "description": "Local development" } ], "paths": { "/api/v1/agents": { "get": { "tags": [ "agents" ], "summary": "List Agents", "operationId": "list_agents_api_v1_agents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AgentOut" }, "type": "array", "title": "Response List Agents Api V1 Agents Get" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "agents" ], "summary": "Create agent", "description": "Creates an agent row and enqueues async provision. Returns immediately with `status=provisioning`. Poll `GET /agents/{id}` and inspect `config.provisioning_stages`. Hard provision failures may surface as 503 so Cloud Tasks retries.", "operationId": "create_agent_api_v1_agents_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "402": { "description": "Plan capacity or billing required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict with current agent state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Transient failure \u2014 Cloud Tasks will retry where applicable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/agents/{agent_id}": { "get": { "tags": [ "agents" ], "summary": "Get agent", "description": "Fetch agent detail. While provisioning, poll `config.provisioning_stages`.", "operationId": "get_agent_api_v1_agents__agent_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "agents" ], "summary": "Update Agent", "operationId": "update_agent_api_v1_agents__agent_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "agents" ], "summary": "Delete Agent", "operationId": "delete_agent_api_v1_agents__agent_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/reprovision": { "post": { "tags": [ "agents" ], "summary": "Reprovision Agent", "description": "Retry provisioning after an error (mints a new attempt id; supersedes in-flight tasks).", "operationId": "reprovision_agent_api_v1_agents__agent_id__reprovision_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/backups": { "get": { "tags": [ "agents" ], "summary": "List Agent Backups", "description": "List restore points for an agent (newest first).", "operationId": "list_agent_backups_api_v1_agents__agent_id__backups_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBackupOut" }, "title": "Response List Agent Backups Api V1 Agents Agent Id Backups Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/restore": { "post": { "tags": [ "agents" ], "summary": "Restore Agent", "description": "Restore hermes-home from a VolumeSnapshot backup; preserves hostname.", "operationId": "restore_agent_api_v1_agents__agent_id__restore_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/migrate-sandbox": { "post": { "tags": [ "agents" ], "summary": "Migrate Agent Sandbox", "description": "Recreate the Hermes pod with/without gVisor; preserves PVC (no full reprovision).", "operationId": "migrate_agent_sandbox_api_v1_agents__agent_id__migrate_sandbox_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrateSandboxBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/credentials/reveal": { "post": { "tags": [ "agents" ], "summary": "Reveal Agent Credentials", "description": "Return dashboard/API secrets for the owner (not included in list/detail).", "operationId": "reveal_agent_credentials_api_v1_agents__agent_id__credentials_reveal_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCredentialsOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/credentials/rotate": { "post": { "tags": [ "agents" ], "summary": "Rotate Agent Credentials", "description": "Rotate dashboard password and/or API key after compromise (invalidates old secrets).", "operationId": "rotate_agent_credentials_api_v1_agents__agent_id__credentials_rotate_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialsRotate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCredentialsOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/dashboard-auth": { "put": { "tags": [ "agents" ], "summary": "Update Dashboard Auth", "description": "Set or rotate Hermes dashboard username/password (HERMES_DASHBOARD_BASIC_AUTH_* env).", "operationId": "update_dashboard_auth_api_v1_agents__agent_id__dashboard_auth_put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardAuthUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/start": { "post": { "tags": [ "agents" ], "summary": "Start Agent", "operationId": "start_agent_api_v1_agents__agent_id__start_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/stop": { "post": { "tags": [ "agents" ], "summary": "Stop Agent", "operationId": "stop_agent_api_v1_agents__agent_id__stop_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/restart": { "post": { "tags": [ "agents" ], "summary": "Restart Agent", "operationId": "restart_agent_api_v1_agents__agent_id__restart_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/logs": { "get": { "tags": [ "agents" ], "summary": "Agent Logs", "operationId": "agent_logs_api_v1_agents__agent_id__logs_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLogsOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/metrics": { "get": { "tags": [ "agents" ], "summary": "Agent Metrics", "operationId": "agent_metrics_api_v1_agents__agent_id__metrics_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMetricsOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/alert-preferences": { "get": { "tags": [ "agents" ], "summary": "Get Alert Preferences", "operationId": "get_alert_preferences_api_v1_agents__agent_id__alert_preferences_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertPreferencesOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "agents" ], "summary": "Put Alert Preferences", "operationId": "put_alert_preferences_api_v1_agents__agent_id__alert_preferences_put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertPreferencesUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertPreferencesOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/secrets": { "put": { "tags": [ "agents" ], "summary": "Upsert Secret", "operationId": "upsert_secret_api_v1_agents__agent_id__secrets_put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretUpsert" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretUpsertOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "402": { "description": "Plan capacity or billing required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Conflict with current agent state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Transient failure \u2014 Cloud Tasks will retry where applicable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agents/{agent_id}/usage": { "post": { "tags": [ "agents" ], "summary": "Record Usage", "operationId": "record_usage_api_v1_agents__agent_id__usage_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/plans": { "get": { "tags": [ "billing" ], "summary": "List Plans", "operationId": "list_plans_api_v1_billing_plans_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object", "title": "Response List Plans Api V1 Billing Plans Get" } } } } } } }, "/api/v1/billing/subscription": { "get": { "tags": [ "billing" ], "summary": "Get Subscription", "operationId": "get_subscription_api_v1_billing_subscription_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionOut" }, { "type": "null" } ], "title": "Response Get Subscription Api V1 Billing Subscription Get" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/billing/checkout": { "post": { "tags": [ "billing" ], "summary": "Checkout", "operationId": "checkout_api_v1_billing_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/billing/portal": { "post": { "tags": [ "billing" ], "summary": "Portal", "operationId": "portal_api_v1_billing_portal_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/me": { "get": { "tags": [ "users" ], "summary": "Me", "operationId": "me_api_v1_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/api-keys": { "get": { "tags": [ "users" ], "summary": "List Keys", "operationId": "list_keys_api_v1_api_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ApiKeyOut" }, "type": "array", "title": "Response List Keys Api V1 Api Keys Get" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "users" ], "summary": "Create API key", "description": "Creates an org-scoped control-plane API key. The full secret (`so_\u2026`) is returned once in `secret`. Use it as `Authorization: Bearer so_\u2026` for programmatic access and the docs try-it console.", "operationId": "create_key_api_v1_api_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyOut" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/api-keys/{key_id}": { "delete": { "tags": [ "users" ], "summary": "Revoke Key", "operationId": "revoke_key_api_v1_api_keys__key_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Key Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/organizations/me": { "get": { "tags": [ "organizations", "organizations" ], "summary": "Current organization", "description": "Active org from Clerk JWT claims or API key binding (null when none).", "operationId": "current_org_api_v1_organizations_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OrganizationMeOut" }, { "type": "null" } ], "title": "Response Current Org Api V1 Organizations Me Get" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/organizations/{org_id}/audit-log": { "get": { "tags": [ "organizations", "audit" ], "summary": "List Audit Log", "operationId": "list_audit_log_api_v1_organizations__org_id__audit_log_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "action", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" } }, { "name": "resource_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Type" } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Since" } }, { "name": "until", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Until" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogPage" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/organizations/{org_id}/audit-log/export": { "get": { "tags": [ "organizations", "audit" ], "summary": "Export Audit Log", "operationId": "export_audit_log_api_v1_organizations__org_id__audit_log_export_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Org Id" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "json", "csv" ], "type": "string", "default": "json", "title": "Format" } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Since" } }, { "name": "until", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Until" } } ], "responses": { "200": { "description": "JSON object with items, or CSV attachment when format=csv", "content": { "application/json": { "schema": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "AuditLogExportOut", "type": "object" } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid Bearer token (Clerk JWT or so_ API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Authenticated but not permitted (role or plan gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/health": { "get": { "tags": [ "health" ], "summary": "Health", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthOut" } } } } } } } }, "components": { "schemas": { "AgentBackupOut": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "agent_id": { "type": "string", "format": "uuid", "title": "Agent Id" }, "snapshot_id": { "type": "string", "title": "Snapshot Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size Bytes" }, "status": { "type": "string", "title": "Status" }, "source": { "type": "string", "title": "Source", "default": "volumesnapshot" } }, "type": "object", "required": [ "id", "agent_id", "snapshot_id", "created_at", "status" ], "title": "AgentBackupOut" }, "AgentConfigPublic": { "properties": { "provisioning_stages": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/ProvisioningStage" }, "type": "object" }, { "type": "null" } ], "title": "Provisioning Stages", "description": "Ordered readiness gates: namespace_created \u2192 helm_installed \u2192 pod_ready \u2192 sandbox_verified \u2192 dns_resolvable \u2192 tls_valid \u2192 wizard_reachable" }, "sandbox": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sandbox", "description": "Runtime sandbox: gvisor | none (legacy tenants may omit)", "examples": [ "gvisor" ] }, "dashboard_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Url" }, "api_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Url" }, "hostname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hostname" }, "dashboard_username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Username" } }, "additionalProperties": true, "type": "object", "title": "AgentConfigPublic", "description": "Documented subset of ``agent.config`` returned on AgentOut (extra keys allowed)." }, "AgentCreate": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name", "description": "Display name for the agent", "examples": [ "my-hermes" ] }, "resource_plan": { "$ref": "#/components/schemas/ResourcePlan", "description": "Plan tier: starter | pro | enterprise (CPU/memory/storage from PLAN_QUOTAS)", "default": "starter", "examples": [ "starter" ] }, "env_vars": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Env Vars", "description": "User-supplied env (filtered; dashboard auth keys rejected)" }, "config": { "additionalProperties": true, "type": "object", "title": "Config", "description": "Optional seed config; provisioning_stages are filled by the control plane" } }, "type": "object", "required": [ "name" ], "title": "AgentCreate" }, "AgentCredentialsOut": { "properties": { "dashboard_username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Username" }, "dashboard_password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Password" }, "api_server_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Server Key" }, "dashboard_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Url" }, "api_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Url" }, "dashboard_handoff_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Handoff Url" } }, "type": "object", "title": "AgentCredentialsOut", "description": "Sensitive Hermes credentials \u2014 only via authenticated reveal." }, "AgentLogsOut": { "properties": { "logs": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Logs", "description": "Recent log lines for the agent namespace" } }, "type": "object", "required": [ "logs" ], "title": "AgentLogsOut" }, "AgentMetricsOut": { "properties": { "cpu_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cpu Pct", "description": "CPU vs plan limit (%)" }, "mem_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mem Pct", "description": "Memory vs plan limit (%)" }, "restarts_24h": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Restarts 24H" }, "pvc_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Pvc Pct", "description": "PVC usage vs plan storage (%)" }, "uptime_pct_24h": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Uptime Pct 24H" }, "latency_p95_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Latency P95 Ms", "description": "Null until Managed Prometheus scrapes with Host match" }, "cpu_cores": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cpu Cores" }, "memory_bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Memory Bytes" }, "series": { "anyOf": [ { "$ref": "#/components/schemas/MetricsSeries" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Series" } }, "additionalProperties": true, "type": "object", "title": "AgentMetricsOut" }, "AgentOut": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Agent UUID" }, "name": { "type": "string", "title": "Name" }, "status": { "$ref": "#/components/schemas/AgentStatus", "description": "pending | provisioning | running | paused | stopped | error | deleting" }, "namespace": { "type": "string", "title": "Namespace", "description": "Kubernetes namespace (agent-{id})" }, "resource_plan": { "$ref": "#/components/schemas/ResourcePlan" }, "env_vars": { "additionalProperties": true, "type": "object", "title": "Env Vars" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/AgentConfigPublic" }, { "additionalProperties": true, "type": "object" } ], "title": "Config", "description": "Public agent config including provisioning_stages (secrets redacted)" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "dashboard_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Url", "examples": [ "https://my-hermes-abcd1234.agents.seaotter.dev" ] }, "api_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Url" }, "dashboard_handoff_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Handoff Url" }, "dashboard_username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dashboard Username" }, "hostname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hostname" } }, "type": "object", "required": [ "id", "name", "status", "namespace", "resource_plan", "config", "created_at", "updated_at" ], "title": "AgentOut" }, "AgentStatus": { "type": "string", "enum": [ "pending", "provisioning", "running", "paused", "stopped", "error", "deleting" ], "title": "AgentStatus" }, "AgentUpdate": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "examples": [ "renamed-hermes" ] }, "env_vars": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Env Vars" }, "config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config" } }, "type": "object", "title": "AgentUpdate" }, "AlertPreferencesOut": { "properties": { "email_enabled": { "type": "boolean", "title": "Email Enabled", "default": false }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url" }, "crash_loop": { "type": "boolean", "title": "Crash Loop", "default": false }, "pvc_high": { "type": "boolean", "title": "Pvc High", "default": false }, "oom": { "type": "boolean", "title": "Oom", "default": false }, "unreachable": { "type": "boolean", "title": "Unreachable", "default": false }, "unreachable_minutes": { "type": "integer", "title": "Unreachable Minutes", "default": 10 } }, "type": "object", "title": "AlertPreferencesOut" }, "AlertPreferencesUpdate": { "properties": { "email_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Email Enabled" }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url" }, "crash_loop": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Crash Loop" }, "pvc_high": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pvc High" }, "oom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Oom" }, "unreachable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Unreachable" }, "unreachable_minutes": { "anyOf": [ { "type": "integer", "maximum": 120.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Unreachable Minutes" } }, "type": "object", "title": "AlertPreferencesUpdate" }, "ApiKeyCreate": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name", "description": "Label for this key", "examples": [ "ci-deploy" ] } }, "type": "object", "required": [ "name" ], "title": "ApiKeyCreate" }, "ApiKeyOut": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "key_prefix": { "type": "string", "title": "Key Prefix", "description": "First characters of the secret for identification" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Secret", "description": "Full secret \u2014 returned only once on create", "examples": [ "so_\u2026" ] } }, "type": "object", "required": [ "id", "name", "key_prefix", "created_at" ], "title": "ApiKeyOut" }, "AuditLogOut": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "org_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Org Id" }, "actor_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Actor User Id" }, "action": { "type": "string", "title": "Action", "description": "Action verb, e.g. agent.create" }, "resource_type": { "type": "string", "title": "Resource Type" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Id" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "action", "resource_type", "created_at" ], "title": "AuditLogOut" }, "AuditLogPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AuditLogOut" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "items", "limit", "offset" ], "title": "AuditLogPage" }, "CheckoutOut": { "properties": { "url": { "type": "string", "title": "Url", "description": "Stripe Checkout URL" }, "id": { "type": "string", "title": "Id", "description": "Stripe Checkout Session id" } }, "type": "object", "required": [ "url", "id" ], "title": "CheckoutOut" }, "CheckoutRequest": { "properties": { "plan": { "$ref": "#/components/schemas/PlanTier", "default": "starter" } }, "type": "object", "title": "CheckoutRequest" }, "CredentialsRotate": { "properties": { "rotate_dashboard_password": { "type": "boolean", "title": "Rotate Dashboard Password", "default": false }, "rotate_api_key": { "type": "boolean", "title": "Rotate Api Key", "default": false }, "username": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Username" }, "password": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 8 }, { "type": "null" } ], "title": "Password" } }, "type": "object", "title": "CredentialsRotate", "description": "Rotate compromised Hermes credentials. At least one flag must be true." }, "DashboardAuthUpdate": { "properties": { "username": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Username" }, "password": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 8 }, { "type": "null" } ], "title": "Password" } }, "type": "object", "required": [ "username" ], "title": "DashboardAuthUpdate", "description": "Update Hermes dashboard basic-auth credentials (injected as HERMES_DASHBOARD_BASIC_AUTH_*)." }, "ErrorBody": { "properties": { "detail": { "anyOf": [ { "type": "string" }, { "items": {}, "type": "array" } ], "title": "Detail", "description": "Human-readable error, or validation error list", "examples": [ "Agent not found" ] } }, "type": "object", "required": [ "detail" ], "title": "ErrorBody", "description": "Standard FastAPI / SeaOtter error payload." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthOut": { "properties": { "status": { "type": "string", "title": "Status", "examples": [ "ok" ] }, "service": { "type": "string", "title": "Service", "examples": [ "seaotter-api" ] }, "environment": { "type": "string", "title": "Environment", "examples": [ "production" ] } }, "type": "object", "required": [ "status", "service", "environment" ], "title": "HealthOut" }, "MetricPoint": { "properties": { "t": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "title": "T", "description": "Unix timestamp or series index" }, "v": { "type": "number", "title": "V", "description": "Sample value" } }, "type": "object", "required": [ "t", "v" ], "title": "MetricPoint" }, "MetricsSeries": { "properties": { "cpu": { "items": { "$ref": "#/components/schemas/MetricPoint" }, "type": "array", "title": "Cpu" }, "memory": { "items": { "$ref": "#/components/schemas/MetricPoint" }, "type": "array", "title": "Memory" }, "requests": { "items": { "$ref": "#/components/schemas/MetricPoint" }, "type": "array", "title": "Requests" }, "errors": { "items": { "$ref": "#/components/schemas/MetricPoint" }, "type": "array", "title": "Errors" } }, "additionalProperties": true, "type": "object", "title": "MetricsSeries" }, "MigrateSandboxBody": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "default": true } }, "type": "object", "title": "MigrateSandboxBody", "description": "Enable or disable gVisor RuntimeClass on an existing tenant (preserves PVC)." }, "OrganizationMeOut": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "clerk_org_id": { "type": "string", "title": "Clerk Org Id" }, "name": { "type": "string", "title": "Name" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" }, "plan": { "$ref": "#/components/schemas/PlanTier" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "org:admin | org:member" }, "can_mutate": { "type": "boolean", "title": "Can Mutate" } }, "type": "object", "required": [ "id", "clerk_org_id", "name", "plan", "can_mutate" ], "title": "OrganizationMeOut" }, "PlanTier": { "type": "string", "enum": [ "starter", "pro", "enterprise" ], "title": "PlanTier" }, "PortalOut": { "properties": { "url": { "type": "string", "title": "Url", "description": "Stripe Customer Portal URL" } }, "type": "object", "required": [ "url" ], "title": "PortalOut" }, "ProvisioningStage": { "properties": { "status": { "$ref": "#/components/schemas/StageStatus", "description": "pending | waiting | ok | error | skipped", "examples": [ "ok" ] }, "ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ms", "description": "Elapsed milliseconds for this stage when known" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail", "description": "Operator-facing detail (events, host, error)" }, "host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Host", "description": "Hostname probed for DNS/TLS/HTTP stages" } }, "type": "object", "required": [ "status" ], "title": "ProvisioningStage", "description": "One readiness gate while an agent provisions or restores." }, "ResourcePlan": { "type": "string", "enum": [ "starter", "pro", "enterprise" ], "title": "ResourcePlan" }, "RestoreBody": { "properties": { "snapshot_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Snapshot Id" } }, "type": "object", "required": [ "snapshot_id" ], "title": "RestoreBody", "description": "Restore hermes-home from a recorded backup (VolumeSnapshot name or backup row id)." }, "SecretUpsert": { "properties": { "key": { "type": "string", "title": "Key", "description": "Env var name", "examples": [ "OPENAI_API_KEY" ] }, "value": { "type": "string", "title": "Value", "description": "Secret value (stored in Secret Manager)" } }, "type": "object", "required": [ "key", "value" ], "title": "SecretUpsert" }, "SecretUpsertOut": { "properties": { "secret_id": { "type": "string", "title": "Secret Id", "description": "GSM secret resource id / name" }, "key": { "type": "string", "title": "Key" } }, "type": "object", "required": [ "secret_id", "key" ], "title": "SecretUpsertOut" }, "StageStatus": { "type": "string", "enum": [ "pending", "waiting", "ok", "error", "skipped" ], "title": "StageStatus" }, "SubscriptionOut": { "properties": { "plan": { "$ref": "#/components/schemas/PlanTier" }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "current_period_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Current Period End" } }, "type": "object", "required": [ "plan", "status", "current_period_end" ], "title": "SubscriptionOut" }, "SubscriptionStatus": { "type": "string", "enum": [ "inactive", "trialing", "active", "past_due", "canceled" ], "title": "SubscriptionStatus" }, "UsageEventIn": { "properties": { "event_type": { "type": "string", "title": "Event Type", "examples": [ "tool_call" ] }, "quantity": { "type": "number", "title": "Quantity", "default": 1.0 }, "unit": { "type": "string", "title": "Unit", "default": "count" }, "meta": { "additionalProperties": true, "type": "object", "title": "Meta" } }, "type": "object", "required": [ "event_type" ], "title": "UsageEventIn" }, "UsageEventOut": { "properties": { "ok": { "type": "boolean", "title": "Ok", "default": true }, "id": { "type": "string", "title": "Id" } }, "type": "object", "required": [ "id" ], "title": "UsageEventOut" }, "UserOut": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "email": { "type": "string", "title": "Email" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "clerk_id": { "type": "string", "title": "Clerk Id" } }, "type": "object", "required": [ "id", "email", "name", "clerk_id" ], "title": "UserOut" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT or so_ API key", "description": "Clerk session JWT for the web app, or a control-plane API key (`so_\u2026`) from POST /api/v1/api-keys for programmatic / docs try-it use." } } }, "tags": [ { "name": "agents", "description": "Provision and operate Hermes agents" }, { "name": "billing", "description": "Stripe plans and subscriptions" }, { "name": "users", "description": "Current user and control-plane API keys" }, { "name": "organizations", "description": "Active organization context" }, { "name": "audit", "description": "Organization audit log (Enterprise)" }, { "name": "health", "description": "Liveness probes" } ] }