Management API

Use the management API to control your organization's keys, guardrails, grants, presets, workspaces, notifications and exports. It also reports usage, spend forecasts, savings, security and audit data.

Every route is served under /v1/... and under /api/v1/.... The two paths act the same.

curl https://dev2-api.routerplus.com/v1/keys \
  -H "Authorization: Bearer $TM_MANAGEMENT_KEY"

Authentication

Send a management key as a Bearer token:

Authorization: Bearer tm_mk_...

• A management key belongs to one organization. Every route acts on that organization only. An id from another organization returns 404.
• A management key never authenticates an inference request. An API key (tm_vk_...) never authenticates a management route, with two exceptions:
  • GET /v1/key returns the calling API key's own status.
  • An API key can request grants for itself and read or cancel them. See Grants.
• A missing, disabled or expired management key returns 401.

Requests and responses

• Send JSON with content-type: application/json. A request body is at most 256 KiB.
• One object comes back as {"data": {...}}. A list comes back as {"data": [...]}.
• Money is in USD. Times are ISO 8601 in UTC. Ids are UUIDs.
• The audit log records every write, with the management key's prefix as the actor.

Errors

{"error": {"code": 400, "message": "limit: must be a number of USD from 0 to 10,000,000", "type": "invalid_request"}}

code is the HTTP status. type is a stable string you can match on.

Key status (API key)

{"data": {"label": "ci", "usage": 1.25, "limit": 10, "limit_remaining": 8.75, "limit_reset": "monthly",
  "expires_at": null, "is_free_tier": false, "rate_limit": {"requests": 300, "interval": "1m"}, "include_byok_in_limit": false}}

• usage is the spend in the current limit period. With no limit_reset, it is the spend over the key's life.
• While an active grant raises the key's limit, limit is the granted value. The answer then also has base_limit (the key's own limit) and grant_id.
• An expired key returns 401 key_expired.

API keys

The create and rotate responses show the raw key once. Store it then. You cannot read it again.

Create fields

Update

PATCH takes name, disabled, and every create field except workspace_id and principal_id. Send null to clear limit, expires_at, ip_allowlist or finance_category.

Rotate

Rotate takes {"grace_seconds": 0..604800} (default 0).

• With 0, the old key is disabled at once. Otherwise the old key expires after the grace period.
• The new key has rotated_from set to the old key's id.
• A disabled or expired key cannot be rotated (409).

Key object

{"key_id": "...", "name": "ci", "key_prefix": "tm_vk_3f9a1c", "workspace_id": "...", "principal_id": "...",
 "disabled": false, "limit": 10, "base_limit": 10, "grant_id": null, "limit_reset": "monthly", "limit_remaining": 8.75,
 "usage": 1.25, "include_byok_in_limit": false, "expires_at": null, "ip_allowlist": ["10.0.0.0/8"], "labels": {"team": "core"},
 "finance_category": null, "rpm_limit": 300, "created_at": "...", "created_via": "management_api",
 "rotated_from": null, "last_used_at": "..."}

While an active grant raises the key's limit, limit and limit_remaining use the granted value. base_limit is the key's own limit and grant_id names the grant. With no grant, base_limit equals limit and grant_id is null.

Management keys

Workload identities

A workload identity lets a CI job or cloud workload trade its OIDC token for a short-lived API key.

Guardrails

A guardrail is a set of rules. It applies only when you assign it to the org, a workspace, a member or a key. When several guardrails apply to a request, the strictest rule wins.

Rules

An unknown field returns 400 invalid_guardrail. A regex that can run too long returns 400 invalid_regex_pattern.

Assignments

A target has at most one guardrail. A new assignment on a target replaces the old one. The response names the replaced guardrail in replaced_guardrail_id.

Status

A status entry:

{"budget_id": "b0", "budget_key": "...", "target_kind": "key", "target_id": "...", "shared": false, "model": null, "provider": null,
 "include_byok": false, "limit_usd": 5, "base_limit_usd": 5, "grant_id": null, "spent_usd": 1.25, "remaining_usd": 3.75,
 "period": "day", "period_start": "2026-10-31T00:00:00.000Z", "resets_at": "2026-11-01T00:00:00.000Z"}

