𝐗𝐀𝐈 𝐗𝐀𝐏𝐈

API Reference

XAI XAPI Reference

Welcome to the XAI XAPI documentation. Our platform provides a comprehensive set of APIs for managing AI services, subaccounts, and resources. This document covers all available endpoints, their functions, parameters, and usage examples.

API Overview

XAI offers the following API categories:

  1. AI Service Proxy - OpenAI/Anthropic compatible endpoints
  2. User Management - Create and manage subaccounts
  3. Key Management - Manage API keys and providers
  4. Billing & Usage - Track usage and billing information
  5. Configuration - System and user configuration
  6. News & Notifications - System announcements and user notifications

Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer sk-Xvs...

Base URL

https://api.xaixapi.com

API Endpoints

1. User Management APIs

1.1 Create Subaccount

Create a new subaccount under your account.

Endpoint: POST /x-users

Request Body:

{
  "Name": "subaccount-1",
  "Email": "[email protected]",
  "CreditGranted": 100,
  "Alias": "Production Account",
  "Rates": 1.0,
  "HardLimit": 1000,
  "SoftLimit": 800,
  "RPM": 60,
  "TPM": 150000
}

Required Fields:

  • Name - Unique account name (4-63 chars, at least 1 letter)
  • Email - Valid email address
  • CreditGranted - Initial credit amount (min: 2)

Optional Fields:

  • Alias - Display name (default: same as Name)
  • BillingEmail - Billing notification email
  • Rates - Rate multiplier (must be ≥ parent's rate)
  • HardLimit - Monthly hard limit
  • SoftLimit - Monthly soft limit (email alert threshold)
  • RPM/RPH/RPD - Request rate limits
  • TPM/TPH/TPD - Token rate limits
  • AllowIPs - IP whitelist
  • AllowModels - Model whitelist
  • Resources - API endpoint whitelist

Example:

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
  }'

Response:

{
  "Action": "add",
  "User": {
    "ID": 42,
    "SecretKey": "sk-Xvs...",
    "Updates": {
      "Name": "prod-account",
      "Email": "[email protected]",
      "CreditGranted": 500,
      "Balance": 500,
      "HardLimit": 5000,
      "SoftLimit": 4000
    }
  }
}

1.2 Update Subaccount

Update an existing subaccount's settings.

Endpoint: PUT /x-users/{identifier}

Identifier: Can be user ID, name, or email

Request Body:

{
  "CreditGranted": 100,      // Recharge amount (negative for refund)
  "Days": 30,                // Credit expiry days (optional)
  "Rates": 1.5,              // Update rate multiplier
  "Status": true,            // Enable/disable account
  "HardLimit": 2000,         // Update limits
  "AllowModels": "gpt-4* claude-*",  // Model whitelist
  "AllowIPs": "192.168.1.0/24 10.0.0.5",  // IP whitelist
  "ModelLimits": {           // Per-model limits
    "gpt-4": {
      "rpm": 30,
      "tpm": 90000
    }
  }
}

Special Operations:

  • Recharge: "CreditGranted": 100
  • Refund: "CreditGranted": -50
  • Custom Expiry: "CreditGranted": 100, "Days": 90
  • Reset Whitelist: "AllowModels": "*"
  • Remove from Whitelist: "AllowModels": "-gpt-3.5-turbo"

Example:

# Recharge with 30-day expiry
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}'

# Update model whitelist
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*"}'

1.3 Get User Information

Retrieve user(s) information.

Endpoints:

  • GET /x-users - Get all direct subaccounts
  • GET /x-users/{identifier} - Get specific user
  • GET /x-dna - Get all descendant accounts
  • GET /x-dna/{identifier} - Get specific descendant

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}), you can use special prefixes:

  • 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 subaccounts
curl -X GET https://api.xaixapi.com/x-users \
  -H "Authorization: Bearer $API_KEY"

