---
name: xrpc-server
description: >-
  Build or edit routes on an AT Protocol service that uses `@atproto/xrpc-server` — `packages/pds`, `packages/bsky`, `packages/ozone`, or any package whose handlers call `server.add()`. Use when adding or changing an endpoint, wiring `createServer` into Express, reading params/input/auth in a handler, returning JSON, binary, streamed, or empty responses, setting response headers, throwing XRPC protocol errors, applying per-route rate limits or body limits, or exposing a WebSocket subscription. To migrate a service off the legacy generated server stack, use the lexification-server skill instead. For calls the service makes *out* to other services, use the lex-client skill.
disable-model-invocation: false
title: xrpc-server
canonical_url: https://skilld.dev/gh/bluesky-social/atproto/xrpc-server
last_updated: 2026-11-18T22:11:22.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install bluesky-social/atproto/xrpc-server`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/xrpc-server`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/bluesky-social/atproto/xrpc-server) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/xrpc-server`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/xrpc-server --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/xrpc-server --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# `@atproto/xrpc-server`

The server half of the AT Protocol XRPC stack. Service code creates a `Server`
and registers endpoints by passing generated lexicon schemas to `server.add()`.

Import it directly — it is **not** re-exported by `@atproto/lex`:

```ts
import { InvalidRequestError, type Server } from '@atproto/xrpc-server'
```

This is the server package the services actually use — `@atproto/lex-server` is
a separate package that no service in this repo consumes. `packages/pds`,
`packages/bsky` and `packages/ozone` are all fully on `server.add()`.

Watch the casing: `XRPCError` is this package's server-side class, thrown in
handlers. `XrpcError` is the _client_-side class from `@atproto/lex-client`.

## Creating the server

```ts
import { createServer } from '@atproto/xrpc-server'

const server = createServer([], {
  validateResponse: config.debugMode,
  payload: {
    jsonLimit: 100 * 1024,
    textLimit: 100 * 1024,
    blobLimit: 5 * 1024 * 1024,
  },
})

app.use(server.router) // Express
```

The first argument is an array of legacy `LexiconDoc`s — pass `[]` for
schema-based setups. It is not middleware. Other `Options` worth knowing:
`catchall` (a fallback `RequestHandler`, used by the PDS for proxying),
`errorParser` (map non-`XRPCError` throwables onto XRPC errors before they are
rendered), and `rateLimits` (global/shared limiter wiring).

`server.router` is the Express app. Legacy generated servers expose
`server.xrpc.router` instead — if you see that, you are in legacy code.

WebSocket upgrades are wired up automatically when the server's router is
mounted on an app that later calls `.listen()`; there is nothing extra to do
for subscriptions beyond registering them.

## Registering a route

`server.add(schema, handlerOrConfig)`. The schema is the generated lexicon
object, e.g. `com.atproto.identity.resolveHandle`.

Bare-function form when the route needs nothing but a handler:

```ts
import type { Server } from '@atproto/xrpc-server'
import { com } from '../../../lexicons/index.js'

