Hatk serves XRPC endpoints at /xrpc/{nsid}. All built-in endpoints use the dev.hatk namespace.

Protocol

• Queries are GET requests with parameters in the query string
• Procedures are POST requests with JSON (or binary) request bodies
• All responses are JSON unless otherwise noted

Authentication

hatk supports two authentication methods:

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.

DPoP browser tokens -- for direct XRPC calls from external clients, pass an OAuth DPoP bearer token in the Authorization header:

Authorization: DPoP <token>

Configure OAuth in your hatk.config.ts to enable authentication. See Configuration.

Client usage

The generated callXrpc() function from $hatk/client provides typed access to all endpoints:

import { callXrpc } from '$hatk/client'

// Query (GET)
const { items, cursor } = await callXrpc('dev.hatk.getRecords', {
  collection: 'fm.teal.alpha.feed.play',
  limit: 10,
})

// Procedure (POST)
const { uri, cid } = await callXrpc('dev.hatk.createRecord', {
  collection: 'fm.teal.alpha.feed.play',
  repo: userDid,
  record: { createdAt: new Date().toISOString() },
})

// Pass SvelteKit's fetch for SSR deduplication
const data = await callXrpc('dev.hatk.getFeed', { feed: 'recent' }, fetch)

The optional third parameter customFetch accepts a fetch function. Pass SvelteKit's fetch from load functions to enable request deduplication between server and client renders.

Built-in endpoints

Endpoint	Type	Auth	Description
getRecord	Query	No	Fetch a single record by AT URI
getRecords	Query	No	List records with filters
createRecord	Procedure	Yes	Create a record via user's PDS
putRecord	Procedure	Yes	Create or update a record
deleteRecord	Procedure	Yes	Delete a record
getFeed	Query	No	Retrieve a named feed
describeFeeds	Query	No	List available feeds
searchRecords	Query	No	Full-text search
uploadBlob	Procedure	Yes	Upload a binary blob
getPreferences	Query	Yes	Get user preferences
putPreference	Procedure	Yes	Set a preference
describeLabels	Query	No	List label definitions
createReport	Procedure	Yes	Report an account or record
describeCollections	Query	No	List indexed collections