Common Scenarios
The examples below assume the following variables are set:
export XSI_BASE_URL="https://api.example.com"
export OWNER_KEY="sk-Xvs..." # Tenant owner key: manages upstreams and tenant configuration
export ADMIN_KEY="sk-Xvs..." # Manager key: manages sub-accounts (may be the same as OWNER_KEY)Multiple upstreams and failover
Goal: OpenAI as primary and Azure OpenAI as backup; Claude goes through Anthropic; switch automatically when an upstream fails.
# 1. Add upstream keys: OpenAI β Level 1, Anthropic β Level 2, Azure β Level 4
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "openai-a", "Level": 1, "Provider": "https://api.openai.com", "SecretKey": "sk-proj-..."}'
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "openai-b", "Level": 1, "Provider": "https://api.openai.com", "SecretKey": "sk-proj-..."}'
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "anthropic", "Level": 2, "Provider": "https://api.anthropic.com", "SecretKey": "sk-ant-..."}'
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "azure", "Level": 4, "Provider": "https://my-res.openai.azure.com", "SecretKey": "...",
"config": {"provider_type": "azure", "model_mapping": {"gpt-6.2-sol": "gpt-prod"}}}'
# 2. Routing and failover
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"LEVEL_MAPPER": "gpt*=1, claude*=2", "SWITCH_OVER": "1=4"}'Result: the two OpenAI keys in the same Level are used in rotation and serve as retries for each other. A key that returns a status in STATUS_CODES (default 429, 401, 402, 408, 503, 524) is put to sleep automatically. If the whole Level keeps failing, accounts with Gear > 0 temporarily fail over to Level 4 and switch back automatically after 1 hour.
Allocating credit to a team
# Create a sub-account for the R&D team with Β₯2,000 of initial credit, allowed to create its own sub-accounts
curl -X POST "$XSI_BASE_URL/x-users" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"Email": "[email protected]", "Name": "rd-team", "CreditGranted": 2000, "UserLimit": 100}'
# Add more credit, valid for 90 days
curl -X PUT "$XSI_BASE_URL/x-users/rd-team" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"CreditGranted": 500, "Days": 90}'
# Grant Β₯50 to every Level 2 descendant (preview first)
curl -X POST "$XSI_BASE_URL/x-users/batch-credit" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"CreditGranted": 50, "Filters": {"level": 2}, "DryRun": true}'Budgets and rate limits
Credit limits and rate limits apply only to Role 2 (strict) and Role 3 (subscription) accounts. Role is set by the tenant owner:
curl -X PUT "$XSI_BASE_URL/x-users/rd-team" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Role": 2, "DailyLimit": 200, "HardLimit": 3000, "RPM": 120, "TPM": 2000000}'Set tenant-wide model-level limits for expensive models (the model name must exactly match the upstream model name):
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"MODEL_LIMITS": "{\"claude-opus-5-5\": {\"rpm\": 20, \"tpd\": 50000000}}"}'Restricting access
curl -X PUT "$XSI_BASE_URL/x-users/42" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{
"AllowModels": "-*,+gpt-6*,+claude-sonnet-5-5",
"AllowIPs": "-*,+203.0.113.0/24,+10.0.0.5",
"Resources": "-*,+/v1/chat/completions,+/v1/responses,+/v1/embeddings"
}'-*,+a,+b fully replaces the scope with the listed items; a list without prefixes is appended to the existing scope. Apply a model allowlist recursively to an entire branch (preview first):
curl -X PUT "$XSI_BASE_URL/x-users/rd-team" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"Scope": "tree", "AllowModels": "-*,+gpt-6*,+claude-sonnet-5-5", "DryRun": true}'Seamless model upgrades
Give applications a stable alias and change only the mapping when you upgrade. Accounts cache alias resolutions, so to make a change take effect immediately for accounts already using the alias, use ModelMapper in POST /x-conf (synced to all descendants); PUT /x-config only updates the tenant configuration:
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"MODEL_MAPPER": "gpt-latest=gpt-6.2-sol, claude-latest=claude-sonnet-5-5"}'Fall back to a backup model automatically when a model fails:
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"MODEL_FAILOVER": "claude-opus-5-5=claude-sonnet-5-5"}'Custom pricing
Override an existing model or add a new one (Rates must be specified):
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"PRICING": "{\"ChatPricing\": {\"qwen3-coder-local\": {\"InputText\": 1, \"OutputText\": 4, \"Rates\": 1}}}"}'
curl "$XSI_BASE_URL/x-pricing" -H "Authorization: Bearer $OWNER_KEY" | jq '.data[] | select(.custom)'Connecting self-hosted models
OpenAI-compatible services such as vLLM, SGLang, and Ollama can be added directly as providers:
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "vllm-local", "Level": 5, "Provider": "http://10.0.0.20:8000", "SecretKey": "local-token-at-least-20chars"}'
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"LEVEL_MAPPER": "gpt*=1, claude*=2, qwen3-coder-local=5"}'Then set a price for qwen3-coder-local as described in the previous section, and it can be called, limited, and billed like any other model. PUT /x-config replaces LEVEL_MAPPER in full, so always specify the complete mapping.
API resale
root (operator)
ββ Channel A: Rates 1.0
β ββ Customer A1: Rates 1.3 β the 30% margin goes to Channel A
ββ Channel B: Rates 1.1, Factor 0.9# Create a customer account with Channel A's key; Rates must not be lower than the channel's own
curl -X POST "$XSI_BASE_URL/x-users" -H "Authorization: Bearer $CHANNEL_A_KEY" -H "Content-Type: application/json" \
-d '{"Email": "[email protected]", "CreditGranted": 1000, "Rates": 1.3}'When Channel A transfers Β₯1,000 of credit to the customer, Channel A itself is debited 1000 Γ· 1.3 Γ 1.0 β 769.23 CNY.
Usage and rankings
curl "$XSI_BASE_URL/x-bill?days=30" -H "Authorization: Bearer $ADMIN_KEY" \
| jq '.usage_users[] | {name, total_credit_used, top_cost_model}'Sending notifications and rotating keys
# Notify a sub-account
curl -X POST "$XSI_BASE_URL/x-news/42" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"title": "Credit reminder", "content": "You have used 80% of your credit for this month.", "days": 7}'
# Rotate your own key
curl -X POST "$XSI_BASE_URL/x-self" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d "{\"confirm\": \"$(date +%F)-ROTATE-SELF\"}"