Guilds¶

A guild (shown as a "server" in the TEBHOS apps) is a community with its own channels, roles, members, expressions and settings. This page covers the guild object and the guild-level operations. Related resources live on their own pages:

• Guild channels: listing, creating and ordering channels and categories
• Guild members: members, nicknames, timeouts, member roles and ownership transfer
• Guild moderation: bans
• Roles and permissions: the role object, role routes and permission bits
• Guild emojis, Guild stickers and Guild audit logs

All routes are relative to https://tebhos.com/api/v1 and require authentication. Routes marked user-only accept only a user session; a valid Bot <token> credential is refused with 403 ACCESS_DENIED. Every other route on this page also accepts a bot token. List current user guilds and Get guild also accept an OAuth2 access token with the guilds scope; every other route answers a valid access token with 403 ACCESS_DENIED. Error bodies follow Errors.

A caller who is not a member of the guild receives 403 FORBIDDEN. Because membership is checked first, a guild ID that does not exist also returns 403 on the member-scoped routes.

Guild object¶

The guild object is returned by Get guild, Modify guild, Create guild and List current user guilds, and it is the payload of the Gateway Guild Update event. The Ready payload carries the same fields for every guild.

Structure¶

member_count is a live count on Get guild (null if the count could not be read). On Modify guild and in Gateway events it may be up to 30 seconds old. List current user guilds omits it and returns approximate_member_count instead when asked.

Image hashes resolve to URLs of the form https://tebhos.com/api/v1/server-icons/{guild_id}/{hash}.webp (and server-banners, server-invite-bg, server-embed-bg for the other images). The resolved *_url fields already contain the full URL. See Media proxy routes.

TEBHOS guild extras object¶

In the Ready payload this object is found at properties.tebhos; everywhere else it is the top-level tebhos field.

Example¶

{
  "id": "1489002177550843904",
  "name": "Ada's Workshop",
  "icon": "a_9f2c1d4e7b",
  "banner": null,
  "banner_width": null,
  "banner_height": null,
  "splash": null,
  "splash_width": null,
  "splash_height": null,
  "embed_splash": null,
  "embed_splash_width": null,
  "embed_splash_height": null,
  "splash_card_alignment": 0,
  "vanity_url_code": "workshop",
  "owner_id": "1489002177550843905",
  "system_channel_id": "1489002177550843907",
  "system_channel_flags": 0,
  "rules_channel_id": null,
  "afk_channel_id": null,
  "afk_timeout": 300,
  "features": ["ANIMATED_BANNER", "ANIMATED_ICON", "BANNER", "INVITE_SPLASH", "VANITY_URL"],
  "verification_level": 1,
  "mfa_level": 0,
  "explicit_content_filter": 0,
  "default_message_notifications": 1,
  "disabled_operations": 0,
  "message_history_cutoff": null,
  "nsfw": false,
  "nsfw_level": 0,
  "content_warning_level": 0,
  "content_warning_text": null,
  "member_count": 128,
  "image_url": "https://tebhos.com/api/v1/server-icons/1489002177550843904/a_9f2c1d4e7b.webp",
  "banner_url": null,
  "splash_url": null,
  "embed_splash_url": null,
  "tebhos": {
    "boost_count": 27,
    "boost_goal": 25,
    "boost_bar_enabled": true,
    "banner_separated": false,
    "description": "A place to build things",
    "region": "europe",
    "max_members": 0,
    "is_public": false,
    "invites_disabled": false
  }
}

Guild features¶

features is the effective feature set. TEBHOS builds it from three sources.

Derived from the guild's boost level. These are never stored; they appear while the guild's boost level is high enough. A guild with an active Business Class subscription counts as level 2.

Toggleable by the guild. A member with MANAGE_GUILD adds or removes these through Modify guild or the feature toggle routes.

Set by the instance. DISCOVERABLE appears while the guild's discovery application is approved. Instance administrators can also set other features. The Gateway acts on UNAVAILABLE_FOR_EVERYONE, UNAVAILABLE_FOR_EVERYONE_BUT_STAFF and UNAVAILABLE_HIDDEN (the guild is reported as unavailable), LARGE_GUILD_OVERRIDE (large-guild handling for notifications) and VOICE_E2EE.

Verification levels¶

TEBHOS has no phone verification, so the phone-based level 4 does not exist. For older clients a request with 4 is accepted and stored as 3 (HIGH), and a guild that still holds 4 is always returned as 3.

