Agent Swarms

The Agent Swarm API lets you submit work to a coordinated team of specialist agents. Tasks are queued asynchronously — submit a task and poll for results using the returned task_id.

Base URL: https://api.ainative.studio

Authentication: JWT bearer or API key. All endpoints require Authorization: Bearer <your_api_key>.

---

Supported Agent Types

When submitting a task you can specify which agent roles to involve. The following types are supported:

Type	Role
architect	System design and high-level planning
backend	Server-side implementation
frontend	UI and client-side implementation
qa	Testing and quality assurance
devops	Infrastructure and deployment
data	Data pipeline and analytics
security	Vulnerability and threat analysis
docs	Documentation authoring

If agent_types is omitted, the swarm defaults to ["architect", "backend", "qa"].

---

Task Lifecycle

submitted → queued → running → completed
                            ↘ failed

Poll GET /api/v1/agent-swarm/tasks/{task_id} until status is completed or failed. The result field is populated on completion.

---

Endpoints

Submit a Swarm Task

POST /api/v1/agent-swarm/tasks

Queue a new task for execution. Returns immediately with status: queued and a task_id to poll.

Request body

Field	Type	Required	Description
description	string	Yes	Natural-language task description (1–4096 chars)
agent_types	string[]	No	Agent roles to involve. Defaults to ["architect", "backend", "qa"]. Optional when registry_agent_id is provided.
registry_agent_id	string	No	ID of a registered agent from the agent cloud registry. When provided, agent config is loaded from the registry.
config	object	No	Arbitrary key-value config forwarded to the swarm execution context

curl -X POST https://api.ainative.studio/api/v1/agent-swarm/tasks \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Add rate limiting middleware to all public API routes",
    "agent_types": ["architect", "backend", "qa", "devops"],
    "config": {
      "repo": "my-org/api-service",
      "branch": "main"
    }
  }'

import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/agent-swarm/tasks",
    headers={"Authorization": "Bearer <your_api_key>"},
    json={
        "description": "Add rate limiting middleware to all public API routes",
        "agent_types": ["architect", "backend", "qa", "devops"],
        "config": {"repo": "my-org/api-service", "branch": "main"},
    },
)
task = resp.json()
task_id = task["task_id"]

Response 201 Created

{
  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "description": "Add rate limiting middleware to all public API routes",
  "agent_types": ["architect", "backend", "devops", "qa"],
  "registry_agent_id": null,
  "config": {
    "repo": "my-org/api-service",
    "branch": "main"
  },
  "result": null,
  "agents_used": [],
  "created_at": "2026-04-25T10:00:00Z",
  "updated_at": "2026-04-25T10:00:00Z",
  "owner_id": "user-uuid"
}

---

Submit Using a Registry Agent

You can bind a swarm task to a registered agent from the agent cloud registry. The swarm loads capabilities and config from the registry automatically. The agent must be ACTIVE and either public or owned by you.

curl -X POST https://api.ainative.studio/api/v1/agent-swarm/tasks \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Run a full security audit on the payment module",
    "registry_agent_id": "550e8400-e29b-41d4-a716-446655440001"
  }'

When registry_agent_id is provided, agent_types becomes optional. If omitted, the type is derived from the registry agent's agent_type field.

---

Get Task Status and Results

GET /api/v1/agent-swarm/tasks/{task_id}

Retrieve the current status and result for a previously submitted task. Returns 404 if the task does not exist or belongs to another user.

curl https://api.ainative.studio/api/v1/agent-swarm/tasks/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer <your_api_key>"

import httpx, time

task_id = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
while True:
    resp = httpx.get(
        f"https://api.ainative.studio/api/v1/agent-swarm/tasks/{task_id}",
        headers={"Authorization": "Bearer <your_api_key>"},
    )
    task = resp.json()
    if task["status"] in ("completed", "failed"):
        break
    time.sleep(5)

print(task["result"])

Response when completed

{
  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "description": "Add rate limiting middleware to all public API routes",
  "agent_types": ["architect", "backend", "devops", "qa"],
  "registry_agent_id": null,
  "config": {...},
  "result": {
    "summary": "Rate limiting middleware implemented using token bucket algorithm",
    "files_changed": ["middleware/rate_limit.py", "app/main.py"],
    "tests_added": 12,
    "coverage": "94%"
  },
  "agents_used": ["arch-agent-01", "backend-agent-03", "qa-agent-02"],
  "created_at": "2026-04-25T10:00:00Z",
  "updated_at": "2026-04-25T10:04:23Z",
  "owner_id": "user-uuid"
}

Task status values

Status	Description
queued	Task accepted, waiting for agent capacity
running	Agents are actively working on the task
completed	Task finished successfully. result is populated.
failed	Task could not be completed. Check result for error details.
cancelled	Task was cancelled before execution

---

List Swarm Tasks

GET /api/v1/agent-swarm/tasks

Paginated list of all tasks submitted by the authenticated user, ordered by created_at descending.

Query parameters

Param	Type	Default	Description
status	string	—	Filter by status: queued, running, completed, failed, cancelled
limit	integer	20	Max results per page (1–100)
offset	integer	0	Number of results to skip

# List only completed tasks
curl "https://api.ainative.studio/api/v1/agent-swarm/tasks?status=completed&limit=10" \
  -H "Authorization: Bearer <your_api_key>"

Response

{
  "tasks": [
    {
      "task_id": "f47ac10b-...",
      "status": "completed",
      "description": "Add rate limiting middleware...",
      ...
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

---

Error Responses

Status	Cause
401	Missing or invalid authentication
403	Task belongs to another user (private registry agent)
404	Task not found
422	Unknown agent_types value or invalid status filter
500	Internal error — safe to retry