Skip to main content
POST
/
v1
/
swarm
/
completions
Execute Swarm Completion
curl --request POST \
  --url https://api.example.com/v1/swarm/completions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "agents": [
    {
      "agent_name": "<string>",
      "description": "<string>",
      "system_prompt": "<string>",
      "model_name": "gpt-4.1",
      "auto_generate_prompt": false,
      "max_tokens": 8192,
      "temperature": 0.5,
      "role": "worker",
      "max_loops": 1,
      "tools_list_dictionary": [
        {}
      ],
      "mcp_url": "<string>",
      "streaming_on": false,
      "llm_args": {},
      "dynamic_temperature_enabled": true,
      "mcp_config": {
        "type": "mcp",
        "url": "http://localhost:8000/mcp",
        "tool_configurations": {},
        "authorization_token": "<string>",
        "transport": "streamable_http",
        "headers": {},
        "timeout": 10
      },
      "mcp_configs": {
        "connections": [
          {
            "type": "mcp",
            "url": "http://localhost:8000/mcp",
            "tool_configurations": {},
            "authorization_token": "<string>",
            "transport": "streamable_http",
            "headers": {},
            "timeout": 10
          }
        ]
      },
      "tool_call_summary": true,
      "reasoning_effort": "<string>",
      "thinking_tokens": 123,
      "reasoning_enabled": false
    }
  ],
  "max_loops": 1,
  "swarm_type": "AgentRearrange",
  "rearrange_flow": "<string>",
  "task": "<string>",
  "img": "<string>",
  "rules": "<string>",
  "tasks": [
    "<string>"
  ],
  "messages": [
    {}
  ],
  "stream": false,
  "heavy_swarm_loops_per_agent": 1,
  "heavy_swarm_question_agent_model_name": "gpt-4.1",
  "heavy_swarm_worker_model_name": "claude-sonnet-4-20250514"
}
'
{
  "job_id": "<string>",
  "status": "<string>",
  "swarm_name": "<string>",
  "description": "<string>",
  "swarm_type": "<string>",
  "output": "<unknown>",
  "number_of_agents": 123,
  "execution_time": 123,
  "usage": {}
}

Headers

​
x-api-key
string
required

Body

application/json
​
name
string | null

The name of the swarm, which serves as an identifier for the group of agents and their collective task.

Maximum string length: 100
​
description
string | null

A comprehensive description of the swarm's objectives, capabilities, and intended outcomes.

​
agents
AgentSpec · object[] | null

A list of agents or specifications that define the agents participating in the swarm.

​
max_loops
integer | null
default:1

The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed.

​
swarm_type
enum<string> | null

The classification of the swarm, indicating its operational style and methodology.

Available options:
AgentRearrange,
MixtureOfAgents,
SequentialWorkflow,
ConcurrentWorkflow,
GroupChat,
MultiAgentRouter,
AutoSwarmBuilder,
HierarchicalSwarm,
auto,
MajorityVoting,
MALT,
CouncilAsAJudge,
InteractiveGroupChat,
HeavySwarm,
BatchedGridWorkflow,
LLMCouncil,
DebateWithJudge,
RoundRobin
​
rearrange_flow
string | null

Instructions on how to rearrange the flow of tasks among agents, if applicable.

​
task
string | null

The specific task or objective that the swarm is designed to accomplish.

​
img
string | null

An optional image URL that may be associated with the swarm's task or representation.

​
rules
string | null

Guidelines or constraints that govern the behavior and interactions of the agents within the swarm.

​
tasks
string[] | null

A list of tasks that the swarm should complete.

​
messages
object
​
stream
boolean | null
default:false

A flag indicating whether the swarm should stream its output.

​
heavy_swarm_loops_per_agent
integer | null
default:1

The number of loops to run per agent in the heavy swarm.

​
heavy_swarm_question_agent_model_name
string | null
default:gpt-4.1

The model name to use for the question agent in the heavy swarm.

​
heavy_swarm_worker_model_name
string | null
default:claude-sonnet-4-20250514

The model name to use for the worker agent in the heavy swarm.

Response

Successful Response

​
job_id
string | null
required

The unique identifier for the swarm completion.

​
status
string | null
required

The status of the swarm completion.

​
swarm_name
string | null
required

The name of the swarm.

​
description
string | null
required

The description of the swarm.

​
swarm_type
string | null
required

The type of the swarm.

​
output
any | null
required

The output of the swarm.

​
number_of_agents
integer | null
required

The number of agents in the swarm.

​
execution_time
number | null
required

The execution time of the swarm.

​
usage
Usage · object
required

The usage of the swarm.