TEBHOS stores the level and returns it, and the apps show it in guild settings, but the API does not currently gate messages or joins on it. A guild listed in discovery cannot lower the level below LOW; such a request fails with 400 INVALID_FORM_BODY.

MFA levels¶

TEBHOS has no guild-level multi-factor requirement. mfa_level stays on the guild object for compatibility and is always 0 (NONE); it never removes permissions from anyone. Account-level multi-factor authentication is unaffected.

Default message notification levels¶

System channel flags¶

When the flag is not set and system_channel_id is set, TEBHOS posts a join message (message type 7) in the system channel for each member who joins through an invite.

Splash card alignments¶

Create guild¶

POST /guilds

Creates a guild owned by the caller and returns its guild object with status 200. The owner's other sessions receive the new guild over the Gateway.

A bot credential is authenticated but refused with 400 BOTS_CANNOT_CREATE_GUILDS.

Rate limit: guild:create, 10 per 60 seconds per account.

JSON body¶

An animated icon needs boost level 2, which a new guild never has, so an animated icon returns 403 FORBIDDEN. Upload it later through Modify guild.

A new guild gets a category named Genel holding a text channel genel and a voice channel Genel, and an @everyone role with the default permission set. The voice channel's bitrate is 64000 (64 kbps). No system channel is set.

curl -X POST https://tebhos.com/api/v1/guilds \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada'\''s Workshop"}'

List current user guilds¶

GET /users/@me/guilds

Returns an array of guild objects, one per guild the caller is a member of, ordered by ascending guild ID. Each object includes permissions, the caller's guild-level mask. roles, emojis, stickers and channels are not included.

Also accepts an OAuth2 access token with the guilds scope; a token without it receives 403 MISSING_OAUTH_SCOPE.

Rate limit: guild:list, 40 per 10 seconds per account.

Query parameters¶

A cursor that names a guild the caller is not in is ignored. A guild whose data cannot be read is skipped rather than failing the request, and permissions is omitted for a guild whose permissions cannot be computed. limit outside 1-200 returns 400 INVALID_FORM_BODY.

curl "https://tebhos.com/api/v1/users/@me/guilds?with_counts=true" \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN"

Get guild¶

GET /guilds/{guild_id}

Returns the guild object with roles (sorted by descending position), emojis, stickers, channels and a live member_count. Requires membership.

Also accepts an OAuth2 access token with the guilds scope; a token without it receives 403 MISSING_OAUTH_SCOPE.

Rate limit: guild:read, 100 per 10 seconds per account and guild.

Modify guild¶

PATCH /guilds/{guild_id}

Updates guild settings and returns the updated guild object. Requires MANAGE_GUILD. Every successful request dispatches Guild Update to the guild and records a GUILD_UPDATE audit log entry.

Rate limit: guild:update, 20 per 10 seconds per account and guild.

JSON body¶

Every field is optional. An omitted field keeps its value. For the fields typed ?, an explicit null clears the value.

nsfw, nsfw_level, content_warning_level and content_warning_text are accepted for compatibility and ignored. Sudo fields (password, mfa_code and so on) are also accepted and ignored.

Images accept PNG, JPEG, GIF and WebP up to 10 MiB decoded, sent as raw base64 or as a data: URL. The asset rules follow the guild's boost level:

A missing level returns 403 FORBIDDEN. Replacing the icon schedules the old icon file for deletion.

features is the full set you want the guild to have, not a difference. Send back the array from the guild object with your changes applied:

• A toggleable feature that is in the array and not in the guild is added; one that is in the guild but not in the array is removed.
• A feature the guild already has in its effective set (including derived features such as BANNER) is accepted and left alone.
• Adding any other feature returns 400 BAD_REQUEST.

system_channel_id and afk_channel_id are stored as given; the route does not check that the channel exists or has the right type.

In a guild listed in discovery, verification_level 0 returns 400 INVALID_FORM_BODY.

curl -X PATCH https://tebhos.com/api/v1/guilds/1489002177550843904 \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada'\''s Lab", "afk_timeout": 600, "system_channel_flags": 1}'

TEBHOS-only settings¶

description, region, boost_goal and boost_bar_enabled (the TEBHOS guild extras) have no field on this route. They are set with PATCH /servers/{guild_id}, which requires MANAGE_GUILD, shares the guild:update bucket, and returns {"message": "..."}:

