Skip to main content
POST
Create agent

Authorizations

Authorization
string
header
required

Clerk session JWT for the web app, or a control-plane API key (so_…) from POST /api/v1/api-keys for programmatic / docs try-it use.

Body

application/json
name
string
required

Display name for the agent

Required string length: 1 - 120
Example:

"my-hermes"

resource_plan
enum<string>
default:starter

Plan tier: starter | pro | enterprise (CPU/memory/storage from PLAN_QUOTAS)

Available options:
starter,
pro,
enterprise
Example:

"starter"

env_vars
Env Vars · object

User-supplied env (filtered; dashboard auth keys rejected)

config
Config · object

Optional seed config; provisioning_stages are filled by the control plane

Response

Successful Response

id
string<uuid>
required

Agent UUID

name
string
required
status
enum<string>
required

pending | provisioning | running | paused | stopped | error | deleting

Available options:
pending,
provisioning,
running,
paused,
stopped,
error,
deleting
namespace
string
required

Kubernetes namespace (agent-{id})

resource_plan
enum<string>
required
Available options:
starter,
pro,
enterprise
config
AgentConfigPublic · object
required

Documented subset of agent.config returned on AgentOut (extra keys allowed).

created_at
string<date-time>
required
updated_at
string<date-time>
required
env_vars
Env Vars · object
error_message
string | null
dashboard_url
string | null
Example:

"https://my-hermes-abcd1234.agents.seaotter.dev"

api_url
string | null
dashboard_handoff_url
string | null
dashboard_username
string | null
hostname
string | null