Skip to content
Developers
Menu

API reference

Channels

Members only see channels they have View Channel in; any other channel answers 404 exactly like an unknown ID. Channels carry their permission overwrites. A channel of kind category groups other channels through their parent_id, as on Discord; categories hold no messages and cannot be nested. A member sees a category if they can view at least one channel in it, or if they have both View Channel and Manage Channels in the category itself (so empty categories stay hidden from everyone else). Lists come in display order: channels without a category first, then each category followed by its channels; inside each group text channels come before voice channels, then position, then id.

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 channels

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

The channels and categories the caller can see, in display order. Members only.

Parameters

Parameters of List channels
Name In Type Description
id Required path string

Community ID.

Responses

200

The channels.

Body: ChannelList

Example response (200)
{
  "channels": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "name": "string",
      "kind": "text",
      "position": 0,
      "parent_id": "string",
      "topic": "string",
      "created_at": "2026-10-15T09:00:00Z",
      "overwrites": [
        {
          "type": "role",
          "id": {},
          "allow": {},
          "deny": {}
        }
      ],
      "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "message_count": 0,
      "member_count": 0,
      "thread_metadata": {
        "archived": false,
        "auto_archive_duration": 60,
        "archive_timestamp": "2026-10-15T09:00:00Z",
        "locked": false,
        "invitable": false,
        "create_timestamp": "2026-10-15T09:00:00Z"
      },
      "user_limit": 0,
      "bitrate": 8000,
      "age_restricted": false
    }
  ]
}
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

Create channel

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

Add a channel or category at the end of its group. Requires Manage Channels. With parent_id the channel goes at the end of that category and starts with a copy of the category's permission overwrites; the caller needs Manage Channels in the category.

Required permissions

Requires Manage Channels.

Parameters

Parameters of Create channel
Name In Type Description
id Required path string

Community ID.

Request body

application/json: CreateChannelRequest (required)

Fields of the application/json request body
FieldTypeDescription
nameRequired string

Trimmed, then 1 to 100 characters with no control or invisible formatting characters. Text channel names are lowercased and each run of whitespace becomes a single -. Emoji are allowed, and the character rules of CreateRoleRequest apply to every kind. While emoji_names_enabled on GET /instance is true names are also normalized as role names are, and text channel names drop ASCII punctuation other than - and _ before the whitespace runs become -, as Discord does (Rules & Info! is stored as rules-info). Voice channel and category names keep their case and spaces. Lengths count code points.
kind ChannelKind

One of text, voice, category, public_thread, private_thread

parent_id string or null

A category in the same community to create the channel in. Not allowed for a category.
topic ChannelTopic or null

Text channels only. Omitted, null or empty means no topic.
user_limit integer

Voice channels only (voice_setting_not_allowed otherwise). 0, the default, means no limit; invalid_user_limit outside 0 to 99.

at least 0; at most 99
bitrate integer

Voice channels only (voice_setting_not_allowed otherwise). Defaults to 64000; invalid_bitrate outside 8000 to 96000.

at least 8000; at most 96000
age_restricted boolean

Text and voice channels only (age_restriction_not_allowed otherwise). Needs the sensitive_media flag on for the community (sensitive_media_disabled otherwise). Recorded in the moderation log with changes.age_restricted on an update.
Example request body
{
  "name": "string",
  "kind": "text",
  "parent_id": "string",
  "topic": "string",
  "user_limit": 0,
  "bitrate": 8000,
  "age_restricted": false
}

Responses

201

Created.

Body: Channel

Example response (201)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "name": "string",
  "kind": "text",
  "position": 0,
  "parent_id": "string",
  "topic": "string",
  "created_at": "2026-10-15T09:00:00Z",
  "overwrites": [
    {
      "type": "role",
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "allow": "2748678791",
      "deny": "2748678791"
    }
  ],
  "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "message_count": 0,
  "member_count": 0,
  "thread_metadata": {
    "archived": false,
    "auto_archive_duration": 60,
    "archive_timestamp": "2026-10-15T09:00:00Z",
    "locked": false,
    "invitable": false,
    "create_timestamp": "2026-10-15T09:00:00Z"
  },
  "user_limit": 0,
  "bitrate": 8000,
  "age_restricted": false
}
400

invalid_body, invalid_name, invalid_channel_kind, invalid_parent (the parent is not a category, or a category was given a parent), invalid_topic, topic_not_allowed (a topic on a voice channel or category), voice_setting_not_allowed (user_limit or bitrate on a text channel or category), invalid_user_limit, invalid_bitrate, age_restriction_not_allowed (age_restricted on a category) or sensitive_media_disabled.

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, or channel_not_found when parent_id names no category the caller can see in this community.

