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

# TypeScript server

> @paddock/server: the TypeScript SDK for your backend. Install, authenticate, and call every operation.

`@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

```bash theme={null}
npm install @paddock/server
```

> [!NOTE]
>
> `@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

```ts theme={null}
import { Paddock } from "@paddock/server";

const paddock = new Paddock(); // PADDOCK_API_KEY, PADDOCK_BASE_URL
```

| Option | Default |
| - | - |
| `apiKey` | `PADDOCK_API_KEY`, then `apiKey` of the [credentials file](https://docs.paddock.build/platform/authentication.md#api-keys) when the base URL is unset or the file's; the constructor throws when none is set |
| `baseUrl` | `PADDOCK_BASE_URL`, then `baseUrl` of the credentials file when the key is the file's, then `https://api.paddock.build/v1` |
| `maxRetries` | 2 retries of idempotent requests; `0` turns them off |
| `timeoutMs` | 60 seconds per request; 10 minutes for files and memory |
| `fetch` | A `fetch` to use instead of the global one |

Never use this SDK in a browser: it holds your API key. The browser uses [`@paddock/client`](https://docs.paddock.build/sdks/client) with a session token.

## Conventions

* Names and fields are spelled exactly as the [API reference](https://docs.paddock.build/api-reference/introduction.md) 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

```ts theme={null}
import { Paddock, isStreamingMessageEvent } from "@paddock/server";

const paddock = new Paddock();
const template = await paddock.templates.create("./agents/code-maintainer/template.yaml");
const agent = await paddock.agents.create({
  template: `${template.name}@${template.version}`,
  metadata: { teamId: "t_42" },
});
const session = await agent.sessions.create({ cwd: "repos/web" });
const sent = await session.send("CI failed on main; fix it.");

const stream = session.stream({ after: sent.seq });
for await (const ev of stream) {
  if (ev.event === "message" && isStreamingMessageEvent(ev.data)) continue; // text so far
  if (ev.event === "message" && ev.data.type === "message" && ev.data.message.kind === "tool_call") {
    console.log(ev.data.message.toolCall.tool, ev.data.message.toolCall.input);
  }
  if (ev.event === "turn.ended") {
    console.log("turn", ev.data.turn.outcome);
    stream.close();
  }
}
```

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

| Resource | Methods |
| - | - |
| `paddock.templates` | `create(pathOrDocument, { dryRun? })`, `get(ref)`, `list({ name? })`, `delete("name@version")` |
| `paddock.models` | `list()` |
| `paddock.modelProviders` | `list()`, `get(name)`, `create(spec)`, `update(name, patch)`, `delete(name)`, `test(nameOrDraft, { testModel? })` |
| `paddock.agents` | `create({ template, metadata? })`, `get(id)`, `list({ template?, metadata? })`, `delete(id)` |
| `agent.mcp`, `agent.plugins`, `agent.env` | `list()`, `get(name)`, `add(entry)`, `update(name, entry)`, `delete(name)` |
| `agent.marketplaces` | The same, and `refresh(name)` |
| `agent.modelSetting`, `agent.smallModelSetting`, `agent.systemPrompt` | `get()`, `set(value)`, `delete()` |
| `agent.permissions` | `get()`, `set(spec)` |
| `agent.workflows` | `list()`, `get(name)` |
| `agent.export()` | The agent's effective spec as a `TemplateDocument` |
| `agent.memory` | `list()`, `read(path)`, `write(path, content)`, `delete(path)` |
| `agent.files` | `list(dir?, { recursive? })`, `read(path)`, `write(path, data)`, `delete(path, { recursive? })` |
| `agent.sessions` | `create({ cwd?, systemPrompt?, metadata? })`, `list({ metadata? })` |
| `paddock.sessions` | `get(id)`, `list({ agentId?, metadata?, createdAfter?, createdBefore? })`, `delete(id)` |
| `session` | `send(text)`, `stop()`, `stream({ after? })`, `createToken({ ttl })` |
| `session.events` | `list({ after?, before?, types?, limit? })` |
| `session.turns` | `list()`, `get(turnId)` |
| `paddock.triggers` | `create(spec)`, `get(id)`, `list()`, `update(id, spec)`, `delete(id)`, `test({ trigger, event })` |
| `trigger.secret` | `get()`, `rotate({ secret? })` |
| `trigger.deliveries` | `list({ status? })`, `get(deliveryId)`, `replay(deliveryId)` |

`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](https://docs.paddock.build/guides/templates.md), [Agents and sessions](https://docs.paddock.build/guides/agents-and-sessions.md), [Capabilities](https://docs.paddock.build/guides/capabilities.md), [Configuration](https://docs.paddock.build/guides/configuration.md), [Models](https://docs.paddock.build/guides/models.md), [Triggers](https://docs.paddock.build/guides/triggers.md), and [Files](https://docs.paddock.build/guides/files.md).

## 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](https://docs.paddock.build/platform/errors.md).


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