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