Agents

These endpoints let you list and fetch the agents in your organization. Use them to discover available agents, read their configuration, or integrate agent listings into external tools.

`GET /agents`

Lists all agents in the organization with summary information.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`50`	Maximum number of results. Maximum: `100`.
`offset`	integer	`0`	Offset for pagination.
`active`	boolean	`true`	Filter by active agents (`true`) or inactive (`false`).

curl https://api.squados.io/v1/agents?limit=10&offset=0&active=true \
  -H "Authorization: Bearer pk_your_key_here"

Response 200

{
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Customer Support",
      "description": "Support agent with knowledge from the product catalog.",
      "model": "gpt-4o-mini",
      "avatar_url": "https://cdn.squados.io/avatars/a1b2c3d4.png",
      "is_public": true,
      "active": true,
      "temperature": 0.7,
      "history_limit": 20,
      "created_at": "2026-01-15T10:30:00Z",
      "conversation_count": 1482,
      "bases_count": 2
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Internal Assistant",
      "description": "Answers the team's questions about internal processes.",
      "model": "claude-3-5-haiku",
      "avatar_url": null,
      "is_public": false,
      "active": true,
      "temperature": 0.4,
      "history_limit": 10,
      "created_at": "2026-02-20T14:00:00Z",
      "conversation_count": 214,
      "bases_count": 1
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0
}

`GET /agents/{agentId}`

Returns the full details of an agent, including the system prompt, model, linked knowledge bases, and tool count.

Path parameters

Parameter	Type	Description
`agentId`	UUID	The agent’s ID.

curl https://api.squados.io/v1/agents/AGENT_ID \
  -H "Authorization: Bearer pk_your_key_here"

Response 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Customer Support",
  "description": "Support agent with knowledge from the product catalog.",
  "prompt": "You are a customer support assistant for Acme. Your goal is to resolve questions about products, orders, and returns in a clear and friendly way. Always greet the customer by name when available.",
  "model": "gpt-4o-mini",
  "model_details": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "GPT-4o mini",
    "provider": "OpenAI",
    "supports_vision": true,
    "supports_files": true
  },
  "avatar_url": "https://cdn.squados.io/avatars/a1b2c3d4.png",
  "is_public": true,
  "active": true,
  "temperature": 0.7,
  "history_limit": 20,
  "created_at": "2026-01-15T10:30:00Z",
  "bases": [
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "name": "Product Catalog"
    },
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "name": "Return Policies"
    }
  ],
  "tools_count": 3,
  "conversation_count": 1482
}

Errors

Status	Code	Description
`404`	`AGENT_NOT_FOUND`	No agent with that ID was found in the organization.

See Errors for the full error response format.