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

# Agents API

> Register, list, update, and delete agents. Manage teams.

## List Agents

```
GET /agents
```

Query parameters:

| Parameter     | Type    | Description                                      |
| ------------- | ------- | ------------------------------------------------ |
| `status`      | string  | Filter: `healthy`, `degraded`, `down`, `unknown` |
| `framework`   | string  | Filter by framework                              |
| `team`        | string  | Filter by team                                   |
| `environment` | string  | Filter: `production`, `staging`, `dev`           |
| `page`        | integer | Page number (default: 1)                         |
| `limit`       | integer | Results per page (default: 20, max: 100)         |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/agents?status=healthy&limit=50" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "agt_abc123",
        "name": "production-summarizer",
        "description": "Summarizes customer support tickets",
        "framework": "crewai",
        "model_provider": "openai",
        "model_name": "gpt-4o",
        "environment": "production",
        "status": "healthy",
        "team": "support-team",
        "risk_level": "limited",
        "last_heartbeat": "2026-03-17T10:30:00Z",
        "created_at": "2026-03-01T08:00:00Z"
      }
    ],
    "meta": { "total": 12, "page": 1, "limit": 50 }
  }
  ```
</ResponseExample>

## Register an Agent

```
POST /agents
```

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/agents \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-summarizer",
    "description": "Summarizes customer support tickets",
    "framework": "crewai",
    "model_provider": "openai",
    "model_name": "gpt-4o",
    "environment": "production",
    "team": "support-team",
    "tags": {"version": "1.2.0"}
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "agt_abc123",
      "name": "production-summarizer",
      "description": "Summarizes customer support tickets",
      "framework": "crewai",
      "model_provider": "openai",
      "model_name": "gpt-4o",
      "environment": "production",
      "status": "unknown",
      "team": "support-team",
      "tags": {"version": "1.2.0"},
      "created_at": "2026-03-17T10:00:00Z"
    }
  }
  ```
</ResponseExample>

## Get an Agent

```
GET /agents/{agent_id}
```

```bash theme={null}
curl https://api.meshai.dev/api/v1/agents/agt_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

## Update an Agent

```
PATCH /agents/{agent_id}
```

```bash theme={null}
curl -X PATCH https://api.meshai.dev/api/v1/agents/agt_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Summarizes and categorizes support tickets",
    "model_name": "gpt-4o-mini",
    "tags": {"version": "1.3.0"}
  }'
```

## Delete an Agent

```
DELETE /agents/{agent_id}
```

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/agents/agt_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Returns `204 No Content` on success. The agent's historical data is preserved in the audit trail.

## Teams

### List Teams

```
GET /teams
```

```bash theme={null}
curl https://api.meshai.dev/api/v1/teams \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "team_abc123",
        "name": "support-team",
        "agent_count": 5,
        "monthly_cost_usd": 456.78,
        "created_at": "2026-02-15T08:00:00Z"
      },
      {
        "id": "team_def456",
        "name": "sales-team",
        "agent_count": 3,
        "monthly_cost_usd": 312.45,
        "created_at": "2026-02-20T08:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>

### Create a Team

```
POST /teams
```

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/teams \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "engineering-team"
  }'
```

### Update a Team

```
PATCH /teams/{team_id}
```

Rename a team. The name must be unique within the tenant.

```bash theme={null}
curl -X PATCH https://api.meshai.dev/api/v1/teams/team_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "platform-engineering"
  }'
```

Returns `409 Conflict` if a team with that name already exists.

### Delete a Team

```
DELETE /teams/{team_id}
```

Delete a team. The team must have no agents assigned to it.

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/teams/team_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Returns `204 No Content` on success. Returns `409 Conflict` if the team still has agents assigned. Reassign or remove them first.