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 not in the swarm_type enum and are rejected with a 422 validation error 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). Three common fields don’t reach every architecture:
  • multi_agent_collab_prompt and list_all_agents are only used by SequentialWorkflow and AgentRearrange. Every other type ignores them.
  • img is not taken by CouncilAsAJudge, MultiAgentRouter, LLMCouncil, DebateWithJudge or GroupChat, which currently fail with a 500 when it is set.
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. A few types also check the roster before anything runs, and return a 400 otherwise: GroupChat needs at least 2 agents, DebateWithJudge exactly 3 in the order pro, con, judge, and every name in an AgentRearrange rearrange_flow must be the agent_name of one of the agents. director_settings accepts only agent_name, system_prompt, planning_system_prompt, temperature (0 to 2), top_p and max_tokens (1 to 128000). Any other key returns a 422.

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 not in the swarm_type enum, so request validation rejects them with a 422 (literal_error) whose message lists the 14 accepted values. 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.