> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Loadout REST API v1 Endpoints and Pagination

> The REST API v1 exposes every agent capability over plain HTTP. Authenticate with your agent token, hit the base URL, and get JSON back.

The REST API v1 gives you direct HTTP access to every capability your agent token unlocks — the same inboxes, vault entries, payment cards, and Linux machines you can reach through MCP. Use it from any language, script, or service that is not an MCP client. Every endpoint accepts and returns JSON.

## Base URL

```
https://agent-loadout.com/api/v1
```

## OpenAPI spec

A machine-readable OpenAPI document is available for import into Postman, Insomnia, or any other HTTP client:

```
https://agent-loadout.com/api/v1/openapi.json
```

## Authentication

Pass your agent token as a Bearer token in the `Authorization` header on every request. Tokens are issued per agent and carry only the capabilities you granted at creation time.

```bash theme={null}
curl https://agent-loadout.com/api/v1/me \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

See [Authentication](/api-reference/authentication) for full details on token types, scopes, and how to issue tokens programmatically.

## Quick examples

<CodeGroup>
  ```bash Who am I? theme={null}
  curl -s https://agent-loadout.com/api/v1/me \
    -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
  ```

  ```bash List inboxes theme={null}
  curl -s https://agent-loadout.com/api/v1/inboxes \
    -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
  ```
</CodeGroup>

## Pagination

The `messages`, `threads`, and `drafts` endpoints are cursor-paginated. Pass `limit` (1–100) to control page size and `cursor` to advance through results. Each response that has more pages includes a `next_cursor` field — pass its value as `cursor` on your next request.

```bash title="Paginating messages" theme={null}
# First page
curl -s "https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/messages?limit=20" \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"

# Next page — use the next_cursor value from the previous response
curl -s "https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/messages?limit=20&cursor=<NEXT_CURSOR>" \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

## Read state

Fetching messages or threads through the API does **not** mark conversations as read. To mark a conversation read for the agent, send a `PATCH` to `/api/v1/threads/:id` with `{"read": true}`. Read state is tracked per side — the agent tracks what it has handled, and members track what they have seen.

## Content-Type

Include `Content-Type: application/json` on all `POST` and `PATCH` requests that carry a body.

```bash title="POST with a JSON body" theme={null}
curl -s -X POST https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/messages \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":["person@example.com"],"subject":"Hello","text":"Sent by my agent.","idempotency_key":"hello-1"}'
```

## Explore the API

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Agent tokens, organization keys, OAuth 2.1 scopes, and how to issue tokens via API.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/api-reference/errors">
    HTTP status codes, JSON error envelope format, and idempotency guidance.
  </Card>

  <Card title="Email" icon="envelope" href="/api-reference/email/messages">
    Read, send, reply, forward, draft, and manage mailbox folders.
  </Card>

  <Card title="Vault" icon="lock" href="/api-reference/vault/credentials">
    List credentials, retrieve values, generate TOTP codes, and manage accounts.
  </Card>

  <Card title="Machines" icon="server" href="/api-reference/machines/machines">
    Create, run, snapshot, and delete Ubuntu machines for your agents.
  </Card>
</CardGroup>