Agents API - MeshAI Documentation

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)

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

{
  "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 }
}

Register an Agent

POST /agents

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"}
  }'

{
  "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"
  }
}

Get an Agent

GET /agents/{agent_id}

curl https://api.meshai.dev/api/v1/agents/agt_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Update an Agent

PATCH /agents/{agent_id}

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}

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

curl https://api.meshai.dev/api/v1/teams \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

{
  "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"
    }
  ]
}

Create a Team

POST /teams

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.

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.

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.

​List Agents

​Register an Agent

​Get an Agent

​Update an Agent

​Delete an Agent

​Teams

​List Teams

​Create a Team

​Update a Team

​Delete a Team