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

# Admin API

> Every endpoint a mak_ admin key reaches, grouped by the permission that opens it.

The admin API is the management plane: everything a script can do to your organization without a person signing in. It takes a `mak_` admin key — see [Admin Keys](https://developers.meshapi.ai/docs/getting-started/admin-keys.md) for minting, scopes, rotation, and expiry.

```bash theme={null}
curl https://api.meshapi.ai/v1/keys \
  -H "Authorization: Bearer $MESH_ADMIN_KEY"
```

Every route below accepts an admin key carrying the permission named beside it. A permission you were not granted is a `403`, whatever the route.

> [!NOTE]
>
> Only six routes on this page appear in the API Reference tab: `POST /v1/usage`, `POST /v1/usage/events`, `POST /v1/usage/rejections`, `GET /v1/usage/events/{event_id}/attempts`, `GET /v1/usage/rate-limits` and `GET /v1/usage/spend-trend`. Everything else here — keys, org, members, billing, alerts, webhook deliveries, routing-policy templates, provider keys, analytics, logs, the CSV export and the two org spend routes — is withheld from the published spec, so this page is its reference.

## Scope, in one line

Each route also has a **minimum scope** — the narrowest key that reaches it. A `self`-scoped key reaches only rows it owns; `org` reaches the whole organization.

Eight permissions act on the organization itself and can therefore only be granted at `org` scope: `org:read`, `org:write`, `alerts:read`, `alerts:write`, `limits:read`, `limits:write`, `logs:read`, `logs:read_bodies`. Asking for them at `self` or `team` is a `422` at mint time.

Of the rest, only `keys:read`, `keys:write` and `provider_keys:read` do anything below org scope. `members:write`, `billing:read` and `usage:read` can be granted narrower, but every route that reads them requires `org` — so a `self`-scoped key carrying one gets a `403` rather than a narrower answer. Grant those at `org` or not at all.

***

## API keys

Manage the `rsk_` inference keys your applications call models with.

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/keys` | `keys:read` | `self` | List inference keys |
| `GET /v1/keys/filter-options` | `keys:read` | `self` | Inference keys for filter dropdowns. The BYOK half comes back empty for an admin key — that needs `provider_keys:read`, which this route does not consult |
| `GET /v1/keys/tools` | `keys:read` | `self` | Tool names a key's `tool_policy` may name |
| `GET /v1/keys/{key_id}/limits` | `keys:read` | `self` | Effective limits for one key, resolved across every tier |
| `POST /v1/keys` | `keys:write` | `self` | Create an inference key. The plaintext is returned once |
| `PATCH /v1/keys/{key_id}` | `keys:write` | `self` | Update a key's metadata or limits |
| `DELETE /v1/keys/{key_id}` | `keys:write` | `self` | Deactivate a key — a soft delete, status becomes `suspended` |

A key minted by an admin key belongs to that key's **lineage**, not to a person, and survives rotation of the admin key that created it. See [Admin Keys](https://developers.meshapi.ai/docs/getting-started/admin-keys.md) for what that means for ownership and billing.

## Organization

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/orgs/current` | `org:read` | `org` | The organization this credential acts in |
| `GET /v1/orgs/current/permissions` | `org:read` | `org` | What this credential may do |
| `GET /v1/orgs/current/permissions/catalogue` | `org:read` | `org` | The permission vocabulary, and what each built-in role holds |
| `GET /v1/orgs/current/billing-profile` | `org:read` | `org` | The billing profile. `404` until one is saved |
| `GET /v1/orgs/current/sso` | `org:read` | `org` | The org's registered SSO provider. Dashboard: **Settings → Single sign-on**. Adding or removing a provider is dashboard-only; see [Single Sign-On](https://developers.meshapi.ai/docs/getting-started/single-sign-on.md) |
| `GET /v1/orgs/current/scim` | `org:read` | `org` | The org's [user provisioning](https://developers.meshapi.ai/docs/getting-started/user-provisioning.md) setup: connection, tokens (never their values), group map, and the groups the IdP pushed. Dashboard: **Settings → Single sign-on → User provisioning (SCIM)**. Setting up, tokens and the group map are dashboard-only |
| `GET /v1/orgs/current/scim/groups` | `org:read` | `org` | Pushed groups whose name contains `?search=`, at most 200, with `truncated`. Dashboard: the group picker under **Group roles**, which searches as you type |
| `PATCH /v1/orgs/current` | `org:write` | `org` | Update org limits, name, or `suspend_keys_on_member_removal`. Dashboard for the last: **Settings → People → Removing a member → Suspend their API keys** |
| `PUT /v1/orgs/current/billing-profile` | `org:write` | `org` | Create or replace the billing profile |
| `DELETE /v1/orgs/current/billing-profile` | `org:write` | `org` | Erase the billing profile |

> [!WARNING]
>
> **`org:write` stops at the three org-wide privacy controls.** `PATCH /v1/orgs/current` refuses `zero_data_retention`, `default_pii_policy` and `default_body_log_policy` to an admin key with a `403`, before it validates anything else in the body. Turning zero data retention off starts storing prompt bodies again and that disclosure cannot be taken back, so it stays a signed-in action. Change them in the dashboard.

## Members and invitations

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/orgs/current/invitations` | `members:write` | `org` | List every invitation, pending or not |
| `POST /v1/orgs/current/invitations/{inv_id}/resend` | `members:write` | `org` | Resend a pending invitation with a fresh token |
| `DELETE /v1/orgs/current/invitations/{inv_id}` | `members:write` | `org` | Revoke a pending invitation |
| `GET /v1/orgs/current/members/{target_user_id}/removal-preview` | `members:write` | `org` | The keys removing this member would suspend, and the org's default (`suspend_keys_default`). Dashboard: the list in the **Remove** dialog under **Settings → People** |
| `DELETE /v1/orgs/current/members/{target_user_id}` | `members:write` | `org` | Remove a member. The org owner cannot be removed. `?suspend_keys=true\|false` overrides the org's default for this removal. Dashboard: **Settings → People → Remove**, with the **Suspend these keys** checkbox |

> [!WARNING]
>
> **Sending a new invitation is a dashboard action.** `POST /v1/orgs/current/members` authenticates a signed-in person, so an admin key can revoke, resend and list invitations but cannot create the first one. Roles, teams and ownership transfer are dashboard-only for the same reason.

## Usage

Seven of these also accept an `rsk_` key carrying the `usage:read` scope. **Three do not** — the CSV export and the two org spend routes take an admin key or a dashboard session, and an `rsk_` bearer gets a `401`. They are marked below.

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `POST /v1/usage` | `usage:read` | `org` | Aggregate usage stats |
| `POST /v1/usage/events` | `usage:read` | `org` | Paginated per-request event history |
| `POST /v1/usage/rejections` | `usage:read` | `org` | Requests refused before any model was called — rate limit, spend cap, balance, model access |
| `GET /v1/usage/events/{event_id}/attempts` | `usage:read` | `org` | Per-attempt timeline for one request, oldest first |
| `GET /v1/usage/events/export` | `usage:read` | `org` | The same event history as a CSV file. **No `rsk_`** |
| `GET /v1/usage/rate-limits` | `usage:read` | `org` | Live RPM / RPD / TPM against your limits, read fresh every call |
| `GET /v1/usage/spend-trend` | `usage:read` | `org` | Historical spend bucketed by granularity, with a moving average |
| `GET /v1/usage/runs/{run_id}` | `usage:read` | `org` | One agent run, by the id sent on `X-Mesh-Run-Id` |
| `GET /v1/orgs/current/spend` | `usage:read` | `org` | Rolling 30-day spend broken down by member. **No `rsk_`** |
| `GET /v1/orgs/current/spend/by-team` | `usage:read` | `org` | The same, broken down by team. **No `rsk_`** |

> [!NOTE]
>
> `GET /v1/usage/requests/{request_id}` — the single-request lookup — is the one usage route an admin key does **not** reach. It takes an `rsk_` key with the `usage:read` scope. [Usage API](https://developers.meshapi.ai/docs/reference/usage-api.md) covers the request and response shapes for this group.

## Analytics

The analytics surface reads the same traffic as the usage group, pre-aggregated. The same `usage:read` permission at `org` scope opens it, and an admin key reads **the whole organization's traffic** here — unlike an `rsk_` key, which sees only its own rows.

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/analytics/usage/summary` | `usage:read` | `org` | Grouped usage from the hourly cube |
| `GET /v1/analytics/usage/summary.csv` | `usage:read` | `org` | The same result, streamed as CSV |
| `GET /v1/analytics/usage/summary.xlsx` | `usage:read` | `org` | The same result, as an Excel workbook |
| `GET /v1/analytics/meta` | `usage:read` | `org` | The dimensions, measures, filters and caps this surface accepts |
| `GET /v1/analytics/findings` | `usage:read` | `org` | Five sections, each with a verdict rather than a chart |
| `GET /v1/analytics/spend/summary` | `usage:read` | `org` | Where the money went, and what moved since last period |
| `GET /v1/analytics/reliability/attribution` | `usage:read` | `org` | Where requests ended up, the two latency legs, and what retries recovered |
| `GET /v1/analytics/views` | `usage:read` | `org` | Saved views. An admin key sees org-shared views only, never a member's personal one |
| `GET /v1/analytics/views/{view_id}` | `usage:read` | `org` | One saved view, subject to the same limit |

> [!NOTE]
>
> **Reads only.** Creating, updating and deleting a saved view is refused to any key, admin key included — saved views are managed from a dashboard session.
>
> Analytics is rolled out per environment. [Analytics API](https://developers.meshapi.ai/docs/reference/analytics-api.md) documents the dimensions, measures and query shapes.

## Billing

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/invoices` | `billing:read` | `org` | The org's invoices, newest first |
| `GET /v1/invoices/{invoice_id}` | `billing:read` | `org` | One invoice |
| `GET /v1/invoices/{invoice_id}/pdf` | `billing:read` | `org` | That invoice as a PDF, rendered from what was stored when it was issued |

> [!WARNING]
>
> Reading invoices is the whole of billing an admin key reaches. **Paying is not** — topping up, checkout and auto-recharge setup all require a signed-in person, and the permission that authorizes spending (`billing:pay`) cannot be granted to an admin key at all. A leaked admin key cannot spend your balance.

## Alerts and notifications

Alert channels, the policies that fire into them, and the outbound webhook delivery log. See [Notifications](https://developers.meshapi.ai/docs/capabilities/notifications.md) for the event catalogue and payload shapes.

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /alerts` | `alerts:read` | `org` | Channels and policies for this org |
| `GET /alerts/report-timezone` | `alerts:read` | `org` | The zone the daily digest is sent in |
| `POST /alerts/channels` | `alerts:write` | `org` | Add an email, Slack or webhook channel |
| `PATCH /alerts/channels/{channel_id}` | `alerts:write` | `org` | Update a channel |
| `DELETE /alerts/channels/{channel_id}` | `alerts:write` | `org` | Remove a channel |
| `POST /alerts/channels/{channel_id}/verify` | `alerts:write` | `org` | Mail a confirmation link to an email channel |
| `POST /alerts/channels/{channel_id}/rotate-secret` | `alerts:write` | `org` | New signing secret, returned once |
| `POST /alerts/policies` | `alerts:write` | `org` | Subscribe a channel to events |
| `PATCH /alerts/policies/{policy_id}` | `alerts:write` | `org` | Update a policy |
| `DELETE /alerts/policies/{policy_id}` | `alerts:write` | `org` | Remove a policy |
| `PUT /alerts/report-timezone` | `alerts:write` | `org` | Set the digest timezone. Null is UTC |

> [!NOTE]
>
> These paths are `/alerts/...`, not `/v1/alerts/...`.

Rotating a channel's signing secret keeps the previous one verifying for a grace window, so a receiver can cut over without dropping deliveries.

### Webhook deliveries

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/webhooks/deliveries` | `alerts:read` | `org` | This org's deliveries. Scope comes from the credential — there is no `org_id` parameter |
| `GET /v1/webhooks/deliveries/stats` | `alerts:read` | `org` | Delivery success and failure counts |
| `GET /v1/webhooks/deliveries/{delivery_id}` | `alerts:read` | `org` | One delivery, with its attempts |
| `POST /v1/webhooks/deliveries/test` | `alerts:write` | `org` | Send a sample payload for one event to one endpoint |
| `POST /v1/webhooks/deliveries/{delivery_id}/redeliver` | `alerts:write` | `org` | Queue a fresh attempt for the same event |

## Routing policy templates

Shared retry and fallback policy that keys reference instead of each carrying their own. See [Retry and fallback](https://developers.meshapi.ai/docs/platform/retry-and-fallback.md).

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/routing-policy-templates` | `limits:read` | `org` | List templates |
| `GET /v1/routing-policy-templates/{template_id}` | `limits:read` | `org` | One template |
| `PATCH /v1/routing-policy-templates/{template_id}` | `limits:write` | `org` | Update a template |
| `DELETE /v1/routing-policy-templates/{template_id}` | `limits:write` | `org` | Soft delete. Every key referencing it falls back to the org default |

> [!NOTE]
>
> **Creating** a template is a dashboard action. An admin key can read and edit templates but cannot create the first one.

## Provider keys

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/provider-keys/supported` | `provider_keys:read` | `self` | Providers that accept a pasted API key |

This is a read of the catalogue, not of your credentials. Adding, listing or removing your own BYOK keys is a dashboard action — see [Bring your own key](https://developers.meshapi.ai/docs/capabilities/byok.md).

## Logs

A Loki-compatible read of your organization's own log tenant, so you can point your Grafana at Mesh directly. `logs:read` covers the query surface; `logs:read_bodies` additionally serves stored request and response bodies.

| Endpoint | Permission | Scope | What it does |
| - | - | - | - |
| `GET /v1/logs/loki/api/v1/query` | `logs:read` | `org` | Instant LogQL query |
| `GET /v1/logs/loki/api/v1/query_range` | `logs:read` | `org` | Range LogQL query |
| `GET /v1/logs/loki/api/v1/labels` | `logs:read` | `org` | Label names |
| `GET /v1/logs/loki/api/v1/label/{name}/values` | `logs:read` | `org` | Values for one label |
| `GET /v1/logs/loki/api/v1/series` | `logs:read` | `org` | Series matching a selector |
| `GET /v1/logs/loki/api/v1/patterns` | `logs:read` | `org` | Detected log patterns |
| `GET /v1/logs/loki/api/v1/detected_fields` | `logs:read` | `org` | Fields detected in matching lines |
| `GET /v1/logs/loki/api/v1/detected_field/{name}/values` | `logs:read` | `org` | Values for one detected field |
| `GET /v1/logs/loki/api/v1/detected_labels` | `logs:read` | `org` | Labels detected in matching lines |
| `GET /v1/logs/loki/api/v1/index/stats` | `logs:read` | `org` | Index statistics for a selector |
| `GET /v1/logs/loki/api/v1/index/volume` | `logs:read` | `org` | Volume for a selector |
| `GET /v1/logs/loki/api/v1/index/volume_range` | `logs:read` | `org` | Volume over a range |
| `GET /v1/logs/loki/api/v1/format_query` | `logs:read` | `org` | Pretty-print a LogQL query |
| `GET /v1/logs/loki/api/v1/status/buildinfo` | `logs:read` | `org` | Build info, for Grafana's datasource probe |
| `GET /v1/logs/bodies` | `logs:read_bodies` | `org` | Stored request and response bodies |

Setup, fields, queries and limits: [Request Logs](https://developers.meshapi.ai/docs/reference/request-logs.md).

> [!WARNING]
>
> `logs:read_bodies` is held by the **owner and admin roles only**: no custom role carries it, so a key carrying it was minted by an owner or an admin. Bodies are never served for an organization under zero data retention.

Reads are capped per organization per minute. Records older than 7 days are not returned.

***

## What an admin key never reaches

| Surface | Why, and what to use instead |
| - | - |
| **Inference** — `/v1/chat/completions` and every other model call | A `mak_` key cannot spend your balance. Use an `rsk_` key |
| **Paying** — top-ups, checkout, auto-recharge setup | `billing:pay` is not grantable to an admin key. Dashboard, signed in |
| **Minting, rotating or revoking admin keys** | An admin key cannot mint another. Dashboard, signed in |
| **Roles, teams, ownership transfer, sending invitations** | Dashboard, signed in |
| **Creating a routing-policy template, adding a BYOK key** | Dashboard, signed in |
| **`GET /v1/usage/requests/{request_id}`** | An `rsk_` key with the `usage:read` scope |
| **`GET /v1/audit-logs`** and its CSV | An `rsk_` key or a dashboard session |
| **Zero data retention, the org PII policy, the org body-log policy** | Refused to an admin key on `PATCH /v1/orgs/current`. Dashboard, signed in |
| **Creating, editing or deleting a saved analytics view** | Dashboard, signed in |

## Errors

| Status | When |
| - | - |
| `401` | The key is revoked, expired, or unknown |
| `403` | The permission was not granted, or the key's scope does not reach the rows asked for |
| `404` | The row exists but your scope cannot see it — or the surface is not enabled for your environment |
| `422` | The request body or query is malformed |
| `429` | A per-organization rate limit — the logs surface caps reads per minute |

[API errors](https://developers.meshapi.ai/docs/reference/errors.md) covers the error envelope.

## Related

* [Admin Keys](https://developers.meshapi.ai/docs/getting-started/admin-keys.md) — minting, permissions, scope, rotation, revocation
* [Authentication](https://developers.meshapi.ai/docs/getting-started/authentication.md) — `rsk_` against `mak_`
* [API Keys](https://developers.meshapi.ai/docs/getting-started/api-keys.md) — the inference keys this API manages
* [Usage API](https://developers.meshapi.ai/docs/reference/usage-api.md) — request and response shapes for the usage group
* [Notifications](https://developers.meshapi.ai/docs/capabilities/notifications.md) — the event catalogue behind alerts and webhooks


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.