Routing keys

GET  /v1/organizations/routing-keys
POST /v1/organizations/routing-keys

Auth: account token. rk_ or sk_ can list; creating needs sk_.

List

curl https://api.proxyllm.ai/v1/organizations/routing-keys \
  -H "Authorization: Bearer rk_your_readonly_token"

{
  "routing_keys": [
    {
      "id": "5e2f8c1a-...",
      "label": "client-acme",
      "key_prefix": "pllm_h3Xk9aQ…1a2b",
      "mode": "fallback",
      "classifier_provider": null,
      "classifier_model": null,
      "classifier_instructions": null,
      "classifier_credential_id": null,
      "monthly_budget_usd": 50,
      "budget_excludes_seats": true,
      "current_month_spend_usd": 12.4,
      "current_month": "2026-07",
      "last_used_at": "2026-07-03T09:12:00.000Z",
      "revoked_at": null,
      "created_at": "2026-06-01T10:00:00.000Z",
      "updated_at": "2026-07-01T10:00:00.000Z",
      "providers": [
        {
          "provider": "codex",
          "model": null,
          "credential_id": null,
          "codex_session_id": "8a1b...",
          "bridge_instance_id": null,
          "category_key": null,
          "category_description": null,
          "fallback_to_default_model": true,
          "reasoning_effort": "low",
          "verbosity": null,
          "service_tier": null
        }
      ]
    }
  ]
}

providers is the key’s lane list in order. The raw key is never returned here; only its display prefix.

Create

curl -X POST https://api.proxyllm.ai/v1/organizations/routing-keys \
  -H "Authorization: Bearer sk_your_account_token" \
  -H "Content-Type: application/json" \
  -d '{"label": "client-acme", "monthly_budget_usd": 50}'

Request body:

Field	Type	Notes
label	string	Up to 60 characters. Defaults to "default".
mode	"fallback" or "classifier"	Defaults to fallback.
monthly_budget_usd	number	Optional cap; omit or send a non-positive number for no budget.
budget_excludes_seats	boolean	Default true: subscription-seat traffic does not count toward the budget.
classifier_provider	string	Required in classifier mode; a provider you have a saved API key for.
classifier_model	string	Required in classifier mode.
classifier_instructions	string	Required in classifier mode, at least 10 characters.
classifier_credential_id	string	Optional. Id of one of your saved keys for classifier_provider; it runs the classifier. Omit to use your oldest saved key for that provider.

Response: the created key in the same shape as the list, plus the raw key, returned once:

{
  "routing_key": {
    "id": "5e2f8c1a-...",
    "label": "client-acme",
    "key_prefix": "pllm_h3Xk9aQ…1a2b",
    "mode": "fallback",
    "monthly_budget_usd": 50,
    "budget_excludes_seats": true,
    "current_month_spend_usd": 0,
    "providers": []
  },
  "raw_key": "pllm_h3Xk9aQm2vL8pTw4rYc6nB0dFgJ5sZq1"
}

Store raw_key immediately; it cannot be fetched again. A key created without providers has no lanes yet; wire them over this API (below) or under Routing keys in the dashboard.

Wiring lanes

Pass mode and a providers array (up to 5) on POST to create and wire in one call, or rewire an existing key:

PATCH https://api.proxyllm.ai/v1/organizations/routing-keys?id=<routing_key_id>

{
  "mode": "fallback",
  "providers": [
    { "provider": "codex", "model": "flagship", "codex_session_id": "...", "reasoning_effort": "high", "verbosity": "low", "service_tier": "priority" },
    { "provider": "openai", "model": "gpt-5", "credential_id": "...", "reasoning_effort": "medium" }
  ]
}

Lane settings, all optional:

Field	Lanes	Values
reasoning_effort	codex, openai	none, low, medium, high, xhigh, max
verbosity	codex	low, medium, high
service_tier	codex	default, priority
fallback_to_default_model	any	true (default) or false

On PATCH, a lane setting you leave out keeps the value the key already has for that lane (matched by provider and the credential, session, or bridge it names); send null to clear it.

codex lanes name one of your connected Codex sessions, bridge lanes name a registered bridge, and API-key providers (openai, anthropic, openrouter, …) name a saved provider key. Every referenced id must belong to you. Find the ids with:

GET https://api.proxyllm.ai/v1/organizations/routing-keys?include=lanes

which adds a lanes object (codex_sessions, bridges, credentials) to the list response. PATCH also accepts label, monthly_budget_usd, revoked (true/false), and regenerate: true (returns a fresh raw_key once).

Errors

Status	Code	When
400	bad_request	Invalid config, a referenced lane is not yours, or classifier fields missing.
401	(none)	No token sent.
401	invalid_account_token	Unknown or revoked token.
402	payment_required	No active membership yet (agent signup).
403	read_only_token	POST or PATCH with an rk_ token.
405	method_not_allowed	Method other than GET, POST, or PATCH.
500	server_error	The database write failed.