Admin API Reference

This page is synchronized with the current backend code (api/main.go + api/handler/*.go) and focuses on Admin-related endpoints.

Base Information

• Runtime domains by mode:
  • SaaS single-tenant: https://api.xairouter.com
  • BYOK multi-tenant: https://api.xaicontrol.com
• Examples below use $BASE_URL; set it first:

export BASE_URL="https://api.xairouter.com"      # SaaS
# export BASE_URL="https://api.xaicontrol.com"   # BYOK

• Auth: Authorization: Bearer sk-Xvs...
• Permission model:
  • Owner: manage /x-keys, /x-conf, /x-config, /x-info
  • Root: create system-wide news via POST /x-news

Endpoint Overview

1) Key Management (/x-keys)

1.1 List keys

GET /x-keys

Query params:

• id
• level
• provider
• page, size (if only size is provided, page is normalized to 1)

Path filters:

• /x-keys/123
• /x-keys/L2
• /x-keys/api.openai.com

Response is an array. Pagination metadata is returned via headers: X-Total-Count, X-Page, X-Per-Page, X-Total-Pages.

curl -H "Authorization: Bearer $API_KEY" \
  "${BASE_URL}/x-keys?page=1&size=20&level=2"

1.2 Create key

POST /x-keys

Request fields (code-accurate):

{
  "Name": "OpenAI Primary",
  "Level": 1,
  "Provider": "https://api.openai.com",
  "SecretKey": "sk-xxxxxxxxxxxxxxxxxxxx",
  "Status": true,
  "config": {
    "provider_type": "standard"
  }
}

Notes:

• Provider is required and must be a valid URL.
• SecretKey is required and must be at least 20 chars.
• The JSON field is lowercase config (json:"config").
• It is recommended to pass Status explicitly.
• After creation, caches/round-robin are refreshed, and auto LevelMapper update may run.

1.3 Update key

PUT /x-keys/{id} or POST /x-keys/{id}

Updatable fields: Name, Level, Provider, SecretKey, Status, config.

curl -X PUT ${BASE_URL}/x-keys/123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Level":2,"Status":true}'

1.4 Delete key

DELETE /x-keys/{id}

curl -X DELETE ${BASE_URL}/x-keys/123 \
  -H "Authorization: Bearer $API_KEY"

2) Owner Batch Config (/x-conf)

2.1 Get config

GET /x-conf

Current response fields:

• Resources
• LevelMapper
• ModelMapper
• ModelFailover
• ModelLimits
• SwitchOver
• SleepingKeys
• DisabledKeys
• UserMinBalance
• UserApiBalance

2.2 Batch update

POST /x-conf

Supported fields:

• LoadKeys (bool)
• LogEnable (bool)
• SaveCache (bool)
• Resources (string)
• LevelMapper (string)
• ModelMapper (string)
• ModelFailover (string)
• DelKeys (bool)
• ModelLimits (object or string)

ModelLimits string operations:

• * or =: clear all
• -model: remove one model

curl -X POST ${BASE_URL}/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ModelMapper":"gpt-3.5*=gpt-4o-mini",
    "LevelMapper":"gpt-4*=2",
    "ModelLimits":{"gpt-4o":{"rpm":30,"tpm":90000}}
  }'

Notes:

• ModelMapper and ModelLimits are cascaded to descendants by backend logic.
• LevelMapper is owner-driven and synchronized to descendants conditionally.

3) Owner Config CRUD (/x-config)

3.1 Get config

GET /x-config

Response format:

{
  "success": true,
  "oid": 1,
  "configs": {
    "MODEL_MAPPER": {},
    "MODEL_FAILOVER": {},
    "LEVEL_MAPPER": {},
    "SWITCH_OVER": {},
    "RESOURCES": {},
    "MODEL_LIMITS": {},
    "PRICING": "",
    "XAI_MAIL": "",
    "EMAIL_PORT": "",
    "EMAIL_SMTP": "",
    "EMAIL_AUTH": ""
  }
}

3.2 Update config

PUT /x-config or POST /x-config

This endpoint decodes payload as map[string]string, so values should be strings.

Allowed keys:

• MODEL_MAPPER
• MODEL_FAILOVER
• LEVEL_MAPPER
• SWITCH_OVER
• RESOURCES
• MODEL_LIMITS (JSON string)
• PRICING (JSON string)
• XAI_MAIL
• EMAIL_PORT
• EMAIL_SMTP
• EMAIL_AUTH
• EMAIL_PASS

curl -X PUT ${BASE_URL}/x-config \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "MODEL_MAPPER":"gpt-4=gpt-4o",
    "MODEL_LIMITS":"{\"gpt-4o\":{\"rpm\":30}}"
  }'

3.3 Delete config keys

DELETE /x-config

{
  "keys": ["MODEL_MAPPER", "PRICING"]
}

4) User detail (/x-info)

GET /x-info?user={id or name}

• user query param is required.
• User must belong to current owner.
• Response uses user_info schema with balance, limits, ACL, mappers, and daily/monthly usage.

5) News (/x-news)

5.1 Create news

• POST /x-news: system-wide news (Root only)
• POST /x-news/{target}: targeted news

target can be:

• user ID
• username
• DNA path (starting with .)

Request body:

{
  "title": "Maintenance Notice",
  "content": "Upgrade window 02:00~03:00",
  "days": 3
}

5.2 Delete news

• DELETE /x-news
• DELETE /x-news/{target}

Delete behavior removes all news entries under the target key.

6) Common errors

• 401 Unauthorized: missing/invalid API key
• 403 Forbidden: non-owner owner APIs or permission violation
• 404 Not Found: target user/key not found
• 400 Bad Request: invalid body/params

Related docs

• Manage API Reference
• Proxy Interface
• Admin Console Guide