TEBHOS API¶

TEBHOS is a chat platform for communities, with text channels, direct messages, voice and screen sharing. This reference describes the public protocol surfaces that clients, bots and integrations use.

To build a client or a bot, start with the HTTP API and the Gateway.
To write a bot, follow the Bots guide.
For voice and screen sharing, read Voice.

Quick links¶

Section	What it covers
Authentication	Credential types and the `Authorization` header
HTTP API overview	Base URL, request and response conventions
Gateway overview	The real-time WebSocket connection
Bots guide	Creating a bot, connecting it and adding it to a community
Errors	Error body shape and error codes
Rate limits	Buckets, headers and the 429 response
Permissions	Permission bits, roles and overwrites
Snowflakes	The 64-bit identifier format
Media proxy	Avatars, icons, attachments and other media
Downloads	Desktop application downloads

Protocol surfaces¶

Use the HTTP API to read and change resources, and Gateway events to receive updates in real time. The media routes serve uploaded files, avatars, icons and proxied external media.

Surface	Address
HTTP API	`https://tebhos.com/api/v1`
Gateway	`wss://tebhos.com/ws?v=1&encoding=json`
Web application	`https://tebhos.com`

Every HTTP path in this reference is relative to the API base URL. For example, GET /channels/{channel_id} means GET https://tebhos.com/api/v1/channels/{channel_id}.

Shared contracts¶

See Authentication, Errors, Rate limits and Locales for behaviour shared by every operation. Most resource identifiers are snowflakes. CAPTCHA handling and Attachment uploads describe two flows that span several operations. Each resource page states where it differs from this shared behaviour.

Field notation¶

In field tables, ? after a field name means optional. Before a type, it means nullable.

Field	Type	Meaning
`name`	`string`	Required and cannot be `null`
`name?`	`string`	Optional, but cannot be `null` when present
`name`	`?string`	Required, but can be `null`
`name?`	`?string`	Can be omitted or set to `null`

An omitted field is different from a field set to null. Each operation explains how these values affect the resource.

In the type column, array[type] is an array of the named type, and map[key, value] is a JSON object keyed by the first type with values of the second. snowflake is a 64-bit identifier sent as a decimal string.

Endpoint discovery¶

Start with the instance discovery document. It requires no authentication.

curl https://tebhos.com/api/v1/.well-known/tebhos

The response describes the instance: its endpoints, enabled features, CAPTCHA provider, limits and version. See Instance for the full object. A trimmed example:

{
  "api_code_version": 1,
  "version": "0.1.0",
  "endpoints": {
    "api": "https://tebhos.com/api",
    "api_client": "https://tebhos.com/api",
    "api_public": "https://tebhos.com/api",
    "gateway": "wss://tebhos.com/ws",
    "media": "https://tebhos.com/api/v1",
    "webapp": "https://tebhos.com",
    "invite": "https://tebhos.com",
    "gift": "https://tebhos.com"
  },
  "features": {
    "voice_enabled": true,
    "presigned_attachment_uploads": true,
    "emails_enabled": true,
    "sms_enabled": false,
    "self_hosted": true,
    "payment_provider": "polar"
  },
  "captcha": {
    "provider": "hcaptcha",
    "hcaptcha_site_key": "00000000-0000-0000-0000-000000000000",
    "turnstile_site_key": null
  }
}

Read base URLs from endpoints rather than hard-coding them:

endpoints.api_public is the API base for bots, libraries and third-party clients. endpoints.api and endpoints.api_client currently carry the same value.
The API base does not include the version. Append /v1 to it, so https://tebhos.com/api becomes https://tebhos.com/api/v1.
endpoints.gateway is the Gateway URL. Connect with ?v=1&encoding=json as described in the Gateway overview.
endpoints.media is the base for media routes such as avatars and icons.

The discovery route has its own rate limit of 60 requests per 60 seconds per client. Cache the document instead of fetching it before every request.

Send credentials in the Authorization header as described in Authentication.