Swarms API Documentation - Build AI Agents & Multi-Agent Systems

Get a comprehensive list of all AI models available through the Swarms API. This endpoint provides information about supported models from various providers including OpenAI, Anthropic, Groq, and others.

The /v1/models/available endpoint returns all models currently supported by the Swarms API, including their capabilities and limitations.

Quick Start

Python
JavaScript
cURL

import requests
import json
import os
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

def get_available_models():
    """Get all available models"""
    response = requests.get(
        f"{BASE_URL}/v1/models/available",
        headers=headers
    )

    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return None

# Get available models
models_data = get_available_models()
if models_data:
    print("✅ Available models retrieved successfully!")
    print(models_data)
    print(f"Model count: {models_data['count']}")

const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";

const headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
};

async function getAvailableModels() {
    try {
        const response = await fetch(`${BASE_URL}/v1/models/available`, {
            method: 'GET',
            headers: headers
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        console.log("✅ Available models retrieved successfully!");
        console.log(JSON.stringify(data, null, 2));
        return data;
    } catch (error) {
        console.error('Error:', error);
        return null;
    }
}

// Get available models
getAvailableModels();

# Get available models
curl -X GET "https://api.swarms.world/v1/models/available" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json"

# Example response:
# {
#   "success": true,
#   "count": 42,
#   "models": [
#     "gpt-4.1",
#     "gpt-4.1-mini",
#     "gpt-4-turbo",
#     "claude-sonnet-4-20250514",
#     "claude-haiku-3.5",
#     "groq/llama-3.1-70b-versatile",
#     "openrouter/aion-labs/aion-3.0"
#   ]
# }

Understanding the Response

The models endpoint returns a flat list of all available model identifiers, filtered by your subscription tier:

{
  "success": true,
  "count": 42,
  "models": [
    "gpt-4.1",
    "gpt-4.1-mini",
    "gpt-4-turbo",
    "gpt-4",
    "gpt-3.5-turbo",
    "claude-sonnet-4-20250514",
    "claude-haiku-3.5",
    "groq/llama-3.1-70b-versatile",
    "groq/llama-3.1-8b-instant"
  ]
}

Field	Type	Description
`success`	boolean	Whether the request succeeded
`count`	integer	Number of models in the `models` list
`models`	array of strings	Flat list of available model identifiers, filtered by your subscription tier (free tier accounts won’t see premium or Groq models)

By default, this list also includes models fetched live from OpenRouter (cached for 5 minutes) and prefixed with openrouter/ (e.g. openrouter/aion-labs/aion-3.0). The base catalog is precomputed and cached server-side, so this endpoint is cheap to call.

OpenAI-Compatible Model List

If you use the OpenAI SDK (or any client that discovers models via GET /v1/models), the same tier-filtered catalog is available in the standard OpenAI list format:

Python
cURL

from openai import OpenAI

client = OpenAI(
    api_key=API_KEY,
    base_url="https://api.swarms.world/v1",
)

models = client.models.list()
print(f"{len(models.data)} models available")
for model in models.data[:10]:
    print(f"{model.id} (owned_by: {model.owned_by})")

curl -X GET "https://api.swarms.world/v1/models" \
  -H "x-api-key: your-api-key"

# Example response:
# {
#   "object": "list",
#   "data": [
#     {"id": "gpt-4.1", "object": "model", "created": 0, "owned_by": "openai"},
#     {"id": "claude-sonnet-4-20250514", "object": "model", "created": 0, "owned_by": "anthropic"}
#   ]
# }

Each entry has id (the model identifier you pass as model_name or model), object (always "model"), created, and owned_by (the resolved provider, e.g. openai, anthropic). See the OpenAI-Compatible Endpoint reference for using these models with the OpenAI SDK.

Model Selection Guide

For Text Generation

Creative Tasks
Analytical Tasks
Fast Responses

# Best for creative writing, brainstorming, content generation
recommended_models = [
    "gpt-4.1",                    # Most capable, balanced performance
    "claude-sonnet-4-20250514", # Excellent for creative tasks
    "gpt-4.1-mini"               # Fast and cost-effective
]

# Best for analysis, reasoning, complex problem-solving
recommended_models = [
    "gpt-4.1",                    # Superior reasoning capabilities
    "claude-sonnet-4-20250514", # Strong analytical performance
    "gpt-4-turbo"               # Good balance of speed and capability
]

# Best for quick responses, simple tasks, cost optimization
recommended_models = [
    "gpt-4.1-mini",              # Fastest and most cost-effective
    "llama-3.1-8b-instant",     # Very fast inference
    "claude-haiku-3.5"         # Fast with good quality
]

Model Capabilities

Vision Models
Streaming Models
Large Context Models

# Models that support image analysis
vision_models = [
    "gpt-4.1",           # Best vision capabilities
    "gpt-4-turbo",      # Good vision support
    "gpt-4.1-mini"      # Basic vision support
]

# Example: Vision-enabled agent
payload = {
    "agent_config": {
        "agent_name": "Vision Analyst",
        "model_name": "gpt-4.1",  # Vision-capable model
        "max_tokens": 2048
    },
    "task": "Describe this image in detail",
    "img": "https://example.com/image.jpg"
}

# Models that support streaming responses
streaming_models = [
    "gpt-4.1",
    "gpt-4.1-mini",
    "claude-sonnet-4-20250514",
    "claude-haiku-3.5"
]

# Example: Streaming-enabled agent
payload = {
    "agent_config": {
        "agent_name": "Streaming Writer",
        "model_name": "gpt-4.1",
        "streaming_on": True,  # Enable streaming
        "max_tokens": 2048
    },
    "task": "Write a creative story"
}

# Models with large context windows
large_context_models = [
    "gpt-4.1",                    # 128k+ tokens
    "claude-sonnet-4-20250514", # 200k+ tokens
    "gpt-4-turbo",             # 128k tokens
]

# Example: Large document analysis
payload = {
    "agent_config": {
        "agent_name": "Document Analyst",
        "model_name": "gpt-4.1",  # Large context
        "max_tokens": 4096
    },
    "task": "Analyze this 50-page document and provide insights"
}

Dynamic Model Selection

Python
JavaScript

def select_best_model(task_type, priority="balanced"):
    """
    Dynamically select the best model based on task type and priority

    Args:
        task_type: Type of task ("creative", "analytical", "fast", "vision")
        priority: Priority ("quality", "speed", "cost", "balanced")
    """
    # Get available models first
    models_data = get_available_models()
    if not models_data or not models_data.get("success"):
        return "gpt-4.1-mini"  # Fallback

    available_models = models_data.get("models", [])

    # Model selection logic
    if task_type == "creative":
        if priority == "quality":
            return "gpt-4.1" if "gpt-4.1" in available_models else "claude-sonnet-4-20250514"
        elif priority == "speed":
            return "gpt-4.1-mini" if "gpt-4.1-mini" in available_models else "claude-haiku-3.5"
        else:  # balanced
            return "gpt-4.1-mini"

    elif task_type == "analytical":
        return "gpt-4.1" if "gpt-4.1" in available_models else "claude-sonnet-4-20250514"

    elif task_type == "fast":
        return "gpt-4.1-mini" if "gpt-4.1-mini" in available_models else "llama-3.1-8b-instant"

    elif task_type == "vision":
        return "gpt-4.1" if "gpt-4.1" in available_models else "gpt-4-turbo"

    return "gpt-4.1-mini"  # Default fallback

# Example usage
best_model = select_best_model("creative", "quality")
print(f"Selected model: {best_model}")

function selectBestModel(taskType, priority = "balanced") {
    // Model selection logic for JavaScript
    const modelPreferences = {
        creative: {
            quality: ["gpt-4.1", "claude-sonnet-4-20250514"],
            speed: ["gpt-4.1-mini", "claude-haiku-3.5"],
            balanced: ["gpt-4.1-mini"],
            cost: ["gpt-4.1-mini", "llama-3.1-8b-instant"]
        },
        analytical: {
            quality: ["gpt-4.1", "claude-sonnet-4-20250514"],
            speed: ["gpt-4-turbo"],
            balanced: ["gpt-4.1"],
            cost: ["gpt-4.1-mini"]
        },
        fast: {
            quality: ["gpt-4.1-mini"],
            speed: ["gpt-4.1-mini", "llama-3.1-8b-instant"],
            balanced: ["gpt-4.1-mini"],
            cost: ["gpt-4.1-mini", "llama-3.1-8b-instant"]
        },
        vision: {
            quality: ["gpt-4.1"],
            speed: ["gpt-4.1-mini"],
            balanced: ["gpt-4.1"],
            cost: ["gpt-4-turbo"]
        }
    };

    const candidates = modelPreferences[taskType]?.[priority] || ["gpt-4.1-mini"];
    return candidates[0]; // Return first preference
}

// Example usage
const bestModel = selectBestModel("creative", "quality");
console.log(`Selected model: ${bestModel}`);

Model Performance Comparison

Model	Context Window	Best For	Speed	Cost
`gpt-4.1`	128k+	Complex reasoning, vision	Medium	High
`gpt-4.1-mini`	128k+	General purpose, fast tasks	Fast	Low
`claude-sonnet-4-20250514`	200k+	Creative writing, analysis	Medium	High
`claude-haiku-3.5`	200k+	Fast responses	Fast	Low
`llama-3.1-70b`	128k	Complex tasks	Medium	Medium
`llama-3.1-8b`	128k	Simple tasks	Fast	Low

Cost Optimization

Python
JavaScript

def optimize_model_selection(task_complexity, budget_constraint):
    """
    Select optimal model based on task complexity and budget
    """
    if task_complexity == "low":
        return "gpt-4.1-mini" if budget_constraint == "strict" else "llama-3.1-8b-instant"
    elif task_complexity == "medium":
        return "gpt-4.1-mini" if budget_constraint == "strict" else "gpt-4.1"
    else:  # high complexity
        return "claude-sonnet-4-20250514" if budget_constraint == "flexible" else "gpt-4.1"

# Example usage
model = optimize_model_selection("high", "flexible")
print(f"Optimized model: {model}")

function optimizeModelSelection(taskComplexity, budgetConstraint) {
    const optimizationMatrix = {
        low: {
            strict: "gpt-4.1-mini",
            flexible: "llama-3.1-8b-instant"
        },
        medium: {
            strict: "gpt-4.1-mini",
            flexible: "gpt-4.1"
        },
        high: {
            strict: "gpt-4.1",
            flexible: "claude-sonnet-4-20250514"
        }
    };

    return optimizationMatrix[taskComplexity]?.[budgetConstraint] || "gpt-4.1-mini";
}

// Example usage
const model = optimizeModelSelection("high", "flexible");
console.log(`Optimized model: ${model}`);

Error Handling

Python
JavaScript

def get_available_models_with_fallback():
    """Get available models with proper error handling"""
    try:
        response = requests.get(
            f"{BASE_URL}/v1/models/available",
            headers=headers,
            timeout=10
        )

        if response.status_code == 200:
            data = response.json()
            if data.get("success"):
                return data.get("models", [])
            else:
                print("❌ API returned success=false")
                return []
        elif response.status_code == 401:
            print("❌ Authentication failed. Check your API key.")
            return []
        elif response.status_code == 429:
            print("❌ Rate limit exceeded. Please wait before retrying.")
            return []
        else:
            print(f"❌ HTTP {response.status_code}: {response.text}")
            return []

    except requests.exceptions.Timeout:
        print("❌ Request timed out")
        return []
    except requests.exceptions.ConnectionError:
        print("❌ Connection error")
        return []
    except Exception as e:
        print(f"❌ Unexpected error: {e}")
        return []

# Use with fallback
models = get_available_models_with_fallback()
if models:
    print(f"Available models: {len(models)}")

async function getAvailableModelsWithFallback() {
    try {
        const controller = new AbortController();
        const timeoutId = setTimeout(() => controller.abort(), 10000);

        const response = await fetch(`${BASE_URL}/v1/models/available`, {
            method: 'GET',
            headers: headers,
            signal: controller.signal
        });

        clearTimeout(timeoutId);

        if (!response.ok) {
            if (response.status === 401) {
                console.log("❌ Authentication failed. Check your API key.");
            } else if (response.status === 429) {
                console.log("❌ Rate limit exceeded. Please wait before retrying.");
            } else {
                console.log(`❌ HTTP ${response.status}: ${await response.text()}`);
            }
            return [];
        }

        const data = await response.json();

        if (!data.success) {
            console.log("❌ API returned success=false");
            return [];
        }

        return data.models || [];

    } catch (error) {
        if (error.name === 'AbortError') {
            console.log("❌ Request timed out");
        } else if (error.name === 'TypeError') {
            console.log("❌ Connection error");
        } else {
            console.log(`❌ Unexpected error: ${error.message}`);
        }
        return [];
    }
}

// Use with fallback
getAvailableModelsWithFallback().then(models => {
    if (models.length > 0) {
        console.log(`Available models: ${models.length}`);
    }
});

Best Practices

Cache Results: Cache the models list to avoid frequent API calls
Handle Changes: Models may be added or removed over time
Fallback Logic: Always have fallback models for reliability
Version Awareness: Be aware of model versioning and deprecation
Cost Monitoring: Track usage costs for different models
Performance Testing: Test model performance for your specific use cases
Documentation Review: Check model-specific limitations and capabilities

Integration Examples

Model Selection in Agent Creation

def create_agent_with_best_model(task_type):
    """Create an agent with the best available model for the task"""
    models = get_available_models()
    best_model = select_best_model(task_type)

    return {
        "agent_config": {
            "agent_name": f"{task_type.title()} Agent",
            "model_name": best_model,
            "max_tokens": 2048,
            "temperature": 0.7
        },
        "task": f"Perform {task_type} task"
    }

Batch Processing with Model Optimization

def optimize_batch_processing(tasks):
    """Optimize model selection for batch processing"""
    optimized_payloads = []

    for task in tasks:
        task_type = classify_task(task)
        best_model = select_best_model(task_type, "cost")
        optimized_payloads.append({
            "agent_config": {
                "agent_name": f"Optimized Agent {len(optimized_payloads) + 1}",
                "model_name": best_model,
                "max_tokens": 1024
            },
            "task": task
        })

    return optimized_payloads

Getting Started

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

Available Models

Quick Start

Understanding the Response

OpenAI-Compatible Model List

Model Selection Guide

For Text Generation

Model Capabilities

Dynamic Model Selection

Model Performance Comparison

Cost Optimization

Error Handling

Best Practices

Integration Examples

Model Selection in Agent Creation

Batch Processing with Model Optimization

​Quick Start

​Understanding the Response

​OpenAI-Compatible Model List

​Model Selection Guide

​For Text Generation

​Model Capabilities

​Dynamic Model Selection

​Model Performance Comparison

​Cost Optimization

​Error Handling

​Best Practices

​Integration Examples

​Model Selection in Agent Creation

​Batch Processing with Model Optimization

Quick Start

Understanding the Response

OpenAI-Compatible Model List

Model Selection Guide

For Text Generation

Model Capabilities

Dynamic Model Selection

Model Performance Comparison

Cost Optimization

Error Handling

Best Practices

Integration Examples

Model Selection in Agent Creation

Batch Processing with Model Optimization