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

The Swarms API enables you to create and orchestrate AI agents for both single-agent tasks and multi-agent workflows. The platform supports various AI models and provides flexible orchestration patterns for complex problem-solving scenarios.

Key Features

Single Agent Operations: Deploy individual AI agents for specific tasks
Multi-Agent Swarms: Coordinate multiple agents working together
Sequential Workflows: Agents work in ordered sequence, building on previous outputs
Concurrent Workflows: Agents work in parallel for faster processing
Tools Integration: Extend agent capabilities with custom functions
Multiple Model Support: Choose from OpenAI, Anthropic, and Groq models

Getting Started

Prerequisites

Before you begin, ensure you have:

Python 3.7+ or Node.js for JavaScript/TypeScript
An API key from Swarms Platform
Required libraries installed

Installation

Python:

pip install requests python-dotenv

JavaScript/TypeScript:

npm install axios dotenv

Authentication

The API uses API key authentication through the x-api-key header. For OpenAI SDK compatibility, the Authorization: Bearer <your-api-key> header is also accepted. Store your API key securely as an environment variable. Base URL:

Production: https://api.swarms.world

Security Note: Never hardcode API keys in your code. Always use environment variables or secure configuration management.

Single Agent Usage

Single agents are ideal for focused tasks that don’t require collaboration between multiple AI systems.

Basic Health Check

Before making API calls, verify your connection: Python:

import os
import requests
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"
}

response = requests.get(f"{BASE_URL}/health", headers=headers)
print(response.json())

JavaScript/TypeScript:

import axios from 'axios';
import * as dotenv from 'dotenv';

dotenv.config();
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'
};

const response = await axios.get(`${BASE_URL}/health`, { headers });
console.log(response.data);

Creating a Basic Agent

A single agent requires an agent configuration and a task to execute: Python:

def run_single_agent():
    payload = {
        "agent_config": {
            "agent_name": "Research Analyst",
            "description": "An expert in analyzing and synthesizing research data",
            "system_prompt": (
                "You are a Research Analyst with expertise in data analysis and synthesis. "
                "Your role is to analyze provided information, identify key insights, "
                "and present findings in a clear, structured format."
            ),
            "model_name": "claude-sonnet-4-20250514",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 1,
            "auto_generate_prompt": False,
            "tools_list_dictionary": None,
        },
        "task": "What are the key trends in renewable energy adoption?",
    }

    response = requests.post(
        f"{BASE_URL}/v1/agent/completions",
        headers=headers,
        json=payload
    )
    return response.json()

JavaScript/TypeScript:

async function runSingleAgent() {
    const payload = {
        agent_config: {
            agent_name: "Research Analyst",
            description: "An expert in analyzing and synthesizing research data",
            system_prompt: "You are a Research Analyst with expertise in data analysis and synthesis.",
            model_name: "claude-sonnet-4-20250514",
            role: "worker",
            max_loops: 1,
            max_tokens: 8192,
            temperature: 1,
            auto_generate_prompt: false,
            tools_list_dictionary: null
        },
        task: "What are the key trends in renewable energy adoption?"
    };

    const response = await axios.post(
        `${BASE_URL}/v1/agent/completions`,
        payload,
        { headers }
    );
    return response.data;
}

Agent Configuration Parameters

agent_name: Descriptive name for your agent
description: Brief description of the agent’s purpose
system_prompt: Detailed instructions defining the agent’s role and capabilities
model_name: AI model to use (see supported models section)
role: Agent role, typically “worker”
max_loops: Maximum number of processing loops
max_tokens: Maximum response length
temperature: Response creativity (0.0 = deterministic, 1.0 = creative)
auto_generate_prompt: Whether to auto-enhance the system prompt
tools_list_dictionary: Optional tools for extended functionality

Maintaining Conversation History

For multi-turn conversations, include previous messages in the history parameter: Python:

