AimableDocs
DocsAPI Reference

Models

Models

The Models domain in the Aimable Platform API provides access to a global catalog of AI models available for use across integrated applications. These models represent various large language models (LLMs) from different providers, each with unique capabilities, context windows, and features.

Understanding which models are available—and their characteristics—is essential for building dynamic AI-powered applications. The Models API allows you to discover, inspect, and select the right model for your use case, such as chat, reasoning, code generation, or content summarization.

Key Concepts

  • Model: A standardized entry in the global catalog representing an AI model. Each has a unique id, a display_name, and metadata like context_window and capabilities.
  • Provider Slug: Identifies the underlying provider (e.g., openai, anthropic, google). This helps you understand where the model runs.
  • Capabilities: A list of strings (e.g., "reasoning", "vision", "function_calling") indicating what the model supports.
  • Pagination: The list endpoint uses cursor-based pagination via limit and cursor parameters to handle large result sets efficiently.

Endpoints

List All Models

Retrieve a paginated list of available models.

GET /api-proxy/v1/models

curl -X GET "https://api.aimable.com/api-proxy/v1/models?limit=5" \
  -H "X-API-Key: your_api_key_here"

Response (200 OK):

{
  "data": [
    {
      "id": "claude-3-opus-20240229",
      "display_name": "Claude 3 Opus",
      "provider_slug": "anthropic",
      "context_window": 200000,
      "capabilities": ["reasoning", "vision", "function_calling"],
      "is_active": true,
      "logo_url": {
        "png": "https://cdn.aimable.com/logos/anthropic.png",
        "svg": "https://cdn.aimable.com/logos/anthropic.svg"
      }
    }
  ],
  "meta": {
    "next_cursor": "cursor_abc123",
    "has_more": true
  }
}

Use next_cursor in subsequent requests to fetch more models:

GET /api-proxy/v1/models?limit=5&cursor=cursor_abc123

Get a Specific Model

Fetch detailed information about a single model by its ID.

GET /api-proxy/v1/models/{model_id}

curl -X GET "https://api.aimable.com/api-proxy/v1/models/claude-3-opus-20240229" \
  -H "X-API-Key: your_api_key_here"

Response (200 OK):

{
  "data": {
    "id": "claude-3-opus-20240229",
    "display_name": "Claude 3 Opus",
    "provider_slug": "anthropic",
    "context_window": 200000,
    "capabilities": ["reasoning", "vision"],
    "reasoning": {
      "type": "chain-of-thought"
    },
    "is_active": true
  }
}

Note: The response does not include provider-specific internal IDs (like model_id on Anthropic or OpenAI), ensuring abstraction and portability.

Common Workflows

1. Discover Models with Specific Capabilities

First, list models and filter by capability:

GET /api-proxy/v1/models?limit=10

In your application:

# Pseudocode: Find all models that support 'reasoning'
reasoning_models = [m for m in response['data'] if 'reasoning' in m.get('capabilities', [])]

Then use one of these models in downstream AI operations.

2. Build a Model Selector UI

Use the display_name, logo_url, and capabilities to create a user-facing model picker in your app:

  • Show logos using logo_url (light mode) and logo_url_dark (dark mode).
  • Highlight features like “Advanced Reasoning” if reasoning object exists.
  • Disable inactive models where is_active == false.

3. Paginate Through Large Model Catalogs

For apps that need full catalog sync:

# First request
GET /api-proxy/v1/models?limit=50
 
# Then continue with cursor
GET /api-proxy/v1/models?limit=50&cursor=next_cursor_value

Continue until "has_more": false.

Authentication & Error Handling

All endpoints require authentication via the X-API-Key header.

Required Header:

X-API-Key: <your_api_key>

Common Errors:

| Status | Meaning | |-------|--------| | 401 Unauthorized | Missing or invalid API key | | 403 Forbidden | API key lacks required permissions | | 422 Unprocessable Entity | Invalid model_id format or malformed query parameters |

Example 422 response:

{
  "detail": [
    {
      "loc": ["path", "model_id"],
      "msg": "Input should be a valid UUID",
      "type": "uuid_type",
      "input": "invalid-id"
    }
  ]
}

Validate inputs before calling the API, especially when using dynamic model_id values.

By leveraging the Models API, you can dynamically adapt your application to available AI backends, support feature-aware model selection, and future-proof integrations as new models are added to the platform.

Related Endpoints