# Get specific user by ID
curl -X GET https://api.xaixapi.com/x-users/42 \
  -H "Authorization: Bearer $API_KEY"

# Get users by level
curl -X GET "https://api.xaixapi.com/x-users?level=2" \
  -H "Authorization: Bearer $API_KEY"

# Get all descendants with pagination
curl -X GET "https://api.xaixapi.com/x-dna?page=1&size=100" \
  -H "Authorization: Bearer $API_KEY"

# Get users by special filters using path
curl -X GET "https://api.xaixapi.com/x-users/L2" \  # All Level 2 users
  -H "Authorization: Bearer $API_KEY"

curl -X GET "https://api.xaixapi.com/x-users/.1.42." \  # Users in DNA path
  -H "Authorization: Bearer $API_KEY"

1.4 Delete Subaccount

Delete a subaccount and refund remaining balance.

Endpoint: DELETE /x-users/{identifier}

Note:

  • Remaining balance is automatically refunded to parent account
  • A transaction fee of $0.2 is deducted
  • Refunded balance has 180-day validity by default

Example:

curl -X DELETE https://api.xaixapi.com/x-users/42 \
  -H "Authorization: Bearer $API_KEY"

2. Key Management APIs

2.1 Add Key

Add an external API key to the system.

Endpoint: POST /x-keys

Request Body:

{
  "SecretKey": "sk-...",
  "Name": "Production Key",
  "Level": 1,
  "Provider": "https://api.openai.com",
  "Status": true
}

Example:

curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "sk-...",
    "Name": "Claude API Key",
    "Level": 2,
    "Provider": "https://api.anthropic.com"
  }'

2.2 Update Key

Update key properties.

Endpoint: PUT /x-keys/{id}

Request Body:

{
  "Name": "Updated Name",
  "Level": 2,
  "Status": false,
  "Provider": "https://api.anthropic.com"
}

2.3 Get Keys

Retrieve keys with optional filters.

Endpoints:

  • GET /x-keys - Get all keys
  • GET /x-keys/{id} - Get specific key
  • GET /x-keys?level={n} - Filter by level
  • GET /x-keys?provider={url} - Filter by provider

Example:

# Get all keys
curl -X GET https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY"

# Get keys by level
curl -X GET "https://api.xaixapi.com/x-keys?level=2" \
  -H "Authorization: Bearer $API_KEY"

3. Billing & Usage APIs

3.1 Get Usage Report

Get detailed usage report for accounts.

Endpoint: GET /x-bill

Query Parameters:

  • u or user - User identifier (ID, name, email, or filter)
  • d or date - Specific date (YYYY-MM-DD)
  • s or start - Start date
  • e or end - End date
  • days - Number of days from today

Examples:

# Current month usage for all subaccounts
curl -X GET https://api.xaixapi.com/x-bill \
  -H "Authorization: Bearer $API_KEY"

# Specific user's usage for last 30 days
curl -X GET "https://api.xaixapi.com/x-bill?user=prod-account&days=30" \
  -H "Authorization: Bearer $API_KEY"

# Date range query
curl -X GET "https://api.xaixapi.com/x-bill?start=2025-01-01&end=2025-01-31" \
  -H "Authorization: Bearer $API_KEY"

# Filter by user attributes
curl -X GET "https://api.xaixapi.com/x-bill?user=L2" \  # All Level 2 users
  -H "Authorization: Bearer $API_KEY"

Response Structure:

{
  "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
        }
      }
    }
  ],
  "total_usage": {
    "requests": 10000,
    "prompt_tokens": 5000000,
    "completion_tokens": 1000000,
    "cached_tokens": 500000,
    "cost": 125.50
  },
  "usage_users": [
    {
      "id": 42,
      "name": "prod-account",
      "email": "[email protected]",
      "total_requests": 5000,
      "total_prompt": 2500000,
      "total_completion": 500000,
      "total_cached": 250000,
      "total_cost": 62.75,
      "usage_analysis": {
        "request_percentage": 50.0,
        "cost_percentage": 50.0,
        "prompt_percentage": 50.0,
        "completion_percentage": 50.0
      },
      "model_usage": {
        "gpt-4": {
          "requests": 2500,
          "cost": 45.00
        },
        "claude-3-opus": {
          "requests": 2500,
          "cost": 17.75
        }
      }
    }
  ]
}