The change is dispatched as Guild Update.

Toggle guild feature¶

Each of these routes adds or removes one toggleable feature and returns the updated guild object. They require MANAGE_GUILD and are user-only. Each dispatches Guild Update.

A missing or non-boolean body field returns 400 BAD_REQUEST.

Delete guild¶

POST /guilds/{guild_id}/delete

Permanently deletes the guild and returns 204. User-only. Only the guild owner can delete a guild; anyone else receives 403 FORBIDDEN.

Rate limit: guild:delete, 10 per 60 seconds per account and guild.

The request body is ignored; you can send {}. No password or sudo proof is required.

Every member receives Guild Delete, members in the guild's voice channels are disconnected, and the guild is removed from search.

Leave guild¶

DELETE /users/@me/guilds/{guild_id}

Removes the caller from the guild and returns 204. The caller's other sessions receive Guild Delete and the remaining members receive Guild Member Remove. The guild is removed from the caller's guild folders.

Rate limit: guild:leave, 10 per 10 seconds per account and guild.

Query parameters¶

Message deletion is best-effort: if it fails, the caller still leaves the guild.

Bulk delete current user's guild messages¶

POST /users/@me/guilds/{guild_id}/messages/bulk-delete-mine

Deletes every message the caller wrote in the guild's channels and returns 202 with no body. The caller stays a member. Requires membership and sudo mode; a bot token satisfies sudo mode for its own account. Each affected channel receives a Message Delete Bulk event.

Rate limit: guild:leave, 10 per 10 seconds per account and guild (shared with Leave guild).

A non-member receives 404 NOT_FOUND; a user session without a sudo grant receives 403 SUDO_MODE_REQUIRED.

Custom invite URL¶

A guild at boost level 2 can claim a custom invite code (its vanity code). https://tebhos.com/vanity/{code} and Get invite resolve it; see Custom invite URLs.

Custom invite URL object¶

Get guild custom invite URL¶

GET /guilds/{guild_id}/vanity-url

Returns the custom invite URL object. Requires MANAGE_GUILD. User-only.

Rate limit: guild:vanity_url:get, 100 per 10 seconds per account and guild.

Modify guild custom invite URL¶

PATCH /guilds/{guild_id}/vanity-url

Sets or removes the custom invite code and returns {"code": "..."} with the code now held (null after removal). Requires MANAGE_GUILD. User-only. Dispatches Guild Update.

Rate limit: guild:vanity_url:patch, 10 per 60 seconds per client and guild.

A code is trimmed and must be 2-32 characters of ASCII letters, digits, - and _. Codes are unique regardless of letter case, and a list of reserved words (such as admin, api, login, invite, settings) cannot be claimed. Removing the code resets uses to 0.

curl -X PATCH https://tebhos.com/api/v1/guilds/1489002177550843904/vanity-url \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "workshop"}'

Resolve custom invite code¶

GET /vanity/{code}/resolve

Resolves a custom invite code without authentication. Letter case is ignored. Each call increases the code's uses. Returns a camelCase object:

An unknown code returns 404 NOT_FOUND.

Guild images¶

Modify guild accepts images inline as base64. The web app instead uploads them straight to storage in two steps, which avoids large JSON bodies. Both steps are user-only and require MANAGE_GUILD (the owner always passes).

1. POST /servers/{guild_id}/{kind}/upload-url with {"filename": string, "content_type": string, "size": integer}. Returns upload_url (a presigned URL valid for 300 seconds), storage_key, url and expires_in. PNG, JPEG, GIF and WebP up to 8 MiB are accepted.
2. Upload the bytes with PUT to upload_url, then POST /servers/{guild_id}/{kind}/confirm with {"storage_key": string}.

{kind} is icon, banner, invite-bg (the invite background, splash) or embed-bg (embed_splash). The banner needs boost level 2 and the invite background level 1, and an animated icon or banner needs level 2, as on Modify guild. Confirming dispatches Guild Update. The icon confirmation returns {"icon_hash": string, "image_url": string}.

Guild boosts¶

A guild's boost level (0, 1 or 2) comes from the number of active boosts and controls the derived guild features, voice bitrate ceilings, upload limits and animated emoji. Boosting, the boost list and pricing are documented under Guild boosts. tebhos.boost_count on the guild object holds the current number of boosts.

Roles¶

Role routes are documented on Roles and permissions:

Adding and removing a single role on a member is covered in Guild members.