API reference

Directory

The public server directory. Search, browse and listing pages need no account and carry only public data; previews and joining need a person's account.

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 directory listing

GET /communities/{id}/directory Bot token

The community's directory listing with its review state, and the requirements checklist (shown before applying too). Needs Manage Community.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request

GET https://api.palloo.app/v1/communities/{id}/directory

Include my token in the copied command

curl command

Response

Parameters

Parameters of Get directory listing
Name	In	Type	Description
id Required	path	string	Community ID.

Responses

200

The listing (null when the community has none) and the requirements.

Body: DirectorySettings

Example response (200)

{
  "listing": {
    "id": {},
    "name": "string",
    "icon": {},
    "icon_dark": {},
    "banner": {},
    "description": "string",
    "primary_category": {},
    "secondary_categories": [],
    "keywords": [],
    "language": {},
    "member_count": 0,
    "online_count": 0,
    "featured": false,
    "partner": false,
    "vanity_code": "string",
    "organization": {},
    "created_at": "2026-10-15T09:00:00Z",
    "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "rules_channel_id": "string",
    "status": "pending",
    "paused": false,
    "status_reason": "string",
    "visible": false,
    "needs_attention": false,
    "revision": "string",
    "weekly_joins": 0,
    "submitted_at": "2026-10-15T09:00:00Z",
    "reviewed_at": "2026-10-15T09:00:00Z",
    "listed_at": "2026-10-15T09:00:00Z",
    "updated_at": "2026-10-15T09:00:00Z"
  },
  "requirements": [
    {
      "key": "members",
      "met": false,
      "required": 0,
      "actual": 0
    }
  ],
  "enabled": false,
  "auto_approve": false
}

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

Put directory listing

PUT /communities/{id}/directory Bot token

