Swarms API Documentation - Build AI Agents & Multi-Agent Systems

Generate Agent Configurations From a Task

curl --request POST \
  --url https://api.swarms.world/v1/auto-agent-builder/completions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "task": "<string>",
  "name": "<string>",
  "description": "<string>",
  "model_name": "<string>",
  "max_agents": 5,
  "num_agents": 50,
  "system_prompt": "<string>",
  "agent_kwargs": {}
}
'

import requests

url = "https://api.swarms.world/v1/auto-agent-builder/completions"

payload = {
    "task": "<string>",
    "name": "<string>",
    "description": "<string>",
    "model_name": "<string>",
    "max_agents": 5,
    "num_agents": 50,
    "system_prompt": "<string>",
    "agent_kwargs": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    task: '<string>',
    name: '<string>',
    description: '<string>',
    model_name: '<string>',
    max_agents: 5,
    num_agents: 50,
    system_prompt: '<string>',
    agent_kwargs: {}
  })
};

fetch('https://api.swarms.world/v1/auto-agent-builder/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.swarms.world/v1/auto-agent-builder/completions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'task' => '<string>',
    'name' => '<string>',
    'description' => '<string>',
    'model_name' => '<string>',
    'max_agents' => 5,
    'num_agents' => 50,
    'system_prompt' => '<string>',
    'agent_kwargs' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.swarms.world/v1/auto-agent-builder/completions"

	payload := strings.NewReader("{\n  \"task\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model_name\": \"<string>\",\n  \"max_agents\": 5,\n  \"num_agents\": 50,\n  \"system_prompt\": \"<string>\",\n  \"agent_kwargs\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.swarms.world/v1/auto-agent-builder/completions")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"task\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model_name\": \"<string>\",\n  \"max_agents\": 5,\n  \"num_agents\": 50,\n  \"system_prompt\": \"<string>\",\n  \"agent_kwargs\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.swarms.world/v1/auto-agent-builder/completions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"task\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model_name\": \"<string>\",\n  \"max_agents\": 5,\n  \"num_agents\": 50,\n  \"system_prompt\": \"<string>\",\n  \"agent_kwargs\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "status": "<string>",
  "agents": [
    {
      "agent_name": "<string>",
      "description": "<string>",
      "system_prompt": "<string>",
      "marketplace_prompt_id": "<string>",
      "model_name": "claude-sonnet-5",
      "fallback_models": [
        "<string>"
      ],
      "fallback_model_name": "<string>",
      "auto_generate_prompt": false,
      "max_tokens": 16000,
      "temperature": 1,
      "role": "worker",
      "max_loops": 1,
      "tools_list_dictionary": [
        {}
      ],
      "selected_tools": "<string>",
      "mcp_url": "<string>",
      "streaming_on": false,
      "llm_args": {},
      "top_p": 123,
      "dynamic_temperature_enabled": false,
      "mcp_config": {
        "type": "mcp",
        "url": "http://localhost:8000/mcp",
        "name": "<string>",
        "tool_configurations": {},
        "authorization_token": "<string>",
        "api_key": "<string>",
        "api_key_header": "Authorization",
        "api_key_prefix": "Bearer",
        "auth_type": "none",
        "oauth": {
          "grant_type": "authorization_code",
          "client_id": "<string>",
          "client_secret": "<string>",
          "scopes": [
            "<string>"
          ],
          "redirect_uri": "http://127.0.0.1:8765/callback",
          "client_name": "Swarms Agent",
          "client_uri": "<string>",
          "authorization_url": "<string>",
          "token_url": "<string>",
          "access_token": "<string>",
          "refresh_token": "<string>",
          "token_storage_path": "<string>",
          "use_token_cache": true,
          "open_browser": true,
          "callback_timeout": 300
        },
        "transport": "auto",
        "headers": {},
        "timeout": 30,
        "sse_read_timeout": 300,
        "tool_timeout": 120,
        "command": "<string>",
        "args": [
          "<string>"
        ],
        "env": {}
      },
      "mcp_configs": [
        {
          "type": "mcp",
          "url": "http://localhost:8000/mcp",
          "name": "<string>",
          "tool_configurations": {},
          "authorization_token": "<string>",
          "api_key": "<string>",
          "api_key_header": "Authorization",
          "api_key_prefix": "Bearer",
          "auth_type": "none",
          "oauth": {
            "grant_type": "authorization_code",
            "client_id": "<string>",
            "client_secret": "<string>",
            "scopes": [
              "<string>"
            ],
            "redirect_uri": "http://127.0.0.1:8765/callback",
            "client_name": "Swarms Agent",
            "client_uri": "<string>",
            "authorization_url": "<string>",
            "token_url": "<string>",
            "access_token": "<string>",
            "refresh_token": "<string>",
            "token_storage_path": "<string>",
            "use_token_cache": true,
            "open_browser": true,
            "callback_timeout": 300
          },
          "transport": "auto",
          "headers": {},
          "timeout": 30,
          "sse_read_timeout": 300,
          "tool_timeout": 120,
          "command": "<string>",
          "args": [
            "<string>"
          ],
          "env": {}
        }
      ],
      "mcp_urls": [
        "<string>"
      ],
      "tool_call_summary": true,
      "reasoning_effort": "minimal",
      "thinking_tokens": 123,
      "reasoning_enabled": false,
      "publish_to_marketplace": false,
      "use_cases": [
        {}
      ],
      "tags": [
        "<string>"
      ],
      "capabilities": [
        "<string>"
      ],
      "category": "<string>",
      "is_free": true,
      "price_usd": 123,
      "handoffs": [
        "<unknown>"
      ]
    }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "total_cost": 123,
    "cost_per_agent": 0.01,
    "flash_sale_applied": false
  },
  "timestamp": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

POST

auto-agent-builder

completions

Generate Agent Configurations From a Task

curl --request POST \
  --url https://api.swarms.world/v1/auto-agent-builder/completions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "task": "<string>",
  "name": "<string>",
  "description": "<string>",
  "model_name": "<string>",
  "max_agents": 5,
  "num_agents": 50,
  "system_prompt": "<string>",
  "agent_kwargs": {}
}
'

