Admin API

Spaces

Browse the spaces on this instance for moderation. These endpoints give operators access to spaces they are not members of, so they live in the admin API rather than the space XRPC API.

While the space inspector is off (see Configuration), listing spaces and accounts, reading a space's metadata or contents, and creating access grants return 403 SpaceInspectorDisabled. Space inspector status, listing your own grants, revoking a grant, and listing a grant's reads stay available, so access can still be ended and audited. Listing spaces and reading their metadata requires spaces:read. Reading a space's records or blobs also requires spaces:inspect and an active access grant covering the request. Every grant, its revocation, and every read made under it is written to the event log as a protected event that can't be purged by hand. The grant or revocation and its event are written together, and content is returned only after its read event is written: if the event can't be written, the request fails with 500 and nothing changes or is returned.

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

Space inspector status

GET /admin/spaces/inspector

Whether the space inspector is on, and how long an access grant can last. Requires spaces:read or spaces:inspect. This route answers while the inspector is off, so the dashboard can show why the other routes are closed.

curl http://127.0.0.1:3000/admin/spaces/inspector -H "$AUTH"

Response: 200 OK

{
  "enabled": true,
  "default_grant_minutes": 60,
  "max_grant_minutes": 120
}

default_grant_minutes is what a grant gets when duration_minutes is omitted: 60 minutes, or max_grant_minutes if that's shorter.

Access grants

A grant names one space or one account, records why, and expires after a limited time (5 minutes to max_grant_minutes, 60 by default — see Configuration).

Grant scopeTargetCovers
spaceA space idRecords and blobs in that space, regardless of author
accountA DIDThat account's own records in any space, and blobs its own records reference

List records in a space also accepts an account grant when the request's repo filter matches the grant's target DID. Get a blob in a space accepts an account grant only for a blob that account's own record references, even when another author's record shares the same CID. List an account's records always needs an account grant for that DID — a space grant never covers it.

Create an access grant

POST /admin/spaces/access-grants

Requires spaces:inspect and the space inspector turned on.

FieldTypeRequiredDescription
scopestringyesspace or account
targetstringyesA space id for space scope, a DID for account scope
reasonstringyesWhy access is needed. Trimmed, 1–2000 characters
duration_minutesnumbernoGrant length in minutes, clamped to 5–max_grant_minutes. Defaults to 60 or max_grant_minutes, whichever is shorter
curl -X POST http://127.0.0.1:3000/admin/spaces/access-grants \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"scope": "space", "target": "0b6c1f0e-...", "reason": "Investigating report #482", "duration_minutes": 30}'

Response: 201 Created

{
  "id": "6f1ecb2a-...",
  "user_id": "u_123",
  "user_did": "did:plc:moderator",
  "scope": "space",
  "target": "0b6c1f0e-...",
  "reason": "Investigating report #482",
  "created_at": "2026-01-01T00:00:00+00:00",
  "expires_at": "2026-01-01T00:30:00+00:00",
  "revoked_at": null,
  "revoked_by": null
}

Returns 403 SpaceInspectorDisabled if the inspector is off, 400 Bad Request for a missing, blank, or over-length reason or an invalid DID, and 404 Not Found if target is a space-scope id that doesn't exist.

List access grants

GET /admin/spaces/access-grants

The caller's own grants, newest first. Requires spaces:inspect.

ParamTypeRequiredDescription
activebooleannoOnly grants that haven't expired or been revoked
curl "http://127.0.0.1:3000/admin/spaces/access-grants?active=true" -H "$AUTH"

Response: 200 OK

{
  "grants": [
    { "id": "6f1ecb2a-...", "scope": "space", "target": "0b6c1f0e-...", "...": "..." }
  ]
}

Revoke an access grant

DELETE /admin/spaces/access-grants/{id}

Ends a grant early. Ending your own grant requires spaces:inspect; ending someone else's requires users:update.

curl -X DELETE http://127.0.0.1:3000/admin/spaces/access-grants/6f1ecb2a-... -H "$AUTH"

