API documentation

Hubble offers a set of lexicon RPC (XRPC) endpoints for programatic access. No authentication is required except for mod actions, though optional tokens may be used for incrased rate-limits in the future.

Requirements

Apps must include a user-agent header that identifies the requesting app or project name, with a contact email address or atmosphere account.

Rate-limiting may be applied: apps should retry with backoff for HTTP 429 and other error response codes.

Endpoints

Standard atproto queries

• com.atproto.sync.listRepos compat note
• com.atproto.sync.getRepo extended
• com.atproto.sync.getRepoStatus

Hubble-specific queries

• blue.microcosm.hubble.getStats
• blue.microcosm.hubble.getRepoInfo
• blue.microcosm.hubble.getAccountStatusLog

Hubble-sync queries

• com.bad-example.hubble-sync.getRepoCountsByState unstable
• com.bad-example.hubble-sync.getRepoCountsByStatus unstable

Admin queries

• com.bad-example.hubble-sync-admin.getAccountStatusLog unstable
• com.bad-example.hubble-sync-admin.getModLog unstable
• com.bad-example.hubble-sync-admin.setAccountModeration unstable auth

Standard atproto queries

GET /xrpc/com.atproto.sync.listRepos

Enumerate Hubble's known repos.

Query parameters

limit optional integer. min: 1, max: 1000, default: 500.

cursor optional string.

Output application/json

{
  "repos": [
    {
      "did": string, // did format
      "rev": string, // tid format
      "head": string, // COMPAT: always empty string
      "active": boolean,
      "status": string, // absent when active is true
    },
  ],
  "cursor": string, // absent when paging has completed
}

compat note: repo head is not tracked by Hubble. In the output of this endpoint, it is always an empty string.

See also: canonical lexicon definition.

GET /xrpc/com.atproto.sync.getRepo

Fetch a full repository archive, at the latest revision seen by Hubble.

Query parameters

did required string, did-format.

accept optional string, car or star-lite. Non-standard, overrides Accept header.

Request headers

Accept optional mime-type, application/vnd.ipld.car or application/x.microcosm.star-lite.

Output

A repository archive in the format negotiated by the Accept header or accept query parameter, or application/vnd.ipld.car by default.

See also: canonical lexicon definition.

GET /xrpc/com.atproto.sync.getRepoStatus

Get the hosting status for a repository on this server.

Query parameters

did required string, did-format.

Output application/json

{
  "did": string, // did format
  "rev": string, // tid format
  "active": boolean,
  "status": string, // absent when active is false
}

See also: canonical lexicon definition.

docs below here are still in progress!

blue.microcosm.hubble.getRepoInfo

Everything hubble knows about one repo.

parameter	type
did	DID	required

{
  "did": did,
  "unverifiedHandle": handle?,   // claimed in the DID document; NOT
                                 // bidirectionally verified
  "pds": uri?,                   // the account's current PDS
  "accountStatus": {
    "active": boolean,
    "upstreamStatus": string?,   // "takendown" | "suspended" |
                                 // "deactivated" | "other" (open set)
    "locallyModerated": boolean?
  },
  "syncState": {
    "state": string,             // "synchronized" | "desynchronized" |
                                 // "pending" (open set)
    "rev": tid?,                 // repo revision of hubble's copy
    "desyncReason": string?,     // see token list below (open set)
    "nextRetryAt": datetime?
  },
  "archive": {
    "available": boolean,        // whether the repo can be downloaded
    "records": integer,
    "formats": [string]          // media types getRepo can negotiate
  },
  "history": {
    "firstSeenAt": datetime,
    "resyncs": integer,
    "pdsChanges": integer,
    "handleChanges": integer,
    "commitsSeen": integer?,
    "lastResync": {
      "at": datetime,
      "source": string?,         // where the resync data came from
      "records": integer?,
      "size": integer?,          // total size of the CAR's blocks, bytes
      "durationMs": integer?
    }?
  }
}

Errors: RepoNotFound (hubble has never seen this DID), RepoGone (the account was deleted and hubble no longer holds its data).

blue.microcosm.hubble.getAccountStatusLog

Upstream account status events hubble has observed for a DID, newest first.

parameter	type
did	DID	required
limit	integer	1–100, default 50
cursor	string	from a previous page

{
  "events": [
    {
      "at": datetime,            // time of the upstream event
      "status": string,          // "active" | "deactivated" | "suspended" |
                                 // "takendown" | "deleted" | "other"
                                 // (open set)
      "upstream": {
        "host": string,          // upstream that reported the event
        "seq": integer?          // its sequence number on that host
      }?
    }
  ],
  "cursor": string?              // absent on the last page
}

Errors: RepoNotFound. Note that deleted accounts still answer here (with a deleted event), even though getRepoInfo reports them as RepoGone.

GET /xrpc/blue.microcosm.hubble.getStats

Global stats for the hubble instance. No parameters.

{
  "records": integer,            // total records stored across all repos
  "upstream": string?,           // the upstream this instance is
                                 // subscribed to
  "reposBySyncState": {
    "synchronized": integer,
    "desynchronized": integer,   // total across every desync reason
    "deactivated": integer,
    "gone": integer
  },
  "reposByAccountStatus": {
    "active": integer,
    "deactivated": integer,
    "suspended": integer,
    "takendown": integer,
    "deleted": integer,
    "other": integer
  }
}