---
title: "Auto-Generate Agent Swarm"
method: POST
path: "/v1/auto-swarm-builder/completions"
tags: ["Auto Swarm Builder"]
---

# Auto-Generate Agent Swarm

`POST /v1/auto-swarm-builder/completions`

Generate and orchestrate agent swarms autonomously using AI-powered swarm composition and task decomposition.

## Headers

- `x-api-key` string, required

## Request body

- AutoSwarmBuilderSchema — Schema for the Auto Swarm Builder input configuration. Attributes: name (Optional[str]): The name of the swarm. description (Optional[str]): A description of the swarm. max_loops (Optional[int]): Maximum number of loops to run (default: 1). return_agents (Optional[bool]): Whether to return agents after building (default: True). model_name (Optional[str]): The model name to use for the swarm (default: "gpt-4.1"). generate_router_config (Optional[bool]): Whether to generate router configuration (default: False). task (Optional[str]): The main task for the swarm (required). max_tokens (Optional[int]): The maximum number of tokens to use for the swarm.
  - `name` string, nullable — The name of the swarm.
  - `description` string, nullable — A description of the swarm.
  - `max_loops` integer, nullable — Maximum number of loops to run.
  - `execution_type` 'return-agents' | 'return-swarm-router-config' | 'return-agents-objects', nullable — The type of execution to perform.
  - `model_name` string, nullable — The model name to use for the swarm.
  - `task` string, nullable — The task for the swarm, if any.
  - `max_tokens` integer, nullable — The maximum number of tokens to use for the swarm.

## Response `200`

Successful Response

- AutoSwarmBuilderResponse — Schema for the Auto Swarm Builder API response. Attributes: success (bool): Whether the swarm was built successfully. job_id (Optional[str]): The job ID of the swarm. outputs (Optional[dict]): The outputs of the auto swarms builder. type (Optional[str]): The type of the swarm execution. timestamp (Optional[str]): The timestamp of the swarm execution. usage (Optional[dict]): The usage statistics of the swarm execution.
  - `success` boolean, required — Whether the swarm was built successfully.
  - `job_id` string, nullable — The job ID of the swarm.
  - `outputs` object, nullable — The outputs of the auto swarms builder.
  - `type` string, nullable — The type of the swarm execution.
  - `timestamp` string, nullable — The timestamp of the swarm execution.
  - `usage` object, nullable — The usage of the swarm execution.

## 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)