4. Dashboard APIs

4.1 User Status

Get current user status and balance.

Endpoint: GET /dashboard/x-user-status

Response:

{
  "object": "user_status",
  "id": 42,
  "name": "prod-account",
  "email": "[email protected]",
  "balance": 450.25,
  "dna": ".1.42."
}

4.2 User Info

Get detailed user information.

Endpoint: GET /dashboard/x-user-info

Response:

{
  "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
    }
  }
}

4.3 User Logs

Get operation logs for the account.

Endpoint: GET /dashboard/x-user-logs

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

Response:

{
  "logs": [
    {
      "id": 123,
      "action": "add_user",
      "operator_id": 1,
      "target_id": 42,
      "details": "Created user with email: [email protected]",
      "created_at": "2025-01-15 10:30:00",
      "status": "success"
    }
  ],
  "total": 150,
  "page": 1,
  "size": 24,
  "has_more": true
}

5. Key Rotation API

Rotate Self Key

Rotate your own API key.

Endpoint: POST /x-self

Request Body:

{
  "confirm": "2025-01-15-ROTATE-SELF"  // Current date + "-ROTATE-SELF"
}

Response:

{
  "success": true,
  "message": "Self key rotated successfully",
  "rotate": {
    "action": "rotate_self",
    "id": 42,
    "name": "prod-account",
    "key": "sk-Xvs...",  // New key
    "timestamp": "2025-01-15T10:30:00Z"
  }

Important Notes:

  • The confirmation phrase must be exactly: {current-date}-ROTATE-SELF
  • The date format is YYYY-MM-DD
  • After rotation, the old key will be immediately invalidated
  • Make sure to save the new key before closing the response

6. News & Notifications APIs

6.1 Create News

Create news/notifications for users.

Endpoints:

  • POST /x-news - System-wide news (root only)
  • POST /x-news/{target} - Targeted news

Target Types:

  • User ID: /x-news/42
  • Username: /x-news/prod-account
  • DNA group: /x-news/.1.42.

Request Body:

{
  "title": "Maintenance Notice",
  "content": "System maintenance scheduled for...",
  "days": 7  // Expiry days (default: 7 for system, 32 for targeted)
}

Example:

# Create system news
curl -X POST https://api.xaixapi.com/x-news \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Feature Release",
    "content": "We are excited to announce...",
    "days": 14
  }'

# Create news for specific user
curl -X POST https://api.xaixapi.com/x-news/42 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Account Update",
    "content": "Your account settings have been updated."
  }'

6.2 Get News

Get news/notifications.

Endpoint: GET /dashboard/x-user-news

Response:

{
  "success": true,
  "system_news": [
    {
      "title": "System Update",
      "content": "...",
      "created_at": "2025-01-15T10:00:00Z",
      "expires_at": "2025-01-22T10:00:00Z"
    }
  ],
  "user_news": [
    {
      "title": "Account Update",
      "content": "...",
      "created_at": "2025-01-15T11:00:00Z",
      "expires_at": "2025-02-15T11:00:00Z"
    }
  ]
}

6.3 Delete News

Delete news items.

Endpoints:

  • DELETE /x-news - Delete all system news
  • DELETE /x-news/{target} - Delete targeted news

Example:

# Delete all news for user 42
curl -X DELETE https://api.xaixapi.com/x-news/42 \
  -H "Authorization: Bearer $API_KEY"

7. Configuration APIs

7.1 Get Configuration

