> ## Documentation Index
> Fetch the complete documentation index at: https://agent37.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Core concepts
> The two planes, the resource model, and the money model behind every Agent37 Cloud call.
Agent37 Cloud is two APIs that share one key, and three resources that nest.
## Two planes, one key
| Plane | Base URL | What it serves |
| --------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hosting API** | `https://api.agent37.com/v1` | Manages the fleet: [instances](/agents-api/instances), [templates](/agents-api/templates), [budgets](/agents-api/budgets), [exec](/agents-api/exec). |
| **Agent API** | `https://{instanceId}.agent37.app` | The agent itself. Every instance serves its own API: `POST /v1/responses` for [chat](/agents-api/chat), plus `/v1/sessions`, `/v1/files`, `/v1/models`, `/v1/health`, and `/v1/version`. |
Both planes take the same `sk_live_` key, in two different headers. The hosting API takes `Authorization: Bearer sk_live_...`. Instance URLs take the raw key as `X-Agent37-Key: sk_live_...`, which leaves `Authorization` free for your own app running inside the instance. Mint keys in the [dashboard](https://www.agent37.com/dashboard/cloud/api-keys); each key is scoped to one workspace. On the hosting API the key selects your workspace. On an instance URL, the platform edge authenticates the key, verifies the instance belongs to your workspace, and forwards the request to the gateway running inside the instance.
So you create an instance with one call to `api.agent37.com`, then talk to it at its own hostname:
```bash theme={null}
curl https://ab12cd34ef.agent37.app/v1/responses \
-H "X-Agent37-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "input": "Research the top 3 EV makers, write a memo." }'
```
Instance URLs require auth on every request: the `X-Agent37-Key` header for API calls, or a time-boxed [signed URL](/agents-api/urls#browser-access-with-signed-urls) to open a preview URL in a browser tab. An unauthenticated request gets a 401.
## The resource model
| Concept | What it is |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Instance** | An isolated, persistent computer that runs your agent. Built from a [template](/agents-api/templates). Lives until you delete it, metered per minute for what it holds: the full rate while running, disk alone while stopped or sleeping. Create one per end user. |
| **Session** | One conversation on an instance. A message starts one; reuse its `session_id` to continue. An instance can hold many. |
| **Response** | One agentic turn: your input, the agent's work, its reply. Stream it live, or reconnect to its stream by id. |
**The agent is not the model.** The *template* installs the agent software, the *gateway* inside the instance runs your sessions on it (Hermes and OpenClaw are the live agents today; Claude Code and Codex are coming soon), and the *model* is the LLM the agent thinks with, chosen per turn as `model` + `provider`.
### How they fit together
* Create an **instance** once per end user with `POST /v1/instances` on the hosting API. It keeps files, connected accounts, and memory across every session. An instance does not have to run around the clock: create it with `auto_sleep: true` and the platform checkpoints it to `sleeping` once it has been idle past its `idle_timeout_seconds`, billing disk alone while it sleeps (awake minutes bill at 4x the compute rate); any request to its URL wakes it transparently, usually well under a second. See [Auto-sleep](/agents-api/instances#auto-sleep).
* Start a **session** by sending a message to the instance's own URL: `POST https://{instanceId}.agent37.app/v1/responses`. Omit `session_id` and the gateway mints a new session; the reply carries the `session_id` you reuse to continue the thread. See [Sessions](/agents-api/sessions).
* Each message produces a **response**. Stream it live with `stream: true` (see [Streaming](/agents-api/streaming)), or reconnect a dropped stream with `GET /v1/responses/{id}/stream`.
## Every port has a derivable URL
Nothing about ports is declared per instance:
* The **instance URL**, `https://{instanceId}.agent37.app`, routes to the template's `default_port` — `3737`, the gateway, unless the template says otherwise. On the default template, `agent37-hermes`, that makes it the chat URL.
* Every other port is reachable at its **preview URL**, `https://{instanceId}-{port}.agent37.app` — for example `https://ab12cd34ef-9119.agent37.app`.
* A port can also get a permanent unauthenticated URL — see [Public ports](/agents-api/public-ports).
See [Instance and preview URLs](/agents-api/urls) for how routing and authentication work, and [Templates](/agents-api/templates) for `default_port` on your own images.
## One wallet, per-instance caps
Your workspace has exactly one pot of money: the wallet, funded by top-up from the [billing dashboard](https://www.agent37.com/dashboard/cloud/billing). Two things draw on it:
* **Compute.** Each instance is metered per minute: the full rate while running, disk alone while stopped or sleeping. See [Billing](/agents-api/billing).
* **Managed usage.** Every instance gets managed LLM, Brave search, and Composio credentials, metered at cost as the agent uses them.
Per-instance [budgets](/agents-api/budgets) are caps, not money. A budget bounds how much managed spend an instance may pull from the wallet: a monthly cap that resets each UTC month (default \$0) plus one-time top-up headroom. Raising a cap moves no funds; an instance with a generous cap and an empty wallet still gets refused.
## Conventions
* **Instance ids** are bare 10-character lowercase alphanumerics, like `ab12cd34ef`. No prefixes. The id doubles as the DNS label in the instance URL.
* **Session and response ids** are 32-character hex strings minted by the gateway, like `7f3e0b6c52a949d2b1c4a8e9d0f31726`.
* **Money** is integer micros: USD x 1e6, in `*_micros` fields.
* **Timestamps** are epoch seconds on the hosting API and epoch milliseconds on the agent API. The [App integrations](/agents-api/integrations) endpoints are the exception: they pass Composio's native shapes through unchanged, with millisecond timestamps.
* **Lists** wrap results in `{ "data": [...] }`. Instance and session lists are newest first. (The App integrations endpoints again pass Composio's native paginated and connection shapes through instead.)
An instance's `status` is one of `provisioning`, `running`, `stopping`, `stopped`, `starting`, `restarting`, `updating`, `sleeping`, `waking`, `failed`, `deleting`, or `deleted`; a response's `status` is `in_progress`, `completed`, `failed`, or `cancelled`.
## Next steps
Fork a white-label, multi-tenant dashboard and rebrand it — the fastest way to ship.
Create, size, and manage the agent's computer.
The core call and its response shape.
Pick a catalog agent or bring your own image.
Cap each instance's managed spend.