Discovery¶

Discovery is the public directory of guilds that any account can browse and join. A guild manager applies to have a guild listed, and TEBHOS staff review the application. Approved guilds are indexed in the TEBHOS search backend (Elasticsearch) and appear in Search discovery guilds.

Every route on this page requires a user session (Authorization: Bearer <token>, see Authentication). A valid bot token is rejected with 403 ACCESS_DENIED.

The application routes live under /guilds/{guild_id}/discovery. The same handlers are also mounted under /servers/{guild_id}/discovery; both paths behave identically. They require the MANAGE_GUILD permission (the guild owner always passes). A caller who is not a member of the guild, or who lacks the permission, receives 403 FORBIDDEN.

Discovery guild object¶

One public guild listing, as returned by Search discovery guilds.

Structure¶

member_count and online_count are refreshed from the gateway for the returned page. When live counts are unavailable, member_count can be stale and online_count is approximated from the presence of the first 2000 members (or 0).

Example¶

{
  "id": "1489002177550843904",
  "name": "Example guild",
  "icon": "a_9f1c2d3e4b5a60718293a4b5c6d7e8f9",
  "banner": null,
  "description": "A place to talk about the example project.",
  "category_type": 4,
  "primary_language": "en-US",
  "custom_tags": ["open source", "rust"],
  "member_count": 4120,
  "online_count": 318,
  "features": ["DISCOVERABLE"],
  "verification_level": 1,
  "boost_level": 2
}

Discovery search result object¶

One page of matching listings.

Structure¶

A client pages with offset until offset reaches total.

Discovery application object¶

One guild's discovery listing and review state. A guild has at most one application. A rejected or removed application remains readable with its outcome and reason until the guild applies again or withdraws it.

Structure¶

Example¶

{
  "guild_id": "1489002177550843904",
  "status": "pending",
  "description": "A place to talk about the example project.",
  "category_type": 4,
  "primary_language": "en-US",
  "custom_tags": ["open source", "rust"],
  "applied_at": "2026-08-04T11:22:19.000000+00:00",
  "reviewed_at": null,
  "review_reason": null,
  "removed_at": null,
  "removal_reason": null
}

Discovery status object¶

The application state of one guild and its current eligibility to apply.

Structure¶

Example¶

{
  "application": null,
  "eligible": true,
  "min_member_count": 1
}

Discovery category object¶

Discovery categories¶

The set is fixed.

A category_type outside 0 through 8 is rejected with 400 BAD_REQUEST. In search queries an out-of-range category is ignored (no category filter is applied).

The display names are not localised; a client that wants translated labels supplies its own, keyed on id.

Discovery application statuses¶

A guild holding a pending or approved application cannot submit another. A new submission after a rejection or removal replaces the previous record.

Primary language¶

Each listing stores one primary language code (for example en-US or tr). The value is trimmed; an omitted or empty value is stored as en-US. Search filters on the exact stored code.

Custom tags¶

A listing has up to ten custom tags. TEBHOS trims every tag and keeps only tags that are 2 through 30 characters long after trimming; shorter or longer tags are dropped silently rather than rejected. At most the first ten remaining tags are stored.

Search discovery guilds¶

GET /discovery/guilds

Searches the discovery index and returns a discovery search result object. The caller needs no permission and no relationship to the matched guilds.

Query parameters¶

Without query, results are ordered by member count (descending). With a query, results are ordered newest guild first. The tag and sort_by parameters are accepted but ignored.

Response¶

Rate limit¶

30 requests per 10 seconds per client, on the discovery:search bucket.

Quick guild search¶

GET /discovery/search

A lightweight search used by the client's search box. Returns an array of discoverable guild index documents (no paging envelope, no live online counts).

List discovery categories¶

GET /discovery/categories

Returns an array of every discovery category object in ascending id order.

[
  { "id": 0, "name": "Gaming" },
  { "id": 1, "name": "Music" }
]

Rate limit¶

60 requests per 10 seconds per client, on the discovery:categories bucket.

List discovery bots¶

GET /discovery/bots

Returns up to 50 bot applications whose owner marked the bot as public, for the "Bots" shelf of the discovery screen. Bots without a readable bot user are skipped.

Response¶

{
  "bots": [
    {
      "id": "1489002177550843905",
      "client_id": "1489002177550843905",
      "bot_user_id": "1489002177550843906",
      "name": "Example Bot",
      "description": "Plays music in voice channels.",
      "avatar": "9f1c2d3e4b5a60718293a4b5c6d7e8f9",
      "banner": null,
      "default_permissions": "12371"
    }
  ]
}

Join discovery guild¶

POST /discovery/guilds/{guild_id}/join

Adds the authenticated account to a discoverable guild and returns 204 with an empty body. No invite is needed and no invite use is consumed.

A guild can be joined this way when it has an approved application, has the DISCOVERABLE feature, or has the BUSINESS_CLASS feature (so that the Business badge's "Join" button works even for unlisted Business guilds).

Response¶

Side effects¶

For a new member, the join dispatches Guild Member Add to the guild and connects the joining account's open sessions to the guild (they receive Guild Create). If the account has "restrict DMs from new servers" enabled, the guild is added to its restricted list. No join system message is posted.

Rate limit¶

10 requests per minute per user, on the discovery:join bucket (not partitioned by guild).

Get discovery status¶

GET /guilds/{guild_id}/discovery

Returns the discovery status object of one guild, including for a guild that has never applied. Requires MANAGE_GUILD.

Rate limit¶

30 requests per 10 seconds per user and guild, on the discovery:status bucket.

Apply for discovery¶

POST /guilds/{guild_id}/discovery

Submits the discovery application of a guild and returns the resulting discovery application object with status pending. Requires MANAGE_GUILD. Every application waits for a staff decision; there is no automatic approval.

JSON body¶

Response¶

Side effects¶

The guild is re-indexed and a Guild Update is dispatched, because the guild's effective features can change.

Rate limit¶

5 requests per minute per user and guild, on the discovery:apply bucket, shared with Edit discovery application and Withdraw discovery application.

Example¶

curl -X POST "https://tebhos.com/api/v1/guilds/1489002177550843904/discovery" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"A place to talk about the example project.","category_type":4,"primary_language":"en-US","custom_tags":["open source","rust"]}'

Edit discovery application¶

PATCH /guilds/{guild_id}/discovery

Updates the stored listing and returns the updated discovery application object. Requires MANAGE_GUILD. The status and review details are preserved.

JSON body¶

Every field is optional; an omitted field keeps the stored value.

Response¶

Changes to an approved listing are pushed to the search index and a Guild Update is dispatched.

Rate limit¶

Shares the discovery:apply bucket (5 requests per minute per user and guild).

Withdraw discovery application¶

DELETE /guilds/{guild_id}/discovery

Deletes the application record of a guild and returns 204 with an empty body. Requires MANAGE_GUILD.

Response¶

Side effects¶

Withdrawing an approved application also removes the DISCOVERABLE guild feature. The guild is re-indexed and a Guild Update is dispatched. Existing members are unaffected.

Rate limit¶

Shares the discovery:apply bucket (5 requests per minute per user and guild).