Cookiebot API v0.1.0

Which commands the deployment uses, busiest first, with how many groups each one reaches — a command with 10,000 invocations in one group and one used everywhere are different facts, and a decision to retire a command should not confuse them.

What the whole deployment's users actually type.

One command across every group, with its reach as well as its volume.

One row per day, summed across every group that was active that day.

active_users is summed per group, so one person in three groups counts three times — deduplicating across groups would need the raw events rather than the rollups, which is a much more expensive question.

The deployment's activity, one row per day.

One day, summed across every group that was active on it.

The busiest groups in the window, most messages first.

A leaderboard, not a directory: a group with no activity in the window is absent here and present in /admin/groups.

The busiest groups. A leaderboard, not a directory: a group with no activity in the window is absent here and present in /admin/groups.

One group's totals across the window, for the leaderboard.

Fleet-wide LLM spend, per provider and model, most expensive first.

Fleet-wide AI spend, most expensive model first.

One provider/model's spend across every group.

The directory, ordered by group_id and keyset-paginated (D11).

The cursor is the id itself, which is stable and unique, so a group added between two pages cannot make a row repeat or vanish the way an OFFSET would.

A page of the directory, ordered by group_id.

One group the bot knows — what it is in, not what it did.

Reach, the window's totals and the LLM budget, in one request.

One request for the dashboard's first screen.

Three round trips server-side rather than three from the Mini App: a phone inside Telegram on a bad connection pays for each of them, and none of the three is useful without the others.

Where the bot is right now — no window, because this is the present.

The window's totals across every group, with the peaks called out rather than averaged — an average of daily percentiles means nothing.

The tenant's soft LLM budget against what the window actually cost.

monthly_llm_budget_usd is what cb_core.llm refuses chat past, so an owner watching this number is watching the thing that will silently turn the conversational features off.

The tenant's own row, read-only.

Read-only because every field here changes how the *bot* behaves — which commands exist, which model answers, where media is written — and a Mini App form that could flip active or empty owner_ids would be one mis-tap from an outage nobody could undo through the same API. Editing a tenant is a deliberate database change, and it stays one.

bot_tokens is deliberately absent: an owner who needs it has it already, and an endpoint that returns bot tokens is one stolen owner token away from being the whole deployment.

What this deployment is configured as. Read-only on purpose — see the note on the endpoint.

Which commands this group actually uses, busiest first, totalled across the window rather than broken down per day.

Which commands this group uses, busiest first.

One command's totals across the window, not one row per day.

One row per day the group was active. Days with no activity have no row — the rollup writes only what it saw, and inventing zeros here would be indistinguishable from a real quiet day.

One row per day the group was active — a chart's x-axis.

One day. Days with no activity have no row at all.

What this group's AI features cost, per provider and model.

The same numbers Tenant.monthly_llm_budget_usd is spent against, so an admin can see why the conversational AI started refusing before asking anyone.

What this group's AI features cost — the same numbers the tenant's budget is spent against, so an admin can see why chat started refusing.

One provider/model's usage and spend across the window.

The window in one object — totals, the peak day's active users, the worst day's p95, and the captcha solve rate (null when nobody was challenged, which is not the same fact as nobody solving it).

cb_core.analytics.summarise, plus the window.

RFC 7009. Revoking an unknown token is a success: the caller's goal is that the token cannot be used, and it cannot.

Always true, including for a token this deployment never issued (RFC 7009): the caller's goal is that it cannot be used, and it cannot.

Exchange a Telegram proof — or a refresh token — for an access token.

RFC 6749 §5.1. The access token is the same RS256 JWT /login mints, verifiable against /.well-known/jwks.json.

The group's trail, newest first, keyset-paginated (D11 — no OFFSET, no unbounded list).

next_before is the cursor for the following page and is null on the last one. Filtering by action or actor_user_id narrows without changing the cursor's meaning.

A page of the trail, newest first, with the cursor for the next one.

One recorded change: what, who, from where, and both values.

The group's effective settings — stored values over tenant defaults over v1's defaults, which is the same resolution the bot itself reads.

