Skip to main content
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

The webhook endpoint of triggers has a host of its own; see Trigger webhook.

Authentication

Send an API key, or a session token on its own session, as a bearer token:
See Authentication for what each credential may call.

Formats

IDs

Every ID is a 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.

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:
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.