> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Swarm Completion

> Execute a swarm completion with the specified task. Supports both standard and streaming responses.



## OpenAPI

````yaml https://api.swarms.world/openapi.json post /v1/swarm/completions
openapi: 3.1.0
info:
  title: Swarms API
  description: >-
    The Swarms API delivers a high-performance, enterprise-grade platform for
    orchestrating advanced multi-agent systems. Built on a Rust-powered agent
    runtime, it enables scalable, robust, and secure agent collaboration,
    supporting complex workflows and dynamic agent communication. The API
    exposes a comprehensive suite of RESTful endpoints for the management,
    execution, and monitoring of agents, swarms, and related resources,
    empowering organizations to automate and optimize mission-critical
    processes. To access the API, obtain your API key from the [Swarms API Keys
    page](https://swarms.world/platform/api-keys). For detailed integration
    guides, best practices, and reference material, consult the [Swarms API
    Documentation](https://docs.swarms.ai).
  version: 1.0.0
servers:
  - url: https://api.swarms.world
    description: Swarms Production API
security: []
paths:
  /v1/swarm/completions:
    post:
      tags:
        - Swarms
      summary: Execute Swarm Completion
      description: >-
        Execute a swarm completion with the specified task. Supports both
        standard and streaming responses.
      operationId: run_swarm_v1_swarm_completions_post
      parameters:
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwarmSpec'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwarmCompletion'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SwarmSpec:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Name
          description: >-
            The name of the swarm, which serves as an identifier for the group
            of agents and their collective task.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            A comprehensive description of the swarm's objectives, capabilities,
            and intended outcomes.
        agents:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentSpec'
                description: The configuration of the agent to be completed.
              type: array
            - type: 'null'
          title: Agents
          description: >-
            A list of agents or specifications that define the agents
            participating in the swarm.
        max_loops:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Loops
          description: >-
            The maximum number of execution loops allowed for the swarm,
            enabling repeated processing if needed.
          default: 1
        swarm_type:
          anyOf:
            - type: string
              enum:
                - AgentRearrange
                - MixtureOfAgents
                - SequentialWorkflow
                - ConcurrentWorkflow
                - GroupChat
                - MultiAgentRouter
                - AutoSwarmBuilder
                - HierarchicalSwarm
                - auto
                - MajorityVoting
                - CouncilAsAJudge
                - HeavySwarm
                - BatchedGridWorkflow
                - LLMCouncil
                - DebateWithJudge
                - RoundRobin
                - PlannerWorkerSwarm
            - type: 'null'
          title: Swarm Type
          description: >-
            The classification of the swarm, indicating its operational style
            and methodology.
        rearrange_flow:
          anyOf:
            - type: string
            - type: 'null'
          title: Rearrange Flow
          description: >-
            Instructions on how to rearrange the flow of tasks among agents, if
            applicable.
        task:
          anyOf:
            - type: string
            - type: 'null'
          title: Task
          description: >-
            The specific task or objective that the swarm is designed to
            accomplish.
        img:
          anyOf:
            - type: string
            - type: 'null'
          title: Img
          description: >-
            An optional image URL that may be associated with the swarm's task
            or representation.
        tasks:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tasks
          description: A list of tasks that the swarm should complete.
        messages:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Messages
          description: A list of messages that the swarm should complete.
        stream:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Stream
          description: A flag indicating whether the swarm should stream its output.
          default: false
        heavy_swarm_question_agent_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Heavy Swarm Question Agent Model Name
          description: The model name to use for the question agent in the heavy swarm.
          default: gpt-4.1
        heavy_swarm_worker_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Heavy Swarm Worker Model Name
          description: The model name to use for the worker agent in the heavy swarm.
          default: claude-sonnet-4-20250514
        heavy_swarm_variant:
          anyOf:
            - type: string
            - type: 'null'
          title: Heavy Swarm Variant
          description: >-
            For HeavySwarm: which agent variant to run. One of 'default',
            'medium', or 'heavy'.
          default: default
        council_judge_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Council Judge Model Name
          description: >-
            For CouncilAsAJudge: the model name used by the judge that delivers
            the final ruling.
          default: gpt-5.4
        chairman_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Chairman Model
          description: >-
            For LLMCouncil: the model name used by the chairman that synthesizes
            the council's responses.
          default: gpt-5.1
        multi_agent_collab_prompt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Multi Agent Collab Prompt
          description: >-
            Inject the multi-agent collaboration prompt so agents coordinate
            with one another. Set False to disable.
          default: true
        heavy_swarm_max_loops:
          anyOf:
            - type: integer
            - type: 'null'
          title: Heavy Swarm Max Loops
          description: >-
            For HeavySwarm: the maximum number of loops each agent in the heavy
            swarm may run.
          default: 1
        list_all_agents:
          anyOf:
            - type: boolean
            - type: 'null'
          title: List All Agents
          description: >-
            Whether to list all agents and their descriptions to one another so
            each agent is aware of the others.
          default: false
      type: object
      title: SwarmSpec
    SwarmCompletion:
      properties:
        job_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Job Id
          description: The unique identifier for the swarm completion.
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: The status of the swarm completion.
        swarm_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Swarm Name
          description: The name of the swarm.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: The description of the swarm.
        swarm_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Swarm Type
          description: The type of the swarm.
        output:
          anyOf:
            - {}
            - type: 'null'
          title: Output
          description: The output of the swarm.
        number_of_agents:
          anyOf:
            - type: integer
            - type: 'null'
          title: Number Of Agents
          description: The number of agents in the swarm.
        execution_time:
          anyOf:
            - type: number
            - type: 'null'
          title: Execution Time
          description: The execution time of the swarm.
        usage:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Usage
          description: The usage of the swarm.
      type: object
      required:
        - job_id
        - status
        - swarm_name
        - description
        - swarm_type
        - output
        - number_of_agents
        - execution_time
        - usage
      title: SwarmCompletion
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentSpec:
      properties:
        agent_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Name
          description: >-
            The unique name assigned to the agent, which identifies its role and
            functionality within the swarm.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            A detailed explanation of the agent's purpose, capabilities, and any
            specific tasks it is designed to perform.
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
          description: >-
            The initial instruction or context provided to the agent, guiding
            its behavior and responses during execution.
        marketplace_prompt_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Marketplace Prompt Id
          description: >-
            The ID of a prompt from the Swarms marketplace to use as the system
            prompt. If provided, the prompt will be automatically retrieved from
            the marketplace.
        model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Name
          description: >-
            The name of the AI model that the agent will utilize for processing
            tasks and generating outputs. For example: gpt-4o, gpt-4.1,
            openai/o3-mini
          default: gpt-4.1
        auto_generate_prompt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auto Generate Prompt
          description: >-
            A flag indicating whether the agent should automatically create
            prompts based on the task requirements.
          default: false
        max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Tokens
          description: >-
            The maximum number of tokens that the agent is allowed to generate
            in its responses, limiting output length.
          default: 8192
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
          description: >-
            A parameter that controls the randomness of the agent's output;
            lower values result in more deterministic responses. If omitted, no
            temperature is sent to the model (the provider's own default
            applies).
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          description: >-
            The designated role of the agent within the swarm, which influences
            its behavior and interaction with other agents.
          default: worker
        max_loops:
          anyOf:
            - type: integer
            - type: string
            - type: 'null'
          title: Max Loops
          description: >-
            Maximum number of iterations the agent can perform for its task.
            Accepts an integer for a fixed count, or 'auto' to allow the system
            to determine the necessary number based on the task's complexity.
          default: 1
        tools_list_dictionary:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tools List Dictionary
          description: A dictionary of tools that the agent can use to complete its task.
        selected_tools:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Selected Tools
          description: >-
            Tools to enable for the autonomous looper when max_loops='auto'.
            Pass a list of tool names to restrict which tools the agent can use,
            or omit to allow all safe defaults. Available tools: create_plan,
            think, subtask_done, complete_task, respond_to_user, create_file,
            update_file, read_file, list_directory, delete_file,
            create_sub_agent, assign_task. Note: run_bash is not permitted.
        mcp_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Url
          description: >-
            The URL of the MCP server that the agent can use to complete its
            task.
        streaming_on:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Streaming On
          description: A flag indicating whether the agent should stream its output.
          default: false
        llm_args:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Llm Args
          description: >-
            Additional arguments to pass to the LLM such as top_p,
            frequency_penalty, presence_penalty, etc.
        dynamic_temperature_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Dynamic Temperature Enabled
          description: >-
            A flag indicating whether the agent should dynamically adjust its
            temperature based on the task.
          default: true
        mcp_config:
          anyOf:
            - $ref: '#/components/schemas/MCPConnection'
            - type: 'null'
          description: The MCP connection to use for the agent.
        mcp_configs:
          anyOf:
            - $ref: '#/components/schemas/MultipleMCPConnections'
            - type: 'null'
          description: >-
            The MCP connections to use for the agent. This is a list of MCP
            connections. Includes multiple MCP connections.
        tool_call_summary:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Tool Call Summary
          description: A parameter enabling an agent to summarize tool calls.
          default: true
        reasoning_effort:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning Effort
          description: 'The effort to put into reasoning. Options: ''low'', ''medium'', ''high''.'
          default: low
        thinking_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Thinking Tokens
          description: The number of tokens to use for thinking.
        reasoning_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Reasoning Enabled
          description: A parameter enabling an agent to use reasoning.
          default: false
        publish_to_marketplace:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Publish To Marketplace
          description: >-
            A flag indicating whether to publish this agent to the Swarms
            marketplace.
          default: false
        use_cases:
          anyOf:
            - items:
                additionalProperties:
                  type: string
                type: object
              type: array
            - type: 'null'
          title: Use Cases
          description: >-
            A list of use case dictionaries with 'title' and 'description' keys.
            Required when publish_to_marketplace is True.
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: >-
            A list of searchable tags/keywords for the marketplace (e.g.,
            ['finance', 'analysis']).
        capabilities:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Capabilities
          description: >-
            A list of agent capabilities or features (e.g., ['trend-analysis',
            'risk-assessment']).
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
          description: >-
            The marketplace category for the agent (e.g., 'research', 'content',
            'coding', 'finance', 'healthcare', 'education', 'legal').
        is_free:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Free
          description: >-
            A flag indicating whether the agent is free to use in the
            marketplace.
          default: true
        price_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Price Usd
          description: >-
            The price in USD for using this agent in the marketplace (if not
            free).
        handoffs:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentSpec'
              type: array
            - type: 'null'
          title: Handoffs
          description: >-
            A list of agent specifications that this agent can hand off tasks
            to. These agents will be created and passed to the agent's handoffs
            parameter.
      type: object
      title: AgentSpec
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    MCPConnection:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: The type of connection, defaults to 'mcp'
          default: mcp
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: The URL endpoint for the MCP server
          default: http://localhost:8000/mcp
        tool_configurations:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Tool Configurations
          description: Dictionary containing configuration settings for MCP tools
        authorization_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Authorization Token
          description: Authentication token for accessing the MCP server
        transport:
          anyOf:
            - type: string
            - type: 'null'
          title: Transport
          description: The transport protocol to use for the MCP server
          default: streamable_http
        headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Headers
          description: Headers to send to the MCP server
        timeout:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timeout
          description: Timeout for the MCP server
          default: 10
      additionalProperties: true
      type: object
      title: MCPConnection
    MultipleMCPConnections:
      properties:
        connections:
          items:
            $ref: '#/components/schemas/MCPConnection'
          type: array
          title: Connections
          description: List of MCP connections
      type: object
      required:
        - connections
      title: MultipleMCPConnections

````