Skip to main content
The Swarms API provides powerful multi-agent orchestration capabilities, enabling you to build complex systems where multiple AI agents collaborate to solve problems. Each multi-agent architecture type is designed for specific use cases and can be combined to create powerful multi-agent systems.

​
Swarm Completions Endpoint

The /v1/swarm/completions endpoint is the primary API for executing multi-agent swarm workflows. This endpoint supports both standard and streaming responses, allowing you to orchestrate complex multi-agent systems. Endpoint: POST /v1/swarm/completions Base URL: https://api.swarms.world

​
Authentication

All requests require an API key in the header:

​
Input Parameters

The request body uses the SwarmSpec schema. All parameters are organized in the tables below:

​
Swarm Configuration Parameters

​
Agent Configuration Parameters (AgentSpec)

Each agent in the agents array can be configured with the following parameters:

​
MCP Connection Configuration Parameters

​
Multiple MCP Connections

​
Output Parameters

The endpoint returns a SwarmCompletion object with the following parameters:

​
Swarm Architectures

Each multi-agent architecture type is designed for specific use cases and can be combined to create powerful multi-agent systems. Below is a comprehensive table of all available swarm architectures with links to their detailed documentation:

​
Best Practices

This section outlines production-grade best practices for using the Swarms API effectively. These guidelines will help you choose the right swarm architecture, optimize costs, and implement robust error handling in your multi-agent systems.

​
Choosing the Right Swarm Architecture

Selecting the optimal swarm architecture is crucial for achieving your desired outcomes. Start by analyzing your task complexity: complex tasks benefit from HierarchicalSwarm or MultiAgentRouter. For dynamic tasks that require adaptive processing, consider AgentRearrange. When evaluating workflow patterns, use SequentialWorkflow for linear processes where each step depends on the previous one, ConcurrentWorkflow for parallel operations that can run independently, and GroupChat for collaborative tasks requiring interactive problem-solving. For multi-domain expertise requirements, MixtureOfAgents combines diverse specialist agents effectively, while MajorityVoting provides consensus-based decision-making for quality assurance needs. Different applications have specific swarm recommendations. Team automation systems excel with HierarchicalSwarm, providing automated team coordination with clear responsibility chains and scalable structures. Research pipelines benefit from SequentialWorkflow, ensuring structured processes with quality control at each stage. Trading systems leverage ConcurrentWorkflow for multi-market coverage and real-time analysis with risk distribution. Content factories utilize MixtureOfAgents for automated content creation with consistent quality and high throughput. Industry-specific patterns also guide architecture selection. In finance, risk analysis uses HierarchicalSwarm, market research employs MixtureOfAgents, and trading strategies leverage ConcurrentWorkflow. Healthcare applications use SequentialWorkflow for patient analysis, MajorityVoting for research review, GroupChat for treatment planning, and MultiAgentRouter for medical records management. Legal workflows apply SequentialWorkflow for document review, MixtureOfAgents for case analysis, HierarchicalSwarm for compliance checks, and ConcurrentWorkflow for contract analysis.

​
Cost Optimization

Effective cost management is essential for scaling your multi-agent systems. Batch processing, which groups related tasks together, can reduce costs by 20-30%. For Swarm Completions, scheduling non-urgent tasks during off-peak hours (8 PM - 6 AM PT) provides a 50% cost reduction on tokens. Token optimization through precise prompts and focused tasks yields 10-20% savings, while caching reusable results can reduce costs by 30-40%. Agent optimization by using the minimum required agents saves 15-25%, smart routing to specialized agents provides 10-15% savings, and prompt engineering to optimize input tokens delivers 15-20% cost reduction. When choosing service tiers, the standard tier is ideal for real-time processing, time-sensitive tasks, and critical workflows, offering immediate execution with higher priority and predictable timing, though at a higher cost with a 5-minute timeout. The off-peak tier for Swarm Completions is perfect for batch processing, non-urgent tasks, and cost-sensitive workloads, providing a 50% cost reduction on tokens during the 8 PM - 6 AM PT window, with the limitation that it only applies to Swarm Completions and has time window restrictions.

​
Production Best Practices

Implementing robust production practices ensures reliable and efficient multi-agent systems. Always use appropriate swarm types for your specific tasks, implement comprehensive error handling with retry logic, and monitor and log all executions to track performance and identify issues. Cache repeated results to reduce redundant processing, rotate API keys regularly for security, and choose the appropriate service tier based on task urgency. For Swarm Completions, schedule non-urgent tasks during off-peak hours (8 PM - 6 AM PT) to benefit from the night-time discount. Avoid common anti-patterns that can compromise your system’s reliability and security. Never hardcode API keys in your application code, always respect rate limits to prevent service disruptions, and ensure error handling is implemented for all API calls. Avoid using excessive agent counts when fewer agents can accomplish the task, maintain adequate monitoring to track system health, and always implement retry logic for failed requests to handle transient failures gracefully.

​
Error Handling

Robust error handling is critical for production systems. For 400 errors (Input Validation), implement pre-request validation with fallback mechanisms to catch issues before they reach the API. Handle 401 errors (Auth Management) through secure key rotation and proper storage of credentials. When encountering 429 errors (Rate Limiting), implement exponential backoff with queuing to manage rate limit constraints. For 500 errors (Resilience), use retry mechanisms with circuit breaking to prevent cascading failures. Handle 503 errors (High Availability) with multi-region redundancy when possible, and manage 504 errors (Timeout Handling) with adaptive timeouts that can return partial results when appropriate.

​
Performance Benchmarks

Monitoring performance metrics helps ensure your multi-agent systems meet production standards. Target response times should be under 2 seconds, with warnings when exceeding 5 seconds. Maintain success rates above 99%, with alerts when dropping below 95%. Keep cost per task under $0.05, with warnings when exceeding $0.10. Aim for cache hit rates above 80%, with alerts when dropping below 60%. Error rates should remain under 1%, with warnings when exceeding 5%. Retry rates should stay under 10%, with alerts when exceeding 30%. These benchmarks help maintain optimal system performance and cost efficiency.

​
Example Usage

​
Basic Swarm Completion

​
Additional Resources