Manage API Reference
Manage API provides users with comprehensive subaccount management and self-service query capabilities, including creating, updating, and deleting subaccounts, as well as querying account status, balance, usage, billing, and operation logs. All users can access these endpoints, but some operations require parent account permissions.
Basic Information
Base URL: https://api.xaixapi.com
Authentication: All requests require an API Key
Authorization: Bearer sk-Xvs...
Permission Notes:
- Dashboard query endpoints: Any valid user
- Subaccount management endpoints: Parent account or ancestor account only
Frontend Consoles: Manage Console / Production Environment
Endpoint Overview
| Feature Module | Endpoint | Description |
|---|---|---|
| Subaccount Management | POST /x-users | Create subaccount |
GET /x-users / GET /x-users/{identifier} | Query subaccounts | |
GET /x-dna / GET /x-dna/{identifier} | Query descendant accounts | |
PUT /x-users/{identifier} | Update subaccount (recharge, configure, etc.) | |
DELETE /x-users/{identifier} | Delete subaccount | |
| Dashboard Queries | GET /dashboard/status | User status |
GET /dashboard/info | User details | |
GET /dashboard/bill | Usage billing | |
GET /dashboard/logs | Operation logs | |
GET /dashboard/news | News notifications | |
GET /dashboard/conf | System configuration | |
GET /dashboard/models | Model list |
1. Subaccount Management API
1.1 Create Subaccount
Create a new subaccount under your account.
Endpoint: POST /x-users
Permission: Requires parent account permission and satisfies balance/quota requirements
Request Body Fields:
{
"Name": "subaccount-1", // Account name (required, 4-63 chars, at least 1 letter)
"Email": "[email protected]", // Email (required)
"CreditGranted": 100, // Initial credit (required, β₯2 USD)
"Alias": "Production Account", // Display name (optional)
"BillingEmail": "[email protected]", // Billing email (optional)
"Rates": 1.0, // Rate multiplier (optional, β₯parent rate)
"Days": 180, // Credit validity days (optional, default 180)
"HardLimit": 1000, // Monthly hard limit (optional)
"SoftLimit": 800, // Monthly soft limit (optional, email alert when reached)
"AutoQuota": 0, // Auto quota (optional)
"RPM": 60, // Requests per minute limit (optional)
"RPH": 3600, // Requests per hour limit (optional)
"RPD": 86400, // Requests per day limit (optional)
"TPM": 150000, // Tokens per minute limit (optional)
"TPH": 9000000, // Tokens per hour limit (optional)
"TPD": 216000000, // Tokens per day limit (optional)
"AllowIPs": "192.168.1.0/24 10.0.0.5", // IP allowlist (optional, space/comma separated)
"AllowModels": "gpt-4* claude-*", // Model allowlist (optional, supports wildcards)
"Resources": "/v1/chat/completions /v1/embeddings", // Resource allowlist (optional)
"ModelLimits": { // Per-model rate limits (optional)
"gpt-4": {"rpm": 30, "tpm": 90000}
}
}
Required Fields:
Name- Unique account name (4-63 chars, at least 1 letter)Email- Valid email addressCreditGranted- Initial credit amount (β₯2 USD)
Optional Field Details:
Basic Configuration:
Alias- Display name (defaults to Name)BillingEmail- Billing notification email (defaults to Email)Rates- Rate multiplier (must be β₯ parent rate, defaults to parent's rate)Days- Credit validity days (default 180)
Limit Settings:
HardLimit- Monthly hard limit (service stops when reached)SoftLimit- Monthly soft limit (email alert when reached)AutoQuota- Auto quota (automatic recharge feature)
Rate Limits:
RPM/RPH/RPD- Request rate limits (per minute/hour/day)TPM/TPH/TPD- Token rate limits (per minute/hour/day)
Access Control:
AllowIPs- IP allowlist (CIDR format, space or comma separated)AllowModels- Model allowlist (supports wildcards likegpt-4*)Resources- Resource allowlist (API endpoint list)
Model Rate Limiting:
ModelLimits- Set independent rate limits for specific models (JSON format)
Examples:
# Basic creation
curl -X POST https://api.xaixapi.com/x-users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name": "prod-account",
"Email": "[email protected]",
"CreditGranted": 500,
"Alias": "Production Environment",
"RPM": 100,
"TPM": 200000
}'
# Complete configuration
curl -X POST https://api.xaixapi.com/x-users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name": "dev-account",
"Email": "[email protected]",
"CreditGranted": 100,
"Alias": "Development Environment",
"Rates": 1.0,
"Days": 30,
"HardLimit": 500,
"SoftLimit": 400,
"RPM": 60,
"TPM": 150000,
"AllowModels": "gpt-4o-mini claude-3-haiku*",
"AllowIPs": "192.168.1.0/24",
"ModelLimits": {
"gpt-4o-mini": {"rpm": 30, "tpm": 90000}
}
}'
Response Example:
{
"Action": "add",
"User": {
"ID": 42,
"SecretKey": "sk-Xvs...",
"Updates": {
"Name": "prod-account",
"Email": "[email protected]",
"CreditGranted": 500,
"Balance": 500,
"HardLimit": 500,
"SoftLimit": 400,
"Status": true,
"Level": 2,
"DNA": ".1.42."
}
}
}
1.2 Query Subaccounts
Query information for one or more subaccounts.
Endpoints:
GET /x-users- Get all direct subaccountsGET /x-users/{identifier}- Get specific userGET /x-dna- Get all descendant accounts (including subaccounts' subaccounts)GET /x-dna/{identifier}- Get specific descendant account
Query Parameters:
id- Filter by user IDname- Filter by username (supports partial match)email- Filter by emaillevel- Filter by level (0-9)dna- Filter by DNA (hierarchy path)page- Page number (default: 1)size- Page size (default: 100, max: 1000)
Special Path Filters:
When using path parameters (e.g., /x-users/{identifier}), the following prefixes are supported:
L{n}- Filter by Level (e.g.,/x-users/L2for all Level 2 users)G{n}- Filter by Gear (e.g.,/x-users/G1)R{n}- Filter by Role (e.g.,/x-users/R3)T{n}- Filter by Tier (e.g.,/x-users/T2)F{n}- Filter by Factor (e.g.,/x-users/F1.5).{dna}- Filter by DNA path (e.g.,/x-users/.1.42.){email}- Filter by email if contains @ (e.g.,/x-users/[email protected]){id}- Numeric ID (e.g.,/x-users/42){name}- Username (e.g.,/x-users/prod-account)
Examples:
# Get all direct subaccounts
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users
# Get specific user by ID
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/42
# Get by username
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/prod-account
# Get by email
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/[email protected]
# Filter by level
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/x-users?level=2"
# Get all descendant accounts (paginated)
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/x-dna?page=1&size=100"
# Use special path filters
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/L2 # All Level 2 users
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/.1.42. # Users under DNA path
Response Example:
{
"success": true,
"users": [
{
"ID": 42,
"Name": "prod-account",
"Email": "[email protected]",
"Alias": "Production Environment",
"Balance": 450.25,
"Level": 2,
"DNA": ".1.42.",
"Status": true,
"Rates": 1.0,
"HardLimit": 1000,
"SoftLimit": 800,
"CreatedAt": "2025-01-01T00:00:00Z"
}
],
"total": 1,
"page": 1,
"size": 100
}
1.3 Update Subaccount
Update configuration, limits, and balance for an existing subaccount.
Endpoint: PUT /x-users/{identifier}
Identifier: Can be user ID, username, or email
Request Body Fields (all optional):
{
"CreditGranted": 100, // Recharge amount (negative for deduction)
"Days": 30, // Credit validity days
"Status": true, // Enable/disable account
"Rates": 1.5, // Update rate multiplier
"HardLimit": 2000, // Update monthly hard limit
"SoftLimit": 1800, // Update monthly soft limit
"AutoQuota": 100, // Auto quota
"RPM": 120, // Requests per minute
"RPH": 7200, // Requests per hour
"RPD": 172800, // Requests per day
"TPM": 300000, // Tokens per minute
"TPH": 18000000, // Tokens per hour
"TPD": 432000000, // Tokens per day
"AllowModels": "gpt-4* claude-*", // Model allowlist
"AllowIPs": "192.168.1.0/24 10.0.0.5", // IP allowlist
"Resources": "/v1/chat/completions /v1/embeddings", // Resource allowlist
"ModelLimits": { // Per-model limits
"gpt-4": {"rpm": 30, "tpm": 90000}
}
}
Special Operations:
Recharge/Deduction:
- Recharge:
"CreditGranted": 100 - Deduction:
"CreditGranted": -50 - Custom validity:
"CreditGranted": 100, "Days": 90
Allowlist Management:
- Reset allowlist:
"AllowModels": "*" - Remove from allowlist:
"AllowModels": "-gpt-3.5-turbo" - Add to allowlist:
"AllowModels": "gpt-4o claude-3-opus"
Examples:
# Recharge with custom validity
curl -X PUT https://api.xaixapi.com/x-users/42 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"CreditGranted": 100, "Days": 30}'
# Deduct credits
curl -X PUT https://api.xaixapi.com/x-users/prod-account \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"CreditGranted": -50}'
# Update model allowlist
curl -X PUT https://api.xaixapi.com/x-users/prod-account \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"AllowModels": "gpt-4* claude-3*"}'
# Update rate limits
curl -X PUT https://api.xaixapi.com/x-users/42 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"RPM": 200, "TPM": 500000}'
# Disable account
curl -X PUT https://api.xaixapi.com/x-users/42 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"Status": false}'
# Batch update (recharge + limits + allowlist)
curl -X PUT https://api.xaixapi.com/x-users/dev-account \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"CreditGranted": 200,
"Days": 60,
"HardLimit": 1000,
"RPM": 100,
"AllowModels": "gpt-4* claude-*",
"ModelLimits": {
"gpt-4o": {"rpm": 50, "tpm": 150000}
}
}'
1.4 Delete Subaccount
Delete a subaccount and refund its remaining balance to the parent account.
Endpoint: DELETE /x-users/{identifier}
Permission: Parent account or owner account only
Behavior Notes:
- Remaining balance is automatically refunded to parent account
- A transaction fee of $0.2 is deducted
- Refunded balance has 180-day validity by default
- Deletion is irreversible
Examples:
curl -X DELETE https://api.xaixapi.com/x-users/42 \
-H "Authorization: Bearer $API_KEY"
curl -X DELETE https://api.xaixapi.com/x-users/dev-account \
-H "Authorization: Bearer $API_KEY"
Response Example:
{
"Action": "delete",
"User": {
"ID": 42,
"Name": "dev-account",
"RefundedBalance": 49.8,
"TransactionFee": 0.2
},
"message": "User deleted successfully"
}
2. Dashboard Query API
2.1 User Status
Get basic status information for the current user, suitable for quick queries.
Endpoint: GET /dashboard/status
Permission: Any valid user
Example:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/status
Response Example:
{
"object": "user_status",
"id": 42,
"dna": ".1.42.",
"name": "prod-account",
"email": "[email protected]",
"alias": "Production Environment",
"public_key": "pk-...",
"balance": 450.25,
"manage": true, // Can access Manage console
"admin": true // Can access Admin console (owner only)
}
2.2 User Details
Get detailed user information including balance breakdown, limit configurations, usage statistics, and access controls.
Endpoint: GET /dashboard/info
Permission: Any valid user
Example:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/info
Response Example:
{
"object": "user_info",
"user": {
"id": 42,
"name": "prod-account",
"email": "[email protected]",
"alias": "Production Environment",
"level": 1,
"gear": 1,
"role": 1,
"tier": 1,
"factor": 1.0,
"rates": 1.0,
"dna": ".1.42.",
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-15T10:00:00Z"
},
"balance": {
"total": 450.25,
"credits": [
{
"amount": 400.00,
"expires_at": "2025-02-15T00:00:00Z"
},
{
"amount": 50.25,
"expires_at": "2025-03-01T00:00:00Z"
}
]
},
"limits": {
"hard_limit": 5000,
"soft_limit": 4000,
"auto_quota": 0,
"rpm": 100,
"rph": 3600,
"rpd": 10000,
"tpm": 200000,
"tph": 6000000,
"tpd": 50000000
},
"usage": {
"today": {
"requests": 150,
"tokens": 450000,
"cost": 12.50
},
"month": {
"requests": 3500,
"tokens": 12500000,
"cost": 285.75
}
},
"restrictions": {
"allow_ips": ["192.168.1.0/24", "10.0.0.5"],
"allow_models": ["gpt-4*", "claude-3*"],
"resources": ["/v1/chat/completions", "/v1/embeddings"]
},
"model_limits": {
"gpt-4": {
"rpm": 30,
"tpm": 90000
},
"claude-3-opus": {
"rpm": 20,
"tpm": 60000
}
}
}
2.3 Usage Billing
Get usage statistics and billing information with date range support.
Endpoint: GET /dashboard/bill
Permission: Any valid user
Query Parameters:
dateord- Specific date (YYYY-MM-DD)startors- Start dateendore- End datedays- Past N days (from today)
Billing Notes:
- Query span >30 days: charged $0.01
- Query span >365 days: auto-truncated to one year, charged $0.05
Examples:
# Get today's usage (default)
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/bill
# Get specific date usage
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/bill?date=2025-01-15"
# Get past 30 days usage
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/bill?days=30"
# Query by date range
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/bill?start=2025-01-01&end=2025-01-31"
Response Example:
{
"object": "list",
"data": [
{
"aggregation_timestamp": 1234567890,
"n_requests": 1000,
"n_context_tokens_total": 500000,
"n_generated_tokens_total": 100000,
"n_cached_tokens_total": 50000,
"usage_details": {
"gpt-4": {
"requests": 100,
"prompt": 50000,
"completion": 10000,
"cost": 3.5
},
"claude-3-opus": {
"requests": 50,
"prompt": 25000,
"completion": 5000,
"cost": 2.8
}
}
}
],
"total_usage": {
"requests": 10000,
"prompt_tokens": 5000000,
"completion_tokens": 1000000,
"cached_tokens": 500000,
"cost": 125.50
},
"query_fee": 0.01
}
2.4 Operation Logs
Get operation logs for the account with pagination and filtering support.
Endpoint: GET /dashboard/logs
Permission: Any valid user (typically views own scope only)
Query Parameters:
page- Page number (default: 1)size- Page size (default: 24, max: 100)action- Filter by action typetarget_id- Filter by target IDstatus- Filter by status
Examples:
# Get recent logs
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/logs
# Get paginated logs
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/logs?page=2&size=50"
# Filter specific action
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/logs?action=add_user"
Response Example:
{
"logs": [
{
"id": 123,
"action": "add_user",
"operator_id": 1,
"target_id": 42,
"details": "Created user with email: [email protected]",
"ip_address": "192.168.1.100",
"created_at": "2025-01-15 10:30:00",
"status": "success"
},
{
"id": 124,
"action": "update_user",
"operator_id": 1,
"target_id": 42,
"details": "Recharged $100 with 30-day validity",
"ip_address": "192.168.1.100",
"created_at": "2025-01-15 10:35:00",
"status": "success"
}
],
"total": 150,
"page": 1,
"size": 24,
"has_more": true
}
Common Action Types:
add_user- Create userupdate_user- Update userdelete_user- Delete useradd_key- Add keyupdate_key- Update keydelete_key- Delete keyrotate_self- Key rotationauto_config- Auto configuration
2.5 News Notifications
Get system news and user notifications.
Endpoint: GET /dashboard/news
Permission: Any valid user
Example:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/news
Response Example:
{
"success": true,
"system_news": [
{
"id": 1,
"title": "System Update Notice",
"content": "The system will undergo...",
"created_at": "2025-01-15T10:00:00Z",
"expires_at": "2025-01-22T10:00:00Z"
}
],
"user_news": [
{
"id": 2,
"title": "Account Balance Alert",
"content": "Your account balance is low...",
"created_at": "2025-01-15T11:00:00Z",
"expires_at": "2025-02-15T11:00:00Z"
}
],
"dna_news": [
{
"id": 3,
"title": "Team Notification",
"content": "Important notice for your team...",
"created_at": "2025-01-15T12:00:00Z",
"expires_at": "2025-02-15T12:00:00Z"
}
]
}
News Type Descriptions:
system_news- System-level news (visible to all users)user_news- User-level news (specific users)dna_news- DNA group-level news (users under specific DNA path)
2.6 System Configuration
Get global key thresholds and configuration parameters.
Endpoint: GET /dashboard/conf
Permission: Any valid user
Example:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/conf
Response Example:
{
"UserMinBalance": 1.0,
"UserApiBalance": 0.5,
"SystemVersion": "v2.5.0",
"Features": {
"sign_enable": true,
"safe_enable": true
}
}
2.7 Model List
Get the current list of built-in/proxy-available models in the system.
Endpoint: GET /dashboard/models
Permission: Any valid user
Example:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/models
Response Example:
{
"models": [
{
"id": "gpt-4o",
"provider": "openai",
"context_window": 128000,
"max_output_tokens": 16384
},
{
"id": "claude-3-opus",
"provider": "anthropic",
"context_window": 200000,
"max_output_tokens": 4096
}
]
}
Use Cases
Use Case 1: Create Development Environment Subaccount
# 1. Create subaccount
curl -X POST https://api.xaixapi.com/x-users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name": "dev-env-001",
"Email": "[email protected]",
"CreditGranted": 10,
"Alias": "Development Environment",
"HardLimit": 50,
"SoftLimit": 40,
"RPM": 30,
"AllowModels": "gpt-4o-mini claude-3-haiku*"
}'
# 2. Verify creation result
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/dev-env-001
Use Case 2: Batch Query Subaccount Status
# Get all subaccounts
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users
# Get all descendant accounts (including subaccounts' subaccounts)
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-dna
# Filter Level 2 accounts
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/x-users?level=2"
Use Case 3: Recharge Subaccount and Update Limits
# Recharge and update configuration
curl -X PUT https://api.xaixapi.com/x-users/dev-env-001 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"CreditGranted": 50,
"Days": 30,
"HardLimit": 100,
"RPM": 60,
"AllowModels": "gpt-4* claude-*"
}'
Use Case 4: View Usage Trends and Billing
# View today's usage
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/bill
# View this month's usage
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/bill?days=30"
# View detailed information (balance, limits, usage)
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/info
Use Case 5: Monitoring and Alerts
# Periodically check account balance
*/60 * * * * curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/info | \
jq '.balance.total' | \
awk '{if($1<10) print "Low balance warning!"}'
# Check operation logs
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/logs?action=delete_user"
Best Practices
Account Management
- Hierarchical Management - Create separate accounts for different environments (development/testing/production)
- Reasonable Limits - Set SoftLimit and HardLimit to avoid unexpected overages
- Model Allowlist - Restrict subaccounts to use only specific models
- Regular Audits - Periodically review subaccount list and usage
Recharge Management
- Recharge On Demand - Don't recharge too much at once
- Set Validity - Set shorter validity periods for test accounts
- Retain Balance - Deduct credits before deleting accounts to recover balance
Usage Monitoring
- Daily Checks - Review daily usage to avoid anomalies
- Trend Analysis - Regularly analyze usage trends to optimize costs
- Model Optimization - Choose appropriate models based on usage data
- Caching Strategy - For
/dashboard/statusand/dashboard/info, recommend caching for 5-10 minutes
Logs and Auditing
- Pagination Handling - Operation logs can be extensive; use pagination parameters to avoid returning too much data at once
- Date Ranges - When querying usage, recommend date ranges not exceeding 90 days for optimal performance
- Cost Control - Frequent queries for long time ranges of billing data will incur additional fees; set query periods reasonably
Related Documentation
- Admin API Reference - Provider key and system configuration API
- Manage Console Usage Guide - Manage UI operation instructions
- Terminology - Level, model mapping, and other concepts