A group's effective settings: stored values over the tenant's defaults over v1's, which is the same resolution the bot itself reads.

The group's effective settings — the same fifteen columns ConfigPatch writes, none of them optional here because a read always resolves to a value (stored, else the tenant's default, else v1's).

Change some settings. Absent fields are left alone — this is a PATCH, not a PUT, because a Mini App form that round-trips every column would overwrite a change another admin made while it was open.

An empty patch is a 400 rather than a no-op success: a client that sent nothing meant to send something.

The writable half of group_configs, every field optional.

Written out rather than derived from GroupConfig's dataclass fields: this is a public contract, and a column added to the table should not silently become writable over HTTP. The bounds are the ones the Telegram menu enforces by refusing to parse anything else, made explicit.

The settings after the patch, and which of them actually moved.

The group's effective settings — the same fifteen columns ConfigPatch writes, none of them optional here because a read always resolves to a value (stored, else the tenant's default, else v1's).

The text /rules prints in the chat, with who last set it and when.

A group that never set any reads back "body": null rather than 404 — not having rules is a normal state of a group, not a missing resource.

The rules or the welcome message, with its provenance. body is null when the group never set one; that is the normal state, not a 404.

What /newrules sets, set from the Mini App instead. Same table, same upsert (cb_core.group_texts), so /rules in the chat shows this text immediately.

The rules, or a welcome message. Length is Telegram's message limit — text this endpoint accepts that the bot could never send would be a setting that saves and then fails silently in the chat.

The rules or the welcome message, with its provenance. body is null when the group never set one; that is the normal state, not a 404.

The message new members are greeted with, exactly as stored.

The <user> placeholders are substituted when the bot sends it, not here, so what comes back is what /newwelcome was given. null when the group never set one.

The rules or the welcome message, with its provenance. body is null when the group never set one; that is the normal state, not a 404.

<user> and its eight sibling spellings are substituted when the message is sent, not here — the body is stored exactly as given, which is what /newwelcome does.

The rules, or a welcome message. Length is Telegram's message limit — text this endpoint accepts that the bot could never send would be a setting that saves and then fails silently in the chat.

The rules or the welcome message, with its provenance. body is null when the group never set one; that is the normal state, not a 404.

Who the token says you are, what it lets you do, and which groups you administer.

The Mini App's first call: it has initData telling it who the user is, but not which of that user's groups this deployment knows about, nor whether they run the whole thing. The list comes from group_admins, which the gateway maintains — so a promotion made a minute ago appears once the bot has seen an admin-gated command in that group, and not before (cb_api.security's note on why this service never calls Telegram to refresh it).

Who the token says you are, what it lets you do, and where.

One group the caller administers, as group_admins records it.

Process is up. No dependency checks — a DB blip must not trigger restarts.

What a liveness probe gets: the process identifying itself.

Dependencies reachable. Fails -> pulled from rotation, not restarted.

Each dependency, separately. One flag for "should I get traffic" would make the two failures indistinguishable in the one place they need to be told apart.

v1 Server.py:55-57. number_chats was the module constant NUMBER_CHATS = 1275 (:17) that nothing ever updated; here it is the real count.

v1's / — what COOKIEBOT-WebHub polls to decide the bot is alive.

v1 Server.py:78-84. v1 published the key of whichever gunicorn worker answered; this publishes every key the deployment might have signed with, so a rotation can overlap.

Every key the deployment might have signed with, so a rotation overlaps.

v1 Server.py:86-95, plus what x_miniapp_auth added.

The five v1 keys are unchanged and in place; the rest describe the token endpoint, its two Telegram grants and the revocation endpoint, which is what a Mini App or an OAuth client library discovers this deployment with. Additive by construction: a consumer written against v1 reads the same five values it always did.

What a Mini App or an OAuth client library discovers this deployment with. The first five keys are v1's, unchanged; the rest arrived with x_miniapp_auth.

Exchange a Telegram login-widget payload for a JWT.

v1 Server.py:59-76. The status codes and the two error bodies are v1's, because the client branches on them.

v1's success body, key for key. COOKIEBOT-WebHub reads accessToken by name (src/lib/api/axios.ts), so neither name may move.