Tenant Configuration API

Tenant Configuration API

Each tenant (owner) has its own configuration, stored in Redis and automatically synchronized across all XSI instances (via publish/subscribe notifications, plus a version check every 3 minutes). All endpoints require the caller to be a tenant owner and act only on the caller's own tenant.

export XSI_BASE_URL="https://api.xsirouter.com"   # Or your own API domain
export XSI_API_KEY="sk-Xvs..."                     # Key of the tenant owner
EndpointPurpose
GET/PUT/POST/DELETE /x-configRead, write in full and reset tenant configuration (recommended)
GET/POST /x-confView runtime state, apply incremental mapping changes synced to sub-accounts, and run operational commands
GET /x-infoLook up detailed information for any account in your tenant

Configuration keys

KeyFormatDescription
MODEL_MAPPERfrom=to,from2=to2Model rewriting; from may contain * wildcards; circular references are detected on write
LEVEL_MAPPERmodel=level,...Selects the key pool group by model; model may contain *; when several wildcards match, the longest wins
SWITCH_OVERfromLevel=toLevel,...Group-level failover; self-references and cycles are rejected
MODEL_FAILOVERmodel=fallback,...Model-level failover replacement; fallback must be a priced model; circular references are detected
STICKY_LEVELS1,2,3When global sticky scheduling is off (STICKY_SCHEDULER=false), only these Levels use sticky sessions; * clears the list
MODEL_LIMITSJSONModel-level limits {"<upstream model name>": {"rpm": N, "rph": N, "rpd": N, "tpm": N, "tph": N, "tpd": N}}; * clears all, -a,b removes the given models
PRICINGJSONPrice overrides with the same structure as api/pricing.json, see below
RESOURCESPath listTenant-level resource allowlist. In the current version it is only stored and displayed; the proxy enforces the account-level Resources
XAI_MAILEmailTenant notification recipient (unknown models, failover, payment notifications, etc.)
EMAIL_SMTP, EMAIL_PORT, EMAIL_AUTH, EMAIL_PASS, EMAIL_SENDERStringTenant's own SMTP; the deployment's default email configuration is used when not set. EMAIL_PASS is write-only
SIGNUP_ALLOW_DOMAINS, SIGNUP_DENY_DOMAINSDomain rulesEmail domain allowlist and denylist for self-service signup; readable and writable by root only

Separators: ,, ; or the full-width Chinese comma ,. For semantic details, see Routing and Failover and Billing and Pricing.

Read configuration

curl "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $XSI_API_KEY"
{
  "success": true,
  "oid": 1,
  "configs": {
    "MODEL_MAPPER": {"gpt-latest": "gpt-6.2-sol"},
    "MODEL_FAILOVER": {},
    "LEVEL_MAPPER": {"gpt*": 1, "claude*": 2},
    "SWITCH_OVER": {"1": 3},
    "STICKY_LEVELS": "",
    "STICKY_SCHEDULER": true,
    "RESOURCES": {},
    "MODEL_LIMITS": {"gpt-6.2-sol": {"rpm": 60, "rph": 3600, "rpd": 86400, "tpm": 1000000, "tph": 999999999999999999, "tpd": 999999999999999999}},
    "PRICING": "",
    "XAI_MAIL": "[email protected]",
    "EMAIL_PORT": "465",
    "EMAIL_SMTP": "smtp.example.com",
    "EMAIL_AUTH": "[email protected]",
    "EMAIL_SENDER": "XSI <[email protected]>"
  }
}
  • STICKY_SCHEDULER reflects the global environment variable and is read-only.
  • PRICING is returned as a raw JSON string.
  • Email fields that are not configured return the deployment defaults.

Write configuration

PUT and POST are equivalent. The request body is {key: string value}, and each key is replaced as a whole:

curl -X PUT "$XSI_BASE_URL/x-config" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "LEVEL_MAPPER": "gpt*=1, claude*=2, deepseek*=3",
    "MODEL_MAPPER": "gpt-latest=gpt-6.2-sol",
    "SWITCH_OVER": "1=3",
    "MODEL_LIMITS": "{\"gpt-6.2-sol\":{\"rpm\":60,\"tpm\":1000000}}"
  }'
{"success": true, "updated": {"LEVEL_MAPPER": "gpt*=1,claude*=2,deepseek*=3"}, "message": "Config updated successfully"}
  • Each key is validated individually; valid keys are written in a single atomic operation.
  • If some keys are invalid, the API still returns 200 but with success set to false and the errors in errors; if all keys are invalid, it returns 400.
  • Common errors: Invalid config key, Circular reference detected: a β†’ b β†’ a, Invalid switch configuration: ..., Invalid MODEL_LIMITS format: ..., Invalid sender address, Only root can modify this config.

