@paddock/server is the TypeScript and JavaScript SDK for your backend, authenticated with a secret API key. It runs on Node.js 20 or later, and on Bun and Deno for everything except reading a template file. It has no runtime dependencies and ships ESM and CommonJS builds with type declarations.
Install
@paddock/server is not on npm yet. Until it is published, build it from the sdk/js workspace of the paddock repository.Create a client
Never use this SDK in a browser: it holds your API key. The browser uses
@paddock/client with a session token.
Conventions
- Names and fields are spelled exactly as the API reference spells them, in camelCase.
- A method takes what it acts on positionally: an ID, a name, a path, or a message’s text, as in
agents.get(id),templates.create(path),files.read(path), andsession.send(text). A value to store comes next, as infiles.write(path, content)andtriggers.update(id, spec). Optional settings and filters come last, in one options object, as inagents.list({ template }),session.stream({ after }), andagent.sessions.create({ cwd }); a method that needs nothing else takes only that object, asagents.create({ template })does. - A list of a paged collection returns a
PageList:awaitit for the first page ({ data, nextCursor }), orfor awaitover it to iterate every item.models.list()takes no options and is one page.session.events.list()resolves to one page,{ data, hasMore }, paged byafterandbefore, andfiles.list()andmemory.list()resolve to every entry,{ data }. agents.createandagents.getreturn an agent with its sub-resources (agent.mcp,agent.sessions,agent.files); sessions carry their operations (session.send,session.stream). They are not enumerable, so the agent serializes as plain data.- Enums are open: a value a newer server sends is kept as a string.
isKnownMessageKind(kind)tells a message kind this version knows apart.
The main flow
AsyncIterable<StreamEvent> with close(). Each StreamEvent has event (the SSE event name), data, and, for a stored event, id. event narrows data: session carries the session, message an event holding a message, and every other event type its event.
Operations
templates.create with a path reads the YAML file and sends it as it is; with a document object it sends JSON. What each operation does is in the guides: Templates, Agents and sessions, Capabilities, Configuration, Models, Triggers, and Files.
Errors
A non-2xx answer throwsPaddockError with status, code, message, details, and requestId. No answer throws PaddockConnectionError, or its subclass PaddockTimeoutError. Check with PaddockError.is(e), which works across separately bundled copies of the SDK. Idempotent requests are retried after a connection error, a timeout, or a 5xx; a POST never is. See Errors.