hatk.dev / hatk
AppView in a box as a Vite plugin thing hatk.dev
fork atom
hatk / docs / site / api / records.md
at main 5.3 kB view raw view code
chadtmiller.com docs: complete docs overhaul for current API surface
0e7be988

title: Records description: Create, read, update, and delete AT Protocol records.#

dev.hatk.getRecord#

Fetch a single record by its AT URI.

  • Type: Query (GET)
  • Auth: None

Parameters#

Name Type Required Description
uri string (AT URI) Yes The AT URI of the record

Example#

curl "http://127.0.0.1:3000/xrpc/dev.hatk.getRecord?uri=at://did:plc:abc/fm.teal.alpha.feed.play/123"

import { callXrpc } from "$hatk/client";

const { record } = await callXrpc("dev.hatk.getRecord", {
  uri: "at://did:plc:abc/fm.teal.alpha.feed.play/123",
});

Response#

{
  "record": { ... }
}

dev.hatk.getRecords#

List records from a collection with optional filters and pagination.

  • Type: Query (GET)
  • Auth: None

Parameters#

Name Type Required Default Description
collection string Yes — Collection NSID
limit integer No 20 Results per page (1–100)
cursor string No — Pagination cursor
sort string No — Sort field
order string No — Sort order

Additional filter parameters are accepted based on the collection's schema — any field defined in the record lexicon can be used as a query parameter.

Example#

curl "http://127.0.0.1:3000/xrpc/dev.hatk.getRecords?collection=fm.teal.alpha.feed.play&limit=10"

import { callXrpc } from "$hatk/client";

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

Response#

{
  "items": [ ... ],
  "cursor": "..."
}

dev.hatk.createRecord#

Create a record via the authenticated user's PDS.

  • Type: Procedure (POST)
  • Auth: Required (session cookie or DPoP token)

Input#

Name Type Required Description
collection string Yes Collection NSID
repo string (DID) Yes The user's DID
record object Yes The record data

Example#

curl -X POST "http://127.0.0.1:3000/xrpc/dev.hatk.createRecord" \
  -H "Authorization: DPoP <token>" \
  -H "Content-Type: application/json" \
  -d '{"collection":"fm.teal.alpha.feed.play","repo":"did:plc:abc","record":{"createdAt":"2025-01-01T00:00:00Z"}}'

import { callXrpc } from "$hatk/client";

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

Response#

{
  "uri": "at://did:plc:abc/fm.teal.alpha.feed.play/123",
  "cid": "bafyrei..."
}

dev.hatk.putRecord#

Create or update a record at a specific rkey via the authenticated user's PDS.

  • Type: Procedure (POST)
  • Auth: Required (session cookie or DPoP token)

Input#

Name Type Required Description
collection string Yes Collection NSID
rkey string Yes Record key
record object Yes The record data
repo string (DID) No The user's DID (inferred from auth if omitted)

Example#

curl -X POST "http://127.0.0.1:3000/xrpc/dev.hatk.putRecord" \
  -H "Authorization: DPoP <token>" \
  -H "Content-Type: application/json" \
  -d '{"collection":"fm.teal.alpha.feed.play","rkey":"self","record":{"createdAt":"2025-01-01T00:00:00Z"}}'

import { callXrpc } from "$hatk/client";

const { uri, cid } = await callXrpc("dev.hatk.putRecord", {
  collection: "fm.teal.alpha.feed.play",
  rkey: "self",
  record: { createdAt: new Date().toISOString() },
});

Response#

{
  "uri": "at://did:plc:abc/fm.teal.alpha.feed.play/self",
  "cid": "bafyrei..."
}

dev.hatk.deleteRecord#

Delete a record via the authenticated user's PDS.

  • Type: Procedure (POST)
  • Auth: Required (session cookie or DPoP token)

Input#

Name Type Required Description
collection string Yes Collection NSID
rkey string Yes Record key

Example#

curl -X POST "http://127.0.0.1:3000/xrpc/dev.hatk.deleteRecord" \
  -H "Authorization: DPoP <token>" \
  -H "Content-Type: application/json" \
  -d '{"collection":"fm.teal.alpha.feed.play","rkey":"123"}'

import { callXrpc } from "$hatk/client";

await callXrpc("dev.hatk.deleteRecord", {
  collection: "fm.teal.alpha.feed.play",
  rkey: "123",
});

Response#

{}