HTTP API¶

Use the HTTP API to read and change resources. Every route lives under one base URL:

https://tebhos.com/api/v1

Paths on these pages are written relative to that base, so GET /channels/{channel_id} means GET https://tebhos.com/api/v1/channels/{channel_id}. A client that needs to discover the base URL, or any other endpoint of the deployment, reads /.well-known/tebhos first. The endpoints.api_public value there is the API root (it ends in /api), and the client appends /v1 itself.

v1 is the only API version. There is no version negotiation header and no older version to fall back to.

Resource limits such as attachment counts, message length, and guild expression counts are published in the limit configuration of instance discovery. Read them from there instead of hard-coding them.

Conventions¶

Snowflakes¶

Every ID is a snowflake: a 64-bit integer that the API always serialises as a decimal string, for example "1501314428688998182". Send IDs back as strings too. A JavaScript client MUST NOT parse an ID into a number, because a snowflake does not fit in a double-precision float.

Snowflakes encode their creation time and sort chronologically, which is what the cursor pagination below relies on.

Timestamps¶

Timestamps are ISO 8601 / RFC 3339 strings in UTC, for example "2026-09-23T00:15:57.000Z". A few fields that come from the realtime layer or from a cache carry Unix time instead, and those are called out on their own page (for example exp and iat in OAuth2 introspection).

Field notation¶

Field tables on every resource page use the same notation:

A client MUST treat an unknown response field as absent rather than failing, because fields are added over time.

Pagination¶

List routes that can grow without bound are cursor-paginated with snowflakes. Where a route supports it, pass before, after, or around with a snowflake ID and limit with a count; the route page states the default and maximum limit. Small, bounded collections (for example connections or the applications a user owns) are returned whole.

Request format¶

Send JSON bodies with Content-Type: application/json. Responses are UTF-8 JSON unless an operation states otherwise. Exceptions are called out on their resource page:

• OAuth2 token, introspection, and revocation take application/x-www-form-urlencoded bodies.
• Message creation and webhook execution also accept multipart/form-data, described on Messages and Webhooks.
• File uploads use presigned URLs; see Attachment uploads.

A body that is not valid JSON, or whose shape does not match the operation (a missing required field, a wrong type), is rejected with 400 before the operation runs.

Unknown paths return 404 with an empty body. A known path called with a method it does not support also returns 404 with an empty body, not 405. Trailing slashes are significant: /users/@me/ is a different path from /users/@me.

Only the public media routes (/files/{key}, /avatars/..., /banners/..., /server-icons/..., and the other image routes described in Media proxy routes) answer HEAD. On every other route, HEAD is treated like any other unsupported method.

Authentication¶

Most routes require an Authorization header. TEBHOS accepts two schemes on the REST API:

A user session token may also be sent bare, without the Bearer prefix. Authentication describes both credentials in full.

Each route states which credentials it accepts. Many user-facing routes are user-only: they read a session token and reject a valid bot token with 403 ACCESS_DENIED (an invalid one with 401). Routes that bots use (messages, reactions, channels, guild reads, and so on) accept both. OAuth2 bearer access tokens are accepted only by the two OAuth2 routes that document them (user information and current authorisation) and by a few read routes that require a matching scope; OAuth2 access tokens lists them. Any other route answers a valid access token with 403 ACCESS_DENIED.

Sensitive account operations additionally require sudo mode: a fresh proof of the password, an authenticator code, or a passkey, supplied in the request body or granted to the session for five minutes.

Standard request headers¶

Standard response headers¶

The X-RateLimit-* headers are sent only on a rate-limit denial, not on successful responses. Rate limits defines the full contract.

Rate limits¶

Every authenticated /api/v1 request counts against a global limit of 50 requests per second per client. The client is identified by its Authorization header, or by its IP address when it sends none. Unauthenticated GET/HEAD requests, public media reads, and webhook execution are exempt from the global limit.

Most routes also have their own route bucket, documented on each operation. A denial from either returns 429 with code RATE_LIMITED:

{
  "error": "429 Too Many Requests",
  "code": "RATE_LIMITED",
  "message": "...",
  "global": false,
  "retry_after": 1.25
}

retry_after is in seconds with a fractional part; Retry-After is the same value rounded up to whole seconds. Rate limits lists the buckets and the header contract.

Cross-origin requests¶

Browser requests are allowed from the TEBHOS web origins (https://tebhos.com and its *.tebhos.com subdomains). For an allowed Origin, the response carries Access-Control-Allow-Origin set to that origin and Access-Control-Allow-Credentials: true. Requests from any other origin receive no Access-Control-Allow-Origin, so a browser blocks them.

The preflight allows the methods GET, POST, PUT, PATCH, DELETE, and OPTIONS, and the request headers Content-Type and Authorization. The rate-limit headers and Retry-After are exposed to script through Access-Control-Expose-Headers.

Public media routes (avatars, icons, banners, and /files/{key}) answer every origin with Access-Control-Allow-Origin: *, so images can be loaded from anywhere.

A bot or server-side client is not a browser and is not affected by CORS.

Error response object¶

A failed request returns a JSON body with a stable error code and a human-readable message.

Structure¶

A client MUST branch on code and the HTTP status, never on message. Messages are written for end users, are currently in Turkish, and can change at any time.

Example¶

{
  "error": "403 Forbidden",
  "code": "FORBIDDEN",
  "message": "Kendi yetkilerinizi değiştiremezsiniz"
}

Some operations add further top-level members with structured detail, and document them. For example, login returns IP_AUTHORIZATION_REQUIRED with ticket, email, and resend_available_in, and a rate-limit denial carries global and retry_after. A client MUST ignore members it does not recognise.

Validation error object¶

Each entry identifies one failed input field.

Structure¶

Example¶

{
  "error": "400 Bad Request",
  "code": "INVALID_FORM_BODY",
  "message": "Kanal sesli kanal olmalı",
  "errors": [
    {"path": "channel_id", "code": "CHANNEL_MUST_BE_VOICE", "message": "CHANNEL_MUST_BE_VOICE"}
  ]
}

In an errors entry, message currently repeats the code. Many validation failures return INVALID_FORM_BODY with a top-level message only and no errors array. Errors lists the codes.

Resource pages¶