Manage API Reference

This page is synchronized with the current backend implementation.

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...
• Manage permission follows the same runtime conditions shown by GET /dashboard/status (manage field)

Endpoint Overview

1) Subaccount APIs (/x-users / /x-dna)

1.1 Create subaccount

POST /x-users

Minimal request:

{
  "Name": "dev-account",
  "Email": "[email protected]",
  "CreditGranted": 100
}

Common optional fields:

• Alias, BillingEmail
• Rates
• RPM/RPH/RPD, TPM/TPH/TPD
• AllowIPs, AllowModels, AllowLevels
• Resources
• ModelLimits

Code-level behavior:

• Name/Email must be valid and unique.
• CreditGranted is normalized by backend min/max rules.
• Child accounts inherit many defaults from parent (ACL, limits, mappers, etc.).

1.2 Query children/descendants

• GET /x-users: direct children only
• GET /x-dna: all descendants
• GET /x-users/{identifier}, GET /x-dna/{identifier}: path filtering

Query params:

• id, name, email, level, dna
• page, size
• order

Path identifier supports:

• numeric ID
• username
• email (contains @)
• DNA path (starts with .)
• prefix filters: L{n}, G{n}, R{n}, T{n}, F{n}

Response body is an array; pagination metadata is in headers: X-Total-Count, X-Page, X-Per-Page, X-Total-Pages.

1.3 Update subaccount

PUT /x-users/{identifier} or POST /x-users/{identifier}

In current code, update identifiers are parsed as ID or username.

Common fields:

• Profile: Name, Email, Alias, BillingEmail, QRCode
• State: Status, Suspended (self-update cannot modify these)
• Credits: CreditGranted, Days, Rates
• Limits: DailyLimit, HardLimit, SoftLimit, UserLimit, AutoQuota
• Rate limits: RPM/RPH/RPD, TPM/TPH/TPD
• ACL: Resources, AllowIPs, AllowModels, AllowLevels
• Mapping/limits: ModelMapper, ModelLimits

Owner-only extras: Level, Role, Factor, LevelMapper.

1.4 Delete subaccount

DELETE /x-users/{identifier} (ID or username)

Response example:

{
  "Action": "delete",
  "User": {
    "ID": 42,
    "Name": "dev-account",
    "Email": "[email protected]",
    "Rates": 1,
    "CreditBalance": []
  }
}

2) Descendant billing (/x-bill)

GET /x-bill

Query params:

• Date: date/d
• Range: start/s, end/e (also start_date, end_date)
• Relative: days
• User filter: user/u (ID, name, email, DNA, or L/G/R/T/F prefix)

Returns bill_info plus usage_users (per-descendant aggregated metrics).

3) Self key rotation (/x-self)

POST /x-self

Request body:

{
  "confirm": "YYYY-MM-DD-ROTATE-SELF",
  "key": "sk-Xvs..."
}

Notes:

• confirm must match the current date phrase exactly.
• key is optional; backend auto-generates one if absent/invalid.

4) Dashboard APIs (/dashboard/*)

4.1 Status

GET /dashboard/status

Key fields:

• manage
• admin
• user_api_balance, user_min_balance
• suspended

4.2 Info

GET /dashboard/info

Flat user_info structure including:

• balance: balance, credit_balance
• limits: daily_limit, hard_limit, soft_limit
• rate limits: rpm/rph/rpd/tpm/tph/tpd
• ACL: resources, allow_ips, allow_models, allow_levels
• mappers/limits: model_mapper, level_mapper, model_limits

4.3 Live

GET /dashboard/live

Extends /dashboard/info with:

• daily_usage
• monthly_usage

4.4 Billing

GET /dashboard/bill

Date parameters are the same as /x-bill (date/start/end/days).

Returns bill_info with:

• daily_costs
• usage_summary
• total_credit_used
• total_requests

4.5 Logs

GET /dashboard/logs

Query params:

• page (default 1)
• size (default 24, max 100)
• action, target_id, status

Response:

{
  "logs": [],
  "total": 0,
  "page": 1,
  "size": 24,
  "has_more": false
}

4.6 News

GET /dashboard/news

Field names are code-aligned:

• sys_news
• user_news
• dna_news

4.7 Model list

GET /dashboard/models (aliases: /v1/models, /models)

OpenAI-style list response:

{
  "object": "list",
  "data": [
    {"id":"gpt-4o","object":"model","owned_by":"xai"}
  ]
}

5) Common errors

• 401 Unauthorized: invalid/missing API key
• 403 Forbidden: no manage permission or out-of-scope operation
• 404 Not Found: user not found
• 400 Bad Request: invalid payload/params

Related docs

• Admin API Reference
• Proxy Interface
• Manage Console Guide