Reference

List agents

Agents (Concierges) this token can reach, with id, status (live or draft) and your role.

REST	`GET /api/v1/agents`
MCP tool	`list_agents`
Classification	Read (changes nothing)
Scope	Any valid token
Minimum role on the agent	any member
Confirmation	Not needed
Retry safety	Safe to retry with the same input
Success status	200

What it does

Agents (Concierges) this token can reach, with id, status (live or draft) and your role. Filter by workspace, brand or status.

Side effects

None. It only reads.

Inputs

Name	Type	Required	In	Description
`workspace_id`	string	no	query
`brand_id`	string	no	query
`published`	boolean or "true" \| "false"	no	query	true or false
`limit`	integer	no	query	At most 100. Default 50.
`offset`	integer	no	query	Default 0.

Example

REST

curl "https://covo.lanaai.io/api/v1/agents?limit=10" \
  -H "Authorization: Bearer $COVO_TOKEN"

MCP (POST /mcp)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_agents",
    "arguments": {
      "limit": 10
    }
  }
}

Response

Returns an object with items, total, limit and offset. This is a real response, shortened to two items per list.

200 response

{
  "items": [
    {
      "id": "agt_4edc89bb2964",
      "name": "Avery Quinn's Concierge",
      "represents": "Avery Quinn",
      "slug": "avery",
      "status": "draft",
      "role": "owner",
      "workspace_id": "df39921a-9546-4e6d-9241-90ee65891dbf",
      "brand_id": "ae435f18-5eab-4afe-abff-eb88f1e3ffd3",
      "url": "https://covo.lanaai.io/avery"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Over MCP the same object comes back as the tool result, in structuredContent and as JSON text.

Errors

Status	Code	Meaning
401	`unauthorized`	No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect.
403	`account_suspended`	The account that owns the token is paused.
400	`bad_request`	An input is invalid; `field` names it.
429	`rate_limited`	Wait `Retry-After` seconds.