# Admin API Admin endpoints manage routes, groups, members, invites, webhook secrets, send logs, and the audit log. They require an admin session cookie obtained via `GET /admin/login` (GitHub OAuth); the signed-in user must be listed in `ADMIN_USER_IDS` or manage a group. For local development only, exact `DEBUG_MODE=true` bypasses authentication and grants full access; never deploy with it enabled. See [Configuration → Web UI](../guide/configuration.md#web-ui) for setup. The console itself is served at `/admin`; its tabs are deep-linkable via the URL path (`/admin/groups`, `/admin/logs`, `/admin/audit`). ## Endpoints | Endpoint | Description | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `GET /admin` | Config console UI | | `GET /admin/login` | Start admin sign-in (GitHub OAuth) | | `GET /admin/logout` | Sign out and destroy the session | | `GET /admin/invite?token=…` | Accept a group invite (browser page) | | `GET /admin/api/me` | Current session, scope, groups, and roles | | `GET /admin/api/routes` | List routes (scoped to access) | | `PUT /admin/api/routes` | Replace routes (owner/admin per group) | | `GET /admin/api/groups` | List groups (each with its `revision`) + the signed-in user's role in each, plus the list `revision` | | `PUT /admin/api/groups` | Bulk write (legacy): super admins replace all groups, owners change/delete their own; only groups that differ are written | | `POST /admin/api/groups` | Create one group (super admins) — body `{ group }`; `409` when the id exists or was used recently | | `PUT /admin/api/groups/:id` | Update one group (owner) — body `{ group }`; `409` when its `revision` is stale | | `DELETE /admin/api/groups/:id` | Delete one group with its routes and fragments (owner) — query `revision`, `routesRevision` and `version` from the confirmation; `409` when anything changed since | | `GET /admin/api/groups/:id/routes` | List a group's routes, with the list's `revision`, the group `version` and `unreadable` | | `PUT /admin/api/groups/:id/routes` | Replace a group's routes (owner/admin) — `409` when the sent `revision` is stale | | `GET /admin/api/groups/:id/fragments` | List a group's named filter fragments, with the list's `revision` | | `PUT /admin/api/groups/:id/fragments` | Replace a group's named filter fragments (owner/admin) — body `{ fragments, revision? }`; `409` when the `revision` is stale | | `PUT /admin/api/groups/:id/rename` | Rename a group (owner) — body `{ newId, revision? }`; routes, fragments and history move in one transaction, the secret and invites stay with the group; the old id stays retired for a few days | | `GET /admin/api/groups/:id/invites` | List pending invites (owner) | | `POST /admin/api/groups/:id/invites` | Create an invite link (owner) — body `{ role, note? }` (`role` is `admin` or `viewer`) | | `DELETE /admin/api/invites/:token` | Revoke an invite (owner) | | `GET /admin/api/groups/:id/webhook` | Group webhook endpoint info (owner) | | `POST /admin/api/groups/:id/webhook/regenerate` | Generate/regenerate the group webhook secret (owner) | | `DELETE /admin/api/groups/:id/webhook` | Disable the group webhook ingress (owner) | | `GET /admin/api/logs` | Send logs of the accessible groups (filtered in SQL before the limit) | | `GET /admin/api/logs/:id` | Single send-log entry (scoped) | | `GET /admin/api/audit` | Audit log of the accessible groups (filtered in SQL before the limit) | | `GET /admin/api/metrics` | Delivery stats (totals, failure rate, per platform/event/status, recent failures); optional `?groupId=` scope; every aggregate is limited to the accessible groups | | `GET /admin/api/delivery/:deliveryId` | The attempts of one delivery that belong to the accessible groups; optional `?groupId=` (two groups' senders may use the same delivery id) | | `POST /admin/api/test-match` | Stateless filter dry-run — evaluate a filter node against a pasted JSON payload (no event is stored) | ## Validation - `PUT /admin/api/routes` — Body `{ "routes": Route[] }`; validates each route (id pattern, unique id within its group, name, enabled, `groupId`, filters — an array, empty only for `fallback` routes or when a valid `ast` is present; patterns the matcher cannot compile — longer than 200 characters, or RE2-unsupported syntax such as backreferences or lookaround — are rejected; flat `filters` hold leaf conditions only (`all`/`any`/`not` belong in `ast`); `keyword` only supports the default `eq`; `exists` may omit `match` — optional `discordRoleIds` (at most 50 numeric Discord role ids), and platform-aware targets: `target.channelId` for Discord, `target.chatId` for Telegram/Feishu, with the id rules and duplicate-destination check in [Routes & Targets](../guide/routes)) and persists to D1 `d1_routes`, rewriting only the groups whose routes changed. A non-super admin pointing a target at a channel another group uses gets `403`. Returns `200 { ok, count }` or `400 { error }` / `401 { error }` / `403 { error }`. Unchanged routes skip the full validation. Route filters support the `field` type (a JSONPath `path` into `payload`, arrays expand so any element matches) and 12 `op` operators (`eq` default / `ne` / `contains` / `startsWith` / `endsWith` / `regex` / `gt` / `gte` / `lt` / `lte` / `in` / `exists`); a nested `ast` (`all` / `any` / `not`) takes precedence over `filters` when present. - `PUT /admin/api/groups` / `POST /admin/api/groups` / `PUT /admin/api/groups/:id` — Validate group ids, `members` (or legacy `adminIds`; a non-empty `members` list needs at least one `owner`), `forgeSources` (at most 20, `name` up to 50 characters, unique type + host), `providers` (`github` / `gitea` / `custom`), and `installationId`; unknown fields are dropped. The source-isolation fields `owners`, `installationId` and `isolated` are super-admin only: an owner's write keeps their stored values. New members' logins are resolved to GitHub user ids with the writer's token; the server-only fields (`instance`, the webhook secret, member user ids) can never be set by the client. - Every write re-checks the writer's role inside its transaction: a request authorized before the role was revoked is refused (`409` for route/fragment writes, `403` for group writes). - Optimistic concurrency — every list or group the API returns carries a `revision`. Send it back with the write (`group.revision`, or `revision` next to `routes` / `fragments` / `newId`, or the list `revision` of the bulk groups write) and the server refuses the write with `409` if the stored data changed since it was loaded, instead of overwriting the newer change. Writes without a `revision` are applied as before. In the bulk groups write, a group echoed back unedited is never written. - `PUT /admin/api/groups/:id/routes` — Optional `discardUnreadable: true` replaces stored routes that cannot be read (otherwise the save is refused while the group has any). - `PUT /admin/api/routes` — Optionally send `revisions` (the per-group map returned by `GET /admin/api/routes`): groups whose list comes back unedited are not written, groups the client never loaded are not touched, and edited groups must still be at their loaded revision (`409` otherwise). Each group is written in its own guarded transaction. - `PUT /admin/api/groups/:id/rename` — Optional `revision`; returns `{ ok, id, group, revision }` (the renamed group and its new revision). Ids starting with `inst-` or `u-` are reserved for super admins. - `DELETE /admin/api/groups/:id` — Requires `revision`, `routesRevision` and `version` as seen at confirmation (`400` when missing, `409` when the group, its routes or fragments changed, or when it has routes that cannot be read). Also revokes the group's invites and webhook secret, detaches its send logs and audit entries (they stay visible to super admins only), and retires the id for a few days so queued deliveries cannot reach a new group that reuses it. - `POST /admin/api/groups/:id/webhook/regenerate` — Returns `{ ok, url, secret, hasSecret }`; the secret is shown only in this response. - `POST /admin/api/test-match` — Body `{ "node": FilterNode | "filters": Filter[], "event"?: string, "payload": object }`; evaluates in memory and returns `{ matched, explanation }`. Nothing is persisted. - `GET/PUT /admin/api/groups/:id/fragments` — Named filter fragments (`{ id, groupId, name, node }`) stored in D1 `d1_fragments`; the editor inlines a fragment's `node` into a route's `ast` on insert (the matcher never resolves fragment references). `PUT` replaces the group's fragments (at most 200) and returns `200 { ok, count }`. - Limits: one save accepts at most 200 routes, 200 fragments per group, and 100 groups in the bulk groups write. Schemas: [Routes & Targets](../guide/routes), [Groups & Access Control](../guide/groups).