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.xsicontrol.com" # Or your own API domain
export XSI_API_KEY="sk-Xvs..." # Key of the tenant owner| Endpoint | Purpose |
|---|---|
GET/PUT/POST/DELETE /x-config | Read, write in full and reset tenant configuration (recommended) |
GET/POST /x-conf | View runtime state, apply incremental mapping changes synced to sub-accounts, and run operational commands |
GET /x-info | Look up detailed information for any account in your tenant |
Configuration keys
| Key | Format | Description |
|---|---|---|
MODEL_MAPPER | from=to,from2=to2 | Model rewriting; from may contain * wildcards; circular references are detected on write |
LEVEL_MAPPER | model=level,... | Selects the key pool group by model; model may contain *; when several wildcards match, the longest wins |
SWITCH_OVER | fromLevel=toLevel,... | Group-level failover; self-references and cycles are rejected |
MODEL_FAILOVER | model=fallback,... | Model-level failover replacement; fallback must be a priced model; circular references are detected |
STICKY_LEVELS | 1,2,3 | When global sticky scheduling is off (STICKY_SCHEDULER=false), only these Levels use sticky sessions; * clears the list |
MODEL_LIMITS | JSON | Model-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 |
PRICING | JSON | Price overrides with the same structure as api/pricing.json, see below |
RESOURCES | Path list | Tenant-level resource allowlist. In the current version it is only stored and displayed; the proxy enforces the account-level Resources |
XAI_MAIL | Tenant notification recipient (unknown models, failover, payment notifications, etc.) | |
EMAIL_SMTP, EMAIL_PORT, EMAIL_AUTH, EMAIL_PASS, EMAIL_SENDER | String | Tenant's own SMTP; the deployment's default email configuration is used when not set. EMAIL_PASS is write-only |
SIGNUP_ALLOW_DOMAINS, SIGNUP_DENY_DOMAINS | Domain rules | Email 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_SCHEDULERreflects the global environment variable and is read-only.PRICINGis 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
200but withsuccessset tofalseand the errors inerrors; if all keys are invalid, it returns400. - 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.orgor.example.orgmatches all subdomains as well asexample.orgitself;@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:
| Field | Description |
|---|---|
SleepingKeys | Keys currently sleeping on this instance (including plaintext upstream keys) |
DisabledKeys | Disabled keys (including plaintext upstream keys) |
UserMinBalance, UserApiBalance | Suspension 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:
| Field | Syntax | Scope |
|---|---|---|
ModelMapper | "a=b, c*=d" sets; "-a" removes; "*" clears | Tenant MODEL_MAPPER, the owner, and all descendants |
LevelMapper | Same as above, with integer Level values; nonexistent Levels are ignored | Tenant LEVEL_MAPPER and descendants with Gear β€ 0 |
ModelLimits | A JSON object, or "-model", "*" | Account-level limits of the owner and all descendants |
ModelFailover | "a=b", replaced as a whole | Tenant MODEL_FAILOVER |
Resources | Path list, replaced as a whole | Tenant RESOURCES |
Gear, Level | Integer | Targeted: 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) |
LoadKeys | true | Reload this tenant's key pool |
DelKeys | true | Wake all of this tenant's sleeping keys on this instance (no keys are deleted) |
SaveCache | true | Persist cached user state to storage immediately |
LogEnable | true/false | Toggle 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 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(oruser) parameter is an account ID or account name; if missing, the API returns400 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.