Talk to us
Shimmy docs

Admin API

Platform admins manage the model catalog (prices, capabilities, strengths) and custom providers (whole OpenAI-compatible vendors) at runtime. Every write takes effect on the next request — no redeploy. The web UI at /optimizer/admin drives these endpoints; they are also callable directly, which is what the bulk catalog importer uses.

Model catalog

The catalog is the price-and-capability source of record. Routing, tiers and the savings meter all read from it; an edit reprices the ladder live.

RoutePurpose
GET /v1/admin/catalogEvery model with its full profile
PUT /v1/admin/catalog/:modelCreate or update one model
DELETE /v1/admin/catalog/:modelRemove a model
POST /v1/admin/catalog/:model/disabledToggle routing off without deleting the row

A model profile:

{
  "model": "kimi-k3",
  "provider": "moonshot",
  "input_per_mtok": 0.15,
  "output_per_mtok": 0.60,
  "cached_input_per_mtok": 0.04,
  "cache_write_multiplier": 1.25,
  "input_modalities": ["text", "image"],
  "output_modalities": ["text"],
  "tools": "full",
  "structured_outputs": true,
  "reasoning_efforts": [],
  "context_length": 200000,
  "max_output_tokens": 8192,
  "search_only": false,
  "moderation_only": false,
  "strengths": { "code": 0.7, "reasoning": 0.6 },
  "disabled": false
}

Disable without deleting — keeps the row and its accumulated evidence, just drops it from routing:

curl -X POST https://rfa-labs.com/v1/admin/catalog/kimi-k3/disabled 
  -H "Authorization: Bearer $ADMIN_KEY" 
  -H "Content-Type: application/json" 
  -d '{ "disabled": true }'

Custom providers

Register any OpenAI-compatible vendor (Moonshot, DeepSeek, Groq, …) at runtime. Models added under it route immediately and join the cross-vendor failover chain.

RoutePurpose
GET /v1/admin/providersRegistered vendors (key_set, never the key itself)
PUT /v1/admin/providers/:nameRegister or update a vendor
DELETE /v1/admin/providers/:nameRemove a vendor
POST /v1/admin/providers/:name/testA live call confirming the base URL + key work

Register a vendor — the name is a lowercase id you choose, the base URL must include the vendor’s version suffix, and the key is encrypted at rest and never returned:

curl -X PUT https://rfa-labs.com/v1/admin/providers/moonshot 
  -H "Authorization: Bearer $ADMIN_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "base_url": "https://api.moonshot.ai/v1",
    "api_key": "sk-vendor-…",
    "enabled": true
  }'

Then confirm it works before routing real traffic:

curl -X POST https://rfa-labs.com/v1/admin/providers/moonshot/test 
  -H "Authorization: Bearer $ADMIN_KEY"

Next