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

# Agent Teams

> Create a validated task DAG, claim and complete tasks; dependency-gated, tenant-scoped, with a read-only view of state.

An agent team organises tasks as a **directed acyclic graph (DAG)** that several workers work through. Creation validates duplicate ids, dangling dependencies, self-dependencies and cycles before anything is stored; the graph shape never changes afterwards, only task state moves `pending` → `claimed` → `done`.

## Endpoints

```http theme={null}
POST /v1/agent-teams
GET  /v1/agent-teams
GET  /v1/agent-teams/{team_id}
POST /v1/agent-teams/{team_id}/tasks/{task_id}/claim
POST /v1/agent-teams/{team_id}/tasks/{task_id}/complete
```

## Authentication

`Authorization: Bearer <api_key>` or `Authorization: ApiKey <key>`. Optional if `AGENT_CLOUD_API_KEY` is unset. Every row is scoped by `principal_id`.

## Request body

**name** `string` *required*

Team name (non-empty).

**tasks** `array` *required*

Non-empty task list. Each item has `id` (optional, `t1`… by default), `title` and `depends_on` (task ids).

For `claim`: `worker` (optional, defaults to the current principal id). For `complete`: `result` (the task output).

## Response

**id** `string`

Team id (server-generated when omitted).

**object** `string`

Always `agent_team`.

**name** `string`

Team name.

**tasks** `array`

Task list with `id`, `title`, `depends_on`, `state`, `claimed_by`, etc.

**done** `integer`

Number of completed tasks.

**total** `integer`

Total number of tasks.

`claim` returns `403` when dependencies are unfinished or the task is already claimed; an unknown team is `404`; a cycle or dangling dependency is `400`; ids owned by another tenant are invisible and unwritable.

```bash cURL theme={null}
curl -X POST https://agent.ariacompute.com/v1/agent-teams \
  -H "Authorization: Bearer $ARIA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "release",
    "tasks": [
      {"id": "spec", "title": "Write the spec"},
      {"id": "impl", "title": "Implement", "depends_on": ["spec"]}
    ]
  }'
```

```json 200 theme={null}
{
  "id": "team_01...",
  "object": "agent_team",
  "name": "release",
  "tasks": [
    {"id": "spec", "title": "Write the spec", "depends_on": [], "state": "pending"},
    {"id": "impl", "title": "Implement", "depends_on": ["spec"], "state": "pending"}
  ],
  "done": 0,
  "total": 2
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.