Authentication

All API requests require authentication using JWT tokens or API keys. Include your credentials in the request headers.

Register a New User

# Request body
{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "SecureP@ssw0rd"
}

Login and Get Token

# Request body
{
  "email": "john@example.com",
  "password": "SecureP@ssw0rd"
}

# Response
{
  "code": 200,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

Using Authentication

# Include token in Authorization header
GET /v1/models
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Or use API Key
GET /v1/models
X-API-Key: your-api-key-here

Core API Endpoints

AI Model Management

Retrieve a paginated list of all AI models with filtering and sorting capabilities.

# Example with query parameters
GET /v1/models?page=1&page_size=20&provider=openai&sort=created_at

# Response
[
  {
    "id": "gpt-4o",
    "name": "GPT-4o",
    "provider": "openai",
    "family": "gpt-4o",
    "family_name": "GPT-4o Plus",
    "family_default": true,
    "context_window": 128000,
    "input_price_per_million": 5.0,
    "output_price_per_million": 15.0
  }
]

Provider Information

Get comprehensive information about all supported AI model providers.

# Get all providers
GET /v1/providers

# Get specific provider details
GET /v1/providers/{provider_id}

API Key Management

Create and manage API keys for programmatic access.

# Create new API key
{
  "name": "Production Key",
  "permissions": ["models:read", "providers:read"],
  "expires_at": "2025-12-31T23:59:59Z"
}

# List all API keys
GET /v1/apikeys

# Revoke an API key
DELETE /v1/apikeys/{key_id}

Leaderboard & Rankings

Access model rankings and performance comparisons.

Rate Limiting & Best Practices

• Default rate limit: 1000 requests/hour per API key
• Use pagination to retrieve large datasets efficiently
• Implement exponential backoff for retries on 429 responses
• Cache frequently accessed data to reduce API calls
• Monitor your usage via the /v1/usage endpoint

Response Format

ModelMeta API uses a streamlined response format:

• Query Endpoints: Return data directly (as shown in examples above) for better performance and SDK compatibility.
• Mutation Endpoints: Return a wrapper for status confirmation:

{
  "code": 200,           // HTTP status code
  "message": "Success", // Status message
  "data": {...}         // Response payload (if any)
}

Error Handling

Common HTTP status codes and their meanings:

• 200 OK - Request successful
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource doesn't exist
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server-side issue