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 ModuleEndpointDescription
Subaccount ManagementPOST /x-usersCreate 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 QueriesGET /dashboard/statusUser status
GET /dashboard/infoUser details
GET /dashboard/billUsage billing
GET /dashboard/logsOperation logs
GET /dashboard/newsNews notifications
GET /dashboard/confSystem configuration
GET /dashboard/modelsModel 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 address
  • CreditGranted - 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 like gpt-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 subaccounts
  • GET /x-users/{identifier} - Get specific user
  • GET /x-dna - Get all descendant accounts (including subaccounts' subaccounts)
  • GET /x-dna/{identifier} - Get specific descendant account

Query Parameters:

  • id - Filter by user ID
  • name - Filter by username (supports partial match)
  • email - Filter by email
  • level - 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/L2 for 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:

  • date or d - Specific date (YYYY-MM-DD)
  • start or s - Start date
  • end or e - End date
  • days - 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 type
  • target_id - Filter by target ID
  • status - 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 user
  • update_user - Update user
  • delete_user - Delete user
  • add_key - Add key
  • update_key - Update key
  • delete_key - Delete key
  • rotate_self - Key rotation
  • auto_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-*"
  }'
# 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

  1. Hierarchical Management - Create separate accounts for different environments (development/testing/production)
  2. Reasonable Limits - Set SoftLimit and HardLimit to avoid unexpected overages
  3. Model Allowlist - Restrict subaccounts to use only specific models
  4. Regular Audits - Periodically review subaccount list and usage

Recharge Management

  1. Recharge On Demand - Don't recharge too much at once
  2. Set Validity - Set shorter validity periods for test accounts
  3. Retain Balance - Deduct credits before deleting accounts to recover balance

Usage Monitoring

  1. Daily Checks - Review daily usage to avoid anomalies
  2. Trend Analysis - Regularly analyze usage trends to optimize costs
  3. Model Optimization - Choose appropriate models based on usage data
  4. Caching Strategy - For /dashboard/status and /dashboard/info, recommend caching for 5-10 minutes

Logs and Auditing

  1. Pagination Handling - Operation logs can be extensive; use pagination parameters to avoid returning too much data at once
  2. Date Ranges - When querying usage, recommend date ranges not exceeding 90 days for optimal performance
  3. Cost Control - Frequent queries for long time ranges of billing data will incur additional fees; set query periods reasonably