# API reference

Reference of the Bluesky.bot API v1: handle availability, resolution, the directory, and the CLI's routes, listing updates included. Generated from OpenAPI 3.1.

[HTML version](https://bluesky.bot/docs/api)

The public endpoints are read-only, without authentication, and rate limited per IP. The `/me/*` endpoints are for the `bsbot` command-line tool: they need a token (`Authorization: Bearer`), which `bsbot login` gets through the browser (`POST /cli/token`). They send no CORS headers. Served only on the main site, never on a bot's handle subdomain. Versioning: the major version is in the path (`/api/v1`); v1 only gets backward-compatible changes (new endpoints, new optional fields or parameters). A breaking change ships as `/api/v2`, and v1 then keeps working for at least 6 months, announced with `Deprecation` and `Sunset` headers. See docs/api.md.

## GET /handles/{name}/availability

Is a handle free to claim?

Applies the exact server-side rules of a claim: format, reserved names, offensive words, then whether a bot already holds it.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| name | path | true | string | The name part, e.g. `weather`; `@weather.bluesky.bot` is accepted too. |

### Responses

- **200**: The availability, with the reason when not available.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited (policy `publicApi`, per IP).

- **500**: Unexpected error.

```bash
curl https://bluesky.bot/api/v1/handles/weather/availability
```

## GET /resolve/{handle}

The DID behind a claimed handle

Same answer as `https://<handle>/.well-known/atproto-did`. Only `*.bluesky.bot` handles.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| handle | path | true | string | A full handle, e.g. `weather.bluesky.bot` (case-insensitive). |

### Responses

- **200**: The handle and its DID.

- **400**: Not a `*.bluesky.bot` handle (code `invalid_handle`).

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited (policy `publicApi`, per IP).

- **500**: Unexpected error.

```bash
curl https://bluesky.bot/api/v1/resolve/weather.bluesky.bot
```

## GET /bots

Bots listed in the directory

Only bots whose creator listed them in the directory and whose handle is live on Bluesky, or stopped being live less than 14 days ago (then `verifiedAt` is null); newest first. Cursor pagination: pass the `cursor` of a page to get the next one; it is null on the last page.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| limit | query | false | integer (1–100), default 20 |  |

| cursor | query | false | string | Opaque cursor from a previous page. |

| category | query | false | string | Exact category. |

| verified | query | false | string: "true", "false" | Only bots whose handle is live on Bluesky (true), or whose handle stopped being live less than 14 days ago (false). |

| q | query | false | string | Case-insensitive search in the handle and the display name. |

| language | query | false | string: "en", "ja", "pt", "es", "fr", "de", "it", "nl", "ko", "zh", "ru", "uk", "pl", "tr", "ar", "fa", "he", "hi", "id", "th", "vi", "sv", "ca", "eo" | Only bots that post in this language (a BCP-47 primary language code of the list). |

| openSource | query | false | string: "true", "false" | Only bots whose creator links the source code and says it is under an open-source licence (true), or only the others (false). |

| selfLabeled | query | false | string: "true", "false" | Only bots that Bluesky shows with the Automation label, their own `bot` self-label (true), or only bots read without it (false). Bots never read match neither. |

| usesGenerativeAi | query | false | string: "true", "false" | Only bots whose creator explicitly declared this generative AI answer; undeclared answers match neither value. |

| activity | query | false | string: "scheduled_posts", "event_posts", "replies_to_mentions" | A creator-declared activity. |

| fediverse | query | false | string: "true", "false" | Only bots that Bridgy Fed bridges to the Fediverse (true), or only the others (false), as Bluesky.bot last checked (daily). |

### Responses

- **200**: A page of bots.

- **400**: Invalid query parameter (code `bad_request`).

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited (policy `publicApi`, per IP).

- **500**: Unexpected error.

```bash
curl https://bluesky.bot/api/v1/bots
```

## GET /bots/{handle}

One bot listed in the directory



| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| handle | path | true | string | A full handle, e.g. `weather.bluesky.bot` (case-insensitive). |

### Responses

- **200**: The bot, with its reliability over 90 days.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited (policy `publicApi`, per IP).

- **500**: Unexpected error.

```bash
curl https://bluesky.bot/api/v1/bots/weather.bluesky.bot
```

## POST /cli/token

Trade a CLI sign-in code for a token

Step 4 of `bsbot login`: the one-time code that /cli/authorize handed to the CLI's loopback address, with the PKCE verifier and the same redirect URI. A code works once and for two minutes; a failed attempt burns it. The token is valid 30 days. Rate limited per IP (`cliToken`).

### Responses

- **200**: A token for the `/me/*` endpoints.

- **400**: Malformed body (`bad_request`), or a code that is unknown, expired, already used, or does not match the verifier or the redirect URI (`invalid_grant`).

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited (policy `publicApi`, per IP).

- **500**: Unexpected error.

```bash
curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"code":"…","code_verifier":"…","redirect_uri":"…"}' \
  https://bluesky.bot/api/v1/cli/token
```

## GET /me

The account behind the token



### Responses

- **200**: Your account and the token's expiry.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me
```

## GET /me/bots

Your bots

Every bot of your account, listed in the directory or not, oldest first. Add a bot from the dashboard: it needs a sign-in on the bot account.

### Responses

- **200**: Your bots.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The token lacks the `handles` scope, or is bound to one bot (`insufficient_scope`).

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me/bots
```

## POST /me/bots/{did}/claim

Claim a handle for one of your bots, and switch to it

The dashboard's own rules: format, reserved names, offensive words, availability (guarded by a unique index), grace period of released handles. Then the bot's handle is switched on Bluesky right away; `switch` says how it went. Changing the handle of a bot that already has one frees the old one.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | path | true | string | The bot's DID, as listed by `GET /me/bots`. |

### Responses

- **200**: The claimed handle and the switch outcome.

- **400**: Malformed body (`bad_request`), or a name that is not allowed (`invalid_handle`, with `reason`).

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The bot is suspended (`forbidden`), or the token lacks the `handles` scope or is bound to one bot (`insufficient_scope`).

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **409**: Another bot holds the handle, or it is in its grace period (`conflict`, reason `taken`).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -X POST \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"weather"}' \
  https://bluesky.bot/api/v1/me/bots/did:plc:yourbot/claim
```

## POST /me/bots/{did}/switch

Ask the bot's PDS again to use its claimed handle



| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | path | true | string | The bot's DID, as listed by `GET /me/bots`. |

### Responses

- **200**: The switch outcome.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The token lacks the `handles` scope, or is bound to one bot (`insufficient_scope`).

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -X POST \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me/bots/did:plc:yourbot/switch
```

## POST /me/bots/{did}/verify

Check whether the claimed handle is live on Bluesky



| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | path | true | string | The bot's DID, as listed by `GET /me/bots`. |

### Responses

- **200**: The check outcome.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The token lacks the `handles` scope, or is bound to one bot (`insufficient_scope`).

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -X POST \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me/bots/did:plc:yourbot/verify
```

## POST /me/bots/{did}/release

Release a bot's handle

The bot goes back to its previous Bluesky handle when possible, the handle stops resolving, and it stays blocked for others during its grace period.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | path | true | string | The bot's DID, as listed by `GET /me/bots`. |

### Responses

- **200**: The released handle and the revert outcome.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The bot is suspended (`forbidden`), or the token lacks the `handles` scope or is bound to one bot (`insufficient_scope`).

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **409**: The bot has no handle to release (`conflict`, reason `no_handle`).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -X POST \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me/bots/did:plc:yourbot/release
```

## GET /me/bots/{did}/doctor

Check a bot's disclosure and setup

The dashboard's Checkup through the authenticated HTTP API: each check with a status and a link to fix it. Reads the bot's Bluesky profile every time. `id` and `status` are stable; `message` is English and may change. Ignore unknown check ids. The proposed external `bsbot doctor` command is absent from the recorded npm CLI 0.1.0.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | path | true | string | The bot's DID, as listed by `GET /me/bots`. |

### Responses