Body: Error

409

channel_limit_reached: the community has 500 channels (categories count).

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

Reorder channels

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

Move several channels and categories at once, like Discord's Modify Guild Channel Positions. Requires Manage Channels, and Manage Channels in every listed channel, in every target category and in the category a channel leaves; channels the caller cannot see answer 404. position is a sort key inside the channel's group (the categories, or the channels with the same parent); listed channels win ties with unlisted ones, then the old order decides, and every group is then renumbered from 0 with text channels before voice channels. parent_id moves a channel into a category (or out of one with null); omitting it keeps the parent. With lock_permissions and a category parent_id, the channel's overwrites are replaced by a copy of the category's, which needs Manage Roles in the channel and the rules of the overwrite endpoints for every overwrite that changes. Everything is checked before anything is written.

Required permissions

Requires Manage Channels, and Manage Channels in every listed channel, in every target category and in the category a channel leaves; channels the caller cannot see answer 404.

Parameters

Parameters of Reorder channels
Name In Type Description
id Required path string

Community ID.

Request body

application/json: ReorderChannelsRequest (required)

Fields of the application/json request body
FieldTypeDescription
channelsRequired array of object

at least 1 items; at most 500 items
channels[].idRequired ID
channels[].positionRequired integer

at least 0; at most 9999
channels[].parent_id string or null

A category in the same community, or null for none. Omit to keep the parent.
channels[].lock_permissions boolean

With a category parent_id, replace the channel's overwrites with the category's. At most 50 entries per request may set it.

default false
Example request body
{
  "channels": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "position": 0,
      "parent_id": "string",
      "lock_permissions": false
    }
  ]
}

Responses

200

Every channel the caller can see, in the new display order. Members get channel_update for each channel whose parent or overwrites changed, then channel_positions.

Body: ChannelList

Example response (200)
{
  "channels": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "name": "string",
      "kind": "text",
      "position": 0,
      "parent_id": "string",
      "topic": "string",
      "created_at": "2026-10-15T09:00:00Z",
      "overwrites": [
        {
          "type": "role",
          "id": {},
          "allow": {},
          "deny": {}
        }
      ],
      "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "message_count": 0,
      "member_count": 0,
      "thread_metadata": {
        "archived": false,
        "auto_archive_duration": 60,
        "archive_timestamp": "2026-10-15T09:00:00Z",
        "locked": false,
        "invitable": false,
        "create_timestamp": "2026-10-15T09:00:00Z"
      },
      "user_limit": 0,
      "bitrate": 8000,
      "age_restricted": false
    }
  ]
}
400

invalid_body, invalid_positions (empty, more than 500 entries, a channel listed twice or a position outside 0 to 9999), too_many_syncs (more than 50 entries set lock_permissions) or invalid_parent (the parent is not a category, or a category was given a parent).

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller lacks the permission, or would grant one it lacks, or role_hierarchy: the target role or member is not below the caller's highest role.

Body: Error

404

community_not_found, or channel_not_found when a listed channel or a parent is unknown, in another community or hidden from the caller.

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 channel

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

Rename a channel, change its topic or move it into or out of a category. Requires Manage Channels in that channel, and to move it, in both the category it leaves and the one it joins. A moved channel goes to the end of its new group and keeps its overwrites. Omitted fields keep their value. A topic change is recorded in the moderation log as channel.update with changes.topic. For a thread this edits the thread instead (name, archived, locked, auto_archive_duration, invitable; see the threads tag): the owner may rename it, change its auto archive duration and archive it, Manage Threads may do everything, and an archived thread only accepts being unarchived or locked. It is recorded as thread.update, sends thread_update and uses the thread rate limit.

Required permissions

Requires Manage Channels in that channel, and to move it, in both the category it leaves and the one it joins.

Parameters

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

Channel ID.

Request body

application/json: UpdateChannelRequest (required)

Fields of the application/json request body
FieldTypeDescription
name string

Same rules as when creating the channel.
parent_id string or null

Move the channel into this category, or out of its category with null.
topic ChannelTopic or null

Text channels only. Null or an empty string clears the topic.
user_limit integer

Voice channels only (voice_setting_not_allowed otherwise). 0, the default, means no limit; invalid_user_limit outside 0 to 99.

at least 0; at most 99
bitrate integer

Voice channels only (voice_setting_not_allowed otherwise). Defaults to 64000; invalid_bitrate outside 8000 to 96000.

