Records

Browse and manage indexed records. All endpoints require the appropriate records:* permission.

cURL

# All examples assume $TOKEN is an API key (hv_...)
AUTH="Authorization: Bearer $TOKEN"

List records

GET /admin/records

Paginated list of records in a collection, ordered by indexed_at descending.

Param	Type	Required	Description
collection	string	yes	Collection NSID to list records from
limit	number	no	Max results per page (default 20, max 100)
cursor	string	no	Pagination cursor from a previous response

cURL

curl "http://127.0.0.1:3000/admin/records?collection=xyz.statusphere.status&limit=10" -H "$AUTH"

Response: 200 OK

{
  "records": [
    {
      "uri": "at://did:plc:abc/xyz.statusphere.status/3k...",
      "did": "did:plc:abc",
      "collection": "xyz.statusphere.status",
      "rkey": "3k...",
      "cid": "bafyrei...",
      "indexed_at": "2025-01-01T00:00:00Z",
      "record": { "...": "..." },
      "labels": []
    }
  ],
  "cursor": "20"
}

cursor is omitted when there are no more results.

List collections

GET /admin/records/collections

Returns the list of collection NSIDs from registered record-type lexicons. This is a fast lookup (no record counting).

cURL

curl http://127.0.0.1:3000/admin/records/collections -H "$AUTH"

Response: 200 OK

{
  "collections": [
    "xyz.statusphere.status",
    "app.bsky.feed.post"
  ]
}

Delete a record

DELETE /admin/records

Delete a single record by AT URI.

Param	Type	Required	Description
uri	string	yes	AT URI of the record to delete

cURL

curl -X DELETE "http://127.0.0.1:3000/admin/records?uri=at://did:plc:abc/xyz.statusphere.status/3k..." -H "$AUTH"

Response: 204 No Content

Returns 404 if the record is not found.

Delete all records in a collection

DELETE /admin/records/collection

Delete all indexed records for a given collection. Requires both records:delete and records:delete-collection permissions.

Param	Type	Required	Description
collection	string	yes	Collection NSID to delete from

cURL

curl -X DELETE "http://127.0.0.1:3000/admin/records/collection?collection=xyz.statusphere.status" -H "$AUTH"

Response: 202 Accepted

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

The delete runs as a happyview.delete-collection job, in batches, so a large collection doesn’t hold the database. Records arriving from the network while it runs are deleted too, until a batch comes back short.

Reconcile a collection

POST /admin/records/collection/reconcile

Compares an indexed collection with what each account’s PDS holds now, and finds records the index still has but the PDS no longer does. A dry run reports them; an apply deletes them. It runs as a happyview.reconcile-collection job, whose result is the report.

Field	Type	Required	Description
collection	string	yes	Collection NSID to reconcile
dry_run	boolean	no	Default true: report only. false deletes what it finds
dids	string[]	no	Only these accounts
pds_requests_per_second	number	no	Requests per second to each PDS, 1 to 20
allow_suspicious	string[]	no	Accounts to reconcile even though their PDS lists suspiciously few records, which the job otherwise skips

Permission: records:read for a dry run, records:delete to apply.

Response: 202 Accepted

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Errors: 400 when collection is empty, isn’t indexed, isn’t a record lexicon, is com.atproto.lexicon.schema, or is served from a shared external record store, and when the rate is out of range.