Create agent
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.
Authorizations
Clerk session JWT for the web app (active organization required), or an organization-scoped SEAOTTER access key (so_…) from POST /api/v1/api-keys for programmatic / docs try-it / MCP use. The same so_… value is both Authorization: Bearer so_… and SEAOTTER_API_KEY.
Body
Display name for the agent
1 - 120"my-hermes"
Plan size: hobby | startup | business | enterprise (CPU/memory/storage from PLAN_QUOTAS)
hobby, startup, business, enterprise, starter, pro "hobby"
Cloud partner id (only gcp is available today)
"gcp"
GCP region for the agent data plane
"us-central1"
User-supplied env (filtered; dashboard auth keys rejected)
Optional seed config; provisioning_stages are filled by the control plane
Response
Successful Response
Agent UUID
pending | provisioning | running | paused | stopped | error | deleting
pending, provisioning, running, paused, stopped, error, deleting Kubernetes namespace (agent-{id})
hobby, startup, business, enterprise, starter, pro Documented subset of agent.config returned on AgentOut (extra keys allowed).
- AgentConfigPublic
- Config
Cloud partner id
Data-plane region
Role-aware env metadata. Members: empty. Admins/API keys: key → gsm | configured (never plaintext or full gsm: resource ids).
"https://my-hermes-abcd1234.agents.seaotter.dev"
True while the Hermes dashboard may be briefly unavailable after a pod restart (secrets, Restart, credential rotate). Poll GET /agents/{id}/dashboard-reachability until clear.
True while a credential rotation is still converging onto the live Hermes gateway. Prefer waiting / retrying talk rather than assuming the revealed key is already accepted.

