Tera Router
API Reference

Dashboard REST API

Reference for the REST endpoints that manage keys, providers, chains, guardrails, and usage.

All endpoints below live on the same server as the gateway (default http://localhost:8080) and power the dashboard UI. Great for automation and integrations.

For the inference endpoints, see the Gateway API section.

Authentication

# sign in
curl -X POST http://localhost:8080/v1/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{ "email": "admin@tera.local", "password": "..." }'
{
  "data": {
    "uid": "…",
    "email": "admin@tera.local",
    "access_token": "…",
    "refresh_token": "…",
    "expires_in": 3600
  }
}
  • Access tokens last 1 hour; refresh tokens 30 days and are rotated on every renewal.
  • Send the token in the Authorization: Bearer <access_token> header.
  • POST /v1/auth/sign-out revokes all session tokens.

Response envelope

ShapeJSON shape
Single resource{"data": …, "metadata": …, "message": …}
List{"data": […], "metadata": {"total", "offset", "limit"}}
Delete{"message": "…"}
Error{"message": "…"}
Validation error{"message": "…", "errors": {…}} (422)

Pagination uses the offset (0-based) and limit (default 10, max 100; /v1/accounts and /v1/keys allow up to 1000) query parameters.

List filters

The dashboard sends its searches, filters and pages to the server; nothing is filtered in the browser. Every parameter is optional, and total in the metadata counts the rows that match before paging. search is case-insensitive.

EndpointQuery parameters
GET /v1/accountsprovider (slug), auth_kind (api_key, oauth, none), search (label or key fingerprint)
GET /v1/keyssearch (name, key preview or plan), status (active, disabled), sort (newest, oldest, name). The metadata adds total_all, total_active and total_disabled.
GET /v1/chainssearch (name, fallback model or a step's provider/model), strategy, enabled (true, false), provider (a step or the fallback uses it), health_window (attaches each chain's health), health (healthy, degraded, down, unknown). Paged only when limit is sent.
GET /v1/aliasessearch (name or group), status (active, inactive)
GET /v1/plansPaged only when limit is sent. The metadata adds keys_assigned, hard_cutoff and unused over every plan.
GET /v1/budgets/statusOrdered closest to the limit first; each row carries scope_name. Paged only when limit is sent. The metadata adds past_alert, exhausted and blocking over every budget.
GET /v1/quotarange, search (provider or account name), provider, status (active, paused, attention), quota_state, sort (attention, name, requests, cost)
GET /v1/usage/modelsrange, search, provider, sort (model, requests, tokens, cost, latency, pricing), order (asc, desc)
GET /v1/usage/providersrange
GET /v1/usage/requestsrange, search (model, key name, client, row id or provider), status (failed). The metadata adds total_all and total_failed.
GET /v1/provider-healthtab (providers, models, chains, probes) returns only that table, status (healthy, degraded, down), offset, limit. counts covers every row and total the rows that match.
GET /v1/providerssearch (name or slug), capability, empty (true keeps connected custom providers with no account), offset, limit (page the connected list)
GET /v1/mediacapability, search (name or slug). The answer also splits the matches into connected and available.
GET /v1/portal/:tokenoffset, limit page the request log (recent); recent_total counts the window.

Endpoints

Auth

MethodPathNotes
POST/v1/auth/sign-inSign in, receive tokens
POST/v1/auth/refreshRotate refresh token
GET/v1/auth/meCurrent user profile
POST/v1/auth/sign-outRevoke all session tokens
POST/v1/auth/totp/setupIssue a fresh TOTP secret to enroll (nothing stored yet)
POST/v1/auth/totp/enableTurn on two-factor auth; needs password + a code from that secret
POST/v1/auth/totp/disableTurn it off; needs password + a current code
GET/v1/auth/sessionsActive sign-in sessions; current marks the caller's
DELETE/v1/auth/sessions/:idRevoke one session; its tokens stop working at once
GET/v1/auth/passkeysYour passkeys
POST/v1/auth/passkeys/register/beginStart adding a passkey; needs password (+ TOTP)
POST/v1/auth/passkeys/register/finishVerify and store the browser's new credential
DELETE/v1/auth/passkeys/:idRemove a passkey
POST/v1/auth/passkey/beginPublic: start a passkey sign-in
POST/v1/auth/passkey/finishPublic: verify the passkey, receive tokens

Passkey calls read the Origin header: the passkey's RP ID is that origin's host, so the dashboard must be on https or http://localhost, under a host name (not an IP), and a passkey works only on the host it was added on. Each begin returns ceremony_id and options (WebAuthn JSON for PublicKeyCredential.parseCreationOptionsFromJSON / parseRequestOptionsFromJSON); send finish the same ceremony_id and credential (the browser's credential.toJSON()) within 5 minutes. A passkey sign-in skips the password and TOTP code.

Keys

MethodPathNotes
GET / POST/v1/keysList / create keys
GET / PATCH/v1/keys/:idDetail / update key
POST/v1/keys/:id/revealPlaintext; needs password (+ TOTP), audited
POST/v1/keys/:id/rotateNew secret, old one revoked; needs password (+ TOTP), audited
DELETE/v1/keys/:idDelete key

Plans

MethodPathNotes
GET / POST/v1/plansList / create
PATCH/v1/plans/:idUpdate
DELETE/v1/plans/:idDelete

Playground

MethodPathNotes
GET/v1/playground/modelsEvery model the playground can address: active catalog models of providers with a usable account (provider/model), then aliases and chains
POST/v1/playground/chatOpenAI chat completion routed exactly like gateway traffic (aliases, chains, fallback, stream)

The playground authenticates with the dashboard JWT, not an API key. Its usage is metered and budgeted like any other traffic but attributed to no key. Responses carry X-TeraRouter-Provider and X-TeraRouter-Model, naming the target the request landed on.

Routing

MethodPathNotes
GET / POST/v1/chainsList / create chains
GET/v1/chains/:idChain detail
PUT/v1/chains/:idUpdate chain
DELETE/v1/chains/:idDelete chain
GET / PUT / DELETE/v1/models/aliasManage alias pools

Providers & accounts

MethodPathNotes
GET/v1/providersConnected/available provider summary
GET / POST/v1/custom-providersCustom providers
GET / PATCH / DELETE/v1/custom-providers/:idManage custom provider
GET/v1/custom-providers/by-slug/:slugResolve a custom provider by slug
POST/v1/custom-providers/bulk-deleteDelete {"ids": [...]}; providers that still have an account are skipped
GET / PATCH/v1/custom-providers/:id/modelsStored model catalog (search, state, offset, limit) / toggle models active or disabled
POST/v1/custom-providers/:id/models/syncFetch the catalog from the provider's upstream model list
POST/v1/custom-providers/:id/models/testSend one test chat to a model
GET / PATCH/v1/providers/:id/modelsSame catalog view for catalog providers (:id is the slug)
POST/v1/providers/:id/models/syncRefresh a catalog provider's models
POST/v1/providers/:id/models/testSend one test chat to a model
GET / POST/v1/accountsList / add accounts
POST/v1/accounts/bulkAdd one API-key account per entry of api_keys; keys already stored are returned as skipped
GET / PATCH / DELETE/v1/accounts/:idManage account
POST/v1/accounts/:id/testTest account connection
POST/v1/accounts/testTest a key before saving it; nothing is stored
GET/v1/accounts/:id/quotaAccount quota
GET / PUT/v1/providers/:id/routingAccount strategy (:id is the provider slug)
POST/v1/providers/:id/accounts/exportDownload the provider's accounts as a file encrypted with passphrase (:id is the slug)
POST/v1/providers/:id/accounts/importAdd the accounts of an export file ({"passphrase", "backup"}); duplicates are skipped
POST/v1/oauth/:provider/authorizeStart a PKCE sign-in (anthropic, codex); returns the URL to open
POST/v1/oauth/:provider/exchangeExchange the returned code and save it as an OAuth account

The model test endpoints take {"model", "messages", "stream"}. With "stream": true the answer is server-sent events: {"type": "delta", "text": …} per text fragment, then one {"type": "done", "result": …} carrying the same result the non-streaming call returns. A streamed test is capped at 2 minutes.

Budgets & usage

MethodPathNotes
GET / POST/v1/budgetsList / create budgets
GET/v1/budgets/statusRunning usage per budget
PUT / PATCH / DELETE/v1/budgets/:idManage budget
GET/v1/usage/telemetryFull Usage page payload
GET/v1/usage/modelsModel accounting rows: searched, sorted and paged
GET/v1/usage/providersProvider accounting rows, paged
GET/v1/usage/requestsRequest log of the range: searched, filtered and paged
GET/v1/usage/activityRequests per UTC day for the last 53 weeks, with per-model counts
GET/v1/provider-healthPer-provider, per-model, and per-chain health (?window=5m|15m|1h|6h|24h|7d|30d|90d, default 15m)
GET/v1/quotaActive quotas
GET/v1/quota/overviewQuota summary
PATCH / DELETE/v1/quota/:idPause / delete quota

Proxy pools

MethodPathNotes
GET / POST/v1/proxy-poolsList / create pools
POST/v1/proxy-pools/bulkBatch import {"pools": [...]}, all or nothing (max 500)
POST/v1/proxy-pools/bulk-deleteDelete {"ids": [...]}, skipping ones already gone
POST/v1/proxy-pools/relay-scriptGenerate a relay script ({"kind": "cloudflare"} or "local")
POST/v1/proxy-pools/health-checkCheck all pools
PATCH / DELETE/v1/proxy-pools/:idEdit / delete pool
POST/v1/proxy-pools/:id/testTest one pool

A pool URL is normally an HTTP/HTTPS/SOCKS forward proxy. A URL of the form relay+https://:<secret>@host is a fetch relay instead: the gateway sends each upstream call to the relay with the real target in X-Tera-Relay-Target and the secret in X-Tera-Relay-Secret. The relay-script endpoint returns a ready-to-deploy Cloudflare Worker or Node script with a fresh secret, plus the pool URL to register (replace RELAY_HOST).

Overrides

MethodPathNotes
GET / POST / DELETE/v1/model-pricing-overridesOverride per-model pricing
GET / PUT/v1/capability-overridesOverride model capabilities
DELETE/v1/capability-overrides/:provider/:modelDelete one override
POST/v1/capability-overrides/resetReset all

Guardrails

MethodPathNotes
GET/v1/guardrailsPolicy summary
POST/v1/guardrailsCreate policy
PUT/v1/guardrails/settingsGlobal guardrail settings
POST/v1/guardrails/evaluateTest policies (dry run)
PATCH / DELETE/v1/guardrails/:idManage policies

IP blocks

MethodPathNotes
GET / POST/v1/ip-blocksActive blocks, manual and automatic / add a permanent block
DELETE/v1/ip-blocks/:idLift a block

A block whose range covers your own address is refused, so you cannot lock yourself out.

Restricted access

MethodPathNotes
GET / PUT/v1/restricted-accessCurrent allowlist period / replace it (whole)

Body: enabled, start_date / end_date (YYYY-MM-DD, inclusive), start_time / end_time (HH:MM, repeats daily, may wrap past midnight), timezone (IANA, empty means UTC) and allowed_ips (addresses or CIDR ranges). Empty dates or times leave that side open. While the period is running, every path except /health answers 403 forbidden to addresses off the list; loopback always passes. Enabling it without your own address on the list is refused.

Backup & import

MethodPathNotes
POST/v1/backup/config/exportJSON config backup; needs password (+ TOTP)
POST/v1/backup/config/importRestore a config backup; each table in it replaces the live one
GET/v1/backup/databaseLive database file info
POST/v1/backup/database/downloadSQLite snapshot; needs password (+ TOTP)
POST/v1/backup/database/restoreReplace the database with an uploaded SQLite file (multipart field file); needs password (+ TOTP)
POST/v1/import/:sourceImport a 9router or omniroute JSON backup

Both restores write a safety copy of the current database first. A restored database must pass an integrity check and carry a schema no newer than the server's; an older schema is migrated up. The database restore re-authenticates like the download: send the multipart fields password and, once the server answers { "totp_required": true }, otp next to file. It refuses a file with no user accounts, with broken references, or whose credentials were sealed with a different APP_SECRET. Imports are additive: rows that already exist are kept and the backup's copy is skipped, so re-running an import is safe.

Tunnels

MethodPathNotes
GET/v1/tunnels/cloudflareinstalled, running, and the quick tunnel url
POST/v1/tunnels/cloudflare/enableStart a quick tunnel (remembered across restarts)
POST/v1/tunnels/cloudflare/disableStop it and keep it off
GET/v1/tunnels/tailscaleinstalled, logged_in, running, and the tailnet url
POST/v1/tunnels/tailscale/enabletailscale serve --bg this server over HTTPS
POST/v1/tunnels/tailscale/disableRemove this server's serve mapping

Enabling and disabling are audit-logged. See Remote access.

Misc

MethodPathNotes
GET / PATCH/v1/settingsRouter settings (timeout, round-robin, etc.)
GET/v1/brandingPublic (no auth): display name, tagline, logo, favicon
GET / POST/v1/skillsList / create skills
PATCH/v1/skills/:idSwitch gateway injection (enabled)
DELETE/v1/skills/:idDelete skill
GET/v1/auditAudit trail, newest first. Query: search, outcome (success/failed), category, offset, limit
GET/v1/audit/statsTotals, action categories, writes and lost writes since start
POST/v1/audit/verifyWalk the hash chain and report the first row that does not match
GET/v1/audit/exportWhole trail as JSON Lines (application/x-ndjson)
GET / DELETE/v1/consoleRing buffer log (1,000 entries; ?after=<id> returns only newer lines, with metadata.first and metadata.session) / clear
GET/v1/system/statsHost & process metrics
GET/v1/system/statusGateway status card: status, version, process uptime, listen address, database
GET/v1/mediaCatalog providers grouped by non-chat capability
GET/v1/endpointsBase URL and route reference for the Endpoints page
GET/v1/cli-tools/:idOne tool's install status and a preview of its config files. Query: base_url, model (the key is a placeholder)
POST/v1/cli-tools/:id/applyWrite the gateway URL, a key and the model into the tool's config files on the host. Body: base_url, model, and key_name (create a dedicated key) or api_key (paste an active key)
GET/healthServer health (no auth)
GET/skills/:slug/SKILL.mdPublic skill document an agent fetches by URL (no auth)

The key reveal and rotate, both backup downloads, the accounts export, and a PATCH /v1/accounts/:id that changes metadata.base_url re-authenticate: send "password", and when two-factor auth is on the server answers { "totp_required": true } until you resend with "otp". Wrong passwords or codes return 422 and count toward the IP block, like failed sign-ins.

On this page