limit_usd is the limit RouterPlus enforces now. base_limit_usd is the guardrail's own limit. While an active grant raises the budget, grant_id names it and limit_usd is the granted value.

Events

Events come newest first. They never hold the matched text.

Grants

A grant is a time-boxed exception to a guardrail budget, an API key's limit, or a guardrail's model rules. A member or an API key requests a grant. An admin approves or rejects it. An approved grant applies from starts_at until expires_at. After that, the base value applies again.

In the console, open Access > Grants.

curl https://dev2-api.routerplus.com/v1/grants \
  -H "Authorization: Bearer $TM_MANAGEMENT_KEY" \
  -H "content-type: application/json" \
  -d '{"target": {"type": "key_limit", "key_id": "8c0d..."},
       "change": {"limit_usd": 50},
       "expires_at": "2026-11-09T00:00:00Z",
       "reason": "Load test for the launch"}'

note is optional, at most 500 characters. An approve or cancel applies to the next request on every gateway.

Request fields

target:

target_kind is org, workspace, member or key, as for assignments.

Rules for limits:

• change.limit_usd is a number of USD from 0 to 10,000,000. It must be more than the current limit.
• When several active grants raise the same limit, the highest one applies.
• A granted limit never goes below the base limit and never above the org's hard limit for that period.

What an API key may request:

• A key_limit grant for its own key only.
• A budget grant only on a guardrail that applies to the key. Without a target, the grant raises the budget of the most specific assignment that covers the key.
• A guardrail grant only on a guardrail that applies to the key. The grant covers that key only.
• An API key cannot set requested_by.

Grant object

{"data": {"id": "...", "status": "approved", "state": "active",
  "target": {"type": "budget", "guardrail_id": "...", "budget_id": "b0", "target_kind": "workspace", "target_id": "..."},
  "change": {"limit_usd": 50}, "base_limit_usd": 20, "workspace_id": "...",
  "starts_at": "...", "expires_at": "...", "reason": "Load test for the launch",
  "requested_by": "key:...", "approved_by": "tm_mk_...", "decided_by": "tm_mk_...", "decided_at": "...",
  "decision_note": null, "cancelled_by": null, "cancelled_at": null, "created_at": "...", "updated_at": "..."}}

• status is pending, approved, rejected or cancelled.
• state adds the time window: pending, scheduled (approved, not started), active, expired, rejected or cancelled.
• base_limit_usd is the limit when the grant was requested. It is null for guardrail grants.
• GET /v1/grants/:id adds events: each state change with action, actor, detail and created_at.

List query

Where grants show

• A response to a request under active grants has the header x-tm-grants, a comma-separated list of grant ids. A refusal under active grants has it too.
• Guardrail status shows limit_usd, base_limit_usd and grant_id per budget.
• Key reads and GET /v1/key show the granted limit, base_limit and grant_id.
• Budget alerts use the granted limits.

Notices

RouterPlus sends a notice to the org's enabled notification channels and by email when:

• a grant is requested (to org owners and admins, and admins of the grant's workspace),
• a grant is approved, rejected or cancelled (to the requester),
• an approved grant ends in less than a day (to the requester and the approver).

Hard limits

A guardrail with "overridable": false is a hard limit.

• It takes no grant. A request for a grant on it returns 409 hard_limit.
• When it is assigned to the org, each of its budgets with no model or provider caps every grant that raises a budget or key limit with the same period. A raise above the cap returns 409 hard_limit.
• Approval checks the target again. A grant whose guardrail became a hard limit, or whose raise is now above the cap, is refused with 409 hard_limit.

Grant errors

Presets

A preset is a versioned request template. Call it with "model": "@preset/<slug>" or "@preset/<slug>@<version>".

• A slug is 1 to 80 of a-z 0-9 _ -, starting with a letter or digit.
• POST returns 409 preset_exists when the slug is in use.
• PUT returns 409 version_conflict when expected_version is not the latest version.

Template

Parameters in defaults and overrides:

How a preset combines with a request

1. 01
   overrides beat the request. The request beats defaults.
2. 02
   The template's model or models replace the request's.
3. 03
   A request's provider object can only narrow the template's. only keeps the providers in both. ignore adds. allow_fallbacks: false, zdr: true and data_collection: "deny" always win. The request's sort and order apply only when the template sets none.
4. 04
   On /v1/messages, a preset sets temperature, top_p, top_k, max_tokens, stop (as stop_sequences) and stream. The other parameters apply on the OpenAI surface only.

Workspaces

• default_sort: routing_cost, price, throughput or latency.
• role: admin, member or viewer.
• The email must belong to a member of the organization.

Clone

A clone gets the source's route policy, finance category and default sort. include can list:

• guardrails: the source workspace's guardrail assignment.
• presets: the presets scoped to the source. Each copy gets the slug <slug>-copy.
• members: the workspace members.

Organization settings

Every change writes an audit row (GET /v1/audit, action org.update). Audit rows cannot be changed or deleted.

Retention

RouterPlus deletes stored records past their limit. A job runs every 30 minutes and deletes at most 5,000 rows per table per run.

retention_days can only make your org's limits shorter. RouterPlus uses the smaller of the default and retention_days.

• For eval results, it counts from when the eval finished.
• For batch files, it counts from their creation.
• For Slack threads, it counts from their last message.
• The sign-in log, OAuth codes and SSO states keep the defaults.

HIPAA mode

With hipaa_mode on:

• Every request gets an implicit org guardrail: zdr: true, data_collection: "deny", server_tools: "block". Its id in x-tm-guardrails is 00000000-0000-4000-8000-000000000074. RouterPlus refuses a model with no route that meets it.
• RouterPlus does not log requests. The org's request_log setting and any batch setting do not apply.
• The response cache and the semantic cache are off. A request that asks for the cache gets an answer with x-tm-cache: skip.
• A broadcast destination with privacy.include_content: true returns 409 hipaa_mode. RouterPlus does not send to a content destination made before HIPAA mode.
• Slack agents keep no thread memory. Each answer uses only the current message. Turning HIPAA mode on empties the stored memory.

HIPAA mode is a set of data rules. It is not a business associate agreement.

Notification channels

Channels receive budget alerts when spend crosses a threshold, and grant notices.

• thresholds are percents of a budget, integers from 1 to 100. Default: [50, 80, 100].
• Each threshold is sent once per budget period. A channel gets one alert per budget, for the highest threshold crossed.
• Alerts cover guardrail budgets and API key limits.
• The Slack URL and the webhook secret come back as "__secret__". Send "__secret__" to keep the stored value.

Broadcast destinations

Destinations receive a trace of each request.

Broadcast to storage and warehouses gives the object layout and the table DDL for the storage and warehouse kinds.

Secrets and header values never come back. They show as "__secret__". Send "__secret__" to keep the stored value.

BYOK connections

Cost reports use the discount (see GET /v1/activity/byok).

Activity

GET /v1/activity takes:

The label, session, cache and BYOK reports take from and to too.

Response rows:

• cache_hit_rate is cached input tokens divided by input tokens.
• estimated_savings_usd is the cached tokens times the difference between the input price and the cached input price.

/v1/activity/cache/advice returns these findings:

Spend forecast

GET /v1/activity/forecast projects your org's spend on RouterPlus credits to the end of the current UTC month, per group. It also gives the first day each budget or key limit is projected to run out. BYOK spend is not projected.

curl "https://demo-api.routerplus.com/v1/activity/forecast?group_by=workspace&horizon=quarter" \
  -H "Authorization: Bearer $TM_MANAGEMENT_KEY"

POST takes the same four fields as a JSON body. An unknown field returns 400.

How RouterPlus projects each group's daily spend:

low_usd and high_usd are about a 90% range. History counts from the first day with spend.

Response:

Projection fields: spent_so_far_usd (this month, today included), projected_usd, low_usd, high_usd, method, history_days, history_too_short, and periods (per month: period, start, end, spent_usd, projected_usd, low_usd, high_usd).

A crossing:

Scenarios

A scenario changes the history that RouterPlus fits the projection to. It never changes spend so far.

curl https://dev2-api.routerplus.com/v1/activity/forecast \
  -H "Authorization: Bearer $TM_MANAGEMENT_KEY" \
  -H "content-type: application/json" \
  -d '{"horizon": "month", "scenario": [{"scale": 2}, {"swap": {"from": "google/gemini-3.1-pro", "to": "google/gemini-3.5-flash"}}]}'

scenario in the response has:

• changes: each change. A swap adds provider, cost_ratio and tokens_basis_days (14), and a note when a had no spend in the last 14 days.
• total: the projection fields and delta_usd, the change from the base projection.
• data: per group, projected_usd, low_usd, high_usd, delta_usd and method.
• crossings: the crossings under the scenario.

A swap returns 400 when the target model is not allowed by your org guardrails, has no catalog price on an allowed route, or when one model is swapped twice.

Savings

GET /v1/activity/savings reprices your traffic on RouterPlus credits for a window. For each model and provider, it shows what the same tokens would cost on a cheaper route of the same model, and on cheaper models of a similar quality tier. BYOK traffic is left out.

curl "https://demo-api.routerplus.com/v1/activity/savings?days=30" \
  -H "Authorization: Bearer $TM_MANAGEMENT_KEY"

The rules:

• A suggestion must save at least 1% of the baseline.
• A suggestion meets the guardrails of the keys that sent the traffic.
• A model of a similar tier has an Artificial Analysis intelligence index at most 3 points below the current model's. A model with no score is not compared. The answer counts those models.
• Each row lists at most 3 other models.
• The figures reprice token counts. They do not show that answers would be as good. Each row with other models includes the body of an eval to test them.

Response:

A data row:

Labels

Label a request in one of three ways:

• The header x-tm-labels: team=search,feature=autocomplete (also x-routerplus-labels).
• The body field trace: an object of string values. RouterPlus removes it before the request reaches a provider.
• Labels set on the key (PATCH /v1/keys/<id> {labels}).

Rules:

• For one name, a request's own label wins over the key's.
• At most 20 labels. Names are lowercase letters, digits, _, . and -, up to 40 characters. Values are up to 200 characters.
• RouterPlus adds task (the kind of request).
• x-tm-finance-category sets the request's finance category.

Security report

Each key also has last_used_at, created_at, expires_at and usage_30d_usd.

Audit log

• source is governance, identity, connection or routing_policy.
• Query: since, until, action, actor, limit (at most 500, default 100).
• Grant changes write the actions grant.request, grant.approve, grant.reject and grant.cancel.

SLA report

Without month, it reports the current month up to now. A month in the future returns 400.

The report counts requests. A request's result is its last attempt:

{"data": {"month": "2026-09", "period_start": "2026-09-01T00:00:00.000Z", "period_end": "2026-10-01T00:00:00.000Z", "complete": true,
  "requests": {"total": 75, "good": 57, "buyer_caused": 4, "upstream_quota": 1, "failed": 13, "pending": 1},
  "availability_percent": 82.6667,
  "degraded": {"bucket_minutes": 5, "min_requests": 20, "failed_percent_over": 5, "minutes": 5, "period_minutes": 43200,
    "minutes_percent_available": 99.9884, "buckets": [{"start": "2026-09-10T12:05:00.000Z", "requests": 20, "failed": 2}]},
  "credit": null}}

Configuration backup

The export:

{"version": 1, "exported_at": "...", "guardrails": [...], "presets": [...], "workspaces": [...],
 "notification_channels": [...], "broadcast_destinations": [...]}

Secrets are written as "__secret__" unless you add ?include_secrets=true.

Import modes:

A "__secret__" value keeps the stored secret. RouterPlus skips a record that needs a secret you did not send.

The response:

{"data": {"mode": "merge", "dry_run": false,
  "counts": {"workspaces": {"created": 1, "updated": 0, "deleted": 0}, "guardrails": {...}, "assignments": {...},
             "presets": {...}, "notification_channels": {...}, "broadcast_destinations": {...}},
  "skipped": [{"kind": "notification_channels", "ref": "slack:...", "reason": "..."}]}}