# Quickstart: from nothing to a running pod in seven calls

Base URL for everything: `https://agentspodium.com/api`. All requests and responses are JSON. Authenticated calls send `Authorization: Bearer <token>`, where the token is either an API key (`ak_live_…`, see [auth](auth.md)) or a session token from the e-mail code.

## 1. See what exists (no auth)

```bash
curl -s https://agentspodium.com/api/engines   # platforms and their smallest plan
curl -s https://agentspodium.com/api/tiers     # plans, prices, resources
curl -s https://agentspodium.com/api/personas  # ready-made agent personas (for the Hermes engine)
```

Current plans:

| plan | monthly | yearly | resources |
|---|---|---|---|
| `tiny` | $2.49 | $24.90 | 1 GB RAM · 1 vCPU · 4 GB disk |
| `small` | $4.99 | $49.90 | 2 GB RAM · 2 vCPU · 6 GB disk |
| `medium` | $9.99 | $99.90 | 4 GB RAM · 2 vCPU · 8 GB disk |
| `large` | $17.99 | $179.90 | 8 GB RAM · 4 vCPU · 16 GB disk |

Current platforms (`engine` values):

| engine | label | smallest plan | status |
|---|---|---|---|
| `hermes` | Hermes | tiny | stable |
| `openclaw` | OpenClaw | tiny | beta |
| `n8n` | n8n | small | beta |
| `claude-code` | Claude Code | small | beta |
| `opencode` | OpenCode | tiny | beta |
| `pi` | Pi | tiny | beta |

## 2. Authenticate

Either use an API key your operator created (recommended for agents):

```bash
export TOKEN=ak_live_…
```

or sign in with an e-mail code if you can read that mailbox — see [auth](auth.md).

## 3. Create the pod

```bash
curl -s -X POST https://agentspodium.com/api/agents \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"personaId":"personal-assistant","tier":"tiny","engine":"hermes","name":"my-first-pod","channels":["web"]}'
```

The call is synchronous: it returns when the pod exists, usually within one to two minutes. The response is `{ "agent": { … } }` with `id`, `status`, `endpointUrl`, `a2aUrl`, `a2aToken`, `dseq` (the namespace) and more — see [instances](instances.md). `status` is `running` when the pod is up; the engine inside may need another ten seconds to answer, which is what the next call tells you.

## 4. Wait until it serves

```bash
curl -s https://agentspodium.com/api/agents/$ID/liveness -H "Authorization: Bearer $TOKEN"
# {"reachable":true,"serving":false}   → pod is up, engine still booting; poll every 5 s
# {"reachable":true,"serving":true}    → ready
```

## 5. Give it a model key

Pods ship without an LLM key; without one the agent accepts messages and answers nothing. Set the customer's own key for the provider they use:

```bash
curl -s -X PATCH https://agentspodium.com/api/agents/$ID/llm-key \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"key":"sk-…","provider":"deepseek","model":"deepseek-v4-flash"}'
```

Providers: `openai`, `anthropic`, `openrouter`, `google`, `gemini`, `groq`, `mistral`, `deepseek`, `xai`, `nous`. Use the model id the provider publishes. This rebuilds the pod (about a minute); poll liveness again.

## 6. Know when it expires

```bash
curl -s https://agentspodium.com/api/agents/$ID/term -H "Authorization: Bearer $TOKEN"
# {"term":{"mode":"trial","stopsAt":"…","deletesAt":"…","paidTill":null,"renewUrl":"…"}}
```

Every new pod starts a 7-day free trial without a card; after `stopsAt` it is paused, after `deletesAt` it is deleted. Details in [expiry](expiry.md); how to pay in [payment](payment.md).

## 7. Talk to it

- Agent-to-agent: `a2aUrl` + `a2aToken`, card at `<a2aUrl>/.well-known/agent-card.json` — see [a2a](a2a.md).
- Human chat: `https://chat.agentspodium.com/?models=<a2aSlug>` for the pod's owner.
- Dashboard of the engine: `endpointUrl`.

Delete when done: `DELETE /api/agents/$ID`.