0
0
---
title: XRPC Handlers
description: Define typed API endpoints — queries for GET, procedures for POST.
---
# XRPC Handlers
XRPC handlers are typed API endpoints that extend your hatk server's API. They come in two kinds: **queries** (read-only GET requests) and **procedures** (POST requests that can modify data). Each handler maps to a lexicon that defines its parameter types, input/output schemas, and error cases.
## Defining a query
Use `defineQuery()` for read-only GET endpoints. The handler receives a typed context object and returns a response via `ctx.ok()`:
```typescript
// server/xrpc/getPlay.ts
import { defineQuery, NotFoundError, views, type Play, type Profile } from '$hatk'
export default defineQuery('xyz.appview.unspecced.getPlay', async (ctx) => {
const { ok, params, resolve, lookup, blobUrl } = ctx
const { uri } = params
const records = await resolve<Play>([uri])
if (records.length === 0) throw new NotFoundError('Play not found')
const record = records[0]
const profiles = await lookup<Profile>('app.bsky.actor.profile', 'did', [record.did])
const profile = profiles.get(record.did)
return ok({
play: views.playView({
record: {
uri: record.uri,
did: record.did,
handle: record.handle,
...record.value,
},
author: profile
? {
did: profile.did,
handle: profile.handle,
displayName: profile.value.displayName,
avatar: blobUrl(profile.did, profile.value.avatar, 'avatar'),
}
: undefined,
}),
})
})
```
The `params` object is typed from your lexicon's parameter definitions. In this case, `params.uri` is a string because the lexicon declares it. The `ok()` function enforces the output schema at the type level -- if your return value doesn't match, TypeScript will error.
## Defining a procedure
Use `defineProcedure()` for POST endpoints that modify data. The request body is available via `ctx.input`, typed from your lexicon's input schema:
```typescript
// server/xrpc/doSomething.ts
import { defineProcedure } from '$hatk'
export default defineProcedure('dev.hatk.unspecced.doSomething', async (ctx) => {
const { ok, db, viewer, input } = ctx
if (!viewer) throw new Error('Authentication required')
const { name, value } = input
await db.run(
`INSERT INTO my_table (did, name, value, created_at) VALUES ($1, $2, $3, $4)`,
viewer.did,
name,
value,
new Date().toISOString(),
)
return ok({})
})
```
## Context reference
Both `defineQuery` and `defineProcedure` handlers receive the same context object:
| Field | Type | Description |
| --------------------- | ------------------------------------------ | --------------------------------------------------------------------- |
| `ok` | function | Wraps your return value with type checking |
| `params` | object | Typed parameters from the lexicon schema |
| `input` | object | Request body (procedures only), typed from the lexicon's input schema |
| `db.query` | function | Run SQL queries against your SQLite database |
| `spaceFilter` | function | Permissioned-space gate for hand-written SQL |
| `db.run` | function | Execute SQL statements (INSERT, UPDATE, DELETE) |
| `viewer` | `{ did: string; handle?: string }` \| null | The authenticated user, or null |
| `limit` | number | Requested page size |
| `cursor` | string \| undefined | Pagination cursor |
| `resolve` | function | Resolve AT URIs into full records |
| `getRecords` | function | Fetch records by URI from another collection |
| `lookup` | function | Look up records by a field value |
| `count` | function | Count records by field value |
| `exists` | function | Check if a record exists matching field filters |
| `search` | function | Full-text search a collection |
| `labels` | function | Query labels for a list of URIs |
| `blobUrl` | function | Resolve a blob reference to a CDN URL |
| `packCursor` | function | Encode a `(primary, cid)` pair into a cursor string |
| `unpackCursor` | function | Decode a cursor back into `{ primary, cid }` |
| `isTakendown` | function | Check if a DID has been taken down |
| `filterTakendownDids` | function | Filter a list of DIDs, returning those taken down |
| `createRecord` | function | Write a record to the viewer's PDS and index locally |
| `putRecord` | function | Create or update a record on the viewer's PDS |
| `deleteRecord` | function | Delete a record from the viewer's PDS and local index |
### `ctx.ok()`
Every handler must return `ctx.ok(data)`. This wraps your response with type checking against the lexicon's output schema. If the shape doesn't match, TypeScript catches it at compile time.
### `ctx.db.query()` and `ctx.db.run()`
Run SQL against your SQLite database. Use `db.query()` for SELECT statements that return rows, and `db.run()` for INSERT/UPDATE/DELETE:
::: warning Hand-written SQL and permissioned spaces
If your instance indexes [permissioned spaces](/guides/spaces), a raw query over a table a space writes into is refused unless it carries `ctx.spaceFilter` — the error names the table. Queries over any other table, and every typed helper below, are unaffected. `ctx.db.unfiltered` is the explicit door for a result never served to a viewer.
:::
```typescript
// Query — returns rows
const rows = await db.query(
`SELECT CAST(COUNT(*) AS INTEGER) AS play_count
FROM "fm.teal.alpha.feed.play"
WHERE did = $1`,
[params.actor],
)
// Run — executes a statement
await db.run(`INSERT INTO my_table (did, value) VALUES ($1, $2)`, viewer.did, input.value)
```
### `ctx.resolve()` and `ctx.lookup()`
These helpers fetch records without writing raw SQL:
```typescript
// Resolve AT URIs into full records
const records = await resolve<Play>([uri])
// Look up records by a field value — returns a Map keyed by the field
const profiles = await lookup<Profile>('app.bsky.actor.profile', 'did', [did1, did2])
const profile = profiles.get(did1)
```
### `ctx.viewer`
`viewer` is `{ did: string; handle?: string }` when the request comes from an authenticated user, or `null` for unauthenticated requests. Check it to protect endpoints that require authentication:
```typescript
if (!viewer) throw new Error('Authentication required')
```
## Error handling
Import error classes from your generated types to throw standard XRPC errors:
```typescript
import { NotFoundError, InvalidRequestError } from '$hatk'
// 404 — record not found
throw new NotFoundError('Play not found')
// 400 — bad request
throw new InvalidRequestError('Missing required field')
```
These map to standard XRPC error responses that clients can handle predictably.
## Lexicon pairing
Each handler must have a matching lexicon definition. The file path mirrors the NSID:
```
lexicons/dev/hatk/unspecced/getPlay.json → server/xrpc/getPlay.ts
```
The lexicon defines parameter types, input/output schemas, and whether the endpoint is a query or procedure. See the [AT Protocol lexicon docs](https://atproto.com/specs/lexicon) for schema details.
## Generating a handler
Use the CLI to scaffold a new handler:
```bash
hatk generate xrpc dev.hatk.unspecced.getPlay
```
This creates the handler file with the right imports and structure.