API reference

Is a handle free to claim?

GET/handles/{name}/availability

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

Parameters

Responses

Example

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

The DID behind a claimed handle

GET/resolve/{handle}

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

Parameters

Responses

Example

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

Bots listed in the directory

GET/bots

Only bots whose creator listed them in the directory, newest first. Cursor pagination: pass the `cursor` of a page to get the next one; it is null on the last page.

Parameters

Responses

Example

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

One bot listed in the directory

GET/bots/{handle}

Parameters

Responses

Example

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

Trade a CLI sign-in code for a token

POST/cli/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

Example

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

The account behind the token

GET/me

Responses

Example

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

Your bots

GET/me/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

Example

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

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

POST/me/bots/{did}/claim

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.

Parameters

Responses

Example

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

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

POST/me/bots/{did}/switch

Parameters

Responses

Example

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

Check whether the claimed handle is live on Bluesky

POST/me/bots/{did}/verify

Parameters

Responses

Example

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

Release a bot's handle

POST/me/bots/{did}/release

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.

Parameters

Responses

Example

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

Revoke the token of this request

DELETE/me/token

What `bsbot logout` calls.

Responses

Example

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