at least 8000; at most 96000
age_restricted boolean

Text and voice channels only (age_restriction_not_allowed otherwise). Needs the sensitive_media flag on for the community (sensitive_media_disabled otherwise). Recorded in the moderation log with changes.age_restricted on an update.
archived boolean

Threads only. Archive or unarchive. The owner or Manage Threads can archive; unarchiving needs Manage Threads when the thread is locked.
locked boolean

Threads only. Needs Manage Threads.
auto_archive_duration integer

Threads only. The owner or Manage Threads.

One of 60, 1440, 4320, 10080

invitable boolean

Private threads only. Needs Manage Threads.
Example request body
{
  "name": "string",
  "parent_id": "string",
  "topic": "string",
  "user_limit": 0,
  "bitrate": 8000,
  "age_restricted": false,
  "archived": false,
  "locked": false,
  "auto_archive_duration": 60,
  "invitable": false
}

Responses

200

The updated channel or thread.

Body: Channel

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "name": "string",
  "kind": "text",
  "position": 0,
  "parent_id": "string",
  "topic": "string",
  "created_at": "2026-10-15T09:00:00Z",
  "overwrites": [
    {
      "type": "role",
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "allow": "2748678791",
      "deny": "2748678791"
    }
  ],
  "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "message_count": 0,
  "member_count": 0,
  "thread_metadata": {
    "archived": false,
    "auto_archive_duration": 60,
    "archive_timestamp": "2026-10-15T09:00:00Z",
    "locked": false,
    "invitable": false,
    "create_timestamp": "2026-10-15T09:00:00Z"
  },
  "user_limit": 0,
  "bitrate": 8000,
  "age_restricted": false
}
400

invalid_body, invalid_name, invalid_parent, invalid_topic, topic_not_allowed (a topic on a voice channel or category), not_thread (a thread field on a channel), invalid_thread_change (a parent or topic on a thread), invalid_auto_archive_duration, voice_setting_not_allowed (user_limit or bitrate on anything but a voice channel), invalid_user_limit, invalid_bitrate, age_restriction_not_allowed (age_restricted on a category or thread) or sensitive_media_disabled.

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission, timed_out or thread_locked.

Body: Error

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

Body: Error

409

thread_archived (only unarchiving or locking changes an archived thread), thread_limit_reached (1000 active threads) or thread_user_limit_reached (the owner unarchiving their own thread already has 25 active threads in the community, 50 with Manage Threads).

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

Get channel

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

A channel or thread the caller can view, with their read state in it. For a thread member says whether the caller joined it. Private threads answer 404 to anyone who is neither a member nor holds Manage Threads in the parent.

Parameters

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

Channel ID.

Responses

200

The channel.

Body: ChannelState

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "name": "string",
  "kind": "text",
  "position": 0,
  "parent_id": "string",
  "topic": "string",
  "created_at": "2026-10-15T09:00:00Z",
  "overwrites": [
    {
      "type": "role",
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "allow": "2748678791",
      "deny": "2748678791"
    }
  ],
  "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "message_count": 0,
  "member_count": 0,
  "thread_metadata": {
    "archived": false,
    "auto_archive_duration": 60,
    "archive_timestamp": "2026-10-15T09:00:00Z",
    "locked": false,
    "invitable": false,
    "create_timestamp": "2026-10-15T09:00:00Z"
  },
  "last_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "last_read_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "mention_count": 0,
  "last_pin_timestamp": "2026-10-15T09:00:00Z",
  "member": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "user_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "join_timestamp": "2026-10-15T09:00:00Z",
    "flags": 0,
    "member": {
      "user": {},
      "nickname": "string",
      "avatar": {},
      "avatar_dark": {},
      "banner": {},
      "bio": "string",
      "pronouns": "string",
      "roles": [],
      "joined_at": "2026-10-15T09:00:00Z",
      "timeout_until": "2026-10-15T09:00:00Z",
      "bot_presence_intent": false
    }
  }
}
401

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

Body: Error

WWW-Authenticate header.

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

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 channel

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

Delete a channel and its messages. Requires Manage Channels in that channel. Deleting a category keeps its channels: they move to the end of the channels without a category, keep their overwrites and are sent as channel_update before the channel_delete. Deleting a text channel deletes its threads with it. Deleting a thread needs Manage Threads in its parent, is recorded as thread.delete and sends thread_delete.

Required permissions

Requires Manage Channels in that channel.

Parameters

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

Channel 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.

Body: Error

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

Body: Error

409

last_text_channel: a community must keep at least one text channel.

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