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

# Introduction

> The HTTP API behind every SDK: base URL, authentication, formats, IDs, lists, and errors.

Every SDK calls this HTTP API, and you can call it directly. The pages of this reference are generated from paddock's OpenAPI document; each operation's title is its SDK spelling, such as `agent.sessions.create(...)`.

## Base URL

```text theme={null}
https://api.paddock.build/v1
```

The webhook endpoint of triggers has a host of its own; see [Trigger webhook](https://docs.paddock.build/api-reference/webhook.md).

## Authentication

Send an API key, or a session token on its own session, as a bearer token:

```bash theme={null}
curl https://api.paddock.build/v1/agents \
  -H "Authorization: Bearer $PADDOCK_API_KEY"
```

See [Authentication](https://docs.paddock.build/platform/authentication.md) for what each credential may call.

## Formats

| Rule | Meaning |
| - | - |
| Bodies | JSON (`application/json`), with camelCase fields. A template document may also be YAML (`application/yaml`); file contents are raw bytes; the stream is `text/event-stream` |
| Timestamps | RFC 3339 in UTC with milliseconds: `2026-11-13T08:15:30.123Z` |
| Requests | Closed: an unknown field is `400 invalid_request` |
| Responses | Open: new fields may appear, and enums may gain values; read them leniently |
| Absent values | A field typed as nullable is present as `null`; an optional field is omitted |
| Request IDs | Every response carries a `Request-Id` header |
| CORS | Any origin may call the API with the `Authorization`, `Content-Type`, and `Paddock-Client` headers; no cookies are used |

## IDs

Every ID is a [TypeID](https://github.com/jetify-com/typeid): a type prefix, an underscore, and 26 lowercase base32 characters, such as `agt_01h455vb4pex5vsknk084sn02q`. IDs sort by creation time. Treat them as opaque strings.

| Prefix | Identifies |
| - | - |
| `agt_` | An agent |
| `ses_` | A session |
| `trn_` | A turn |
| `msg_` | A message |
| `trg_`, `dlv_` | A trigger, and a delivery to it |
| `key_` | An API key |
| `req_` | A request, in `Request-Id` |

## Lists

Lists of templates, agents, sessions, turns, capability entries, model providers, triggers, and deliveries take `limit` (default 50, at most 200) and `cursor`, and return:

```json theme={null}
{ "data": [], "nextCursor": "eyJ..." }
```

Pass `nextCursor` as `cursor` for the next page; it is `null` on the last. Lists are newest first by creation, except templates (newest first by their latest version's creation), capability collections (by name), turns (newest first by start), deliveries (newest first by receipt), and model providers (by name). A metadata filter matches every listed key exactly: `?metadata[teamId]=t_42`. `GET /models` is one page.

A session's events are paged by `seq` instead: `after`, `before`, `types`, and `limit`, answered as `{ data, hasMore }`. A directory of files or memory is answered whole, as `{ data }`.

## Errors

Every non-2xx response is `{ "error": { "code", "message", "details" } }` with a stable `code` mapped to the HTTP status; `details` is left out when it would be empty. See [Errors](https://docs.paddock.build/platform/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.