def run_agent_with_history():
    payload = {
        "agent_config": {
            "agent_name": "Conversation Agent",
            "description": "An agent that maintains conversation context",
            "system_prompt": "You are a helpful assistant that maintains context.",
            "model_name": "claude-sonnet-4-20250514",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.7,
            "auto_generate_prompt": False,
        },
        "task": "What's the weather like?",
        "history": [
            {
                "role": "user",
                "content": "I'm planning a trip to New York."
            },
            {
                "role": "assistant",
                "content": "That's great! When are you planning to visit?"
            },
            {
                "role": "user",
                "content": "Next week."
            }
        ]
    }

    response = requests.post(
        f"{BASE_URL}/v1/agent/completions",
        headers=headers,
        json=payload
    )
    return response.json()

Multi-Agent Swarms

Multi-agent swarms enable complex problem-solving by coordinating multiple AI agents. Swarms support two primary workflow types:

Workflow Types

Sequential Workflow: Agents execute in order, with each agent building upon the previous agent’s output. This is ideal for tasks requiring step-by-step processing. Concurrent Workflow: Agents work simultaneously on the same task, providing parallel processing for faster results and diverse perspectives.

Sequential Workflow Example

Sequential workflows are perfect for analysis pipelines where each step depends on the previous one: Python:

def run_sequential_swarm():
    payload = {
        "name": "Financial Analysis Swarm",
        "description": "Market analysis swarm",
        "agents": [
            {
                "agent_name": "Market Analyst",
                "description": "Analyzes market trends",
                "system_prompt": "You are a financial analyst expert specializing in market trend analysis.",
                "model_name": "gpt-4.1-mini",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Economic Forecaster",
                "description": "Predicts economic trends",
                "system_prompt": "You are an expert in economic forecasting. Use the market analysis to provide economic predictions.",
                "model_name": "gpt-4.1-mini",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False
            }
        ],
        "max_loops": 1,
        "swarm_type": "SequentialWorkflow",
        "task": "Analyze the current market conditions and provide economic forecasts."
    }

    response = requests.post(
        f"{BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=payload
    )
    return response.json()

Concurrent Workflow Example

Concurrent workflows are ideal when you need multiple perspectives or parallel processing: Python:

def run_concurrent_swarm():
    payload = {
        "name": "Medical Analysis Swarm",
        "description": "Analyzes medical data concurrently",
        "agents": [
            {
                "agent_name": "Lab Data Analyzer",
                "description": "Analyzes lab report data",
                "system_prompt": "You are a medical data analyst specializing in lab results interpretation.",
                "model_name": "claude-sonnet-4-20250514",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Clinical Specialist",
                "description": "Provides clinical interpretations",
                "system_prompt": "You are an expert in clinical diagnosis and patient care recommendations.",
                "model_name": "claude-sonnet-4-20250514",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False
            }
        ],
        "max_loops": 1,
        "swarm_type": "ConcurrentWorkflow",
        "task": "Analyze these lab results and provide clinical interpretations."
    }

    response = requests.post(
        f"{BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=payload
    )
    return response.json()

Batch Processing

Premium Tier Required: The /v1/swarm/batch/completions endpoint is restricted to Pro, Ultra, and Premium plan subscribers. Upgrade your account to access batch swarm processing.

Process multiple swarms in a single request for improved efficiency: Python:

def run_batch_swarms():
    payload = [
        {
            "name": "Research Swarm",
            "description": "Conducts comprehensive research",
            "agents": [
                {
                    "agent_name": "Research Agent",
                    "description": "Conducts initial research",
                    "system_prompt": "You are a research assistant specializing in comprehensive data gathering.",
                    "model_name": "gpt-4",
                    "role": "worker",
                    "max_loops": 1,
                    "max_tokens": 8192,
                    "temperature": 0.7,
                    "auto_generate_prompt": False
                },
                {
                    "agent_name": "Analysis Agent",
                    "description": "Analyzes research data",
                    "system_prompt": "You are a data analyst who synthesizes research findings.",
                    "model_name": "gpt-4",
                    "role": "worker",
                    "max_loops": 1,
                    "max_tokens": 8192,
                    "temperature": 0.7,
                    "auto_generate_prompt": False
                }
            ],
            "max_loops": 1,
            "swarm_type": "SequentialWorkflow",
            "task": "Research recent AI advancements and provide analysis."
        }
    ]

    response = requests.post(
        f"{BASE_URL}/v1/swarm/batch/completions",
        headers=headers,
        json=payload
    )
    return response.json()

Advanced Features

Tools Integration

