--- title: "Run Swarm" method: POST path: "/v1/swarm/completions" --- # Run Swarm `POST /v1/swarm/completions` Run a swarm with the specified task. Supports streaming when stream=True. ## Headers - `x-api-key` string, required ## Request body - SwarmSpec - `name` string, nullable — The name of the swarm, which serves as an identifier for the group of agents and their collective task. - `description` string, nullable — A comprehensive description of the swarm's objectives, capabilities, and intended outcomes. - `agents` AgentSpec[], nullable — A list of agents or specifications that define the agents participating in the swarm. - `agent_name` string, nullable, required — The unique name assigned to the agent, which identifies its role and functionality within the swarm. - `description` string, nullable — A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform. - `system_prompt` string, nullable — The initial instruction or context provided to the agent, guiding its behavior and responses during execution. - `model_name` string, nullable — The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4o-mini, openai/o3-mini - `auto_generate_prompt` boolean, nullable — A flag indicating whether the agent should automatically create prompts based on the task requirements. - `max_tokens` integer, nullable — The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length. - `temperature` number, nullable — A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses. - `role` string, nullable — The designated role of the agent within the swarm, which influences its behavior and interaction with other agents. - `max_loops` integer, nullable — The maximum number of times the agent is allowed to repeat its task, enabling iterative processing if necessary. - `tools_list_dictionary` object[], nullable — A dictionary of tools that the agent can use to complete its task. - `mcp_url` string, nullable — The URL of the MCP server that the agent can use to complete its task. - `streaming_on` boolean, nullable — A flag indicating whether the agent should stream its output. - `llm_args` object, nullable — Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc. - `dynamic_temperature_enabled` boolean, nullable — A flag indicating whether the agent should dynamically adjust its temperature based on the task. - `mcp_config` MCPConnection - `type` string, nullable — The type of connection, defaults to 'mcp' - `url` string, nullable — The URL endpoint for the MCP server - `tool_configurations` object, nullable — Dictionary containing configuration settings for MCP tools - `authorization_token` string, nullable — Authentication token for accessing the MCP server - `transport` string, nullable — The transport protocol to use for the MCP server - `headers` object, nullable — Headers to send to the MCP server - `timeout` integer, nullable — Timeout for the MCP server - `mcp_configs` MultipleMCPConnections - `connections` MCPConnection[], required — List of MCP connections - `type` string, nullable — The type of connection, defaults to 'mcp' - `url` string, nullable — The URL endpoint for the MCP server - `tool_configurations` object, nullable — Dictionary containing configuration settings for MCP tools - `authorization_token` string, nullable — Authentication token for accessing the MCP server - `transport` string, nullable — The transport protocol to use for the MCP server - `headers` object, nullable — Headers to send to the MCP server - `timeout` integer, nullable — Timeout for the MCP server - `tool_call_summary` boolean, nullable — A parameter enabling an agent to summarize tool calls. - `reasoning_effort` string, nullable — The effort to put into reasoning. - `thinking_tokens` integer, nullable — The number of tokens to use for thinking. - `reasoning_enabled` boolean, nullable — A parameter enabling an agent to use reasoning. - `max_loops` integer, nullable — The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed. - `swarm_type` 'AgentRearrange' | 'MixtureOfAgents' | 'SequentialWorkflow' | 'ConcurrentWorkflow' | 'GroupChat' | 'MultiAgentRouter' | 'AutoSwarmBuilder' | 'HiearchicalSwarm' | 'auto' | 'MajorityVoting' | 'MALT' | 'DeepResearchSwarm' | 'CouncilAsAJudge' | 'InteractiveGroupChat' | 'HeavySwarm', nullable — The classification of the swarm, indicating its operational style and methodology. - `rearrange_flow` string, nullable — Instructions on how to rearrange the flow of tasks among agents, if applicable. - `task` string, nullable — The specific task or objective that the swarm is designed to accomplish. - `img` string, nullable — An optional image URL that may be associated with the swarm's task or representation. - `rules` string, nullable — Guidelines or constraints that govern the behavior and interactions of the agents within the swarm. - `tasks` string[], nullable — A list of tasks that the swarm should complete. - `messages` union — A list of messages that the swarm should complete. - object[] - object - `stream` boolean, nullable — A flag indicating whether the swarm should stream its output. - `service_tier` string, nullable — The service tier to use for processing. Options: 'standard' (default) or 'flex' for lower cost but slower processing. - `heavy_swarm_loops_per_agent` integer, nullable — The number of loops to run per agent in the heavy swarm. - `heavy_swarm_question_agent_model_name` string, nullable — The model name to use for the question agent in the heavy swarm. - `heavy_swarm_worker_model_name` string, nullable — The model name to use for the worker agent in the heavy swarm. ## Response `200` Successful Response - SwarmCompletion - `job_id` string, nullable, required — The unique identifier for the swarm completion. - `status` string, nullable, required — The status of the swarm completion. - `swarm_name` string, nullable, required — The name of the swarm. - `description` string, nullable, required — The description of the swarm. - `swarm_type` string, nullable, required — The type of the swarm. - `output` unknown, required - `number_of_agents` integer, nullable, required — The number of agents in the swarm. - `service_tier` string, nullable, required — The service tier of the swarm. - `execution_time` number, nullable, required — The execution time of the swarm. - `usage` object, nullable, required — The usage of the swarm. ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/the-swarm-corporation/apis/swarms-api.md) · [All operations](https://skmtc.net/the-swarm-corporation/apis/swarms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/the-swarm-corporation/swarms-api/revisions/7618ad18b40e/schema)