Apply to the directory, or replace the whole listing. Needs Manage Community. A new listing starts pending (or approved with the instance's auto-approval). Changing the description, categories, keywords, language or rules channel of an approved listing sends it back to review; any replace of a rejected listing reapplies. Omitted lists become empty and an omitted rules_channel_id clears it. Logged as community.directory_update.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request body (JSON, required)

Prefilled from the example above. Replace the placeholder values; unknown fields are refused.

Request

PUT https://api.palloo.app/v1/communities/{id}/directory

Include my token in the copied command

curl command

Response

Parameters

Parameters of Put directory listing
Name	In	Type	Description
id Required	path	string	Community ID.

Request body

application/json: DirectoryListingRequest (required)

Fields of the application/json request body
Field	Type	Description
descriptionRequired	string	1 to 300 characters, one line, no control or invisible formatting characters.
primary_categoryRequired	DirectoryCategory
secondary_categories	array of DirectoryCategory	at most 3 items
keywords	array of string	2 to 32 letters, digits, spaces or hyphens each; lowercased and deduplicated. at most 10 items
languageRequired	DirectoryLanguage
rules_channel_id	string or null	A text channel of the community; `@everyone` must be able to read it to meet `rules_channel`.
paused	boolean

Example request body

{
  "description": "string",
  "primary_category": "gaming",
  "secondary_categories": [
    "gaming"
  ],
  "keywords": [
    "string"
  ],
  "language": "ar",
  "rules_channel_id": "string",
  "paused": false
}

Responses

200

The listing was replaced.

Body: DirectorySettings

Example response (200)

{
  "listing": {
    "id": {},
    "name": "string",
    "icon": {},
    "icon_dark": {},
    "banner": {},
    "description": "string",
    "primary_category": {},
    "secondary_categories": [],
    "keywords": [],
    "language": {},
    "member_count": 0,
    "online_count": 0,
    "featured": false,
    "partner": false,
    "vanity_code": "string",
    "organization": {},
    "created_at": "2026-10-15T09:00:00Z",
    "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "rules_channel_id": "string",
    "status": "pending",
    "paused": false,
    "status_reason": "string",
    "visible": false,
    "needs_attention": false,
    "revision": "string",
    "weekly_joins": 0,
    "submitted_at": "2026-10-15T09:00:00Z",
    "reviewed_at": "2026-10-15T09:00:00Z",
    "listed_at": "2026-10-15T09:00:00Z",
    "updated_at": "2026-10-15T09:00:00Z"
  },
  "requirements": [
    {
      "key": "members",
      "met": false,
      "required": 0,
      "actual": 0
    }
  ],
  "enabled": false,
  "auto_approve": false
}

201

The community applied.

Body: DirectorySettings

Example response (201)

{
  "listing": {
    "id": {},
    "name": "string",
    "icon": {},
    "icon_dark": {},
    "banner": {},
    "description": "string",
    "primary_category": {},
    "secondary_categories": [],
    "keywords": [],
    "language": {},
    "member_count": 0,
    "online_count": 0,
    "featured": false,
    "partner": false,
    "vanity_code": "string",
    "organization": {},
    "created_at": "2026-10-15T09:00:00Z",
    "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "rules_channel_id": "string",
    "status": "pending",
    "paused": false,
    "status_reason": "string",
    "visible": false,
    "needs_attention": false,
    "revision": "string",
    "weekly_joins": 0,
    "submitted_at": "2026-10-15T09:00:00Z",
    "reviewed_at": "2026-10-15T09:00:00Z",
    "listed_at": "2026-10-15T09:00:00Z",
    "updated_at": "2026-10-15T09:00:00Z"
  },
  "requirements": [
    {
      "key": "members",
      "met": false,
      "required": 0,
      "actual": 0
    }
  ],
  "enabled": false,
  "auto_approve": false
}

400

invalid_body, invalid_description, invalid_category, invalid_keywords, invalid_language or invalid_rules_channel.

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission, timed_out or directory_disabled.

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

409

directory_requirements_unmet: the message names the unmet requirement keys. Nothing was saved. GET .../directory has the checklist.

Body: Error

429

rate_limited: listing changes are limited per community (10, then 1 every 6 minutes) and count as structure changes of the caller.

Body: Error

Retry-After header.

500

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

Body: Error

Update directory listing

PATCH /communities/{id}/directory Bot token

Change some fields of the listing, including paused, which hides an approved listing without losing its review. The same review rules as PUT; pausing never needs one.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request body (JSON, required)

Prefilled from the example above. Replace the placeholder values; unknown fields are refused.

Request

PATCH https://api.palloo.app/v1/communities/{id}/directory

Include my token in the copied command

curl command

Response

Parameters

Parameters of Update directory listing
Name	In	Type	Description
id Required	path	string	Community ID.

Request body

application/json: DirectoryListingPatch (required)

Fields of the application/json request body
Field	Type	Description
description	string
primary_category	DirectoryCategory
secondary_categories	array of DirectoryCategory	at most 3 items
keywords	array of string	at most 10 items
language	DirectoryLanguage
rules_channel_id	string or null
paused	boolean

Example request body

{
  "description": "string",
  "primary_category": "gaming",
  "secondary_categories": [
    "gaming"
  ],
  "keywords": [
    "string"
  ],
  "language": "ar",
  "rules_channel_id": "string",
  "paused": false
}

Responses

200

The listing.

Body: DirectorySettings

Example response (200)

{
  "listing": {
    "id": {},
    "name": "string",
    "icon": {},
    "icon_dark": {},
    "banner": {},
    "description": "string",
    "primary_category": {},
    "secondary_categories": [],
    "keywords": [],
    "language": {},
    "member_count": 0,
    "online_count": 0,
    "featured": false,
    "partner": false,
    "vanity_code": "string",
    "organization": {},
    "created_at": "2026-10-15T09:00:00Z",
    "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "rules_channel_id": "string",
    "status": "pending",
    "paused": false,
    "status_reason": "string",
    "visible": false,
    "needs_attention": false,
    "revision": "string",
    "weekly_joins": 0,
    "submitted_at": "2026-10-15T09:00:00Z",
    "reviewed_at": "2026-10-15T09:00:00Z",
    "listed_at": "2026-10-15T09:00:00Z",
    "updated_at": "2026-10-15T09:00:00Z"
  },
  "requirements": [
    {
      "key": "members",
      "met": false,
      "required": 0,
      "actual": 0
    }
  ],
  "enabled": false,
  "auto_approve": false
}

400

invalid_body, invalid_description, invalid_category, invalid_keywords, invalid_language or invalid_rules_channel.

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission, timed_out or directory_disabled.

Body: Error

404

community_not_found or listing_not_found (the community has no listing).

Body: Error

409

directory_requirements_unmet: the message names the unmet requirement keys. Nothing was saved. GET .../directory has the checklist.

Body: Error

429

rate_limited: listing changes are limited per community (10, then 1 every 6 minutes) and count as structure changes of the caller.

Body: Error

Retry-After header.

500

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

Body: Error

Withdraw directory listing

DELETE /communities/{id}/directory Bot token

Withdraw the listing. Needs Manage Community. A delisted listing cannot be withdrawn.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request

DELETE https://api.palloo.app/v1/communities/{id}/directory

Include my token in the copied command

curl command

Response

Parameters

Parameters of Withdraw directory listing
Name	In	Type	Description
id Required	path	string	Community ID.

Responses

204

Withdrawn.

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

Body: Error

409

listing_delisted: instance admins delisted it; only they can review it again.

Body: Error

429

rate_limited: listing changes are limited per community (10, then 1 every 6 minutes) and count as structure changes of the caller.

Body: Error

Retry-After header.

500

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

Body: Error