hatk.dev
AppView in a box as a Vite plugin thing
hatk.dev
chadtmiller.com
1---
2title: API Overview
3description: XRPC endpoints served by your Hatk server.
4---
5
6Hatk serves [XRPC](https://atproto.com/specs/xrpc) endpoints at `/xrpc/{nsid}`. All built-in endpoints use the `dev.hatk` namespace.
7
8## Protocol
9
10- **Queries** are GET requests with parameters in the query string
11- **Procedures** are POST requests with JSON (or binary) request bodies
12- All responses are JSON unless otherwise noted
13
14## Authentication
15
16hatk supports two authentication methods:
17
18**Session cookies** (recommended for SvelteKit apps) -- `login()`, `logout()`, and `parseViewer()` from `$hatk/client` handle the full OAuth flow and store the session in an encrypted cookie. See the [Auth guide](/guides/auth).
19
20**DPoP browser tokens** -- for direct XRPC calls from external clients, pass an OAuth DPoP bearer token in the `Authorization` header:
21
22```
23Authorization: DPoP <token>
24```
25
26Configure OAuth in your `hatk.config.ts` to enable authentication. See [Configuration](/getting-started/configuration).
27
28## Client usage
29
30The generated `callXrpc()` function from `$hatk/client` provides typed access to all endpoints:
31
32```typescript
33import { callXrpc } from "$hatk/client";
34
35// Query (GET)
36const { items, cursor } = await callXrpc("dev.hatk.getRecords", {
37 collection: "fm.teal.alpha.feed.play",
38 limit: 10,
39});
40
41// Procedure (POST)
42const { uri, cid } = await callXrpc("dev.hatk.createRecord", {
43 collection: "fm.teal.alpha.feed.play",
44 repo: userDid,
45 record: { createdAt: new Date().toISOString() },
46});
47
48// Pass SvelteKit's fetch for SSR deduplication
49const data = await callXrpc("dev.hatk.getFeed", { feed: "recent" }, fetch);
50```
51
52The optional third parameter `customFetch` accepts a fetch function. Pass SvelteKit's `fetch` from load functions to enable request deduplication between server and client renders.
53
54## Built-in endpoints
55
56| Endpoint | Type | Auth | Description |
57| ------------------------------------ | --------- | ---- | ------------------------------- |
58| [`getRecord`](/api/records) | Query | No | Fetch a single record by AT URI |
59| [`getRecords`](/api/records) | Query | No | List records with filters |
60| [`createRecord`](/api/records) | Procedure | Yes | Create a record via user's PDS |
61| [`putRecord`](/api/records) | Procedure | Yes | Create or update a record |
62| [`deleteRecord`](/api/records) | Procedure | Yes | Delete a record |
63| [`getFeed`](/api/feeds) | Query | No | Retrieve a named feed |
64| [`describeFeeds`](/api/feeds) | Query | No | List available feeds |
65| [`searchRecords`](/api/search) | Query | No | Full-text search |
66| [`uploadBlob`](/api/blobs) | Procedure | Yes | Upload a binary blob |
67| [`getPreferences`](/api/preferences) | Query | Yes | Get user preferences |
68| [`putPreference`](/api/preferences) | Procedure | Yes | Set a preference |
69| [`describeLabels`](/api/labels) | Query | No | List label definitions |
70| [`createReport`](/api/labels) | Procedure | Yes | Report an account or record |
71| `describeCollections` | Query | No | List indexed collections |