> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel-docs-benchmark-writeup-and-tooling.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Endpoints

> Built-in REST API and dashboard for monitoring usage, budgets, models, and gateway health.

## Philosophy

GoModel ships with admin endpoints **enabled by default**. The goal is simple: you should be able to deploy GoModel and immediately have visibility into what's happening — no extra services, no separate monitoring stack, no configuration.

The admin layer is split into two independently controllable pieces:

1. **Admin REST API** (`/admin/*`) — machine-readable JSON endpoints for usage data, budgets, and model inventory. Protected by `GOMODEL_MASTER_KEY` like all other API routes.
2. **Admin Dashboard UI** (`/admin/dashboard`) — a lightweight, embedded HTML dashboard that visualizes the same data. No external dependencies, no JavaScript frameworks to install — it's compiled into the binary.

Both are on by default because observability shouldn't be opt-in. If you don't need them, turn them off with a single environment variable.

## Configuration

Admin and dashboard behavior is controlled by environment variables (or the
equivalent `admin:` YAML block). See
[Admin configuration](/advanced/configuration#admin) for the full table of
variables, defaults, and the equivalent `admin:` YAML block.

<Note>
  The dashboard UI requires the REST API to be enabled. If you set
  `ADMIN_ENDPOINTS_ENABLED=false` but leave `ADMIN_UI_ENABLED=true`, the UI
  will be automatically disabled with a warning in the logs.
</Note>

## Authentication

The admin REST API endpoints (`/admin/*`) are protected by the same `GOMODEL_MASTER_KEY` authentication as the main API routes. Include the key as a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer $GOMODEL_MASTER_KEY" \
  http://localhost:8080/admin/usage/summary
```

The dashboard UI pages (`/admin/dashboard`) and static assets (`/admin/static/*`) **skip authentication** so the dashboard is accessible without configuring API keys in the browser.

<Warning>
  If your GoModel instance is publicly accessible, be aware that the dashboard
  UI is unauthenticated. Disable it with `ADMIN_UI_ENABLED=false` or restrict
  access at the network level.
</Warning>

## REST API Endpoints

All admin API endpoints are mounted under `/admin`.

<Note>
  **Legacy path alias** — until **2026-08-09**, the same endpoints are also
  reachable under `/admin/api/v1/*`. Responses on the legacy path carry
  `Deprecation: true`, `Sunset: Sun, 09 Aug 2026 00:00:00 GMT`, and a `Link`
  header pointing to the new path. To migrate, replace `/admin/api/v1/` with
  `/admin/` in your scripts. One endpoint also moved within `/admin`:
  `/admin/api/v1/dashboard/config` → `/admin/runtime/config`.
</Note>

### GET /admin/usage/summary

Returns aggregate token usage statistics over a configurable time window.

**Query parameters:**

| Parameter    | Type   | Description                                               | Default            |
| ------------ | ------ | --------------------------------------------------------- | ------------------ |
| `start_date` | string | Range start in `YYYY-MM-DD` format                        | 29 days before end |
| `end_date`   | string | Range end in `YYYY-MM-DD` format                          | Today              |
| `days`       | int    | Shorthand for look-back window (ignored if dates are set) | `30`               |

Use `start_date`/`end_date` for explicit ranges or `days` as a shorthand. When both are provided, `start_date`/`end_date` take priority.

**Response:**

```json theme={null}
{
  "total_requests": 1542,
  "total_input_tokens": 2450000,
  "total_output_tokens": 890000,
  "total_tokens": 3340000
}
```

If usage tracking is disabled, returns zeroed values.

### GET /admin/usage/daily

Returns per-period token usage breakdown over a configurable time window, grouped by the specified interval.

**Query parameters:**

| Parameter    | Type   | Description                                               | Default            |
| ------------ | ------ | --------------------------------------------------------- | ------------------ |
| `start_date` | string | Range start in `YYYY-MM-DD` format                        | 29 days before end |
| `end_date`   | string | Range end in `YYYY-MM-DD` format                          | Today              |
| `days`       | int    | Shorthand for look-back window (ignored if dates are set) | `30`               |
| `interval`   | string | Grouping: `daily`, `weekly`, `monthly`, `yearly`          | `daily`            |

The `date` field in the response changes format based on the interval: `YYYY-MM-DD` (daily), `YYYY-Www` (weekly), `YYYY-MM` (monthly), or `YYYY` (yearly).

**Response:**

```json theme={null}
[
  {
    "date": "2026-02-17",
    "requests": 84,
    "input_tokens": 120000,
    "output_tokens": 45000,
    "total_tokens": 165000
  },
  {
    "date": "2026-02-16",
    "requests": 102,
    "input_tokens": 155000,
    "output_tokens": 58000,
    "total_tokens": 213000
  }
]
```

Returns an empty array if usage tracking is disabled or no data exists for the period.

### Budget endpoints

Budgets are managed under `/admin/budgets`. These endpoints are
available when budget management is enabled.

| Method   | Path                                  | Description                      |
| -------- | ------------------------------------- | -------------------------------- |
| `GET`    | `/admin/budgets`                      | List budgets with current status |
| `PUT`    | `/admin/budgets/{user_path}/{period}` | Create or update one budget      |
| `DELETE` | `/admin/budgets/{user_path}/{period}` | Delete one budget                |
| `GET`    | `/admin/budgets/settings`             | Read budget reset settings       |
| `PUT`    | `/admin/budgets/settings`             | Update budget reset settings     |
| `POST`   | `/admin/budgets/reset-one`            | Reset one budget period          |
| `POST`   | `/admin/budgets/reset`                | Reset all budget periods         |

`PUT`, `DELETE`, and `reset-one` identify one budget by the composite
`(user_path, period)` key, or `(user_path, period_seconds)` for custom periods.
These operations are not global per period. For the path-scoped `PUT` and
`DELETE` routes, URL-encode `user_path`; see [Budgets](/features/budgets) for
the request shape.

See [Budgets](/features/budgets) for request examples and enforcement behavior.

### GET /admin/models

Returns all registered models with both provider type and configured provider name.

**Response:**

```json theme={null}
[
  {
    "model": {
      "id": "gpt-4o",
      "object": "model",
      "created": 1715367049,
      "owned_by": "system"
    },
    "provider_type": "openai",
    "provider_name": "openai_primary",
    "selector": "openai_primary/gpt-4o"
  },
  {
    "model": {
      "id": "claude-sonnet-4-5-20250929",
      "object": "model",
      "created": 1727568000,
      "owned_by": "system"
    },
    "provider_type": "anthropic",
    "provider_name": "anthropic_main",
    "selector": "anthropic_main/claude-sonnet-4-5-20250929"
  }
]
```

This differs from the standard `/v1/models` endpoint: the admin version includes both `provider_type` and `provider_name` for each model, making it useful for understanding both the provider family and the concrete configured provider instance that serves the model.

## Admin Dashboard

The dashboard is a server-rendered HTML page embedded in the GoModel binary. Access it at:

```
http://localhost:8080/admin/dashboard
```

It provides a visual overview of usage statistics and registered models using the same data as the REST API endpoints above.

When `DASHBOARD_LIVE_LOGS_ENABLED=true`, the dashboard opens
`GET /admin/live/logs` and streams compact audit/usage lifecycle previews. This
lets the Audit Logs and Usage pages show a request as it moves through the
workflow before the async database flush finishes. The stream uses sequence
cursors, bounded replay, and heartbeat events so reconnecting browsers can catch
up after short network drops.

The persisted audit and usage tables remain the source of truth. If the
browser's cursor falls outside the replay buffer, the stream sends a reset event
and the dashboard reloads from the normal REST endpoints.

## Disabling Admin Features

To disable all admin features:

```bash theme={null}
export ADMIN_ENDPOINTS_ENABLED=false
```

This disables both the REST API and the dashboard UI. To keep the API but hide the dashboard:

```bash theme={null}
export ADMIN_ENDPOINTS_ENABLED=true
export ADMIN_UI_ENABLED=false
```

<Tip>
  The admin layer is designed to degrade gracefully. If usage tracking is off,
  the usage endpoints return empty results instead of errors. If the model
  registry isn't ready, the models endpoint returns an empty array. The gateway
  keeps running regardless.
</Tip>