# 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](health.md) |
| `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](a2a.md) |
| `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](health.md).

## Data

- `POST /api/agents/:id/backup` and `GET /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.