> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oximail.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin REST API

> The /admin/v1 operational REST surface: authentication, the endpoint map (accounts, tenants, bans, queue, spam, config, version), and where admin-over-JMAP takes over.

The REST API under `/admin/v1` is the **operational** surface: the endpoints scripts and monitoring call — deploy verification, bans, the queue, config overrides. Administrative *data* objects (organizations, audit log, journaling rules, admin principal management) live on **admin-over-JMAP** instead (`urn:oximail:params:jmap:v2:admin`, ADR-075) — new admin objects are added there, not here.

## Authentication

Every endpoint requires the admin bearer token from `[admin] token`:

```bash theme={null}
curl -H "Authorization: Bearer $ADMIN_TOKEN" https://mail.example.com/admin/v1/version
```

Bind the admin surface to a separate local port with `[server] admin_bind` if you prefer it off the public listener.

## Endpoint map

### Deploy & health

| Endpoint                     | Purpose                                                            |
| ---------------------------- | ------------------------------------------------------------------ |
| `GET /admin/v1/version`      | Version and `migrations_applied` — the post-deploy check.          |
| `GET /admin/v1/stats`        | Instance statistics.                                               |
| `GET /admin/v1/logs/summary` | Aggregated recent-log summary.                                     |
| `GET /metrics`               | Prometheus metrics ([operations](../operator/operations#metrics)). |

### Accounts and organizations

| Endpoint                                                                                                                           | Purpose                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET/POST /admin/v1/accounts`, `POST …/batch`                                                                                      | List and provision accounts.                                                                   |
| `GET/PUT/DELETE /admin/v1/accounts/{id}`                                                                                           | Inspect, update, delete (delete enqueues the [erasure phase machine](../operator/compliance)). |
| `POST …/{id}/enable`, `…/disable`, `PUT …/{id}/role`                                                                               | Lifecycle and role.                                                                            |
| `GET …/{id}/capabilities`                                                                                                          | Effective capability set.                                                                      |
| `GET …/{id}/mailboxes`, `emails`, `identities`, `sieve` (+`/{name}/activate`), `calendars`, `events`, `contacts`, `tasks`, `files` | Per-account data views for support tooling.                                                    |
| `GET/POST /admin/v1/tenants`, `GET/PUT /admin/v1/tenants/{id}`                                                                     | Organizations.                                                                                 |
| `PUT …/{id}/branding`, `…/{id}/plan`, `GET …/{id}/capabilities`, `…/capabilities-matrix`                                           | Per-organization branding, plan, and capability toggles.                                       |

### Security

| Endpoint                                                  | Purpose                            |
| --------------------------------------------------------- | ---------------------------------- |
| `GET/DELETE /admin/v1/bans`, `DELETE /admin/v1/bans/{ip}` | The in-binary fail2ban's ban list. |
| `GET/POST/DELETE /admin/v1/whitelist(/{ip})`              | The trust whitelist.               |

### Mail operations

| Endpoint                                                                                                                               | Purpose                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `GET /admin/v1/queue`, `GET/DELETE …/{id}`, `POST …/{id}/retry`, `POST …/flush`                                                        | The outbound delivery queue.                                   |
| `GET /admin/v1/spam/stats`, `POST …/test`, `POST …/feedback/{tenant}`, `POST …/retrain/{tenant}`, `GET/PUT …/blocklist`, `GET …/model` | The [spam pipeline](../operator/anti-spam)'s corpus and model. |
| `POST /admin/v1/reindex-blobs`                                                                                                         | Blob-related reindex maintenance.                              |

### Configuration

| Endpoint               | Purpose                                                                                                                                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PUT /admin/v1/config` | Set runtime config overrides (`{"overrides": {"key": value}}`) — see [configuration](../operator/configuration#setting-a-runtime-override). `GET` returns a usage hint, not a dump, at v0.30.0. |

## Conventions

* Responses are JSON; errors carry a machine-readable reason and an HTTP status that means what it says.
* Everything here is also reachable from the [CLI](../operator/cli) — both are thin adapters over the same orchestration, so behaviour is identical.
* The API is **per organization** where data is organization-scoped; there is deliberately no cross-tenant data view.