Response: 200 OK with the grant, revoked_at and revoked_by set. Revoking a grant that's already expired or revoked is a no-op that returns it unchanged. Returns 404 Not Found if no grant has that ID.

List a grant's reads

GET /admin/spaces/access-grants/{id}/reads

The space.moderator_read events logged under a grant, oldest first, a page at a time. Requires events:read.

ParamTypeRequiredDescription
limitnumbernoMax results per page (default 100, max 500)
cursorstringnoPagination cursor from a previous response
curl http://127.0.0.1:3000/admin/spaces/access-grants/6f1ecb2a-.../reads -H "$AUTH"

Response: 200 OK

{
  "events": [
    {
      "id": "...",
      "event_type": "space.moderator_read",
      "severity": "info",
      "actor_did": "did:plc:moderator",
      "subject": "at://did:web:happyview.example.com/space/com.example.forum/main",
      "detail": { "action": "list_records", "grant_id": "6f1ecb2a-...", "scope": "space", "...": "..." },
      "created_at": "2026-01-01T00:05:00Z"
    }
  ],
  "cursor": "..."
}

cursor is omitted when there are no more reads.

List spaces

GET /admin/spaces

Every space on the instance, newest first.

ParamTypeRequiredDescription
limitnumbernoMax results per page (default 50, max 100)
cursorstringnoPagination cursor from a previous response
curl "http://127.0.0.1:3000/admin/spaces?limit=20" -H "$AUTH"

Response: 200 OK

