Agents

The Agents endpoints are read-only. They let you discover non-archived agents in the token’s organization and inspect the full configuration of a specific agent.

Every call requires Authorization: Bearer pk_.... The base is https://api.squados.io/v1; see Authentication and Errors for shared contracts.

List agents

`GET /agents`

Returns the organization’s agents, newest first. Archived agents never appear in the list.

Query	Type	Default	Current behavior
`limit`	integer	`50`	Page size. The maximum is `100`; larger values are reduced to 100.
`offset`	integer	`0`	Number of agents skipped before the page.
`active`	boolean	`true`	Missing or different from the literal text `false`: returns active agents only. `false`: removes the filter and returns active and inactive agents.

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

Response 200

{
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Customer Support",
      "description": "Answers questions about products and orders.",
      "model": "openai/gpt-4o-mini",
      "avatar_url": null,
      "is_public": true,
      "active": true,
      "temperature": 0.7,
      "history_limit": 20,
      "created_at": "2026-01-15T10:30:00Z",
      "conversation_count": 1482,
      "bases_count": 2
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

total covers all agents matching the current filter, not only the returned page. A page without results returns agents: [] and total: 0.

List fields

model is the linked model’s slug. If the agent has no linked model, the API returns the system’s active default model slug.
description and avatar_url can be null.
conversation_count counts conversations assigned to the agent.
bases_count counts links between the agent and knowledge bases.
A failure while querying agents returns 500 internal_error.

Get an agent

`GET /agents/{agentId}`

The UUID must identify a non-archived agent in the token’s organization.

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": "Answers questions about products and orders.",
  "prompt": "You are a clear and friendly customer support assistant.",
  "model": "openai/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": null,
  "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"
    }
  ],
  "tools_count": 3,
  "conversation_count": 1482
}

Interpreting the detail

prompt contains the agent’s complete system prompt. Treat it as sensitive configuration from your organization.
model always contains a slug: it uses the linked model or the system’s active default.
model_details contains data for the linked model and can be null when the agent relies on the default model.
bases contains only the id and name of linked bases.
tools_count counts only active native tools in agent_native_tools; it is not the sum of every integration and custom tool available to the agent.
conversation_count counts conversations assigned to the agent.

Errors and limits

Situation	Response
`agentId` is not a valid UUID	`400 invalid_request`
Agent is missing, archived, or belongs to another organization	`404 not_found`
Token is missing, invalid, or revoked	`401 unauthorized`

API v1 has no public operations to create, edit, activate, deactivate, or archive agents. Perform those actions in the product and use these endpoints for reading and integration.