Enhance agent capabilities by providing specialized tools. Tools are defined using OpenAPI-style function specifications: Python:

def run_agent_with_tools():
    tools_dictionary = [
        {
            "type": "function",
            "function": {
                "name": "search_topic",
                "description": "Conduct an in-depth search on a specific topic",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "depth": {
                            "type": "integer",
                            "description": "Search depth level (1-3, where 3 is most comprehensive)"
                        },
                        "detailed_queries": {
                            "type": "array",
                            "description": "List of specific search queries to execute",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    "required": ["depth", "detailed_queries"]
                }
            }
        }
    ]

    payload = {
        "agent_config": {
            "agent_name": "Research Assistant",
            "description": "Expert researcher with advanced search capabilities",
            "system_prompt": "You are a research assistant with access to advanced search tools. Use the search_topic function when you need to gather comprehensive information.",
            "model_name": "gpt-4",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.7,
            "auto_generate_prompt": False,
            "tools_list_dictionary": tools_dictionary
        },
        "task": "Research the latest developments in quantum computing and provide a comprehensive analysis."
    }

    response = requests.post(
        f"{BASE_URL}/v1/agent/completions",
        headers=headers,
        json=payload
    )
    return response.json()

Tool Definition Guidelines

When creating tools for your agents:

Clear Names: Use descriptive function names that clearly indicate the tool’s purpose
Detailed Descriptions: Provide comprehensive descriptions of what the tool does
Parameter Specifications: Define all parameters with appropriate types and descriptions
Required Fields: Specify which parameters are mandatory
Usage Context: Include guidance in the system prompt about when to use specific tools

Supported Models

Choose the appropriate model based on your use case requirements:

