Skip to content
Developers
Menu

API reference

Communities

Communities are shown to people as "servers". A caller who is not a member gets the same 404 as for an ID that does not exist.

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

List my communities

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

Communities the current user belongs to, in the order they joined.

Responses

200

The user's communities.

Body: CommunityList

Example response (200)
{
  "communities": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "name": "string",
      "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "icon": "string",
      "icon_dark": "string",
      "banner": "string",
      "mfa_level": 0,
      "default_notification_level": "all",
      "bot_presence_allowed": false,
      "tier": "standard",
      "limits": {
        "members": 0,
        "channels": 0,
        "roles": 0,
        "upload_bytes": 0,
        "emoji_slots": 0,
        "sticker_slots": 0
      },
      "perks": [
        "vanity_invite"
      ],
      "features": [
        "threads"
      ],
      "vanity_code": "string",
      "organization": {
        "id": {},
        "name": "string",
        "domain": "string"
      },
      "created_at": "2026-10-15T09:00:00Z",
      "directory": {
        "status": {},
        "paused": false,
        "reason": "string",
        "visible": false,
        "needs_attention": false,
        "updated_at": "2026-10-15T09:00:00Z"
      }
    }
  ]
}
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

Get community

GET /communities/{id} Bot token: Call it with a bot token (people can call it too).

One community. Members only.

Parameters

Parameters of Get community
Name In Type Description
id Required path string

Community ID.

Responses

200

The community.

Body: Community

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "name": "string",
  "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "icon": "string",
  "icon_dark": "string",
  "banner": "string",
  "mfa_level": 0,
  "default_notification_level": "all",
  "bot_presence_allowed": false,
  "tier": "standard",
  "limits": {
    "members": 0,
    "channels": 0,
    "roles": 0,
    "upload_bytes": 0,
    "emoji_slots": 0,
    "sticker_slots": 0
  },
  "perks": [
    "vanity_invite"
  ],
  "features": [
    "threads"
  ],
  "vanity_code": "string",
  "organization": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "name": "string",
    "domain": "string"
  },
  "created_at": "2026-10-15T09:00:00Z",
  "directory": {
    "status": "pending",
    "paused": false,
    "reason": "string",
    "visible": false,
    "needs_attention": false,
    "updated_at": "2026-10-15T09:00:00Z"
  }
}
401

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

Body: Error

WWW-Authenticate header.

404

community_not_found: no such community, or the caller is not a member. The two cases are indistinguishable on purpose.

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

Update community

PATCH /communities/{id} Bot token: Call it with a bot token (people can call it too).

Change a community's name, icon, banner, default notification level or bot presence setting. Requires Manage Community.

Omitted fields keep their value. icon and banner take a finalized upload of the caller's for this community, or null. Members receive community_update.

Required permissions

Requires Manage Community.

Parameters

Parameters of Update community
Name In Type Description
id Required path string

Community ID.

Request body

application/json: UpdateCommunityRequest (required)

Fields of the application/json request body
FieldTypeDescription
name string

Trimmed, then 1 to 100 characters with no control or invisible formatting characters.
default_notification_level DefaultNotificationLevel
bot_presence_allowed boolean

Whether bots with the presence intent receive this community's presence.
icon string or null

A finalized community_icon upload's ID, or null to remove the icon.
icon_dark string or null

A finalized community_icon_dark upload's ID, or null to remove the dark mode icon. Needs Manage Server, like icon.
banner string or null

A finalized community_banner upload's ID, or null to remove the banner.
Example request body
{
  "name": "string",
  "default_notification_level": "all",
  "bot_presence_allowed": false,
  "icon": "string",
  "icon_dark": "string",
  "banner": "string"
}

Responses

200

The updated community.

Body: Community

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "name": "string",
  "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "icon": "string",
  "icon_dark": "string",
  "banner": "string",
  "mfa_level": 0,
  "default_notification_level": "all",
  "bot_presence_allowed": false,
  "tier": "standard",
  "limits": {
    "members": 0,
    "channels": 0,
    "roles": 0,
    "upload_bytes": 0,
    "emoji_slots": 0,
    "sticker_slots": 0
  },
  "perks": [
    "vanity_invite"
  ],
  "features": [
    "threads"
  ],
  "vanity_code": "string",
  "organization": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "name": "string",
    "domain": "string"
  },
  "created_at": "2026-10-15T09:00:00Z",
  "directory": {
    "status": "pending",
    "paused": false,
    "reason": "string",
    "visible": false,
    "needs_attention": false,
    "updated_at": "2026-10-15T09:00:00Z"
  }
}
400

invalid_body, invalid_name, invalid_setting (default_notification_level is not all or mentions) or invalid_attachment (icon or banner is not a finished upload for this community).

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller is a member but lacks the permission.

Body: Error

404

community_not_found: no such community, or the caller is not a member. The two cases are indistinguishable on purpose.

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

Delete community

DELETE /communities/{id} Bot token: Call it with a bot token (people can call it too).

Delete a community and everything in it. Only the owner can. Delete a community with all of its channels, messages, members and invites. Requires Manage Community.

Required permissions

Requires Manage Community.

Try it: not available. Only people can do this, and Try it takes bot tokens only.

Parameters

Parameters of Delete community
Name In Type Description
id Required path string

Community ID.

Responses

204

Deleted.

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller is a member but lacks the permission, or mfa_sudo_required: the account has MFA and this session has not verified a factor in the last 5 minutes (POST /users/@me/mfa/sudo, then retry).

Body: Error

404

community_not_found: no such community, or the caller is not a member. The two cases are indistinguishable on purpose.

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