Skip to main content
@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), and session.send(text). A value to store comes next, as in files.write(path, content) and triggers.update(id, spec). Optional settings and filters come last, in one options object, as in agents.list({ template }), session.stream({ after }), and agent.sessions.create({ cwd }); a method that needs nothing else takes only that object, as agents.create({ template }) does.
  • A list of a paged collection returns a PageList: await it for the first page ({ data, nextCursor }), or for await over it to iterate every item. models.list() takes no options and is one page. session.events.list() resolves to one page, { data, hasMore }, paged by after and before, and files.list() and memory.list() resolve to every entry, { data }.
  • agents.create and agents.get return 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

A stream is an 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 throws PaddockError 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.