import requests

url = "https://api.swarms.world/v1/auto-agent-builder/completions"

payload = {
    "task": "<string>",
    "name": "<string>",
    "description": "<string>",
    "model_name": "<string>",
    "max_agents": 5,
    "num_agents": 50,
    "system_prompt": "<string>",
    "agent_kwargs": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    task: '<string>',
    name: '<string>',
    description: '<string>',
    model_name: '<string>',
    max_agents: 5,
    num_agents: 50,
    system_prompt: '<string>',
    agent_kwargs: {}
  })
};

fetch('https://api.swarms.world/v1/auto-agent-builder/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.swarms.world/v1/auto-agent-builder/completions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'task' => '<string>',
    'name' => '<string>',
    'description' => '<string>',
    'model_name' => '<string>',
    'max_agents' => 5,
    'num_agents' => 50,
    'system_prompt' => '<string>',
    'agent_kwargs' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.swarms.world/v1/auto-agent-builder/completions"

	payload := strings.NewReader("{\n  \"task\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model_name\": \"<string>\",\n  \"max_agents\": 5,\n  \"num_agents\": 50,\n  \"system_prompt\": \"<string>\",\n  \"agent_kwargs\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.swarms.world/v1/auto-agent-builder/completions")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"task\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model_name\": \"<string>\",\n  \"max_agents\": 5,\n  \"num_agents\": 50,\n  \"system_prompt\": \"<string>\",\n  \"agent_kwargs\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.swarms.world/v1/auto-agent-builder/completions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"task\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model_name\": \"<string>\",\n  \"max_agents\": 5,\n  \"num_agents\": 50,\n  \"system_prompt\": \"<string>\",\n  \"agent_kwargs\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "status": "<string>",
  "agents": [
    {
      "agent_name": "<string>",
      "description": "<string>",
      "system_prompt": "<string>",
      "marketplace_prompt_id": "<string>",
      "model_name": "claude-sonnet-5",
      "fallback_models": [
        "<string>"
      ],
      "fallback_model_name": "<string>",
      "auto_generate_prompt": false,
      "max_tokens": 16000,
      "temperature": 1,
      "role": "worker",
      "max_loops": 1,
      "tools_list_dictionary": [
        {}
      ],
      "selected_tools": "<string>",
      "mcp_url": "<string>",
      "streaming_on": false,
      "llm_args": {},
      "top_p": 123,
      "dynamic_temperature_enabled": false,
      "mcp_config": {
        "type": "mcp",
        "url": "http://localhost:8000/mcp",
        "name": "<string>",
        "tool_configurations": {},
        "authorization_token": "<string>",
        "api_key": "<string>",
        "api_key_header": "Authorization",
        "api_key_prefix": "Bearer",
        "auth_type": "none",
        "oauth": {
          "grant_type": "authorization_code",
          "client_id": "<string>",
          "client_secret": "<string>",
          "scopes": [
            "<string>"
          ],
          "redirect_uri": "http://127.0.0.1:8765/callback",
          "client_name": "Swarms Agent",
          "client_uri": "<string>",
          "authorization_url": "<string>",
          "token_url": "<string>",
          "access_token": "<string>",
          "refresh_token": "<string>",
          "token_storage_path": "<string>",
          "use_token_cache": true,
          "open_browser": true,
          "callback_timeout": 300
        },
        "transport": "auto",
        "headers": {},
        "timeout": 30,
        "sse_read_timeout": 300,
        "tool_timeout": 120,
        "command": "<string>",
        "args": [
          "<string>"
        ],
        "env": {}
      },
      "mcp_configs": [
        {
          "type": "mcp",
          "url": "http://localhost:8000/mcp",
          "name": "<string>",
          "tool_configurations": {},
          "authorization_token": "<string>",
          "api_key": "<string>",
          "api_key_header": "Authorization",
          "api_key_prefix": "Bearer",
          "auth_type": "none",
          "oauth": {
            "grant_type": "authorization_code",
            "client_id": "<string>",
            "client_secret": "<string>",
            "scopes": [
              "<string>"
            ],
            "redirect_uri": "http://127.0.0.1:8765/callback",
            "client_name": "Swarms Agent",
            "client_uri": "<string>",
            "authorization_url": "<string>",
            "token_url": "<string>",
            "access_token": "<string>",
            "refresh_token": "<string>",
            "token_storage_path": "<string>",
            "use_token_cache": true,
            "open_browser": true,
            "callback_timeout": 300
          },
          "transport": "auto",
          "headers": {},
          "timeout": 30,
          "sse_read_timeout": 300,
          "tool_timeout": 120,
          "command": "<string>",
          "args": [
            "<string>"
          ],
          "env": {}
        }
      ],
      "mcp_urls": [
        "<string>"
      ],
      "tool_call_summary": true,
      "reasoning_effort": "minimal",
      "thinking_tokens": 123,
      "reasoning_enabled": false,
      "publish_to_marketplace": false,
      "use_cases": [
        {}
      ],
      "tags": [
        "<string>"
      ],
      "capabilities": [
        "<string>"
      ],
      "category": "<string>",
      "is_free": true,
      "price_usd": 123,
      "handoffs": [
        "<unknown>"
      ]
    }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "total_cost": 123,
    "cost_per_agent": 0.01,
    "flash_sale_applied": false
  },
  "timestamp": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Headers

x-api-key

string

required

Body

application/json

task

string

required

The task the generated team should be able to handle. This is the only required field.

Minimum string length: 1

name

string | null

The name of this auto agent builder run.

description

string | null

The description of this auto agent builder run.

model_name

string | null

The model backing the builder agent itself — not the models given to the generated agents; the builder chooses those per agent. Defaults to the framework's builder default.

max_agents

integer | null

default:5

Upper bound on roster size. This is a ceiling, not a target — the builder prefers the smallest roster that covers the task.

Required range: 1 <= x <= 100

num_agents

integer | null

Exact number of agents to generate. When set, this overrides max_agents and the builder's prefer-fewer guidance.

Required range: 1 <= x <= 100

system_prompt

string | null

Custom instructions for the builder agent. Defaults to the framework's builder system prompt.

agent_kwargs

Agent Kwargs · object | null

Passed to the builder, but it has no effect on the response: the builder sets only agent_name, description, system_prompt and model_name, and every other field is the AgentSpec default. Set fields such as max_loops on the returned agents before running them.

Response

Successful Response

job_id

string

required

The job ID of the auto agent builder run.

name

string

required

The name of the auto agent builder run.

description

string

required

The description of the auto agent builder run.

status

string

required

The status of the auto agent builder run.

agents

AgentSpec · object[]

required

The generated roster. Each entry is a complete AgentSpec that can be posted unmodified to /v1/swarm/completions or the other multi-agent endpoints.

Show child attributes

usage

Usage · object

required

The usage of the auto agent builder run.

Show child attributes

timestamp

string

required

The timestamp of the auto agent builder run.

General

Swarms

Account Management

Anthropic Compatible

OpenAI Compatible

Agents

Reasoning Agents

Decision Models

Logging

Metrics

Models

Rate Limiting

Tool Management

Batched Grid Workflow

Graph Workflow

Auto Agent Builder

Pricing

Generate Agent Configurations From a Task

Headers

Body

Response