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

# Team provisioning API

> Provision multi-agent teams with pre-built or custom configurations

# Team provisioning API

Provision coordinated multi-agent teams for Collective, Label, and Network plan tiers. Each agent in the team receives its own container service.

<Note>Team provisioning requires a Collective plan or higher. Solo plan users are limited to single-agent provisioning via [`POST /api/provision`](/api-reference/agents#provision-with-channel-tokens).</Note>

## Plan agent limits

Each plan tier has a maximum number of agents that can be provisioned in a single team:

| Plan         | Max agents per team                 |
| ------------ | ----------------------------------- |
| `solo`       | 1 (team provisioning not available) |
| `collective` | 3                                   |
| `label`      | 10                                  |
| `network`    | 50                                  |

## Provision a team

```http theme={"dark"}
POST /api/provision/team
```

Creates a team of agents using a pre-built template or a custom agent configuration. Requires session authentication.

### Request body

| Field                  | Type   | Required    | Description                                                                                                                                                                                           |
| ---------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plan`                 | string | Yes         | Plan tier. Must be one of `collective`, `label`, or `network`.                                                                                                                                        |
| `stripeSubscriptionId` | string | Conditional | Stripe subscription ID. Required unless the caller is an admin. Can also be passed via the `x-stripe-subscription-id` request header. When missing for non-admin callers, the endpoint returns `402`. |
| `templateKey`          | string | No          | Key of the pre-built team template to use (default: `dev_team`). Ignored when `customAgents` is provided. See [list templates](#list-team-templates) for available options.                           |
| `customAgents`         | array  | No          | Custom agent configurations. When provided, overrides the template. The number of agents must not exceed the plan's agent limit.                                                                      |

#### Custom agent object

Each object in the `customAgents` array has the following fields:

| Field          | Type      | Required | Description                                                                                     |
| -------------- | --------- | -------- | ----------------------------------------------------------------------------------------------- |
| `name`         | string    | Yes      | Agent identifier within the team                                                                |
| `role`         | string    | Yes      | Agent role (for example, `Engineer`, `QA`)                                                      |
| `description`  | string    | Yes      | Short description of the agent's purpose                                                        |
| `instruction`  | string    | Yes      | System instruction for the agent                                                                |
| `model`        | string    | Yes      | AI model identifier (for example, `openrouter/xiaomi/mimo-v2-pro`)                              |
| `tools`        | string\[] | Yes      | List of tools the agent can use (for example, `filesystem`, `shell`, `think`, `todo`, `memory`) |
| `memoryShared` | boolean   | Yes      | Whether the agent shares memory with other agents in the team                                   |

### Response

```json theme={"dark"}
{
  "success": true,
  "teamId": "team_1711234567890_a1b2c3",
  "template": "Dev Team",
  "agents": [
    {
      "container": "team_1711234567890_a1b2c3/pm",
      "status": "running",
      "url": "https://agentbot-agent-user123-pm.up.railway.app"
    },
    {
      "container": "team_1711234567890_a1b2c3/engineer",
      "status": "running",
      "url": "https://agentbot-agent-user123-engineer.up.railway.app"
    },
    {
      "container": "team_1711234567890_a1b2c3/qa",
      "status": "running",
      "url": "https://agentbot-agent-user123-qa.up.railway.app"
    }
  ],
  "yaml_config": "# Agentbot Team Configuration\n..."
}
```

| Field                | Type    | Description                                                  |
| -------------------- | ------- | ------------------------------------------------------------ |
| `success`            | boolean | Whether the team was provisioned                             |
| `teamId`             | string  | Unique team identifier (format: `team_{timestamp}_{random}`) |
| `template`           | string  | Name of the team template used                               |
| `agents`             | array   | Per-agent provisioning results                               |
| `agents[].container` | string  | Container path (format: `{teamId}/{agentName}`)              |
| `agents[].status`    | string  | Agent status (`running` or `failed`)                         |
| `agents[].url`       | string  | Agent service URL                                            |
| `yaml_config`        | string  | Generated YAML configuration for the team                    |

<Note>If an individual agent in the team fails to provision, its `status` is set to `failed` and the remaining agents continue provisioning. The overall request still returns `200` — check each agent's `status` field to identify failures.</Note>

### Errors

| Code | Description                                                                                                                                                                                                                                                                             |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | Invalid or missing `plan`. The error message reads `"Team provisioning requires collect, label, or network plan"` (the message says "collect" but the valid value is `collective`). Response includes `available_templates` listing valid template keys.                                |
| 401  | Unauthorized — missing or invalid session                                                                                                                                                                                                                                               |
| 402  | Active subscription required. Returned when `stripeSubscriptionId` is missing (from both body and `x-stripe-subscription-id` header) and the caller is not an admin. Response includes `code: "PAYMENT_REQUIRED"`.                                                                      |
| 402  | Agent limit reached for your plan. Returned when the user's active agent count meets or exceeds the plan limit. Response includes `code: "AGENT_LIMIT_REACHED"`, `current` (current agent count), and `limit` (maximum allowed). Plan limits: `collective` 3, `label` 10, `network` 50. |
| 500  | Team provisioning failed                                                                                                                                                                                                                                                                |

### Example request

```bash theme={"dark"}
curl -X POST https://api.agentbot.raveculture.xyz/api/provision/team \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "plan": "collective",
    "templateKey": "dev_team"
  }'