{
  "spaces": [
    {
      "id": "0b6c1f0e-...",
      "uri": "at://did:web:happyview.example.com/space/com.example.forum/main",
      "did": "did:web:happyview.example.com",
      "authority_did": "did:web:happyview.example.com",
      "creator_did": "did:plc:creator123",
      "type": "com.example.forum",
      "skey": "main",
      "display_name": "Forum",
      "description": null,
      "read_policy": { "$type": "com.atproto.simplespace.defs#memberListPolicy" },
      "write_policy": { "$type": "com.atproto.simplespace.defs#memberListPolicy" },
      "app_access": { "$type": "com.atproto.simplespace.defs#open" },
      "config": { "membership_public": false, "records_public": false },
      "revision": "3k...",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "cursor": "20"
}

cursor is omitted when there are no more results.

Get a space

GET /admin/spaces/{id}

A space's metadata, its resolved member list (including members added through delegation), and the record count of each collection in it. {id} is the space's id from List spaces.

curl http://127.0.0.1:3000/admin/spaces/0b6c1f0e-... -H "$AUTH"

Response: 200 OK

{
  "space": { "id": "0b6c1f0e-...", "uri": "at://...", "...": "..." },
  "members": [
    { "did": "did:plc:creator123", "read": true, "write": true }
  ],
  "collections": [
    { "collection": "com.example.forum.post", "count": 42 }
  ]
}

Returns 403 SpaceInspectorDisabled if the space inspector is off, and 404 Not Found if no space has that ID.

Get the grant covering a space

GET /admin/spaces/{id}/access

The caller's active access grant that covers this space: a space grant for it if there is one, otherwise the account grant expiring last whose account is a member of the space or has records in it. Only the caller's own grants are considered. Requires spaces:inspect.

curl http://127.0.0.1:3000/admin/spaces/0b6c1f0e-.../access -H "$AUTH"

Response: 200 OK

{ "grant": { "id": "6f1ecb2a-...", "scope": "space", "target": "0b6c1f0e-...", "...": "..." } }

grant is null when none of the caller's active grants covers the space. Returns 403 SpaceInspectorDisabled if the space inspector is off and 404 Not Found if no space has that ID.

List records in a space

GET /admin/spaces/{id}/records

Records in a space, newest first. Requires spaces:inspect, the space inspector on, and an access grant covering the space — or, when repo is set, an account grant for that DID.

ParamTypeRequiredDescription
repostringnoOnly records authored by this DID
collectionstringnoOnly records in this collection
limitnumbernoMax results per page (default 20, max 100)
cursorstringnoPagination cursor from a previous response
curl "http://127.0.0.1:3000/admin/spaces/0b6c1f0e-.../records?collection=com.example.forum.post" -H "$AUTH"

Response: 200 OK

{
  "records": [
    {
      "uri": "at://did:web:happyview.example.com/space/com.example.forum/main/did:plc:abc/com.example.forum.post/3k...",
      "did": "did:plc:abc",
      "collection": "com.example.forum.post",
      "rkey": "3k...",
      "cid": "bafyrei...",
      "indexed_at": "2026-01-01T00:00:00Z",
      "record": { "...": "..." }
    }
  ],
  "cursor": "..."
}

cursor is omitted when there are no more results.

Returns 403 SpaceInspectorDisabled if the space inspector is off, 403 SpaceAccessGrantRequired if no active grant covers the space (or the repo filter), and 404 Not Found if no space has that ID.

Get a blob in a space

GET /admin/spaces/{id}/blob

A blob referenced by a record in the space, fetched from its author's PDS. The response body is the blob, with the content type the PDS reports. Requires spaces:inspect, the space inspector on, and a covering access grant.

ParamTypeRequiredDescription
cidstringyesThe blob CID
curl "http://127.0.0.1:3000/admin/spaces/0b6c1f0e-.../blob?cid=bafkrei..." -H "$AUTH" -o blob

A space grant covering this space opens any blob a record in it references, regardless of author. Without one, each active account grant is checked in turn, longest-expiring first, and opens the blob only when that account's own record references it — if another author's record happens to share the CID, the account grant doesn't cover it.

Returns 403 SpaceAccessGrantRequired if no grant covers the space and the caller holds no account grant at all. If the caller holds an account grant but none of them reference this blob, the response is 404 Not Found instead, the same as a CID no record references — an account grant that misses looks identical to the blob not existing. Also returns 502 Bad Gateway if the author's PDS cannot serve it.

List an account's spaces

GET /admin/accounts/{did}/spaces

Where an account has membership or records. Metadata only — no access grant required. Requires spaces:read. Returns 403 SpaceInspectorDisabled if the space inspector is off.

curl http://127.0.0.1:3000/admin/accounts/did:plc:abc/spaces -H "$AUTH"

Response: 200 OK

{
  "spaces": [
    { "space": { "id": "0b6c1f0e-...", "uri": "at://...", "...": "..." }, "record_count": 12 }
  ]
}

Get the grant covering an account

GET /admin/accounts/{did}/access

The caller's active account grant for {did}, chosen by the same rule List an account's records enforces: the one expiring last. Requires spaces:inspect.

curl http://127.0.0.1:3000/admin/accounts/did:plc:abc/access -H "$AUTH"

Response: 200 OK with { "grant": { ... } }, or { "grant": null } when no active grant covers the account. Returns 403 SpaceInspectorDisabled if the space inspector is off.

List an account's records

GET /admin/accounts/{did}/space-records

One account's records across every space, newest first. Requires spaces:inspect, the space inspector on, and an account-scoped access grant for {did} — a space grant never covers this endpoint, even for a space the account belongs to.

ParamTypeRequiredDescription
spacestringnoOnly records in this space
collectionstringnoOnly records in this collection
limitnumbernoMax results per page (default 20, max 100)
cursorstringnoPagination cursor from a previous response
curl "http://127.0.0.1:3000/admin/accounts/did:plc:abc/space-records?collection=com.example.forum.post" -H "$AUTH"

Response: 200 OK

{
  "records": [
    {
      "uri": "at://did:web:happyview.example.com/space/com.example.forum/main/did:plc:abc/com.example.forum.post/3k...",
      "did": "did:plc:abc",
      "collection": "com.example.forum.post",
      "rkey": "3k...",
      "cid": "bafyrei...",
      "indexed_at": "2026-01-01T00:00:00Z",
      "record": { "...": "..." },
      "space_id": "0b6c1f0e-...",
      "space_uri": "at://did:web:happyview.example.com/space/com.example.forum/main"
    }
  ],
  "cursor": "..."
}

Returns 403 SpaceInspectorDisabled if the space inspector is off, and 403 SpaceAccessGrantRequired if the caller has no account grant for {did}.