Instances
An instance is one pod running one platform (engine). The API calls it an *agent*; the namespace it runs in is dseq (ap-…).
Create
POST /api/agents — body fields:
| field | required | meaning |
|---|---|---|
personaId | yes | which persona to load; any id from GET /api/personas (Hermes uses it fully, other engines only for the name) |
tier | yes | tiny, small, medium, large; must satisfy the engine's minTier |
engine | no | default hermes; see GET /api/engines |
name | no | up to 60 chars; the pod's hostnames are derived from it |
channels | no | subset of web, telegram, discord, whatsapp, email; default ["web"] |
lang | no | en or ru, passed to the persona |
model | no | model id for the engine, e.g. deepseek-v4-flash |
tools | no | { "enabled": [toolset ids], "mcpServers": [...] }; ids from GET /api/tools; a2a enables agent-to-agent and the web chat |
domain | no | your own hostname, e.g. agent.example.com; names under agentspodium.com are assigned automatically and refused here |
extraSoul | no | up to 4000 chars of owner instructions appended to the persona |
Free pods per account: 3 at once. Above that the call answers 400 and asks to upgrade or delete one.
Read
GET /api/agents— all your instances.GET /api/agents/:id— one; the important fields:
| field | meaning |
|---|---|
status | provisioning (being built), running, stopped (paused), failed, deleted |
endpointUrl | the engine's own dashboard, https://<slug>-pod.agentspodium.com |
a2aUrl, a2aToken | agent-to-agent endpoint and its bearer; both null when the a2a toolset is off |
a2aSlug | the stable label all hostnames are built from |
domain | your own domain if set, otherwise <slug>.agentspodium.com |
quotaStatus, quota | resource state; see health |
llmProvider | which provider's key is installed, null when none |
dseq | namespace on the cluster |
Change
| call | effect |
|---|---|
POST /api/agents/:id/upgrade { "tier" } | new plan, pod rebuilt with data migrated |
PATCH /api/agents/:id/llm-key { "key", "provider", "model"? } | install a model key; "key": null removes it |
PATCH /api/agents/:id/tools | toolsets and MCP servers |
PATCH /api/agents/:id/channels | messengers |
PATCH /api/agents/:id/telegram { "token" } | Telegram bot token for the pod |
PATCH /api/agents/:id/instructions | owner instructions |
PATCH /api/agents/:id/timezone | schedules use it |
PUT /api/agents/:id/peers | other agents this one may call, see a2a |
POST /api/agents/:id/pause, /resume | stop billing the pod's resources / start again |
POST /api/agents/:id/rebuild | fresh pod from the last backup |
DELETE /api/agents/:id | gone, after a final backup |
Every change that rebuilds the pod answers with status: "provisioning"; poll GET /api/agents/:id until running, then liveness.
Data
POST /api/agents/:id/backupandGET /api/agents/:id/backups— server-side snapshots, kept 7 days, one taken daily.GET /api/agents/:id/export— a tar of the pod's own data (persona, skills, memory), any time, free.GET /api/agents/:id/memory— what a Hermes agent remembers, read-only.