Some models are restricted to premium-tier accounts. gpt-4.1 and all groq/* models are rejected for free-tier API keys. Call GET /v1/models with your key to see the models available to your tier.

OpenAI Models

gpt-4: High-quality reasoning and complex task handling
gpt-4.1: Optimized version with improved performance (premium tier only)
gpt-4.1-mini: Lightweight version for faster responses

Anthropic Models

claude-sonnet-4-20250514: Balanced performance and reasoning
claude-3-7-sonnet-latest: Latest Claude model with enhanced capabilities

Groq Models (premium tier only)

groq/llama3-70b-8192: High-performance open-source model
groq/deepseek-r1-distill-llama-70b: Specialized reasoning model

Model Selection Guidelines

Complex Analysis: Use GPT-4 or Claude Sonnet 4 for tasks requiring deep reasoning
Fast Responses: Choose gpt-4.1-mini for quick, straightforward tasks
Creative Tasks: Higher temperature settings work better with creative models
Factual Tasks: Lower temperature settings provide more consistent, factual responses

API Reference

Endpoints

Method	Endpoint	Description
`GET`	`/health`	Health check
`POST`	`/v1/agent/completions`	Single agent completions
`POST`	`/v1/agent/batch/completions`	Batch agent completions (premium)
`POST`	`/v1/swarm/completions`	Swarm completions
`POST`	`/v1/swarm/batch/completions`	Batch swarm completions (premium)
`POST`	`/v1/reasoning-agent/completions`	Reasoning agent completions (premium)
`GET`	`/v1/reasoning-agent/types`	List available reasoning agent types
`POST`	`/v1/chat/completions`	OpenAI-compatible chat completions
`POST`	`/v1/batched-grid-workflow/completions`	Batched grid workflow (premium)
`POST`	`/v1/graph-workflow/completions`	Graph workflow (premium)
`GET`	`/v1/swarms/available`	List available swarm types
`GET`	`/v1/models`	List supported models
`GET`	`/v1/models/available`	List available models with metadata
`GET`	`/v1/tools/available`	List available tools
`GET`	`/v1/agents/list`	List your agents
`GET`	`/v1/swarm/logs`	Retrieve your API request logs
`GET`	`/v1/rate/limits`	View your rate limits and usage
`GET`	`/v1/metrics/summary`	Usage metrics summary
`GET`	`/v1/usage/costs`	Usage cost breakdown
`GET`	`/v1/account/credits`	Check your credit balance

Best Practices

Security

Never commit API keys to version control
Use environment variables for all sensitive configuration
Implement proper access controls in production environments
Regularly rotate API keys

Error Handling

Implement robust error handling for production applications: Python:

import time
from tenacity import retry, wait_exponential, stop_after_attempt

@retry(
    wait=wait_exponential(multiplier=1, min=4, max=10),
    stop=stop_after_attempt(3)
)
def make_api_call(payload):
    try:
        response = requests.post(
            f"{BASE_URL}/v1/agent/completions",
            headers=headers,
            json=payload,
            timeout=30
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API call failed: {e}")
        raise

def validate_payload(payload):
    required_fields = ["agent_config", "task"]
    if not all(field in payload for field in required_fields):
        raise ValueError("Missing required fields in payload")
    
    agent_config = payload["agent_config"]
    required_config_fields = ["agent_name", "system_prompt", "model_name"]
    if not all(field in agent_config for field in required_config_fields):
        raise ValueError("Missing required fields in agent_config")

Rate Limiting

Implement exponential backoff for failed requests
Monitor your API usage to stay within limits
Use batch processing when possible to reduce individual request volume

Performance Optimization

Cache responses when appropriate
Use concurrent workflows for independent tasks
Choose the right model for your specific use case
Optimize token usage by being specific in your prompts

Testing Strategy

Start with simple, single-agent tasks
Test with different models to find the best fit
Gradually increase complexity as you understand the system
Implement comprehensive logging for debugging

Troubleshooting

Common Issues

Authentication Errors:

Verify your API key is correct and active
Check that the x-api-key header (or Authorization: Bearer <key>) is properly set
Ensure your API key has the necessary permissions

Timeout Issues:

Increase request timeout values
Consider breaking complex tasks into smaller chunks
Use batch processing for multiple operations

Model Availability:

Check if your requested model is currently available
Have fallback models configured
Monitor model status through the health endpoint

Payload Validation:

Ensure all required fields are present
Validate data types match the expected format
Check that tool definitions follow the correct schema

Getting Help

Community Resources

Documentation: docs.swarms.ai
Discord Community: Join Discord
Technical Blog: Medium

Professional Support

Onboarding Sessions: Book with Kye Gomez
Enterprise Support: Contact through the platform

Stay Updated

Twitter: @kyegomez
LinkedIn: The Swarm Corporation
YouTube: Swarms Channel
Community Events: Sign up here

Conclusion

The Swarms API provides a powerful platform for building sophisticated AI agent systems. Whether you’re working with single agents for focused tasks or orchestrating complex multi-agent workflows, the platform offers the flexibility and tools needed to create effective AI solutions. Start with simple implementations and gradually explore more advanced features like tools integration and multi-agent coordination. The community and documentation resources are available to help you succeed in building powerful agent-based applications.

​Key Features

​Getting Started

​Prerequisites

​Installation

​Authentication

​Single Agent Usage

​Basic Health Check

​Creating a Basic Agent

​Agent Configuration Parameters

​Maintaining Conversation History

​Multi-Agent Swarms

​Workflow Types

​Sequential Workflow Example

​Concurrent Workflow Example

​Batch Processing

​Advanced Features

​Tools Integration

​Tool Definition Guidelines

​Supported Models

​OpenAI Models

​Anthropic Models

​Groq Models (premium tier only)

​Model Selection Guidelines

​API Reference

​Endpoints

​Best Practices

​Security

​Error Handling

​Rate Limiting

​Performance Optimization

​Testing Strategy

​Troubleshooting

​Common Issues

​Getting Help

​Community Resources

​Professional Support

​Stay Updated

​Conclusion

Key Features

Getting Started

Prerequisites

Installation

Authentication

Single Agent Usage

Basic Health Check

Creating a Basic Agent

Agent Configuration Parameters

Maintaining Conversation History

Multi-Agent Swarms

Workflow Types

Sequential Workflow Example

Concurrent Workflow Example

Batch Processing

Advanced Features

Tools Integration

Tool Definition Guidelines

Supported Models

OpenAI Models

Anthropic Models

Groq Models (premium tier only)

Model Selection Guidelines

API Reference

Endpoints

Best Practices

Security

Error Handling

Rate Limiting

Performance Optimization

Testing Strategy

Troubleshooting

Common Issues

Getting Help

Community Resources

Professional Support

Stay Updated

Conclusion