- **200**: The bot's checkup.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The bot is suspended (`forbidden`), or the token lacks the `handles` scope or is bound to one bot (`insufficient_scope`).

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `botDoctor` per account (120 checkups an hour, shared with the dashboard's Run again).

- **500**: Unexpected error.

```bash
curl \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me/bots/did:plc:yourbot/doctor
```

## POST /me/bots/{did}/automation-label

Set the bot's Automation label

Only the profile's bot self-label changes. Requires a CLI token and prior profile-editing consent from the bot's dashboard.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | path | true | string | The bot's DID, as listed by `GET /me/bots`. |

### Responses

- **200**: The label was written or already in the requested state.

- **400**: Send a JSON object with one boolean field: on.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The bot is suspended (`forbidden`), or the token lacks the `handles` scope or is bound to one bot (`insufficient_scope`).

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **409**: Profile-editing consent is required: open the dashboard URL in error.url.

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

- **502**: The bot's server could not apply the label.

```bash
curl \
  -X POST \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me/bots/did:plc:yourbot/automation-label
```

## GET /me/bots/{did}/listing

A bot's directory listing

What the dashboard's Directory, Links and Disclosure tabs edit, available through HTTP and authenticated MCP tools. Sent back unchanged as a `PATCH`, it normally changes nothing (a value stored before a rule changed can be refused). Needs the `listing` scope. The proposed external `bsbot listing get` command is absent from the recorded npm CLI 0.1.0.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | path | true | string | The bot's DID, as listed by `GET /me/bots`. |

### Responses

- **200**: The listing.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The token lacks the `listing` scope (`insufficient_scope`, with `scope` and a `WWW-Authenticate` challenge): a CLI token issued before this scope existed. Run `bsbot login` again.

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me/bots/did:plc:yourbot/listing
```

## PATCH /me/bots/{did}/listing

Update a bot's directory listing

Only the fields sent change; in `operator` and `disclosure`, only the keys sent. `null` clears a field; a list replaces the stored one. The dashboard's own rules, all or nothing: nothing is saved when one field is refused. A patch equal to the stored values writes nothing (`changed: false`). Needs the `listing` scope.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | path | true | string | The bot's DID, as listed by `GET /me/bots`. |

### Responses

- **200**: The listing after the update, and whether anything changed.

- **400**: Not a JSON object, or an unknown field (`bad_request`, with `parameter`); or a refused value (`invalid_listing`, with `field`, e.g. `usage[1].example`, and `reason`, the dashboard rule's code, e.g. `too_long`, `link`, `unknown_category`, `cleared_by_admin`).

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **403**: The token lacks the `listing` scope (`insufficient_scope`, with `scope` and a `WWW-Authenticate` challenge): a CLI token issued before this scope existed. Run `bsbot login` again.

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `botSettings` per account (30 changes an hour, shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -X PATCH \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"category":"weather"}' \
  https://bluesky.bot/api/v1/me/bots/did:plc:yourbot/listing
```

## DELETE /me/token

Revoke the token of this request

What `bsbot logout` calls.

### Responses

- **204**: Revoked. No body.

- **401**: Missing, expired or revoked token (code `unauthorized`). Run `bsbot login` again.

- **404**: No such bot in your account, or a bot's handle subdomain (the API is only served on the main site).

- **429**: Rate limited: `publicApi` per IP, `creatorApi` per account, and `handleChange` per account for claims, switches, checks and releases (shared with the dashboard).

- **500**: Unexpected error.

```bash
curl \
  -X DELETE \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/me/token
```

## GET /tools/bot-checker

Bluesky declared bot signals

Shows verifiable public automation declarations: the Automation self-label, attributed labels from Bluesky.bot only, a live bot handle and a fresh public listing. No behavioural scoring or bot/human classification. Partial results stay unknown. Costs 3 calls.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| actor | query | true | string | A Bluesky handle, DID or bsky.app profile link. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "actor=demo.bluesky.bot" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/bot-checker
```

## GET /tools/did-finder

Bluesky DID finder

Finds the DID behind a Bluesky handle: DNS TXT and HTTPS well-known answers, the AppView's opinion, and whether the DID document claims the handle back.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| handle | query | true | string | A handle (`alice.bsky.social`, `@alice.bsky.social`) or a bsky.app profile link. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "handle=bsky.app" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/did-finder
```

## GET /tools/handle-finder

Bluesky handle finder (DID to handle)

Finds the handle of a DID: the handle its DID document claims, whether that handle resolves back to it, and the display name and avatar when the AppView serves them.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| did | query | true | string | A DID (`did:plc:…`, `did:web:example.com`), an `at://did…` URI or a bsky.app link with a DID. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "did=did:plc:z72i7hdynmk6r22z27h6tvur" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/handle-finder
```

## GET /tools/whois

Bluesky whois

Everything public about a Bluesky handle or DID: verification both ways, the DID document (PDS, signing key, aliases), the relay's account status, the profile, and Bluesky.bot facts (listed bot, labels). Costs 3 calls.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| actor | query | true | string | A handle, a DID, an `at://` URI or a bsky.app link. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "actor=bsky.app" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/whois
```

## GET /tools/account-age

Bluesky account age checker

When a Bluesky account joined: the date its DID was created in the PLC directory (or the profile's date for a did:web), its age and its next Bluesky birthday.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| actor | query | true | string | A handle, a DID, an `at://` URI or a bsky.app link. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "actor=bsky.app" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/account-age
```

## GET /tools/at-uri-converter

AT URI and bsky.app link converter

Converts a bsky.app link (profile, post, feed, list, starter pack) to its `at://` URI with the DID, and an `at://` URI back to its bsky.app links.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| uri | query | true | string | A bsky.app link or an `at://` URI (a handle or a DID alone is a profile). |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "uri=https://bsky.app/profile/bsky.app" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/at-uri-converter
```

## GET /tools/tid-decoder

AT Protocol TID decoder

Decodes a TID (a timestamp identifier, the record key of a post) into the time it encodes and its clock identifier. The time is set by the app that wrote the record: a claim, not a proof.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| tid | query | true | string | A TID (`3l6oveex3ii2l`), or a bsky.app post link or `at://` URI that ends with one. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

```bash
curl \
  -G \
  --data-urlencode "tid=3l6oveex3ii2l" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/tid-decoder
```

## GET /tools/character-counter

Bluesky post character counter

Counts a post's length the way Bluesky does (graphemes, limit 300; UTF-8 bytes, limit 3000) and, when it is too long, splits it into thread parts that each fit.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| text | query | true | string | The text of the post, up to 10,000 characters. |

| numbered | query | false | boolean, default true | End each thread part with ` 1/3`, ` 2/3`… |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

```bash
curl \
  -G \
  --data-urlencode "text=Hello Bluesky! 👋" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/character-counter
```

## GET /tools/facet-builder

Bluesky rich text facet builder

Detects the mentions, links and hashtags of a post the way Bluesky does, with their UTF-8 byte ranges, resolves the first 20 mentions to DIDs, and returns the `facets` array and the `app.bsky.feed.post` record to send. Costs 1 call, plus 1 per 3 mentions not resolved in the last minute.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| text | query | true | string | The text of the post, up to 5,000 characters. In a GET address, about 8 KB once encoded: a non-ASCII character takes up to 12 bytes (`%XX` per byte), so use MCP for long or non-Latin text. |

| langs | query | false | string | Optional: up to 3 language tags, comma-separated, e.g. `en,fr`. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

```bash
curl \
  -G \
  --data-urlencode "text=Hi @bsky.app! 👋 https://bsky.app" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/facet-builder
```

## GET /tools/custom-handle-checker

Bluesky custom domain handle checker

Checks why a custom domain handle is invalid: the handle syntax, the DNS TXT record at `_atproto.<domain>`, the file `/.well-known/atproto-did`, the DID document and what Bluesky shows, then gives the exact record to add. Asks fresh every time; costs 2 calls.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| domain | query | true | string | The domain to check, e.g. `alice.example.com`. |

| expected | query | false | string | Optional: the account the domain should point to, as a handle or a DID. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "domain=bsky.app" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/custom-handle-checker
```

## GET /tools/handle-availability

Bluesky handle availability checker

Checks whether a name is free on bsky.social (Bluesky's own answer and suggestions) and as a Bluesky.bot handle for a bot (with free alternatives).

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| name | query | true | string | A name such as `alice`, or a full handle. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "name=alice" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/handle-availability
```

## GET /tools/plc-history

PLC history of a Bluesky identity

The operation log of a did:plc identity from the PLC directory, as a timeline: creation, handle changes, server (PDS) moves, signing and rotation key changes, nullified operations, tombstones. Takes a handle too. One page of operations, newest first; raw operations on request. Costs 2 calls.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| q | query | true | string | A did:plc, a handle or a bsky.app profile link. |

| limit | query | false | integer (1–100), default 50 | Operations per page, newest first: 1 to 100, 50 by default. |

| page | query | false | integer (1–), default 1 | The page of operations, from 1. |

| include_raw | query | false | boolean, default false | Add each operation as the PLC directory published it (`operation`). |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "q=did:plc:z72i7hdynmk6r22z27h6tvur" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/plc-history
```

## GET /tools/starter-pack-analyser

Bluesky starter pack analyser

Analyses a Bluesky starter pack: its creator, how many joined through it, its feeds, and every member (at most 150) with followers, posts, whether they say they are a bot and whether they are listed on Bluesky.bot. A handle or a DID lists the packs that account made. Costs 5 calls, 1 for a list.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| q | query | true | string | A starter pack link (bsky.app or go.bsky.app), its at:// URI, or a handle or DID to list that account's packs. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "q=https://go.bsky.app/R4eqmGf" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/starter-pack-analyser
```

## GET /tools/post-viewer

Bluesky post and thread viewer

Reads a public Bluesky post without an account: its text, counts and labels, its parents up to the root and its first 50 replies, its author's self-thread as Markdown, and optionally Bluesky's official embed snippet. Authors who share only with signed-in users are respected. Costs 3 calls.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| post | query | true | string | A bsky.app post link (`https://bsky.app/profile/<handle>/post/<rkey>`) or an `at://…/app.bsky.feed.post/…` URI. |

| embed | query | false | boolean, default false | Also return Bluesky's embed snippet (an HTML string). |

| width | query | false | integer (220–600), default 550 | The embed's maximum width in pixels, 220 to 600. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "post=bsky.app/profile/bsky.app/post/3n22yg6lg2k2f" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/post-viewer
```

## GET /tools/feed-inspector

Bluesky feed inspector

Inspects a Bluesky custom feed without an account: name, creator, likes, whether the AppView sees it online and valid, and its first 20 posts. `check` adds a health check of its generator. A handle or a DID lists that account's feeds. Costs 3 calls.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| feed | query | true | string | A bsky.app feed link (`https://bsky.app/profile/<handle>/feed/<rkey>`), an `at://…/app.bsky.feed.generator/…` URI, or a handle or DID to list that account's feeds. |

| check | query | false | boolean, default false | Also run the health check of the feed generator. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "feed=bsky.app/profile/bsky.app/feed/whats-hot" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/feed-inspector
```

## GET /tools/label-inspector

Bluesky label inspector

Inspect attributed moderation and self-labels on a Bluesky account or post. Checks the top 100 known labelers, or all on request; reports actual AppView coverage and partial failures. No sign-in. Costs 3 calls (12 for all).

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| q | query | true | string | A handle, DID, bsky.app profile or post link, or post AT URI. |

| all | query | false | boolean, default false | Ask all indexed labelers instead of the 100 most liked; stricter rate limit. |

| locale | query | false | string, default en | Preferred language of the labeler's definitions; falls back to English, then the raw value. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "q=demo.bluesky.bot" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/label-inspector
```

## GET /tools/follower-export

Preview Bluesky followers or following

Preview the first 100 followers or followed accounts of a public Bluesky account. Hidden accounts are omitted. The page offers a rate-limited streamed CSV of up to 5,000 examined accounts. No sign-in or write access. Costs 2 calls.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| q | query | true | string | A Bluesky handle, DID or profile link. |

| list | query | false | string: "followers", "following", default followers | Followers of the account, or the accounts it follows. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "q=demo.bluesky.bot" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/follower-export
```

## GET /tools/repo-explorer

AT Protocol repository explorer

Browse a Bluesky account's public PDS repository, collections and individual records. PDS requests use SSRF checks. Records are bounded JSON; blobs remain references. No sign-in or write access. Costs 2 calls.

| Parameter | In | Required | Type | Description |

| --- | --- | --- | --- | --- |

| q | query | true | string | A handle, DID or AT URI at repository, collection or record level. |

| cursor | query | false | string, default  | The next-page cursor of listRecords; empty for the first page. |

| reverse | query | false | boolean, default false | Oldest records first instead of newest first. |

### Responses

- **200**: The tool's answer, with the canonical URL of its page.

- **400**: Invalid query parameter (code `bad_request`).

- **401**: Unknown, expired or revoked token (code `unauthorized`). Without an `Authorization` header, the tool answers anonymously.

- **404**: Not found. Also returned on a bot's handle subdomain: the API is only served on the main site.

- **429**: Rate limited: `toolsApi` (60 a minute) and `toolsApiDaily` (2,000 a day) per IP, or 10 times both per account with a creator's token. A tool that fans out costs more than one call.

- **500**: Unexpected error.

- **502**: The service the tool asks did not answer (code `upstream_error`).

```bash
curl \
  -G \
  --data-urlencode "q=bsky.app" \
  -H "Authorization: Bearer $BLUESKY_BOT_TOKEN" \
  https://bluesky.bot/api/v1/tools/repo-explorer
```

## Error
| Field | Type | Description |
| --- | --- | --- |
| error | object |  |
| error.code | string: "bad_request", "invalid_handle", "not_found", "rate_limited", "internal_error", "unauthorized", "forbidden", "conflict", "invalid_grant", "upstream_error", "insufficient_scope", "invalid_listing", "consent_required" |  |
| error.message | string |  |
| error.reason | string | With `invalid_handle`, `invalid_listing`, `conflict` and `forbidden`: e.g. `reserved`, `taken`, `too_long`, `no_handle`, `suspended`. |
| error.url | string, uri | With consent_required: open this dashboard page to grant profile editing. |
| error.field | string | With `invalid_listing`: the refused field. |
| error.scope | string | With `insufficient_scope`: the scope the token lacks. |
| error.parameter | string | The invalid query parameter. |
| error.retryAfterSeconds | integer (1–) | With `rate_limited`. |

## Availability
| Field | Type | Description |
| --- | --- | --- |
| name | string | The normalised name (as typed when invalid). |
| handle | string | null | The full handle, e.g. `weather.bluesky.bot`; null when the name is invalid. |
| available | boolean |  |
| reason | null | string: "required", "too_short", "too_long", "invalid_characters", "invalid_hyphen", "reserved", "not_allowed", "taken" | Why it is not available; null when it is. Names are 3–30 characters of a-z, 0-9 and single hyphens. |
| suggestions | string[] | Only when the name is not available: up to 3 names free to claim right now, best first (the name cleaned up, or with a number); empty when none is. |

## Resolution
| Field | Type | Description |
| --- | --- | --- |
| handle | string |  |
| did | string |  |

## Bot
| Field | Type | Description |
| --- | --- | --- |
| votes | integer (0–) | All-time private good-bot votes, shown only as an aggregate. |
| did | string |  |
| handle | string |  |
| displayName | string | null |  |
| avatar | string | null | Avatar URL. |
| description | string | null |  |
| category | string | null |  |
| verifiedAt | string | null, date-time | When the handle was confirmed live on Bluesky; null while it is not live (not yet, or not any more: checked again daily). |
| operator | string | null | Who runs the bot (a team, a company), as its creator wrote it: plain text, never a link. Null when the creator hid it or wrote none. |
| operatorAccount | object | null | The Bluesky account that confirmed it runs the bot, by signing in to Bluesky.bot as that account. Shown instead of the operator text when set. Null when no account confirmed, when its handle no longer verifies, or when the creator hid the operator line. |
| operatorAccount.did | string |  |
| operatorAccount.handle | string | Its handle, verified both ways (DNS or HTTPS, and the DID document) and refreshed daily. Link the profile by DID: the handle can change. |
| operatorAccount.displayName | string | null |  |
| operatorAccount.confirmedAt | string, date-time | When the account confirmed. |
| website | object | null | The website the bot is the official bot of ("Official bot of example.org"), proven by the domain itself: a DNS TXT record or a well-known file naming the bot's DID, or a confirmed operator account whose handle is the domain. Checked again daily. Null when none is proven, or a moderator removed it. |
| website.domain | string | The domain, lowercase ASCII (punycode for an internationalised name). The site is https://<domain>. |
| website.displayDomain | string | The domain as Bluesky.bot shows it: its Unicode form when every label is in one script, else the ASCII form (a homograph shows as punycode). |
| website.method | string: "dns", "well_known", "operator_handle" | How the domain proved it. |
| website.verifiedAt | string, date-time | When the proof passed first, in its current run of passing checks. |
| languages | string: "en", "ja", "pt", "es", "fr", "de", "it", "nl", "ko", "zh", "ru", "uk", "pl", "tr", "ar", "fa", "he", "hi", "id", "th", "vi", "sv", "ca", "eo"[] | The languages the bot posts in, as BCP-47 primary language codes, the main one first: declared by its creator, else detected from the language tags of its posts. Empty when unknown. |
| sourceUrl | string | null, uri | The link to the bot's source code, as its creator gave it, normalised: an https repository page (or a folder of one) on GitHub, GitLab, Codeberg, Tangled, sourcehut or Bitbucket. Null when not given. Never fetched by Bluesky.bot. |
| openSource | boolean | The bot's creator says its code is under an open-source licence. Always false without a sourceUrl. |
| supportUrl | string | null, uri | The creator's own donation page for the bot, normalised: an https Ko-fi, Liberapay or GitHub Sponsors profile. The money goes to the creator; Bluesky.bot takes no cut and does not check how it is used. Null when not given, and while the handle is not live (verifiedAt null). Link it with rel="nofollow ugc". |
| selfLabeled | boolean | null | Bluesky shows the Automation label on the bot's profile: the bot set its own `bot` self-label (in the Bluesky app: Settings → Account → Automation label). Read from its public profile, at least daily for a bot with a claimed handle; null while never read. |
| usage | BotUsageLine[] | How to use the bot, as its creator wrote it, in order (the bot page's "How to use me" card). Empty when none. |
| disclosure | BotDisclosure |  |
| fediverse | object | null | The bot on the Fediverse: Bridgy Fed bridges its account, so people on Mastodon and other Fediverse servers can follow it, by pasting its `address` (`@<handle>@bsky.brid.gy`) in their server's search. Checked daily with Bridgy Fed. Null when not bridged, and while the handle is not live (verifiedAt null). |

## BotDetail
| Field | Type | Description |
| --- | --- | --- |
| votes | integer (0–) | All-time private good-bot votes, shown only as an aggregate. |
| did | string |  |
| handle | string |  |
| displayName | string | null |  |
| avatar | string | null | Avatar URL. |
| description | string | null |  |
| category | string | null |  |
| verifiedAt | string | null, date-time | When the handle was confirmed live on Bluesky; null while it is not live (not yet, or not any more: checked again daily). |
| operator | string | null | Who runs the bot (a team, a company), as its creator wrote it: plain text, never a link. Null when the creator hid it or wrote none. |
| operatorAccount | object | null | The Bluesky account that confirmed it runs the bot, by signing in to Bluesky.bot as that account. Shown instead of the operator text when set. Null when no account confirmed, when its handle no longer verifies, or when the creator hid the operator line. |
| operatorAccount.did | string |  |
| operatorAccount.handle | string | Its handle, verified both ways (DNS or HTTPS, and the DID document) and refreshed daily. Link the profile by DID: the handle can change. |
| operatorAccount.displayName | string | null |  |
| operatorAccount.confirmedAt | string, date-time | When the account confirmed. |
| website | object | null | The website the bot is the official bot of ("Official bot of example.org"), proven by the domain itself: a DNS TXT record or a well-known file naming the bot's DID, or a confirmed operator account whose handle is the domain. Checked again daily. Null when none is proven, or a moderator removed it. |
| website.domain | string | The domain, lowercase ASCII (punycode for an internationalised name). The site is https://<domain>. |
| website.displayDomain | string | The domain as Bluesky.bot shows it: its Unicode form when every label is in one script, else the ASCII form (a homograph shows as punycode). |
| website.method | string: "dns", "well_known", "operator_handle" | How the domain proved it. |
| website.verifiedAt | string, date-time | When the proof passed first, in its current run of passing checks. |
| languages | string: "en", "ja", "pt", "es", "fr", "de", "it", "nl", "ko", "zh", "ru", "uk", "pl", "tr", "ar", "fa", "he", "hi", "id", "th", "vi", "sv", "ca", "eo"[] | The languages the bot posts in, as BCP-47 primary language codes, the main one first: declared by its creator, else detected from the language tags of its posts. Empty when unknown. |
| sourceUrl | string | null, uri | The link to the bot's source code, as its creator gave it, normalised: an https repository page (or a folder of one) on GitHub, GitLab, Codeberg, Tangled, sourcehut or Bitbucket. Null when not given. Never fetched by Bluesky.bot. |
| openSource | boolean | The bot's creator says its code is under an open-source licence. Always false without a sourceUrl. |
| supportUrl | string | null, uri | The creator's own donation page for the bot, normalised: an https Ko-fi, Liberapay or GitHub Sponsors profile. The money goes to the creator; Bluesky.bot takes no cut and does not check how it is used. Null when not given, and while the handle is not live (verifiedAt null). Link it with rel="nofollow ugc". |
| selfLabeled | boolean | null | Bluesky shows the Automation label on the bot's profile: the bot set its own `bot` self-label (in the Bluesky app: Settings → Account → Automation label). Read from its public profile, at least daily for a bot with a claimed handle; null while never read. |
| usage | BotUsageLine[] | How to use the bot, as its creator wrote it, in order (the bot page's "How to use me" card). Empty when none. |
| disclosure | BotDisclosure |  |
| fediverse | object | null | The bot on the Fediverse: Bridgy Fed bridges its account, so people on Mastodon and other Fediverse servers can follow it, by pasting its `address` (`@<handle>@bsky.brid.gy`) in their server's search. Checked daily with Bridgy Fed. Null when not bridged, and while the handle is not live (verifiedAt null). |
| externalDisclosures | object[] |  |
| externalDisclosures[].nsid | string: "studio.voyager.account.autonomy", "systems.witchcraft.disclosure" |  |
| externalDisclosures[].uri | string |  |
| externalDisclosures[].cid | string |  |
| externalDisclosures[].fetchedAt | string, date-time |  |
| externalDisclosures[].record | object |  |
| uptime | object | The bot's reliability as Bluesky.bot measured it, over the last 90 complete UTC days (today excluded). Percentages have one decimal and are never 100 when any minute was down. A row needs 7 days of data: null before that. |
| uptime.windowDays | integer = 90 |  |
| uptime.since | string | null, date | The first UTC day measured within the window (YYYY-MM-DD); null when nothing was measured yet. |
| uptime.handleLivePercent | number | null (0–100) | Share of the measured time the handle was live on Bluesky (an account Bluesky did not serve counts as down). Null with fewer than 7 measured days. |
| uptime.onSchedulePercent | number | null (0–100) | Share of the watched time the bot kept the posting rhythm its creator declared (liveness alerts, pauses excluded). Null unless the creator shows it publicly and monitoring is on, or with fewer than 7 measured days. |

## BotDisclosure
| Field | Type | Description |
| --- | --- | --- |
| operator | string | null | The same value as the bot's `operator`. |
| purpose | string | null | What the bot is for, as its creator wrote it: one line of plain text, never a link. |
| contact | object | object | object | null | Whom to contact: an https link, Bluesky handle, or consented e-mail shown as an obfuscated display only. Null when absent or e-mail publication was not consented to. Raw e-mail addresses never appear in this public object. |
| sourceUrl | string | null, uri | The same value as the bot's `sourceUrl`. |
| usesGenerativeAi | boolean | null | Whether the bot uses generative AI, as its creator says. Null when not said. |
| automationLevel | string | null: "automated", "collaborative", "assisted", null | How automated the bot is, in the vocabulary of the `studio.voyager.account.autonomy` lexicon: `automated` (posts on its own), `collaborative` (a person reviews or steers it), `assisted` (a person decides, the bot helps). Declared by its creator; else `automated` when Bluesky shows the Automation label on the bot (`selfLabeled`); else null. |
| automationLevelSource | string | null: "creator", "self_label", null | Who said `automationLevel`: its creator, or Bluesky's Automation label (`self_label`). Null with the level. |
| activities | string: "scheduled_posts", "event_posts", "replies_to_mentions"[] | What the bot does, as its creator says: `scheduled_posts` (posts on a schedule), `event_posts` (posts when something happens), `replies_to_mentions` (replies when mentioned). Empty when not said. |
| selfLabeled | boolean | null | Bluesky shows the Automation label on the bot's profile: the bot set its own `bot` self-label (in the Bluesky app: Settings → Account → Automation label). Read from its public profile, at least daily for a bot with a claimed handle; null while never read. |

## BotUsageLine
| Field | Type | Description |
| --- | --- | --- |
| kind | string: "mention", "follow", "dm" | `mention`: mention the bot with `example`; `follow`: follow the bot; `dm`: send it a direct message. |
| description | string | What the bot does, in one line of plain text. |
| example | string | Mention lines only (always there for them): the text that follows `@handle` in the post. Never a link or another mention. |

## BotList
| Field | Type | Description |
| --- | --- | --- |
| bots | Bot[] |  |
| cursor | string | null | Cursor of the next page; null on the last page. |

## CliTokenRequest
| Field | Type | Description |
| --- | --- | --- |
| code | string |  |
| code_verifier | string | The PKCE verifier (RFC 7636). |
| redirect_uri | string | The same `http://127.0.0.1:<port>/callback` as on /cli/authorize. |

## CliToken
| Field | Type | Description |
| --- | --- | --- |
| token | string | Keep it secret: it acts as you on `/me/*`. |
| tokenType | string = "Bearer" |  |
| expiresAt | string, date-time |  |
| creator | Account |  |

## Account
| Field | Type | Description |
| --- | --- | --- |
| did | string |  |
| handle | string | Your Bluesky handle. |
| displayName | string | null |  |

## Me
| Field | Type | Description |
| --- | --- | --- |
| creator | Account |  |
| token | object |  |
| token.kind | string: "cli", "deploy" | A CLI login token, or a listing-only deploy token made in Settings. |
| token.name | string | The token name given at login or in Settings. |
| token.createdAt | string, date-time |  |
| token.expiresAt | string, date-time |  |
| token.scopes | string: "handles", "listing"[] | What the token may do: `handles` (list the bots, claim, switch, verify, release, checkups) and `listing` (read and edit listings). A CLI token issued before the `listing` scope has `handles` only. |
| token.botDid | string | null | The only bot the token may touch; null for all your bots. |

## MyBot
| Field | Type | Description |
| --- | --- | --- |
| did | string |  |
| handle | string | null | The claimed `*.bluesky.bot` handle; null when none. |
| previousHandle | string | null | The bot's handle before it got one here. |
| displayName | string | null |  |
| avatar | string | null |  |
| verifiedAt | string | null, date-time | When the claimed handle was confirmed live on Bluesky. |
| listed | boolean | Shown in the public directory. |
| status | string: "active", "suspended" |  |
| selfLabeled | boolean | null | Bluesky shows the Automation label on the bot's profile: the bot set its own `bot` self-label (in the Bluesky app: Settings → Account → Automation label). Read from its public profile, at least daily for a bot with a claimed handle; null while never read. |

## BotListing
| Field | Type | Description |
| --- | --- | --- |
| listed | boolean | Shown in the public directory. |
| category | string | null: "news", "art", "utility", "fun", "weather", "dev", "ai", "other", null |  |
| description | string | null |  |
| languages | string: "en", "ja", "pt", "es", "fr", "de", "it", "nl", "ko", "zh", "ru", "uk", "pl", "tr", "ar", "fa", "he", "hi", "id", "th", "vi", "sv", "ca", "eo"[] | The languages the creator declared, the main one first (BCP-47 primary codes). |
| showRecentPosts | boolean | The bot page shows its latest posts. |
| operator | object | The operator line and whether it is shown. |
| operator.name | string | null |  |
| operator.shown | boolean |  |
| usage | BotUsageLine[] |  |
| sourceUrl | string | null |  |
| openSource | boolean |  |
| supportUrl | string | null |  |
| disclosure | object |  |
| disclosure.purpose | string | null |  |
| disclosure.contact | string | null | An https link, a Bluesky handle written `@handle`, or an e-mail address. This authenticated endpoint returns the editable address, never the obfuscated public display. |
| disclosure.contactEmailPublic | boolean | Explicit publication consent for an e-mail contact; required as true when setting a new address. Clear contact to withdraw it. |
| disclosure.usesGenerativeAi | boolean | null | Required as true or false when choosing the AI category or publishing an AI listing. False is valid; historic unknown answers remain null. Category and disclosure changes are checked atomically. |
| disclosure.automationLevel | string | null: "automated", "collaborative", "assisted", null |  |
| disclosure.activities | string: "scheduled_posts", "event_posts", "replies_to_mentions"[] |  |

## BotListingPatch
| Field | Type | Description |
| --- | --- | --- |
| listed | boolean | Shown in the public directory. |
| category | string | null: "news", "art", "utility", "fun", "weather", "dev", "ai", "other", "", null |  |
| description | string | null |  |
| languages | array | null | The languages the creator declared, the main one first (BCP-47 primary codes). |
| showRecentPosts | boolean | The bot page shows its latest posts. |
| operator | object | The operator line and whether it is shown. |
| operator.name | string | null |  |
| operator.shown | boolean |  |
| usage | array | null |  |
| sourceUrl | string | null |  |
| openSource | boolean |  |
| supportUrl | string | null |  |
| disclosure | object |  |
| disclosure.purpose | string | null |  |
| disclosure.contact | string | null | An https link, a Bluesky handle written `@handle`, or an e-mail address. This authenticated endpoint returns the editable address, never the obfuscated public display. |
| disclosure.contactEmailPublic | boolean | Explicit publication consent for an e-mail contact; required as true when setting a new address. Clear contact to withdraw it. |
| disclosure.usesGenerativeAi | boolean | null | Required as true or false when choosing the AI category or publishing an AI listing. False is valid; historic unknown answers remain null. Category and disclosure changes are checked atomically. |
| disclosure.automationLevel | string | null: "automated", "collaborative", "assisted", null |  |
| disclosure.activities | array | null |  |

## BotListingResult
| Field | Type | Description |
| --- | --- | --- |
| listing | BotListing |  |

## BotListingUpdate
| Field | Type | Description |
| --- | --- | --- |
| listing | BotListing |  |
| changed | boolean | False when every value sent equals the stored one: nothing was written. |

## MyBotList
| Field | Type | Description |
| --- | --- | --- |
| bots | MyBot[] |  |

## ClaimRequest
| Field | Type | Description |
| --- | --- | --- |
| name | string | The name part, e.g. `weather` for `weather.bluesky.bot`. |

## SwitchOutcome
| Field | Type | Description |
| --- | --- | --- |
| status | string: "verified", "pending", "manual" |  |
| verifiedAt | string, date-time |  |
| reason | string: "reauthorize", "pds_refused", "pds_unreachable" |  |

## ClaimResult
| Field | Type | Description |
| --- | --- | --- |
| handle | string |  |
| switch | SwitchOutcome |  |

## SwitchResult
| Field | Type | Description |
| --- | --- | --- |
| switch | SwitchOutcome |  |

## Checkup
| Field | Type | Description |
| --- | --- | --- |
| bot | object |  |
| bot.did | string |  |
| bot.handle | string | null | The claimed `*.bluesky.bot` handle; null when none. |
| checkedAt | string, date-time |  |
| summary | object | `passed` out of `total`, the checks that pass, warn or fail (`info` and `unknown` are not counted); `fail` to fix, `warn` suggestions. |
| summary.passed | integer (0–) |  |
| summary.total | integer (0–) |  |
| summary.fail | integer (0–) |  |
| summary.warn | integer (0–) |  |
| checks | Check[] |  |

## Check
| Field | Type | Description |
| --- | --- | --- |
| id | string | `automation_label`, `bio_disclosure`, `avatar`, `description`, `operator`, `handle`, `listed` today; more may come. |
| status | string: "pass", "warn", "fail", "info", "unknown" | `fail`: to fix. `warn`: a suggestion. `info`: optional. `unknown`: Bluesky did not answer. |
| message | string |  |
| fixUrl | string | null | Where to fix it; null when it passes or is unknown. |
| docsUrl | string | null |  |

## ReleaseResult
| Field | Type | Description |
| --- | --- | --- |
| handle | string | The released handle. |
| revert | object | `reverted`: the bot is back on `handle`. `manual`: change the bot's handle yourself on Bluesky; `reason` says why. |
| revert.status | string: "reverted", "manual" |  |
| revert.handle | string |  |
| revert.reason | string: "reauthorize", "pds_refused", "pds_unreachable", "no_previous_handle" |  |
| revert.previousHandle | string | null |  |

## ToolBotChecker
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "bot-checker" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.did | string | The public DID of the inspected account. |
| result.handle | string | null | The handle reported by the public AppView, or null when unavailable. |
| result.checkedAt | string | The signal capture timestamp in ISO 8601. |
| result.outcome | string: "declared", "not_declared", "unknown" | Observed declarations only; never a bot/human classification. |
| result.summary | string | A neutral explanation of the observed declarations and uncertainty. |
| result.automationLabel | string: "present", "absent", "unknown" | Whether the account carries its own non-negated bot self-label. |
| result.liveHandle | string: "present", "absent", "unknown" | Whether its current Bluesky.bot handle resolves to this DID. |
| result.ourLabels | object | At most one bot labeler is consulted: Bluesky.bot. Positive labels are attributed; partial coverage is explicit. |
| result.ourLabels.status | string: "present", "absent", "unknown" | Present, absent or unknown; an unavailable source is never treated as absent. |
| result.ourLabels.source | string | null | Only this site’s configured labeler DID; null when unavailable. |
| result.ourLabels.values | string: "verified-bot", "certified-bot", "official-bot", "scheduled", "reply-on-mention", "ai-generated"[] | Current attributed labels from this site, not other labelers. |
| result.ourLabels.partial | boolean | A source failed or the AppView did not confirm the requested labeler. |
| result.selfDescription | string | null | The public biography, quoted as self-description only; null for unavailable or hidden profiles. |
| result.listing | object | Public live listing only, re-read on each call after the shared cache. |
| result.listing.status | string: "present", "absent", "unknown" | Present, absent or unknown; an unavailable source is never treated as absent. |
| result.listing.name | string | null | The public directory page name, never an internal id. |
| result.listing.category | string | null | The creator-selected public category, if listed. |
| result.listing.operator | string | null | Only the operator line that its creator chose to show publicly. |
| result.listing.usage | string[] | The public usage-card text, if listed. |

## ToolDidFinder
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "did-finder" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.status | string: "found", "conflict", "free" | `found`: a DID; `conflict`: the methods disagree, so the handle does not resolve; `free`: an unclaimed Bluesky.bot name. |
| result.handle | string | The handle, normalised. |
| result.unicodeHandle | string | null | The Unicode form of an internationalised handle, else null. |
| result.did | string | null | The DID, or null. |
| result.method |  | Which method gave the DID: `dns`, `https`, `both`, or `appview` when only the AppView knows it. |
| result.dns | object | What one resolution method answered. |
| result.dns.status | string: "found", "none", "invalid", "conflict", "error" | `found`: a DID; `none`: no answer; `invalid`: an answer that is not a DID; `conflict`: several DNS records with different DIDs; `error`: could not check. |
| result.dns.did | string | The DID this method found. |
| result.dns.dids | string[] | The DIDs of conflicting DNS records. |
| result.https | object | What one resolution method answered. |
| result.https.status | string: "found", "none", "invalid", "conflict", "error" | `found`: a DID; `none`: no answer; `invalid`: an answer that is not a DID; `conflict`: several DNS records with different DIDs; `error`: could not check. |
| result.https.did | string | The DID this method found. |
| result.https.dids | string[] | The DIDs of conflicting DNS records. |
| result.appview | object | What one resolution method answered. |
| result.appview.status | string: "found", "none", "invalid", "conflict", "error" | `found`: a DID; `none`: no answer; `invalid`: an answer that is not a DID; `conflict`: several DNS records with different DIDs; `error`: could not check. |
| result.appview.did | string | The DID this method found. |
| result.appview.dids | string[] | The DIDs of conflicting DNS records. |
| result.verified | boolean | null | The handle verifies both ways: DNS or HTTPS names the DID and its document claims the handle back. False for a DID only the AppView knows; null when it could not be checked. |
| result.claimedHandle | string | null | The handle the DID document claims, when it is another one. |
| result.warnings | string: "not_bidirectional", "dns_https_conflict", "handle_moved", "multiple_txt", "handle_invalid", "account_gone", "appview_only"[] | Problems found, explained on the tool's page: `not_bidirectional`, `dns_https_conflict`, `handle_moved`, `multiple_txt`, `handle_invalid`, `account_gone`, `appview_only`. |

## ToolHandleFinder
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "handle-finder" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.did | string | The DID. |
| result.didMethod | string: "plc", "web" | The DID method. |
| result.handle | string | null | The handle the DID document claims; null when it claims none. |
| result.unicodeHandle | string | null | The Unicode form of an internationalised handle, else null. |
| result.verified | boolean | null | The handle resolves back to this DID; null when it could not be checked. |
| result.resolvesTo | string | null | The DID the handle resolves to now, when it is another one. |
| result.displayName | string | null | The display name, when the AppView serves it. |
| result.avatar | string | null | The avatar's URL, when the AppView serves it. |
| result.accountStatus |  | Why the account is gone (`takendown`, `suspended`, `deactivated`, `deleted`…); null when it is not. |
| result.warnings | string: "not_bidirectional", "dns_https_conflict", "handle_moved", "multiple_txt", "handle_invalid", "account_gone", "appview_only"[] | Problems found, explained on the tool's page: `not_bidirectional`, `dns_https_conflict`, `handle_moved`, `multiple_txt`, `handle_invalid`, `account_gone`, `appview_only`. |

## ToolWhois
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "whois" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.status | string: "found", "conflict", "free" | `found`: a report; `conflict`: the handle's methods disagree, so it does not resolve; `free`: an unclaimed Bluesky.bot name. |
| result.input | string: "handle", "did" | What was looked up. |
| result.handle | string | null | The handle, or null. |
| result.unicodeHandle | string | null | The Unicode form of an internationalised handle, else null. |
| result.did | string | null | The DID, or null. |
| result.didMethod |  | The DID method. |
| result.resolution |  | How the handle resolves, when there is a handle. |
| result.verified | boolean | null | The handle and the DID point to each other; null when it could not be checked. |
| result.documentStatus | string: "found", "not_found", "error", "none" | Whether the DID document could be read. |
| result.document |  | The DID document. |
| result.repoStatus | string | The relay's account status: `active`, `deactivated`, `takendown`, `suspended`, `deleted`…, `not_found`, or `unknown`. |
| result.profileStatus | string: "found", "gone", "error", "none" | Whether the AppView served the profile. |
| result.profile |  | The profile, when served; never for a gone account. |
| result.accountStatus |  | Why the account is gone (`takendown`, `suspended`, `deactivated`, `deleted`…); null when it is not. |
| result.createdAt | string | null | When the DID was created, from the PLC directory. |
| result.blueskyBot |  | What Bluesky.bot knows about the account. |
| result.warnings | string: "not_bidirectional", "dns_https_conflict", "handle_moved", "multiple_txt", "handle_invalid", "account_gone", "appview_only"[] | Problems found, explained on the tool's page: `not_bidirectional`, `dns_https_conflict`, `handle_moved`, `multiple_txt`, `handle_invalid`, `account_gone`, `appview_only`. |

## ToolAccountAge
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "account-age" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.did | string | The DID. |
| result.handle | string | null | A handle that verifies for this DID (the one asked when it verifies), or null. |
| result.inputHandle | string | null | The handle that was asked, verified or not; null for a DID. |
| result.handleStatus | string: "verified", "not_verified", "unchecked", "none" | Whether the handle asked verifies both ways. With `not_verified` or `unchecked`, the answer is about the DID it points to, not about that handle; `none` when a DID was asked. |
| result.joinedAt | string | null | When the account joined (ISO 8601), or null. |
| result.source |  | Where the date comes from: `plc`, the PLC directory's first operation; `profile`, the profile's own date. |
| result.profileCreatedAt | string | null | The profile's own date, when it differs. |
| result.accountStatus |  | Why the account is gone (`takendown`, `suspended`, `deactivated`, `deleted`…); null when it is not. |
| result.age |  | The account's age today (UTC). |
| result.nextBirthday |  | The next anniversary of the join date. |

## ToolAtUriConverter
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "at-uri-converter" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.atUri | string | The `at://` URI, with the DID. |
| result.did | string | The DID. |
| result.handle | string | null | A handle verified both ways for the DID (it resolves to the DID, and the DID document claims it), or null. |
| result.collection | string | null | The collection NSID. |
| result.rkey | string | null | The record key. |
| result.kind | string: "profile", "post", "feed", "list", "starterpack", "other" | What the URI points to; `other` has no bsky.app page. |
| result.bskyUrl | string | null | The bsky.app link with the handle. |
| result.bskyUrlDid | string | null | The stable bsky.app link, with the DID. |
| result.rkeyIsTid | boolean | The record key is a TID, which holds a date. |

## ToolTidDecoder
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "tid-decoder" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.tid | string | The TID. |
| result.timestamp | string | The time it encodes, ISO 8601 in UTC (milliseconds). |
| result.microseconds | string | The time in microseconds since the UNIX epoch, as a decimal string (exact: it can pass 2^53). |
| result.clockId | integer | The clock identifier, 0 to 1023. |
| result.topBitSet | boolean | The top bit is set (first character `c` to `j`): valid syntax, but not a real timestamp. |

## ToolCharacterCounter
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "character-counter" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.graphemes | integer | Length in graphemes: what a reader sees as one character (an emoji, a flag, a letter with its accent). |
| result.bytes | integer | Size in UTF-8 bytes. |
| result.graphemesLeft | integer | Graphemes left before the limit; negative when over. |
| result.bytesLeft | integer | Bytes left before the limit; negative when over. |
| result.over | boolean | Over either limit: Bluesky would refuse it. |
| result.limits | object | The limits of a post's text. |
| result.limits.graphemes | integer | Bluesky's limit: 300. |
| result.limits.bytes | integer | Bluesky's limit: 3000. |
| result.parts | object[] | The thread, when the text is over a limit: parts cut at a paragraph, a sentence or a space. Empty when it fits. |
| result.parts[].text | string | The part's text, numbered when asked. |
| result.parts[].graphemes | integer | The part's length in graphemes. |
| result.parts[].bytes | integer | The part's size in UTF-8 bytes. |
| result.parts[].over | boolean | The part is still too long: a single grapheme bigger than a post. |

## ToolFacetBuilder
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "facet-builder" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.entities | object[] | Every mention, link and tag found, in text order. |
| result.entities[].kind | string: "mention", "link", "tag" | `mention`, `link` or `tag`. |
| result.entities[].text | string | The text the facet covers. |
| result.entities[].value | string | The handle, the full URI or the tag, without `#`. |
| result.entities[].byteStart | integer | Start of the range, in UTF-8 bytes. |
| result.entities[].byteEnd | integer | End of the range, in UTF-8 bytes, exclusive. |
| result.entities[].status |  | A mention's resolution: `resolved`, `unresolved` (the handle does not resolve), `invalid` (not a valid handle, never asked) or `over_cap` (past the first 20, not asked); null for a link or a tag. Only resolved mentions are in `facets`. |
| result.entities[].did | string | null | A resolved mention's DID; null otherwise. |
| result.facets | object[] | The `facets` array of the record, ready to send. |
| result.record | object | The full `app.bsky.feed.post` record, `createdAt` set to the time of the call. |
| result.graphemes | integer | Length in graphemes; Bluesky's limit is 300. |
| result.bytes | integer | Size in UTF-8 bytes; Bluesky's limit is 3000. |

## ToolCustomHandleChecker
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "custom-handle-checker" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.domain | string | The domain checked, normalised. |
| result.did | string | null | The DID the domain points to (DNS first, then HTTPS); null when none. |
| result.expected |  | The expected account; null without one. |
| result.method | string: "dns", "https", "both", "none" | The methods that work: `dns`, `https`, `both` or `none`. |
| result.verification | string: "verified", "not_verified", "could_not_check" | `verified` only when DNS or the HTTPS file gives the DID and the DID document claims the domain back (the AppView alone never verifies); `could_not_check` when one of them did not answer; `not_verified` otherwise. |
| result.ok | boolean | Verified, and no check fails, the AppView's included. |
| result.problems | integer | How many checks fail. |
| result.warnings | integer | How many checks warn. |
| result.checks | object[] | The seven checks, in order. |
| result.checks[].id | string: "syntax", "dns", "https", "agreement", "document", "expected", "appview" | `syntax`, `dns`, `https`, `agreement`, `document`, `expected` or `appview`, in this order. |
| result.checks[].status | string: "pass", "fail", "warning", "not_checked" | `pass`, `fail`, `warning` or `not_checked`. |
| result.checks[].reason | string | Why, as a stable code, listed on the tool's documentation page. |
| result.checks[].details | object | What the check saw: TXT values, DIDs, an HTTP status, a handle. |
| result.record | object | The DNS record to add. |
| result.record.name | string | The host to type in the panel of `zone`: `_atproto`, or `_atproto.alice` for `alice.example.com` in `example.com`. |
| result.record.fullName | string | The full name, for panels that want it. |
| result.record.zone | string | The DNS zone the record goes in, found by an SOA lookup. |
| result.record.zoneGuessed | boolean | No SOA answered: the zone is the domain's last two labels. |
| result.record.type | string = "TXT" | The record type: `TXT`. |
| result.record.value | string | null | The value, `did=<did>`; null while the DID is unknown. |
| result.file | object | The other way: the HTTPS file. |
| result.file.url | string | Where to serve the file. |
| result.file.body | string | null | What it must hold: the DID alone; null while unknown. |
| result.bot | boolean | The account behind the domain is a self-labelled bot. |

## ToolHandleAvailability
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "handle-availability" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.name | string | The name checked, normalised. |
| result.bskySocial | object | The answer of bsky.social. |
| result.bskySocial.handle | string | The bsky.social handle. |
| result.bskySocial.status | string: "available", "taken", "not_allowed", "unknown" | `available`, `taken`, `not_allowed` (3 to 18 characters) or `unknown` when Bluesky did not answer as expected. |
| result.bskySocial.suggestions | string[] | Bluesky's suggestions when it is taken. |
| result.blueskyBot | object | The answer of Bluesky.bot, for a bot. |
| result.blueskyBot.handle | string | null | The Bluesky.bot handle; null when the name is invalid. |
| result.blueskyBot.status | string: "available", "taken", "invalid" | `available`, `taken` or `invalid`. |
| result.blueskyBot.suggestions | string[] | Free alternatives when it is not available. |

## ToolPlcHistory
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "plc-history" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.did | string | The DID whose history this is. |
| result.kind | string: "history", "too_long", "not_plc" | `history`; `too_long` when the log is over 1 MB; `not_plc` for a did:web or another method, which has no public log. |
| result.summary |  | The identity at a glance; null unless `kind` is `history`. |
| result.truncated | boolean | More than 1,000 operations: only the latest 1,000 are listed. |
| result.operations | object[] | One page of the operations, newest first. |
| result.operations[].cid | string | The operation's CID. |
| result.operations[].createdAt | string | When the PLC directory received it. |
| result.operations[].type | string: "plc_operation", "create", "plc_tombstone" | `plc_operation`, the legacy `create`, or `plc_tombstone`. |
| result.operations[].nullified | boolean | Overridden later by a higher-priority rotation key (within 72 hours); the directory keeps it. |
| result.operations[].events | object[] | What changed compared with the previous valid operation. |
| result.operations[].events[].kind | string: "created", "handle", "pds", "signing_key", "rotation_keys", "services", "other", "tombstone", "no_change" | `created`, `handle`, `pds` (moved to another server), `signing_key`, `rotation_keys`, `services` (other services), `other` (other aliases or verification methods), `tombstone` or `no_change`. |
| result.operations[].events[].from | string | null | Before: the handle, the PDS endpoint or the signing key; null when absent or not applicable. |
| result.operations[].events[].to | string | null | After: the handle, the PDS endpoint or the signing key; null when absent or not applicable. |
| result.operations[].events[].added | string[] | Rotation keys added. |
| result.operations[].events[].removed | string[] | Rotation keys removed. |
| result.operations[].operation | object | The operation as the PLC directory published it, with `include_raw` only. |
| result.page | integer | The page of operations returned. |
| result.pages | integer | How many pages of operations there are at this `limit`. |
| result.notes | object[] | Notes worth a look: `keys_and_server` when the rotation keys and the server changed within 24 hours (a migration, or a takeover). |
| result.notes[].kind | string: "keys_and_server" | The note's kind. |
| result.notes[].at | string | When the server changed. |

## ToolStarterPackAnalyser
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "starter-pack-analyser" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.kind | string: "pack", "actor" | `pack` for a pack's analysis, `actor` for an account's packs. |
| result.pack |  | The analysis; null for `actor`. |
| result.actor |  | The account's packs; null for `pack`. |

## ToolPostViewer
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "post-viewer" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.status | string: "post", "hidden", "gone" | `post`; `hidden`: the author shares only with signed-in users, or a moderation label hides it (nothing else is returned); `gone`: the author's account is taken down, suspended, deactivated or deleted. |
| result.reason | string | null | Why it is hidden (`no_unauthenticated`, `account_label`, `post_label`) or gone (`takendown`, `suspended`, `deactivated`, `deleted`); null for a post. |
| result.url | string | The post on bsky.app. |
| result.post |  | The post; null when hidden or gone. |
| result.parents | object[] | The parents, root first; empty for a root post. |
| result.parents[].depth | integer | 0 for the root among the parents, 1 for a direct reply. |
| result.parents[].status | string: "post", "hidden", "not_found", "blocked" | `post`; `hidden`: its author shares only with signed-in users or a moderation label hides it; `not_found`: deleted; `blocked`. |
| result.parents[].post |  | The post, when `status` is `post`. |
| result.replies | object[] | The replies in reading order (depth first), at most 50 and 6 levels deep. |
| result.replies[].depth | integer | 0 for the root among the parents, 1 for a direct reply. |
| result.replies[].status | string: "post", "hidden", "not_found", "blocked" | `post`; `hidden`: its author shares only with signed-in users or a moderation label hides it; `not_found`: deleted; `blocked`. |
| result.replies[].post |  | The post, when `status` is `post`. |
| result.article | string | null | The root author's self-thread as Markdown, when it has two posts or more; else null. |
| result.embedHtml | string | null | Bluesky's embed snippet, when asked for and available. Paste it in a web page as is. |

## ToolFeedInspector
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "feed-inspector" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.mode | string: "feed", "actor", "hidden" | `feed`: one feed; `actor`: the feeds of an account; `hidden`: the creator shares only with signed-in users, or a moderation label hides the account or the feed (nothing else is returned). |
| result.reason |  | Why it is hidden; null otherwise. |
| result.url | string | null | When hidden, the feed or the account on bsky.app; else null. |
| result.check | string: "not_asked", "done", "rate_limited" | The health check: `not_asked`, `done` (see `health`), or `rate_limited` (asked, but the site-wide limit refused it: try again later). |
| result.feed |  | The feed; null in actor mode. |
| result.isOnline | boolean | null | The AppView reached the feed generator recently. |
| result.isValid | boolean | null | The AppView considers the generator's answers valid. |
| result.preview |  | What the feed serves right now, logged out. |
| result.health |  | The health check, when asked for; null otherwise. |
| result.feeds | object[] | In actor mode, the account's feeds; else empty. |
| result.feeds[].uri | string | The feed's AT URI. |
| result.feeds[].displayName | string | The feed's name. |
| result.feeds[].description | string | The feed's description. |
| result.feeds[].likes | integer | Likes of the feed. |

## ToolLabelInspector
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "label-inspector" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.subject | string: "account", "post" | The kind of inspected subject. |
| result.did | string | The account's or post author's DID. |
| result.uri | string | The inspected account DID or post AT URI. |
| result.labels | object[] | Current, non-negated, unexpired labels, deduplicated by source, value and subject. |
| result.labels[].source | string | The labeler's DID, or the subject DID for a self-label. |
| result.labels[].subject | string | The DID or AT URI the label applies to. |
| result.labels[].value | string | The label's raw value. |
| result.labels[].name | string | The labeler's name for this value, with language fallback. |
| result.labels[].description | string | null | The labeler's description; null when not defined. |
| result.labels[].group | string: "bluesky", "self", "ours", "community" | Who applied the label. |
| result.labels[].effect | string: "hidden", "warned", "informational" | The default effect; actual viewing preferences can differ. |
| result.labels[].createdAt | string | Label creation timestamp, ISO 8601. |
| result.labels[].expiresAt | string | null | Label expiry timestamp, or null. |
| result.requestedLabelers | integer | Labelers requested through the accept-labelers header. |
| result.appliedLabelers | integer | Labelers confirmed by AppView response headers, not an assumption. |
| result.knownLabelers | integer | Known labelers including Bluesky moderation and this site's labeler. |
| result.partial | boolean | At least one batch or local source failed, a requested labeler was not applied, or the index is unavailable. |
| result.indexedAt | string | null | The latest index observation, ISO 8601, or null before the first scan. |

## ToolFollowerExport
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "follower-export" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.did | string | The public account's DID. |
| result.handle | string | The public account's handle. |
| result.list | string: "followers", "following" | Which list was read. |
| result.accounts | object[] | At most 100 visible accounts from the first page; no hidden identities. |
| result.accounts[].did | string | The listed account's DID. |
| result.accounts[].handle | string | The listed account's handle. |
| result.accounts[].displayName | string | null | Its display name, or null. |
| result.accounts[].isBot | boolean | The account declares Bluesky's Automation self-label. |
| result.accounts[].listedName | string | null | Its Bluesky.bot directory page name when public, or null. |
| result.hidden | integer | Accounts omitted from this page because their labels hide them from signed-out visitors. |
| result.hasMore | boolean | The public AppView has another page; this preview does not fetch it. |

## ToolRepoExplorer
| Field | Type | Description |
| --- | --- | --- |
| tool | string = "repo-explorer" | The tool's slug. |
| url | string | The canonical URL of the tool's page on Bluesky.bot. |
| result | object | The tool's answer. |
| result.level | string: "repo", "collection", "record" | Which repository level was requested. |
| result.status | string: "ok", "pds_unreachable", "inactive" | Whether public data could be read from the PDS. |
| result.did | string | The repository's DID. |
| result.handle | string | null | The PDS-reported handle at repository level, or null. |
| result.handleIsCorrect | boolean | null | The PDS's handle check, or null outside describeRepo. |
| result.pdsHost | string | null | The PDS host named by the DID document, or null. |
| result.relay | string: "active", "inactive", "not_found", "unknown" | What the public relay reports; unknown means it could not be checked. |
| result.collections | string[] | Collection NSIDs, at repository level. |
| result.collection | string | null | The selected collection, or null. |
| result.records | object[] | Up to 50 records in a collection, or the requested single record. |
| result.records[].uri | string | The record's AT URI. |
| result.records[].cid | string | The record's CID. |
| result.records[].rkey | string | The record key. |
| result.records[].createdAt | string | null | The TID key's timestamp, or null for a non-TID key. |
| result.records[].preview | string | A short text preview of the record. |
| result.records[].value | object | The record's escaped JSON data; limited to 256 KB and depth 20. |
| result.cursor | string | null | Next-page cursor, or null at the end. |
| result.reverse | boolean | Whether oldest-first order was requested. |
