Instance¶

Discover a TEBHOS deployment's endpoints, enabled features, public configuration, and limits with one unauthenticated request.

Get instance discovery is the entry point of the API. A client that knows only the TEBHOS origin reads /.well-known/tebhos first, and that single response describes the API base URL, the Gateway WebSocket URL, the media base URL, the CAPTCHA provider, and the limits that apply to accounts and guilds.

The route is unauthenticated, and a credential changes nothing in the response. It is also exempt from the global rate limit when sent without an Authorization header.

Instance discovery object¶

The discovery document is the complete public description of one deployment. Every field listed here is always present.

Structure¶

The last four fields are a compact legacy summary kept for older consumers. New clients read endpoints instead of gateway.

Example¶

{
  "api_code_version": 1,
  "version": "0.1.0",
  "gateway": "wss://tebhos.com/ws",
  "cdn": "https://cdn.tebhos.com",
  "experiments": {},
  "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",
    "static_cdn": "https://tebhos.com",
    "marketing": "https://tebhos.com",
    "admin": "https://admin.tebhos.com",
    "invite": "https://tebhos.com",
    "gift": "https://tebhos.com",
    "webapp": "https://tebhos.com"
  },
  "captcha": {
    "provider": "hcaptcha",
    "hcaptcha_site_key": "00000000-0000-0000-0000-000000000000",
    "turnstile_site_key": null
  },
  "features": {
    "voice_enabled": true,
    "stripe_enabled": true,
    "payment_provider": "polar",
    "self_hosted": true,
    "presigned_attachment_uploads": true,
    "emails_enabled": true,
    "sms_enabled": false
  },
  "gif": {"provider": "klipy", "display_name": "KLIPY", "attribution_required": true},
  "sso": {"enabled": false, "enforced": false, "display_name": null, "redirect_uri": "https://tebhos.com/auth/sso/callback"},
  "registration": {"mode": "open", "admin_registration_urls_enabled": true},
  "community": {"single_community": false, "single_community_guild_id": null, "direct_messages_disabled": false},
  "services": {"gif_enabled": true, "youtube_enabled": false, "bluesky_enabled": false},
  "limits": {"version": 1, "traitDefinitions": ["premium"], "rules": ["..."]},
  "push": {"public_vapid_key": "BM4KrfS2..."},
  "app_public": {
    "branding": {"product_name": "TEBHOS", "icon_url": null, "symbol_url": null, "logo_url": null, "wordmark_url": null, "favicon_url": null, "theme_color": null},
    "setup": {"configured": true, "admin_url": "https://admin.tebhos.com"},
    "legal": {"terms_url": null, "privacy_url": null},
    "registration": {"collect_date_of_birth": true}
  }
}

The values above are illustrative. Always use the values the deployment actually returns.

Instance endpoints object¶

Each value is an absolute URL. Several endpoints can share one origin and differ only by path.

Structure¶

invite and gift default to the web application URL unless the deployment configures separate domains.

CAPTCHA configuration object¶

Which CAPTCHA provider the deployment uses, and the site key a client needs to render its challenge.

Structure¶

provider is hcaptcha when both the hCaptcha secret and site key are configured, otherwise turnstile when both Turnstile keys are configured, otherwise none. A site key can be present while provider is none, because the key is published whenever it is configured; branch on provider, not on the presence of a key.

CAPTCHA providers¶

The challenge handshake, including the X-Captcha-Token and X-Captcha-Type request headers, is described in CAPTCHA handling.

Instance features object¶

Deployment-wide switches a client reads before offering a feature.

Structure¶

GIF provider object¶

The GIF provider and whether a client must show its attribution.

Structure¶

A client reads services.gif_enabled to decide whether to offer the GIF picker at all.

Registration policy object¶

Who can register an account on this deployment.

Structure¶

Registration modes¶

The value reflects the setting stored by the administration panel. See Register an account for what the registration route itself checks.

Community policy object¶

Whether the deployment runs as one community, and whether direct messages are available.

Structure¶

Service availability object¶

Whether each optional integration is available.

Structure¶

Push configuration object¶

The deployment's public Web Push identity.

Structure¶

Limit configuration object¶

The ordered rules a client evaluates to work out the limits that apply to an account or a guild.

Structure¶

The stock configuration has three rules: default (no filters, sets every limit key), premium (filtered on the premium trait), and very_large_guild (filtered on the VERY_LARGE_GUILD guild feature).

A client starts from the default rule, then applies each rule whose filters all match: every trait it names is one of the account's traits, and every guild feature it names is one of the guild's features. A matching rule's values replace the current ones for the keys it sets.

Limit rule object¶

One rule of the limit configuration.

Structure¶

A rule edited in the administration panel can carry extra bookkeeping members (for example modifiedFields). A client MUST ignore members it does not recognise.

Example¶

{
  "id": "premium",
  "filters": {"traits": ["premium"]},
  "limits": {"feature_higher_video_quality": 1}
}

Limit filters object¶

The traits and guild features a limit rule requires.

Structure¶

Limit keys¶

A key whose name begins with feature_ is a feature gate: 0 when the feature is unavailable and 1 when it is available. Every other key is a bound in the unit its description names. The defaults are the values of the stock default rule; a deployment can change them.

Public application configuration object¶

Branding, setup state, legal links, and registration-form settings a client reads before anyone signs in. The administration panel edits these values.

Structure¶

Public branding object¶

Structure¶

Public setup state object¶

Structure¶

Public legal configuration object¶

Structure¶

Public registration fields object¶

Structure¶

Get instance discovery¶

GET /.well-known/tebhos

Returns the instance discovery object. Authentication is not required. The response has Cache-Control: no-cache, so a client revalidates it on each start; the web app uses version to notice a new deployment.

The path is under the v1 base: https://tebhos.com/api/v1/.well-known/tebhos.

Response¶

Rate limit¶

60 requests per minute for each client, on the instance:info bucket. The client is identified by its Authorization header, or by its IP address when it sends none.

Example¶

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