> ## 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 Graph Workflow

> Execute a graph workflow with directed agent nodes and edges. Enables complex multi-agent collaboration with parallel execution, automatic compilation, and comprehensive workflow orchestration.



## OpenAPI

````yaml https://api.swarms.world/openapi.json post /v1/graph-workflow/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/graph-workflow/completions:
    post:
      tags:
        - Graph Workflow
      summary: Execute Graph Workflow
      description: >-
        Execute a graph workflow with directed agent nodes and edges. Enables
        complex multi-agent collaboration with parallel execution, automatic
        compilation, and comprehensive workflow orchestration.
      operationId: run_graph_workflow_v1_graph_workflow_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/GraphWorkflowInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphWorkflowOutput'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    GraphWorkflowInput:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: The name of the graph workflow.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: The description of the graph workflow.
        agents:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentSpec'
                description: The configuration of the agent to be completed.
              type: array
            - type: 'null'
          title: Agents
          description: >-
            List of agent specifications to be used as nodes in the workflow
            graph.
        edges:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/EdgeSpec'
                  - additionalProperties: true
                    type: object
              type: array
            - type: 'null'
          title: Edges
          description: >-
            List of edges connecting nodes. Can be EdgeSpec objects or
            dictionaries with 'source' and 'target' keys.
        entry_points:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Entry Points
          description: List of node IDs that serve as starting points for the workflow.
        end_points:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: End Points
          description: List of node IDs that serve as ending points for the workflow.
        max_loops:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Loops
          description: The maximum number of execution loops for the workflow.
          default: 1
        task:
          anyOf:
            - type: string
            - type: 'null'
          title: Task
          description: The task to be executed by the workflow.
        img:
          anyOf:
            - type: string
            - type: 'null'
          title: Img
          description: Optional image path for vision-enabled agents.
        auto_compile:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auto Compile
          description: Whether to automatically compile the workflow for optimization.
          default: true
        verbose:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Verbose
          description: Whether to enable detailed logging.
          default: false
      type: object
      title: GraphWorkflowInput
      description: Input schema for GraphWorkflow completion requests.
    GraphWorkflowOutput:
      properties:
        job_id:
          type: string
          title: Job Id
          description: The job ID of the graph workflow.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: The name of the graph workflow.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: The description of the graph workflow.
        status:
          type: string
          title: Status
          description: The status of the graph workflow.
        outputs:
          title: Outputs
          description: The outputs of the graph workflow.
        usage:
          $ref: '#/components/schemas/api__schemas__Usage'
          description: The usage statistics of the workflow.
        timestamp:
          type: string
          title: Timestamp
          description: The timestamp of the graph workflow execution.
      type: object
      required:
        - job_id
        - status
        - outputs
        - usage
        - timestamp
      title: GraphWorkflowOutput
      description: Output schema for GraphWorkflow completion responses.
    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
    EdgeSpec:
      properties:
        source:
          type: string
          title: Source
          description: The source node ID.
        target:
          type: string
          title: Target
          description: The target node ID.
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Optional metadata for the edge.
      type: object
      required:
        - source
        - target
      title: EdgeSpec
      description: Schema for defining an edge between nodes in the workflow graph.
    api__schemas__Usage:
      properties:
        input_tokens:
          type: integer
          title: Input Tokens
          description: The number of input tokens.
        output_tokens:
          type: integer
          title: Output Tokens
          description: The number of output tokens.
        total_tokens:
          type: integer
          title: Total Tokens
          description: The total number of tokens.
        token_cost:
          type: number
          title: Token Cost
          description: The cost in credits for the tokens.
        cost_per_agent:
          type: number
          title: Cost Per Agent
          description: The cost in credits for the agents.
          default: 0.01
      type: object
      required:
        - input_tokens
        - output_tokens
        - total_tokens
        - token_cost
      title: Usage
      description: Usage statistics for the workflow execution.
    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

````