Admin panel: all routes and API contracts

Documentation of every route in the built-in telesrv admin panel — the SPA page addresses and the API routes behind them. The panel server lives in cmd/telesrv-admin; routes are declared in (*server).routes() (server.go:50).

The panel is a plain HTTP server: it serves the built frontend (/) and a JSON API under the /api/ prefix. Every API path requires a session (cookie), and every mutating request additionally requires a CSRF token. Many routes also check an operator permission (permission).

How to use this document

• For each GET endpoint, the request parameters (query) and a short response shape are listed.
• For each POST endpoint under /api/actions/* and the verification decisions, the request body (JSON) is given. They all share common fields (see below) plus their own specific fields.
• int64 in JSON may be sent either as a number or as a string (e.g. "user_id": "123" or "user_id": 123) — the server accepts both (flexInt64). flexUnix accepts Unix seconds or a date in 2006-01-02 / RFC3339 form.
• All mutating requests go to the Admin API. A command's response is either {"status":..., "message":..., "command_id":...} on success (HTTP 200) or {"error":..., "code":...} on error. An optimistic-locking conflict is 409.

Authentication and session

The session lives in a signed cookie (default TTL 12 hours); there is no server-side session store. Every request except GET/HEAD/OPTIONS and /api/login must present:

• the telesrv_admin_csrf cookie;
• the X-CSRF-Token header with the same value;
• an Origin matching the host (when Origin is present).

Violating any of the three — 403 Forbidden.

Permissions and their checks

The panel distinguishes plain authorization (requireAuthAPI) from a permission check (requirePermission). Permission names match the strings in TELESRV_ADMIN_UI_PERMISSIONS, and the list below is exactly what assignablePermissions() (cmd/telesrv-admin/security.go) offers the operator-accounts screen — a right that is not in that list cannot be granted to a named operator account.

Most sections are a read/manage pair: the read right opens the page, the manage right is what the buttons on it need. The panel checks the read right for the page's own GET endpoints and the manage right per action, so granting only accounts.read gives a working read-only account screen.

A few rights are deliberately independent of the section they sit in: verification.review and botverification.review are granted separately because the two queues are separate mechanisms over separate tables, and verification.revoke is checked in addition to verification.review. admins.manage is the one right that can hand out every other right, so it is never implied by anything, and audit.read is supervisory rather than riding on the sections it covers.

The session's permission list is returned from /api/session, and the frontend uses it to decide which sidebar sections to show and which pages to refuse — see "Navigation and permissions in the UI" below.

Navigation and permissions in the UI

The panel's sidebar, its in-page tab bars and its route table are three views of one declaration: cmd/telesrv-admin/web/src/nav.ts. That file lists every section, the paths that belong to it, and the right each of those paths enforces server-side. Layout.tsx renders the sidebar from it and, above every page, the active section's tab bar through SectionTabs.tsx, which reads that section's tab list from it; Routes.tsx asks it a single question -- routePermission(path) -- and gates the whole surface in one place.

Two consequences worth knowing before changing anything here:

• A section is rendered when the session holds any of its tabs' rights, and its link resolves to the first visible tab. An operator holding only prices.manage gets one Economy row that opens on Bot prices. A section reduced to a single visible tab draws no tab bar at all.
• A page can never be advertised and then answer 403. Before this table existed, twelve sidebar entries rendered unconditionally while every endpoint behind them was gated -- an operator without accounts.read still saw Accounts, and clicking it produced a bare 403 rather than the explanation PermissionDenied gives. The gate is now derived from the same strings the sidebar reads.

Adding a page to the panel

In order, because skipping a step produces the drift this section exists to prevent:

1. Decide whether it is a new section or a tab of an existing one. If the page is a sibling of something already there -- it serves the same job over a different slice -- it is a tab, not a second sidebar row. Economy already holds Stars balances, Premium, Bot prices, Donations and Account Rating; Server holds Storage, Operators and the Audit log. A new sidebar row is only for a genuinely new job.
2. Add it to nav.ts, with the right its route enforces server-side. If you need a right that does not exist yet, add it to permissions.tsx (permissionLabels and permissionGroups) and to assignablePermissions() in security.go -- a right that is not assignable cannot be granted, and the operator-accounts picker will not show it.
3. Add the route in Routes.tsx. Do not wrap it in PermissionGate: the gate is already applied from routePermission, and a hand-wrapped branch is the thing that let the old gaps accumulate.
4. Add the page in web/src/pages/, and take a navigate prop if it needs one. Do not render <SectionTabs> in it: the shell (Layout.tsx) already draws the active section's tab bar above every page from nav.ts, so a page that renders its own shows two. gen_admin_panel_doc_tables.py --check fails on any <SectionTabs under pages/.
5. Translate it. Every user-visible string goes through useI18n() and gets an entry in all three language blocks of i18n.tsx.
6. Rebuild the bundle. cmd/telesrv-admin/server.go does //go:embed web/dist, so web/dist is what a non-Docker build ships. Run npm run build and commit the result, including the deletion of the old hashed assets. A src change without a rebuilt dist does not ship.
7. Regenerate the tables in this document: python3 scripts/gen_admin_panel_doc_tables.py --write.

The generated tables

Both the navigation table below and the permission table above are produced by scripts/gen_admin_panel_doc_tables.py from nav.ts, permissions.tsx and security.go. They drifted badly once -- a dozen routes were missing entirely -- because nothing checked them. Do not hand-edit them; edit the source and rerun. --check exits non-zero when they are stale, which is the form worth putting in CI.

SPA routes are declarative: any unknown frontend path is served as / (index.html) and the router decides what to render (web/src/pages/Routes.tsx). The tables below come from nav.ts, the single declaration the sidebar and the router both read.

Section tabs

Every tab of every section, with the right its route enforces. /statistics is the one path with no tab: the statistics charts were folded into the overview, and the old URL still lands there rather than 404ing on a bookmark.

A section with one visible tab shows no tab bar, and its sidebar link points at that tab directly.

Detail and sub-routes

These paths belong to the section above but are not tabs of it -- they are a specific record inside one, and each is gated by the same right as its list.

/premium is a permanent alias of /monetization. /messages is an alias of /messages/private.

An unknown API path returns 404 {"error":"api route not found"}; any unknown frontend path is served as /.

Response conventions

• Successful reads — 200 + JSON; files (avatars, animations, previews) — the file itself.
• Errors — JSON of the form {"error": "...", "code": "..."} with the corresponding HTTP status.
• 401 — missing/expired session; 403 — CSRF/Origin violation or missing permission (in requirePermission the body gets an added permission field); 409 — optimistic-locking conflict (moderation case, verification); 502 — Admin API unreachable.
• Errors from commands sent to the Admin API are returned as {"status": ..., "message": ..., "error": ...}.

Common command fields (POST /api/actions/*)

Every mutating request carries in its body:

API: dashboard and storage

API: accounts

API: channels and supergroups

API: bots and broadcasts

API: media catalogs

API: message audit

API: star gifts and collectibles

API: Premium

All routes in this section require the premium.manage permission (checked both at the panel and at the Admin API).

API: moderation

All reads pass query parameters through to the Admin API as-is (/v1/moderation/...). Decisions are POST (see below).

API: official verification

All routes require the verification.review permission. Reads go straight to PostgreSQL; decisions always go through the Admin API (command journal, state machine, optimistic locking).

A "decided by another moderator" conflict is returned as 409 Conflict.

API: third-party (bot) verification

A separate mechanism with separate tables, permissions, and routes. Queue reads and decisions require botverification.review; managing verifiers, the icon catalog, and stripping marks requires botverification.manage.

API: account actions

All routes are POST /api/actions/..., require a session and CSRF. The request body always contains the common command fields (command_id, reason, confirm) plus the fields from the table below.

Example (granting Premium, the case from above):

POST /api/actions/grant-premium
Content-Type: application/json
X-CSRF-Token: <csrf from /api/session>

{
  "command_id": "grant-premium-001",
  "reason": "Incident compensation",
  "confirm": true,
  "user_id": 123456789,
  "months": 12
}

API: machine account lookup (v1)

POST /v1/accounts/resolve-by-phone — bearer-token-protected, read-only account lookup used by the Telegram store bot's "fetch my ID" flow. It resolves the numeric account ID from a phone number without viewer privacy projection, so the bot can auto-save a user's server ID when they have already set up an account there. Unlike every /api/actions/... route it carries no command metadata, because the endpoint never mutates state and writes no audit entry.

Response 200 OK:

Errors: 401 — invalid/absent bearer token; 500 — lookup failure; 501 — deployment built without a lookup backend. Missing numbers are a success with found: false, never 404.

Example:

POST /v1/accounts/resolve-by-phone
Authorization: Bearer <token>
Content-Type: application/json

{ "phone": "+79991234567" }

// 200
{ "found": true, "user_id": 1780243207 }

API: channel actions

API: bot actions

API: sticker and emoji actions

API: GIF catalog actions

API: gift and collectible actions

API: collectible username actions

API: anonymous number actions

Gift inventory when importing or replacing a revision

For a new official gift, enabling include_collectible uses supply_total as both the unique-gift supply and the base gift's initial sales cap. If omitted, the collectible supply is derived from the snapshot's availability or upgrade variants. With collectible import disabled, this input does not limit ordinary base gifts. Auctions still require their own finite supply.

An existing gift_id keeps its original base supply, limited flag, remaining stock, resale counters and sale dates. Replacement never replenishes exhausted stock or converts it to unlimited. A different base cap or auction/non-auction mode requires a new gift identity; requesting it on an existing identity fails without publishing either revision. The separate collectible-pool editor does not change base stock. Inventory is rechecked under the purchase/catalog lock at execution, and the result reports the committed remaining stock. Dry-run does not reserve stock. The catalog badge shows remaining / total copies.

API: account rating actions

API: message deletion

API: verification decisions (request bodies)

Official verification — revoke-verification:

Third-party verification — verifier/mark actions (botverification.manage):

All of these also carry the common fields (command_id, reason, confirm).