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\"}"