PRICING

The value of PRICING has the same structure as api/pricing.json (top-level ChatPricing, ImgPricing, VideoPricing, AudioPricing, RerankPricing, CallPricing, FineTuningPricing). It replaces the system default price per model as a whole entry and can also add new models:

{
  "ChatPricing": {
    "gpt-6.2-sol": {"InputText": 2, "CachedText": 0.1, "CacheWrite": 2.5, "OutputText": 10, "Rates": 8}
  }
}
  • Raw text ≀ 128 KiB, ≀ 1024 entries; unknown fields are rejected; values must be finite and non-negative.
  • Whole-entry replacement means any field not written in the override entry becomes 0. Always include Rates, or the model's token cost will be 0.
  • For field meanings, see Billing and Pricing.

Signup domain rules (root only)

{"SIGNUP_ALLOW_DOMAINS": "example.com, *.example.org", "SIGNUP_DENY_DOMAINS": "mailinator.com"}
  • *.example.org or .example.org matches all subdomains as well as example.org itself; @ and a trailing . are stripped.
  • The allowlist is checked first (when non-empty, the domain must match), then the denylist.

Reset to defaults

curl -X DELETE "$XSI_BASE_URL/x-config" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["MODEL_FAILOVER", "STICKY_LEVELS"]}'

Response: {"success": true, "deleted": ["MODEL_FAILOVER", "STICKY_LEVELS"], "message": "Config deleted successfully"}.

Runtime control /x-conf

View

curl "$XSI_BASE_URL/x-conf" -H "Authorization: Bearer $XSI_API_KEY"

Returns Resources, LevelMapper, ModelMapper, ModelFailover, ModelLimits and SwitchOver, plus:

FieldDescription
SleepingKeysKeys currently sleeping on this instance (including plaintext upstream keys)
DisabledKeysDisabled keys (including plaintext upstream keys)
UserMinBalance, UserApiBalanceSuspension threshold and manager balance threshold (global environment variables)

Modify

Mapping values in POST /x-conf are incremental commands, and changes are synced to sub-accounts:

FieldSyntaxScope
ModelMapper"a=b, c*=d" sets; "-a" removes; "*" clearsTenant MODEL_MAPPER, the owner, and all descendants
LevelMapperSame as above, with integer Level values; nonexistent Levels are ignoredTenant LEVEL_MAPPER and descendants with Gear ≀ 0
ModelLimitsA JSON object, or "-model", "*"Account-level limits of the owner and all descendants
ModelFailover"a=b", replaced as a wholeTenant MODEL_FAILOVER
ResourcesPath list, replaced as a wholeTenant RESOURCES
Gear, LevelIntegerTargeted: if ModelMapper is given with Gear or Level, only matching descendants are modified and the tenant configuration is unchanged; LevelMapper is targeted only when Level is given (Gear can narrow further)
LoadKeystrueReload this tenant's key pool
DelKeystrueWake all of this tenant's sleeping keys on this instance (no keys are deleted)
SaveCachetruePersist cached user state to storage immediately
LogEnabletrue/falseToggle request body logging for this process (not persisted; current instance only)
curl -X POST "$XSI_BASE_URL/x-conf" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ModelMapper": "gpt-latest=gpt-6.2-sol, -legacy-model", "LoadKeys": true}'

The response includes only the fields processed in this call. Fields are processed in a fixed order; if an error occurs partway, the API returns 500 and changes already applied are not rolled back.

/x-config or /x-conf?/x-config is declarative, whole-value configuration that writes only the tenant configuration itself, which suits version-controlled management. /x-conf is imperative and incremental, and also rewrites mappings and limits on sub-accounts, which suits live adjustments. Accounts cache model alias resolutions, so after changing MODEL_MAPPER, use /x-conf when existing accounts must pick up the change immediately. A regular owner's sync covers at most 8192 descendants per call; when root changes ModelMapper or ModelLimits via /x-conf, the change applies to accounts in all tenants, so use it with care.

Account details /x-info

curl "$XSI_BASE_URL/x-info?u=dev-a" -H "Authorization: Bearer $XSI_API_KEY"
  • The u (or user) parameter is an account ID or account name; if missing, the API returns 400 User parameter is required.
  • Any account at any depth in your tenant can be queried (including the owner); accounts in other tenants return 404 User not found.
  • The response has the same structure as GET /dashboard/live (snake_case), including usage for the current day and month.