API

Authorization

Send the token in the Authorization header of each request, after Bearer. A token in the URL is refused. You choose scopes when you create a token. They control which endpoints it can use. Any valid token can use /whoami, regardless of scopes.

curl https://api.handle.pub/handles/Ada \
  -H "Authorization: Bearer $HANDLE_TOKEN"

Keep the token secret. Anyone who has it can use it until it expires or you revoke it in Settings.

Endpoints

• GET https://api.handle.pub/

  The status of the API. No token needed.

• GET https://api.handle.pub/handles/{handle}

  A handle's public profile, as a signed-out visitor sees it. Needs a token with the profile:read scope.

• POST https://api.handle.pub/handles/{handle}

  Update your profile name, bio, status (including its emoji), location and time zone. Needs a token with the profile:write scope.

• GET https://api.handle.pub/handles/{handle}/privacy

  Read your profile visibility and whether new followers are paused. Needs a token with the privacy:read scope.

• POST https://api.handle.pub/handles/{handle}/privacy

  Update your privacy settings. Omitted fields stay unchanged. Needs a token with the privacy:write scope.

• GET https://api.handle.pub/handles/{handle}/privacy/blocks

  List the handles you block, newest first. Needs a token with the blocks:read scope.

• POST https://api.handle.pub/handles/{handle}/privacy/blocks

  Block a claimed handle and end follows and requests in both directions. Needs a token with the blocks:write scope.

• GET https://api.handle.pub/handles/{handle}/privacy/blocks/{blockedHandle}

  Check whether you block a handle. Needs a token with the blocks:read scope.

• DELETE https://api.handle.pub/handles/{handle}/privacy/blocks/{blockedHandle}

  Unblock a handle without restoring follows. Needs a token with the blocks:write scope.

• GET https://api.handle.pub/whoami

  The handle that owns the token. Needs a valid token, regardless of scopes.

To update your profile, POST a JSON object to /handles/{handle} with any of profile_name, pronouns, bio, status, location and time_zone. Replace {handle} with the token owner's handle; other handles are refused. Status is an object with emoji and text. Omitted fields stay unchanged; null clears a field. Location and time zone keep their current visibility; clearing either turns visibility off. Set Content-Type: application/json and use a token with Profile Write.

Read your privacy settings with GET /handles/{handle}/privacy using Privacy Read. To update them, POST a JSON object to the same URL using Privacy Write, which includes Read. Send visibility as public or private, or followers_paused as a boolean. Omitted fields stay unchanged; null and unknown fields are refused. Making a private profile public approves unexpired follow requests and sends approval emails, as Settings does.

To block a handle, POST a JSON object such as {"handle":"Bob"} to /handles/{handle}/privacy/blocks. Use GET /handles/{handle}/privacy/blocks to list your blocks, GET /handles/{handle}/privacy/blocks/Bob to check one, and DELETE /handles/{handle}/privacy/blocks/Bob to unblock it. Replace {handle} with the token owner's handle for privacy and blocks; another owner is refused. Block handles Write includes Read. Blocks are directional, with a limit of 250. They restrict signed-in access; public profiles remain available when signed out.

An error is a JSON problem details body. Switch on its type.