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

Explore all available swarm architectures supported by the Swarms API. The /v1/swarms/available endpoint provides information about different swarm types, their capabilities, and use cases.

Different swarm types are optimized for different workflows - choose the right architecture for your specific needs.

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_swarm_types():
    """Get all available swarm types"""
    response = requests.get(
        f"{BASE_URL}/v1/swarms/available",
        headers=headers
    )

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

# Get swarm types
swarm_data = get_swarm_types()
if swarm_data:
    print("✅ Swarm types retrieved successfully!")
    print(json.dumps(swarm_data, indent=2))

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 getSwarmTypes() {
    try {
        const response = await fetch(`${BASE_URL}/v1/swarms/available`, {
            method: 'GET',
            headers: headers
        });

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

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

// Get swarm types
getSwarmTypes();

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

# Example response (truncated — swarm_types_metadata has one entry per
# swarm_type with name, description, category, best_for, parameters and
# documentation_url; see "Understanding the Response" below):
# {
#   "status": true,
#   "timestamp": "2026-07-13T19:37:41.821232",
#   "swarm_types": [
#     "AgentRearrange",
#     "MixtureOfAgents",
#     "SequentialWorkflow",
#     "ConcurrentWorkflow",
#     "GroupChat",
#     "MultiAgentRouter",
#     "HierarchicalSwarm",
#     "MajorityVoting",
#     "CouncilAsAJudge",
#     "HeavySwarm",
#     "LLMCouncil",
#     "DebateWithJudge",
#     "RoundRobin",
#     "PlannerWorkerSwarm"
#   ],
#   "swarm_types_metadata": [
#     {
#       "swarm_type": "AgentRearrange",
#       "name": "Agent Rearrange",
#       "description": "Runs agents according to an explicit flow you define with `rearrange_flow`, supporting sequential (`->`) and concurrent (`,`) steps so you can reorganize how agents pass work to one another.",
#       "category": "routing",
#       "best_for": [
#         "Custom execution graphs mixing sequential and parallel stages",
#         "Reorganizing a pipeline without changing the agents themselves",
#         "Fine-grained control over which agents run when"
#       ],
#       "parameters": ["rearrange_flow"],
#       "documentation_url": "https://docs.swarms.ai/docs/documentation/multi-agent/agent_rearrange"
#     }
#     # ...one entry for each of the 14 swarm_types
#   ]
# }

swarm_types is a flat list of the 14 identifiers you pass as swarm_type in a SwarmSpec. swarm_types_metadata carries the same 14 types with rich metadata: name, description, category (workflow, collaboration, routing, judgment, or auto), best_for (representative use cases), parameters (swarm-type-specific SwarmSpec fields beyond the common agents/task/max_loops), and documentation_url (null for types without a dedicated docs page).

Swarm Type Selection Guide

For Different Use Cases

Complex Problem Solving
Step-by-Step Processes
Parallel Processing
Dynamic Optimization

# Use MixtureOfAgents for diverse expertise
swarm_config = {
    "name": "Research Swarm",
    "description": "Multi-disciplinary research team",
    "agents": [
        {
            "agent_name": "Data Analyst",
            "model_name": "gpt-4.1",
            "role": "analyst"
        },
        {
            "agent_name": "Domain Expert",
            "model_name": "gpt-4.1",
            "role": "expert"
        }
    ],
    "swarm_type": "MixtureOfAgents",
    "task": "Analyze market trends and provide strategic recommendations"
}

# Use SequentialWorkflow for ordered tasks
swarm_config = {
    "name": "Content Creation Pipeline",
    "description": "Structured content creation process",
    "agents": [
        {
            "agent_name": "Researcher",
            "model_name": "gpt-4.1-mini",
            "role": "research"
        },
        {
            "agent_name": "Writer",
            "model_name": "gpt-4.1",
            "role": "writing"
        },
        {
            "agent_name": "Editor",
            "model_name": "gpt-4.1-mini",
            "role": "editing"
        }
    ],
    "swarm_type": "SequentialWorkflow",
    "task": "Create a comprehensive article about AI ethics"
}

# Use ConcurrentWorkflow for independent tasks
swarm_config = {
    "name": "Data Processing Swarm",
    "description": "Parallel data analysis",
    "agents": [
        {
            "agent_name": "Data Processor 1",
            "model_name": "gpt-4.1-mini"
        },
        {
            "agent_name": "Data Processor 2",
            "model_name": "gpt-4.1-mini"
        },
        {
            "agent_name": "Data Processor 3",
            "model_name": "gpt-4.1-mini"
        }
    ],
    "swarm_type": "ConcurrentWorkflow",
    "tasks": [
        "Process dataset A",
        "Process dataset B",
        "Process dataset C"
    ]
}

# Use AgentRearrange for adaptive workflows
swarm_config = {
    "name": "Adaptive Analysis Swarm",
    "description": "Self-optimizing agent arrangement",
    "agents": [
        {
            "agent_name": "Primary Analyst",
            "model_name": "gpt-4.1"
        },
        {
            "agent_name": "Secondary Analyst",
            "model_name": "gpt-4.1-mini"
        }
    ],
    "swarm_type": "AgentRearrange",
    "rearrange_flow": "Primary Analyst -> Secondary Analyst",
    "task": "Analyze complex business data"
}

Swarm Type Comparison

The /v1/swarms/available endpoint currently returns 14 swarm types (the swarm_type value, its category, and the first best_for use case from swarm_types_metadata):

Swarm Type	Category	Best For	Type-Specific Parameters
AgentRearrange	routing	Custom execution graphs mixing sequential and parallel stages	`rearrange_flow`
MixtureOfAgents	collaboration	Complex tasks that benefit from multiple expert perspectives	—
SequentialWorkflow	workflow	Multi-stage pipelines where each step builds on the previous	—
ConcurrentWorkflow	workflow	Independent subtasks that do not depend on one another	—
GroupChat	collaboration	Brainstorming and open-ended discussion	—
MultiAgentRouter	routing	Routing heterogeneous requests to the right specialist	—
HierarchicalSwarm	collaboration	Large tasks that need decomposition and coordination	`director_model_name`, `director_settings`
MajorityVoting	judgment	Reducing variance and hallucination through consensus	—
CouncilAsAJudge	judgment	Evaluating, scoring or grading outputs	`council_judge_model_name`
HeavySwarm	collaboration	Deep, thorough analysis of complex questions	`heavy_swarm_question_agent_model_name`, `heavy_swarm_worker_model_name`, `heavy_swarm_variant`, `heavy_swarm_max_loops`
LLMCouncil	judgment	Deliberative decision-making	`chairman_model`
DebateWithJudge	judgment	Exploring trade-offs from multiple sides	—
RoundRobin	workflow	Evenly distributing turns across agents	—
PlannerWorkerSwarm	collaboration	Tasks that benefit from explicit planning before execution	—

swarm_type: "auto" and swarm_type: "SpreadSheetSwarm" are rejected with a 400 error (“…are not supported currently”) by /v1/swarm/completions — always pass one of the 14 types above.

Advanced Swarm Configuration

Hierarchical Swarm
Group Chat Swarm

swarm_config = {
    "name": "Corporate Analysis Department",
    "description": "Hierarchical corporate structure",
    "agents": [
        {
            "agent_name": "CEO Agent",
            "model_name": "gpt-4.1",
            "role": "executive"
        },
        {
            "agent_name": "Manager Agent",
            "model_name": "gpt-4.1",
            "role": "manager"
        },
        {
            "agent_name": "Analyst Agent 1",
            "model_name": "gpt-4.1-mini",
            "role": "analyst"
        },
        {
            "agent_name": "Analyst Agent 2",
            "model_name": "gpt-4.1-mini",
            "role": "analyst"
        }
    ],
    "swarm_type": "HierarchicalSwarm",
    "task": "Conduct comprehensive market analysis"
}

swarm_config = {
    "name": "Brainstorming Session",
    "description": "Interactive group discussion",
    "agents": [
        {
            "agent_name": "Moderator",
            "model_name": "gpt-4.1",
            "role": "moderator"
        },
        {
            "agent_name": "Creative Thinker",
            "model_name": "gpt-4.1",
            "role": "creative"
        },
        {
            "agent_name": "Technical Expert",
            "model_name": "gpt-4.1",
            "role": "technical"
        },
        {
            "agent_name": "Business Analyst",
            "model_name": "gpt-4.1-mini",
            "role": "business"
        }
    ],
    "swarm_type": "GroupChat",
    "messages": [
        {"role": "user", "content": "Let's brainstorm innovative product ideas"},
        {"role": "user", "content": "What are the technical challenges?"},
        {"role": "user", "content": "How can we monetize this?"}
    ],
    "task": "Brainstorm and evaluate new product concepts"
}

Swarm Performance Optimization

Load Balancing
Cost Optimization
Quality Optimization

def optimize_swarm_for_load(tasks, available_resources):
    """Optimize swarm configuration based on load"""
    task_count = len(tasks)
    resource_count = len(available_resources)

    if task_count > resource_count * 2:
        # High load - run every task in parallel via the "tasks" list
        return {
            "swarm_type": "ConcurrentWorkflow",
            "tasks": tasks
        }
    elif task_count > resource_count:
        # Medium load - use mixture of agents
        return {
            "swarm_type": "MixtureOfAgents"
        }
    else:
        # Low load - use sequential for quality
        return {
            "swarm_type": "SequentialWorkflow"
        }

def optimize_swarm_for_cost(task_complexity, budget_limit):
    """Optimize swarm for cost efficiency"""
    # model_name and max_tokens are per-agent settings — apply them to
    # every entry in the payload's "agents" list.
    if budget_limit < 0.1:  # Very low budget
        return {
            "swarm_type": "ConcurrentWorkflow",
            "agents": [
                {"agent_name": "Worker", "model_name": "gpt-4.1-mini", "max_tokens": 512}
            ]
        }
    elif budget_limit < 0.5:  # Medium budget
        return {
            "swarm_type": "SequentialWorkflow",
            "agents": [
                {"agent_name": "Worker", "model_name": "gpt-4.1-mini"}
            ]
        }
    else:  # High budget
        return {
            "swarm_type": "MixtureOfAgents",
            "agents": [
                {"agent_name": "Expert", "model_name": "gpt-4.1"}
            ]
        }

def optimize_swarm_for_quality(requirements):
    """Optimize swarm for maximum quality"""
    if requirements.get("consensus_required"):
        # Use an odd number of agents in the payload's "agents" list
        # so MajorityVoting can always reach a decision
        return {
            "swarm_type": "MajorityVoting"
        }
    elif requirements.get("iterative_improvement"):
        return {
            "swarm_type": "AgentRearrange",
            "max_loops": 3
        }
    else:
        return {
            "swarm_type": "MixtureOfAgents"
        }

Best Practices

Swarm Design

Match Type to Task: Choose swarm type based on your specific requirements
Agent Diversity: Use diverse agents with different expertise areas
Clear Roles: Define clear roles and responsibilities for each agent
Communication Protocols: Establish clear communication patterns

Performance Optimization

Resource Allocation: Allocate resources based on task complexity
Load Balancing: Distribute work evenly across agents
Monitoring: Monitor swarm performance and adjust configuration
Scalability: Design swarms that can scale with increased load

Quality Assurance

Testing: Test swarm configurations with sample tasks
Validation: Validate outputs against expected results
Feedback Loops: Implement feedback mechanisms for improvement
Version Control: Track swarm configuration versions

Cost Management

Model Selection: Choose appropriate models based on task requirements
Resource Limits: Set appropriate limits to control costs
Usage Monitoring: Monitor resource usage and costs
Optimization: Continuously optimize for cost efficiency

Getting Started

MCP Server Tutorials

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 Swarm Types

Quick Start

Swarm Type Selection Guide

For Different Use Cases

Swarm Type Comparison

Advanced Swarm Configuration

Swarm Performance Optimization

Best Practices

Swarm Design

Performance Optimization

Quality Assurance

Cost Management

​Quick Start

​Swarm Type Selection Guide

​For Different Use Cases

​Swarm Type Comparison

​Advanced Swarm Configuration

​Swarm Performance Optimization

​Best Practices

​Swarm Design

​Performance Optimization

​Quality Assurance

​Cost Management

Quick Start

Swarm Type Selection Guide

For Different Use Cases

Swarm Type Comparison

Advanced Swarm Configuration

Swarm Performance Optimization

Best Practices

Swarm Design

Performance Optimization

Quality Assurance

Cost Management