export default function (server: Server, ctx: AppContext) {
  server.add(com.atproto.identity.resolveHandle, async ({ params }) => {
    const did = await resolve(params.handle)
    return { encoding: 'application/json', body: { did } }
  })
}
```

Object form for anything else — `auth`, `rateLimit`, `opts`:

```ts
server.add(app.bsky.draft.createDraft, {
  auth: ctx.authVerifier.standardWriteService(),
  handler: async ({ input, auth }) => {
    const actorDid = auth.credentials.iss
    if (atLimit)
      throw new InvalidRequestError('Drafts limit reached', 'DraftLimitReached')
    return { encoding: 'application/json', body: { draft } }
  },
})
```

Registration is conditional-friendly: it is normal to `return` early when a
dependency is absent (`if (!ctx.bskyAppView) return`), or to register a
different handler for the same NSID on each branch of an `if`.

### Handler context

`{ params, input, auth, req, res, resetRouteRateLimits }`. Queries read
`params`, procedures read `input.body`; `req`/`res` are Express objects, useful
for reading request headers or setting response headers directly.

There is **no `signal`** on a method handler — only subscription handlers get
one. `resetRouteRateLimits()` clears the consumed points for this route,
e.g. after a successful login.

### Route options and rate limits

```ts
server.add(com.atproto.repo.createRecord, {
  auth: ctx.authVerifier.authorization({ authorize: () => {} }),
  rateLimit: [
    {
      name: 'repo-write-hour',
      calcKey: ({ auth }) => auth.credentials.did,
      calcPoints: () => 3,
    },
  ],
  opts: { jsonLimit: 1_000_000 },
  handler: async ({ input, auth }) => {
    /* ... */
  },
})
```

`rateLimit` is one entry or an array; `{ name }` references a shared limiter
declared in `createServer`'s `rateLimits.shared`, while `{ durationMs, points }`
declares a route-local one. `opts` is `RouteOptions` — `jsonLimit`, `textLimit`,
`blobLimit`, `paramsParseLoose` — overriding the server-wide `payload` defaults.

## Return values

A JSON response is `{ encoding, body }`, optionally with `headers`:

```ts
return {
  encoding: 'application/json',
  body: result,
  headers: { 'server-timing': serverTimingHeader([timerSkele, timerHydr]) },
}
```

Other shapes the server understands:

| Return                           | Effect                                                                   |
| -------------------------------- | ------------------------------------------------------------------------ |
| nothing (`undefined`)            | 200 with an empty body — correct for lexicons with no `output`           |
| `{ encoding, body: Readable }`   | streamed binary response                                                 |
| `{ encoding, buffer, headers? }` | `HandlerPipeThroughBuffer`                                               |
| `{ encoding, stream, headers? }` | `HandlerPipeThroughStream` — what the PDS `pipethrough()` helper returns |

Binary example, from `packages/pds/src/api/com/atproto/sync/getBlob.ts`:

```ts
res.setHeader('content-security-policy', `default-src 'none'; sandbox`)
return {
  encoding: found.mimeType || ('application/octet-stream' as const),
  body: found.stream,
}
```

Bodies are validated against the schema's output unless the server was
constructed with `validateResponse: false`.

### When `encoding` needs `as const`

Returning the object literal _directly_ from a handler that declares at least
one parameter is contextually typed by `server.add()`, so `encoding:
'application/json'` is already narrow and needs nothing — this is what most
handlers in `packages/bsky/src/api/` do.

Contextual typing is lost in two cases, and then `'application/json'` widens to
`string` and no longer matches the schema:

- the response is built into an intermediate variable before being returned
- the handler declares no parameters at all (`async () => ({ ... })`)

Fix either with `as const` on the literal, or by anchoring the whole object with
`satisfies app.bsky.graph.getRelationships.$Output`. A
`Promise<…$Output>` return-type annotation does **not** fix the
intermediate-variable case — it produces an assignability error instead.

## Errors

Throw an `XRPCError` subclass. Constructors are
`(message?, errorName?, options?)`; `errorName` should match an error declared
in the lexicon, and `options` is standard `ErrorOptions` so causes can be
chained:

```ts
throw new InvalidRequestError('Drafts limit reached', 'DraftLimitReached')
throw new InvalidRequestError('Unable to resolve handle', undefined, {
  cause: err,
})
```

| Class                       | Status |
| --------------------------- | ------ |
| `InvalidRequestError`       | 400    |
| `AuthRequiredError`         | 401    |
| `ForbiddenError`            | 403    |
| `InternalServerError`       | 500    |
| `MethodNotImplementedError` | 501    |
| `UpstreamFailureError`      | 502    |
| `NotEnoughResourcesError`   | 503    |
| `UpstreamTimeoutError`      | 504    |

`RateLimitExceededError` (429) also exists but takes a `RateLimiterStatus` as its
first argument and is thrown by the rate limiter, not by handlers.

Each subclass overrides `Symbol.hasInstance` to match on the response type
rather than the prototype chain, so `err instanceof InvalidRequestError` is true
for _any_ `XRPCError` with a 400 type, however it was constructed.

`ErrorResult` (`{ status, error?, message? }`) is the non-throwing counterpart,
returned by auth verifiers; `excludeErrorResult(v)` converts one back into a
thrown `XRPCError`.

## Schema accessors inside handlers

The schema object is in scope — use its accessors instead of NSID string
literals (see [STYLE_GUIDE.md](../../../STYLE_GUIDE.md)):

```ts
const lxm = app.bsky.actor.getPreferences.$lxm // 'app.bsky.actor.getPreferences'
const aud = computeProxyTo(ctx, req, lxm)
permissions.assertRpc({ aud, lxm })
```

| Accessor        | Use                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------- |
| `$lxm`          | lexicon method id, for auth scopes and proxy targets                                        |
| `$type`         | record type, e.g. `uri.collection === app.bsky.feed.post.$type`                             |
| `$token`        | a token def's string value; prefer the PascalCase export (`app.bsky.graph.defs.Curatelist`) |
| `$build({...})` | construct a value with its `$type` set                                                      |

`$build` is how union members are constructed:

```ts
app.bsky.graph.defs.notFoundActor.$build({ actor, notFound: true })
```

For shapes that carry no `$type`, just annotate or `satisfies` the exported type
(`com.atproto.server.defs.InviteCode`).

## Type-only references

```ts
type Params = app.bsky.feed.getAuthorFeed.$Params
type Output = app.bsky.feed.getAuthorFeed.$Output // { encoding, body }
type Body = app.bsky.feed.getAuthorFeed.$OutputBody // just the body
type PostRecord = app.bsky.feed.post.Main
type PostView = app.bsky.feed.defs.PostView
```

`$OutputBody` is the one you want for helper functions that compute a response
body; `$Output` includes the `encoding` wrapper. Inputs mirror this with
`$Input` / `$InputBody`, and subscriptions use `$Message`.

## Subscriptions

Register a subscription schema with an async generator. Yield `$build()`-ed
messages; the server frames and (unless `validateResponse: false`) validates
each one. `signal` aborts when the client disconnects — thread it into whatever
produces events so the generator unwinds.

```ts
server.add(
  com.atproto.sync.subscribeRepos,
  async function* ({
    params,
    signal,
  }): AsyncGenerator<com.atproto.sync.subscribeRepos.$Message> {
    const { cursor } = params
    const curr = await ctx.sequencer.curr()
    if (cursor !== undefined && cursor > (curr ?? 0)) {
      throw new InvalidRequestError('Cursor in the future.', 'FutureCursor')
    }
    for await (const evt of outbox.events(cursor, signal)) {
      yield com.atproto.sync.subscribeRepos.commit.$build({
        seq: evt.seq,
        time: evt.time,
        ...evt.evt,
      })
    }
  },
)
```

Annotating the generator's return type keeps errors on the offending `yield`
rather than on the whole `server.add()` call. Throwing before the first yield
rejects the connection with that error. The subscription context is
`{ params, auth, req, signal }` — and `req` here is a raw Node
`IncomingMessage`, not an Express `Request`.

`packages/pds/src/api/com/atproto/sync/subscribeRepos.ts` is the reference
implementation; `packages/ozone/src/api/label/subscribeLabels.ts` follows the
same shape. To _consume_ a subscription, see the
[lex-client skill](../lex-client/SKILL.md#subscriptions).

## File layout

Handlers live under `src/api/<nsid-path>.ts`, one file per method, filename
matching the method name in camelCase (the documented exception to the
kebab-case rule), each default-exporting a registrar:

```
packages/bsky/src/api/
  app/bsky/feed/getAuthorFeed.ts   ← export default function (server, ctx) { server.add(...) }
  com/atproto/identity/resolveHandle.ts
  index.ts                         ← imports each module and calls it
```

`src/api/index.ts` is a flat list of imports followed by a flat list of
`handler(server, ctx)` calls; add new routes in both places.

## Related skills

- **[lex-schema](../lex-schema/SKILL.md)** — the generated schemas passed to
  `server.add()`, and their `$`-accessors. Needed alongside this skill for
  almost any route work.
- **[lex-data](../lex-data/SKILL.md)** — branded strings, `BlobRef`, CBOR, and
  datetimes at route boundaries.
- **[lex-client](../lex-client/SKILL.md)** — when the service also calls _out_
  to other services.
- **[lexification-server](../lexification-server/SKILL.md)** — migrating an
  existing service off the legacy `lex gen-server` stack onto the patterns
  above.
- **[lex-setup](../lex-setup/SKILL.md)** — lexicon install/build configuration.
- **[testing](../testing/SKILL.md)** — runner choice and test placement when
  testing route handlers.
