Skip to content
Developers
Menu

API reference

Users

Every path is relative to https://api.palloo.app/v1. Send a bot token as Authorization: Bearer palloo_bot_... unless the operation says otherwise; see Authentication.

On this page

Get me

GET /users/@me Bot token: Call it with a bot token (people can call it too).

The authenticated user, with their email address and whether it is verified.

Responses

200

The current user.

Body: CurrentUser

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "username": "string",
  "display_name": "string",
  "kind": "user",
  "avatar": "string",
  "avatar_dark": "string",
  "banner": "string",
  "bio": "string",
  "pronouns": "string",
  "banner_color": 0,
  "instance_role": "owner",
  "created_at": "2026-10-15T09:00:00Z",
  "email": "string",
  "email_verified": false,
  "address": "string",
  "handle": "string",
  "terms_version_accepted": "string",
  "terms_accepted_at": "2026-10-15T09:00:00Z",
  "terms_acceptance_required": false,
  "features": [
    "threads"
  ],
  "mfa_enabled": false
}
401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

Update me

PATCH /users/@me Bot token: Call it with a bot token (people can call it too).

Change the caller's profile (display name, About Me, pronouns, banner color, avatar, dark mode avatar or banner); bots included.

Omitted fields keep their value. For images, set a finalized upload of the matching purpose, or null to remove the image; the old image's files are deleted an hour later. Nothing is written unless every field is valid. The user's own connections, every community they are in, their friends and everyone they share a direct message with receive user_update.

Request body

application/json: UpdateCurrentUserRequest (required)

Fields of the application/json request body
FieldTypeDescription
display_name string or null

Trimmed, then at most 64 characters with no control or invisible formatting characters. Null or an empty string goes back to the username.
bio AboutMe or null
pronouns Pronouns or null
banner_color BannerColor or null
avatar string or null

A finalized avatar upload's ID, or null to remove the avatar. Omit to keep it.
avatar_dark string or null

A finalized avatar_dark upload's ID, or null to remove the dark mode avatar. Omit to keep it.
banner string or null

A finalized banner upload's ID, or null to remove it. Omit to keep it.
Example request body
{
  "display_name": "string",
  "bio": "string",
  "pronouns": "string",
  "banner_color": 0,
  "avatar": "string",
  "avatar_dark": "string",
  "banner": "string"
}

Responses

200

The current user.

Body: CurrentUser

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "username": "string",
  "display_name": "string",
  "kind": "user",
  "avatar": "string",
  "avatar_dark": "string",
  "banner": "string",
  "bio": "string",
  "pronouns": "string",
  "banner_color": 0,
  "instance_role": "owner",
  "created_at": "2026-10-15T09:00:00Z",
  "email": "string",
  "email_verified": false,
  "address": "string",
  "handle": "string",
  "terms_version_accepted": "string",
  "terms_accepted_at": "2026-10-15T09:00:00Z",
  "terms_acceptance_required": false,
  "features": [
    "threads"
  ],
  "mfa_enabled": false
}
400

invalid_body, invalid_attachment (not a finished upload of the caller's for that purpose), invalid_display_name, name_reserved (changing to a reserved name; a name already held is kept), invalid_bio, invalid_pronouns or invalid_banner_color.

Body: Error

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

403

terms_acceptance_required: the instance's terms of service changed (or were never accepted) and this account has not accepted the current version. Show the terms and call POST /users/@me/terms, then retry.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

Lookup user

GET /users/lookup Bot token: Call it with a bot token (people can call it too).

Find a local account by address, alias handle or ID. A moved account still answers, with moved_to set, so clients can follow it. Give exactly one of address and id.

Parameters

Parameters of Lookup user
Name In Type Description
address query string

An address or handle, such as alice@example.com.
id query ID

A ULID. Sorts lexically in creation order.

pattern ^[0-9A-HJKMNP-TV-Z]{26}$

Responses

200

The profile.

Body: Profile

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "username": "string",
  "display_name": "string",
  "kind": "user",
  "avatar": "string",
  "avatar_dark": "string",
  "banner": "string",
  "bio": "string",
  "pronouns": "string",
  "banner_color": 0,
  "created_at": "2026-10-15T09:00:00Z",
  "address": "string",
  "handle": "string",
  "moved_to": "string",
  "signing_key": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "algorithm": "ed25519",
    "public_key": "string",
    "created_at": "2026-10-15T09:00:00Z",
    "retired_at": "2026-10-15T09:00:00Z",
    "retire_reason": "rotated"
  },
  "verified_domains": [
    "string"
  ],
  "badges": [
    {
      "key": "staff",
      "name": "string",
      "description": "string",
      "label": "string",
      "kind": "automatic",
      "issuer": "string",
      "tier": {
        "key": "string",
        "name": "string",
        "level": 1
      },
      "next_tier": {
        "key": "string",
        "name": "string",
        "requirement": "string"
      },
      "active": false,
      "hidden": false,
      "hideable": false,
      "granted_at": "2026-10-15T09:00:00Z",
      "expires_at": "2026-10-15T09:00:00Z",
      "organization": {
        "id": {},
        "name": "string",
        "domain": "string"
      },
      "domains": [
        "string"
      ]
    }
  ]
}
400

invalid_query: give exactly one of address and id.

Body: Error

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

404

user_not_found.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error