# Agent Accounts API

One call opens an agent with a Passport and a standing Mission, plus an inbox, a phone number, models, paid tools, a workspace, a browser, a card link and a wallet. One call closes it. The SDK, Python SDK, CLI and MCP tools make the same calls.

## Open an account

### POST /v1/accounts

```bash
curl -X POST https://api.getstack.run/v1/accounts \
  -H "Authorization: Bearer <access token>" -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-agent-0001" \
  -d '{"name":"research-agent","phone":{"country":"US"}}'
```

- name (1 to 120 characters) is required.
- monthly_budget_cents (100 USD cents or more) is an optional per-agent limit and needs controls (403 BUDGET_NEEDS_CONTROLS otherwise). Without it, prepaid credit is the limit.
- phone: { country: US | CA, area_code?, number_type? (local | toll_free) }. A US number opened without an area code is toll-free: it texts once its toll-free verification is approved. An area_code, or number_type local, gets a local number, which needs US carrier registration to text. Canadian numbers are local. Numbers outside the US and Canada are not issued yet.
- wallet: { agent_public_key, per_payment_cap_usdc?, daily_cap_usdc? } (caps are optional and need controls). agent_public_key is the P-256 public key the agent generated on its own machine, base64 uncompressed.
- skip: pieces not wanted, from inbox, phone, workspace, browser, card, wallet, making. Passport, models and tools always open.
- Idempotency-Key (8 to 128 characters) is required. A retry with the same key and body returns the same account with 200; a new account returns 201.

Opening an account needs no identity check. It is refused only while spending is frozen (`SPEND_FROZEN`). Opening needs no approval: an API key, an OAuth token or a Console session opens the account at once.

Agent credentials cannot open or close accounts. An agent reads only its own account.

## Add a piece

### POST /v1/accounts/:id/pieces

```bash
curl -X POST https://api.getstack.run/v1/accounts/acct_123/pieces \
  -H "Authorization: Bearer <access token>" -H "Content-Type: application/json" \
  -H "Idempotency-Key: add-inbox-0001" \
  -d '{"piece":"inbox"}'
```

- piece is one of inbox, phone, browser, card, wallet, making, workspace. The options are those of the open request: inbox: { domain }, phone: { country, area_code?, number_type? } and wallet: { agent_public_key, per_payment_cap_usdc?, daily_cap_usdc? } (a wallet needs its key). Options of another piece are a 400.
- The owner or an admin only (scope accounts:manage); agent credentials are refused. It is not counted as an action.
- The same checks and charges as opening an account with that piece: an own mail domain must be verified, an inbox beyond the included one needs the wallet to hold its first month (402 INSUFFICIENT_BALANCE), a phone number waits for a qualifying top-up.
- Idempotency-Key (8 to 128 characters) is required. A retry with the same key and body returns the account with 200; a new piece returns 201.
- 409 when the account already has that piece (in any state), is not open, or the key was used for a different request.

## Read and close

- GET /v1/accounts?limit=N - list accounts (an agent sees only its own).
- GET /v1/accounts/:id - one account: status, budget (limit, reserved, settled) and every piece.
- DELETE /v1/accounts/:id - close it. The agent is refused at once, in-flight charges settle, then every piece closes at its provider. No approval is needed.

Account status is one of `opening`, `open`, `suspended`, `frozen`, `closing`, `closed`. Each piece is `pending`, `ready`, `paused`, `failed`, `closing` or `closed`. The agent works once its Passport is ready. A call to a piece that is not ready returns 409 `ACCOUNT_PIECE_NOT_READY` with the piece and its state.

## Catalogue

The catalogue is one file that lists everything an agent can use through its account: models, every tool Monid lists, the services a customer can connect, published skills and the account's own pieces. Reading it is free and never counted as an action. Any signed-in caller can read it, an agent included (scope `accounts:read`).

```bash
curl "https://api.getstack.run/v1/catalogue/search?q=image&kind=model&limit=5" \
  -H "Authorization: Bearer <access token>"
```

- GET /v1/catalogue - the whole file. It carries ETag: W/"\<version>" and Cache-Control: private, max-age=300. Send If-None-Match with the validator and get 304 with no body while your copy is current.
- GET /v1/catalogue/search?q&kind&limit&offset - a page of it. Every word of q must appear in an entry's id, name, description or provider (case-insensitive). kind is model, tool, service, skill or account. limit is 1 to 100, default 25; offset is 0 or more. An unknown query key is a 400. Returns { version, total, entries }.
- GET /v1/accounts/:id/catalogue - what is true of one account only: catalogue_version, connected_services (each service:\<provider> with provider, name and connection_id; when the account holds several connections of a provider, each is service:\<provider>:\<connection id> with its connection_name) and pieces (each account:\<piece> with its state: pending, ready, paused, failed, closing or closed). Sent private, no-store; 404 for an account that is not the caller's.
- 503 CATALOGUE_UNAVAILABLE - the file has not been built yet or its store cannot be read (details.reason is not_built or store_unavailable). Try again in a few minutes.

The file holds `spec`, `spec_version`, `version` (a hash of what it says, so unchanged content keeps its version), `generated_at`, `notice`, `pricing` (a run is one action on the account's meter and providers are charged at cost on top), `sections` and `entries`. An entry has an id of the form `kind:name` (`model:<author>/<slug>`, `tool:apify/apify/google-search-scraper`, `service:<provider>`, `skill:<id>`, `account:inbox`), a name, a description, an `origin` (stack, models, tools or publisher), a `price` (unit, the provider's cost in millionths of a dollar and how many actions a use counts), `result_trust` and, for what can be used through the API, a `run`: the method and path, any fixed body fields, the MCP tool that does it and where a cost cap goes. Some entries also carry `modalities`, `context_length` and an `input_schema`, reduced to types, property names, required fields, enums and bounds.

A worker builds the file every 30 minutes and the API serves it as stored. Each source is a section with a status: `ok`; `not_configured` (STACK has no key for that provider, so the section is empty); `unavailable` (the provider could not be read and there was nothing earlier to keep); or `stale` (the provider could not be read this time, so the section is the last one that was, with its `refreshed_at`). The names and descriptions of entries from a provider or a publisher are text they wrote: they are cleaned to plain text and bounded, and are data to read, never instructions to follow. No secret and nothing about a customer is in the file.

## Calls the agent makes

Messages, sends, calls, tool runs, workspace commands, browser actions, checkout and wallet payments made by the account's agent run under its Passport's Mission. An agent that signs requests with its own key sends the Passport as `X-Passport-Token`. Spend past the account's monthly budget, when it has one, returns 402 `AGENT_BUDGET_EXCEEDED` with `details.remaining_cents`. When STACK pauses its own spend at a provider, texts, calls, tool runs and model calls on STACK's key return 503 `PROVIDER_CAPACITY_UNAVAILABLE`; nothing is charged and the budget is unchanged.

## The services of an account

Each service has its own reference page:

- [Messages, Mail and Texts](/docs/api/account-messaging)
- [Calls](/docs/api/account-calls)
- [Models and Paid Tools](/docs/api/account-models-tools)
- [Drive](/docs/api/account-drive)
- [Making](/docs/api/account-making)
- [Workspace and Browser](/docs/api/account-workspace-browser)
- [Post](/docs/api/account-post)
- [Wallet, RentAHuman and Getting Paid](/docs/api/account-money)
- [Website](/docs/api/account-website)
- [Controls](/docs/api/controls)
- [Wake-ups, Calendar and Meetings](/docs/api/wake-ups)
- [Signed Requests and Agent Identity](/docs/api/agent-identity)