Get current system configuration.

Endpoint: GET /x-config

Response:

{
  "success": true,
  "configs": {
    "MODEL_MAPPER": "gpt-3.5-turbo=gpt-4",
    "LEVEL_MAPPER": "gpt-4=2",
    "RESOURCES": "/v1/chat/completions,/v1/embeddings",
    "XAI_MAIL": "[email protected]"
  }
}

7.2 Update Configuration

Update system configuration.

Endpoint: POST /x-config

Request Body:

{
  "MODEL_MAPPER": "gpt-3.5-turbo=gpt-4,claude-2=claude-3",
  "LEVEL_MAPPER": "gpt-4=2,claude-3=2",
  "RESOURCES": "/v1/chat/completions,/v1/embeddings"
}

Available Configuration Keys:

  • MODEL_MAPPER - Model name mappings (e.g., map gpt-3.5-turbo to gpt-4)
  • LEVEL_MAPPER - Model to level mappings (determines which level can access which models)
  • SWITCH_OVER - Level switching rules for automatic failover
  • RESOURCES - Allowed API endpoints (comma-separated list)
  • XAI_MAIL - System notification email
  • EMAIL_SERVER - SMTP server address
  • EMAIL_PORT - SMTP server port
  • EMAIL_USERNAME - SMTP authentication username
  • EMAIL_PASSWORD - SMTP authentication password
  • EMAIL_FROM - Default sender email address

Rate Limiting

The API implements multiple levels of rate limiting:

  1. Request Rate Limits:

    • RPM - Requests per minute
    • RPH - Requests per hour
    • RPD - Requests per day

  2. Token Rate Limits:

    • TPM - Tokens per minute
    • TPH - Tokens per hour
    • TPD - Tokens per day

  3. Model-Specific Limits:

    • Set via ModelLimits in user configuration
    • Overrides global limits for specific models

Error Responses

All errors follow a consistent format:

{
  "error": {
    "message": "Description of the error",
    "type": "error_type",
    "code": "error_code"
  }
}

Common HTTP status codes:

  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

Response Formats

Success Response

All successful API responses include relevant data in JSON format with appropriate HTTP status codes (200, 201, etc.).

User Object Fields

User objects returned by the API include:

  • ID - Unique user identifier
  • Name - Username
  • Email - Email address
  • Alias - Display name
  • SecretKey - API key (only shown on creation or rotation)
  • Balance - Current credit balance
  • CreditBalance - Detailed credit information with expiry dates
  • Level, Gear, Role, Tier, Factor - User attributes for permissions and billing
  • Rates - Rate multiplier for billing
  • DNA - Hierarchical path showing user lineage
  • HardLimit, SoftLimit, AutoQuota - Usage limits
  • RPM, RPH, RPD - Request rate limits
  • TPM, TPH, TPD - Token rate limits
  • AllowIPs - IP whitelist
  • AllowModels - Model access whitelist
  • Resources - API endpoint access list
  • ModelLimits - Per-model rate limits
  • CreatedAt, UpdatedAt - Timestamps

Best Practices

  1. Key Management:

    • Rotate keys regularly using the rotation API
    • Use different keys for different environments
    • Monitor key usage through logs

  2. Rate Limiting:

    • Set appropriate limits based on usage patterns
    • Use model-specific limits for expensive models
    • Monitor usage to avoid hitting limits

  3. Access Control:

    • Use IP whitelisting for production environments
    • Restrict model access based on requirements
    • Regularly review and update permissions

  4. Billing:

    • Monitor usage regularly through billing API
    • Set up soft limits for email alerts
    • Use auto-quota for automatic limit adjustments

  5. Error Handling:

    • Implement exponential backoff for retries
    • Handle rate limit errors gracefully
    • Log errors for debugging
For real-time support and updates, join our community channels or contact [email protected]
← Access Control (ACL)
Getting Started with XAPI Free Services →