Skip to main content

​
Overview

The Swarms API provides a diverse range of multi-agent architectures, each designed to solve specific types of problems and workflows. Set a request’s swarm_type field (in the SwarmSpec body of POST /v1/swarm/completions) to one of the values below to select the architecture. This page is a curated summary. The authoritative, machine-readable version of the same information — the same name, description, category, best_for and parameters for every type — is served live by:
which returns {"status", "timestamp", "swarm_types": [...], "swarm_types_metadata": [...]}. Call it if you want to check this list programmatically rather than trusting a docs page to stay current.
As of this writing there are 14 supported swarm_type values. "auto" and "SpreadSheetSwarm" are explicitly rejected with a 400 error (“not supported currently”) if you send them, even though you may see them referenced elsewhere. BatchedGridWorkflow and GraphWorkflow are not swarm_type values at all — each is a separate, premium-only endpoint. See Not a swarm_type below.

​
Architecture Categories

GET /v1/swarms/available groups every architecture into one of these categories:
  • workflow — ordered or parallel execution patterns
  • collaboration — agents work together toward one result
  • routing — organize or dispatch work across agents
  • judgment — decision-making, voting, and evaluation

​
All 14 Architectures

Descriptions above are the exact strings the live API returns for each type’s description field.

​
Tuning Parameters by Architecture

Every architecture accepts the common SwarmSpec fields (agents, task/tasks/messages, max_loops, name, description, stream, multi_agent_collab_prompt, list_all_agents, img). Some architectures also read additional, type-specific fields — sending them for a different swarm_type is harmless but has no effect. Full field definitions are on the Swarm Completions Reference.

​
Best-For Use Cases

  • Custom execution graphs mixing sequential and parallel stages
  • Reorganizing a pipeline without changing the agents themselves
  • Fine-grained control over which agents run when
  • Complex tasks that benefit from multiple expert perspectives
  • Combining domain specialists (e.g. legal + financial + technical)
  • Improving answer quality by synthesizing parallel drafts
  • Multi-stage pipelines where each step builds on the previous
  • Deterministic, ordered processing (e.g. research -> draft -> edit)
  • ETL-style transformations
  • Independent subtasks that do not depend on one another
  • Fan-out processing for lower latency
  • Gathering several independent analyses at once
  • Brainstorming and open-ended discussion
  • Collaborative problem-solving that needs back-and-forth
  • Simulating a panel or team meeting
  • Routing heterogeneous requests to the right specialist
  • Exposing a single entry point over many domain agents
  • Capability-based task dispatch
  • Large tasks that need decomposition and coordination
  • Manager/worker patterns with oversight
  • Workflows requiring delegation and result aggregation
  • Reducing variance and hallucination through consensus
  • Classification or decision tasks with a discrete answer
  • Higher-confidence answers via agreement
  • Evaluating, scoring or grading outputs
  • Quality assurance and review
  • Multi-criteria assessment of responses
Full walkthrough: Council as a Judge. It is a valid, fully supported swarm_type today; send council_judge_model_name (default "gpt-5.4") to control the judge model.
  • Deep, thorough analysis of complex questions
  • Research-heavy tasks that need broad coverage
  • When answer quality matters more than latency or cost
HeavySwarm is the one architecture that can run with agents: [] — it builds its own question/research/analysis/synthesis team internally. See Heavy Swarm.
  • Deliberative decision-making
  • Synthesizing diverse model opinions
  • High-stakes questions that benefit from a panel
Full walkthrough: LLM Council. It is a valid, fully supported swarm_type today; send chairman_model (default "gpt-5.1") to control the model that synthesizes the panel’s responses.
  • Exploring trade-offs from multiple sides
  • Adversarial stress-testing of a position
  • Decisions that benefit from argument and rebuttal
  • Evenly distributing turns across agents
  • Cyclical processing where each agent contributes in order
  • Simple, fair task rotation
  • Tasks that benefit from explicit planning before execution
  • Decoupling decomposition from the work itself
  • Queue-based parallel execution of sub-tasks
Full walkthrough: Planner / Worker Swarm. It is a valid, fully supported swarm_type today and takes only the common SwarmSpec fields.

​
Not a swarm_type — separate endpoints

Two related workflow types are not values you can pass to swarm_type; each has its own request/response schema and its own endpoint:

​
Rejected values

"auto" (automatic architecture selection) and "SpreadSheetSwarm" are checked explicitly by the API and rejected with a 400 Bad Request (“SpreadSheetSwarm and auto swarm types are not supported currently”). Do not send either as swarm_type.

​
Getting Started

To use any of the 14 supported architectures, make a request to /v1/swarm/completions with swarm_type set to your desired value, an agents array (required for every type except HeavySwarm), and a task (or tasks/messages). See the Swarm Completions Reference for the full request/response schema, or the Multi-Agent Overview for a conceptual introduction.