```

### Example with custom agents

```bash theme={"dark"}
curl -X POST https://api.agentbot.raveculture.xyz/api/provision/team \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "plan": "label",
    "customAgents": [
      {
        "name": "planner",
        "role": "Project Planner",
        "description": "Breaks down tasks and coordinates work",
        "instruction": "You are the planner. Break requirements into tasks.",
        "model": "openrouter/xiaomi/mimo-v2-pro",
        "tools": ["filesystem", "think", "todo", "memory"],
        "memoryShared": true
      },
      {
        "name": "coder",
        "role": "Developer",
        "description": "Implements features and writes code",
        "instruction": "You are the developer. Write clean code.",
        "model": "openrouter/xiaomi/mimo-v2-pro",
        "tools": ["filesystem", "shell", "think"],
        "memoryShared": true
      }
    ]
  }'
```

## List team templates

```http theme={"dark"}
GET /api/provision/team/templates
```

Returns all available pre-built team templates. Requires bearer token authentication (applied at the route mount level).

### Response

```json theme={"dark"}
{
  "templates": [
    {
      "key": "dev_team",
      "name": "Dev Team",
      "description": "Product Manager + Engineer + QA",
      "agent_count": 3,
      "agents": [
        { "name": "pm", "role": "Product Manager" },
        { "name": "engineer", "role": "Engineer" },
        { "name": "qa", "role": "QA" }
      ]
    },
    {
      "key": "devops_team",
      "name": "DevOps Team",
      "description": "SRE Lead + Infrastructure Engineer + Security Auditor",
      "agent_count": 3,
      "agents": [
        { "name": "sre", "role": "SRE Lead" },
        { "name": "infra", "role": "Infrastructure Engineer" },
        { "name": "security", "role": "Security Auditor" }
      ]
    }
  ],
  "categories": [
    {
      "key": "developer",
      "label": "Developer",
      "templates": ["dev_team", "devops_team", "api_team"]
    },
    {
      "key": "creator",
      "label": "Creator",
      "templates": ["content_team", "social_media_team", "research_team"]
    },
    {
      "key": "business",
      "label": "Business",
      "templates": ["legal_team", "finance_team", "marketing_team", "sales_team"]
    },
    {
      "key": "personal",
      "label": "Personal",
      "templates": ["personal_assistant", "solopreneur"]
    }
  ]
}
```

| Field                       | Type      | Description                                              |
| --------------------------- | --------- | -------------------------------------------------------- |
| `templates`                 | array     | Available team templates                                 |
| `templates[].key`           | string    | Template identifier used in `templateKey` parameter      |
| `templates[].name`          | string    | Human-readable template name                             |
| `templates[].description`   | string    | Summary of the team composition                          |
| `templates[].agent_count`   | number    | Number of agents in the template                         |
| `templates[].agents`        | array     | Agent definitions within the template                    |
| `templates[].agents[].name` | string    | Agent identifier                                         |
| `templates[].agents[].role` | string    | Agent role                                               |
| `categories`                | array     | Template categories for organizing templates by use case |
| `categories[].key`          | string    | Category identifier                                      |
| `categories[].label`        | string    | Human-readable category name                             |
| `categories[].templates`    | string\[] | List of template keys belonging to this category         |

## Available templates

Templates are organized into four categories: **Developer**, **Creator**, **Business**, and **Personal**.

### Developer

#### Dev Team (`dev_team`)

A development team with three agents:

| Agent      | Role            | Tools                                   |
| ---------- | --------------- | --------------------------------------- |
| `pm`       | Product Manager | `filesystem`, `think`, `todo`, `memory` |
| `engineer` | Engineer        | `filesystem`, `shell`, `think`          |
| `qa`       | QA              | `filesystem`, `shell`, `think`          |

#### DevOps Team (`devops_team`)

An infrastructure and reliability team with three agents:

| Agent      | Role                    | Tools                                            |
| ---------- | ----------------------- | ------------------------------------------------ |
| `sre`      | SRE Lead                | `filesystem`, `shell`, `think`, `todo`, `memory` |
| `infra`    | Infrastructure Engineer | `filesystem`, `shell`, `think`                   |
| `security` | Security Auditor        | `filesystem`, `shell`, `think`                   |

#### API Team (`api_team`)

An API development team with three agents:

| Agent       | Role             | Tools                                   |
| ----------- | ---------------- | --------------------------------------- |
| `architect` | API Architect    | `filesystem`, `think`, `todo`, `memory` |
| `backend`   | Backend Engineer | `filesystem`, `shell`, `think`          |
| `docs`      | Docs Writer      | `filesystem`, `think`                   |

### Creator

#### Content Team (`content_team`)

A content production team with three agents:

| Agent     | Role            | Tools                                   |
| --------- | --------------- | --------------------------------------- |
| `manager` | Content Manager | `filesystem`, `think`, `todo`, `memory` |
| `writer`  | Writer          | `filesystem`, `think`, `memory`         |
| `editor`  | Editor          | `filesystem`, `think`                   |

#### Social Media Team (`social_media_team`)

A social media team with three agents:

| Agent        | Role               | Tools                                   |
| ------------ | ------------------ | --------------------------------------- |
| `strategy`   | Strategy Lead      | `filesystem`, `think`, `todo`, `memory` |
| `creator`    | Content Creator    | `filesystem`, `think`, `memory`         |
| `engagement` | Engagement Manager | `filesystem`, `think`, `memory`         |

#### Research Team (`research_team`)

A research team with three agents:

| Agent     | Role            | Tools                                   |
| --------- | --------------- | --------------------------------------- |
| `lead`    | Lead Researcher | `filesystem`, `think`, `todo`, `memory` |
| `analyst` | Analyst         | `filesystem`, `shell`, `think`          |
| `writer`  | Research Writer | `filesystem`, `think`                   |

### Business

#### Legal Team (`legal_team`)

A legal advisory team with three agents:

| Agent        | Role               | Tools                                   |
| ------------ | ------------------ | --------------------------------------- |
| `advisor`    | Legal Advisor      | `filesystem`, `think`, `todo`, `memory` |
| `drafter`    | Contract Drafter   | `filesystem`, `think`                   |
| `compliance` | Compliance Officer | `filesystem`, `think`, `memory`         |

#### Finance Team (`finance_team`)

A financial operations team with three agents:

| Agent        | Role              | Tools                                    |
| ------------ | ----------------- | ---------------------------------------- |
| `analyst`    | Financial Analyst | `filesystem`, `shell`, `think`, `memory` |
| `accountant` | Accountant        | `filesystem`, `think`                    |
| `budget`     | Budget Manager    | `filesystem`, `think`, `todo`            |

#### Marketing Team (`marketing_team`)

A marketing team with three agents:

| Agent        | Role                 | Tools                                   |
| ------------ | -------------------- | --------------------------------------- |
| `strategist` | Marketing Strategist | `filesystem`, `think`, `todo`, `memory` |
| `copywriter` | Copywriter           | `filesystem`, `think`, `memory`         |
| `growth`     | Growth Analyst       | `filesystem`, `shell`, `think`          |

#### Sales Team (`sales_team`)

A sales team with three agents:

| Agent       | Role              | Tools                                   |
| ----------- | ----------------- | --------------------------------------- |
| `manager`   | Sales Manager     | `filesystem`, `think`, `todo`, `memory` |
| `qualifier` | Lead Qualifier    | `filesystem`, `think`, `memory`         |
| `ae`        | Account Executive | `filesystem`, `think`, `memory`         |

### Personal

#### Personal Assistant (`personal_assistant`)

A daily productivity team with three agents:

| Agent        | Role       | Tools                                   |
| ------------ | ---------- | --------------------------------------- |
| `scheduler`  | Scheduler  | `filesystem`, `think`, `todo`, `memory` |
| `researcher` | Researcher | `filesystem`, `think`, `memory`         |
| `writer`     | Writer     | `filesystem`, `think`, `memory`         |

#### Solopreneur (`solopreneur`)

A solo business operations team with three agents:

| Agent      | Role             | Tools                                   |
| ---------- | ---------------- | --------------------------------------- |
| `ops`      | Business Manager | `filesystem`, `think`, `todo`, `memory` |
| `marketer` | Marketer         | `filesystem`, `think`, `memory`         |
| `support`  | Support Agent    | `filesystem`, `think`, `memory`         |

<Note>All pre-built templates use `openrouter/xiaomi/mimo-v2-pro` as the default model and enable shared memory across all agents in the team.</Note>