---
title: "List Agents"
method: GET
path: "/api/agents"
tags: ["agents"]
---

# List Agents

`GET /api/agents`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/agents`
- Auth: none declared

List all agents visible to the current identity.

TOS-419 optional filters: ``archetype`` and ``tag`` (a tag slug) narrow the
result server-side. Both are AND-combined when present.

TOS-595: the system-only ``integration`` archetype is accepted HERE as a
read filter (it surfaces the caller's integration-agent wrappers), even
though it is rejected as a manual assignment on PUT /api/agents/{id}. The
accepted read set is therefore ``ALL_ARCHETYPES``; any other value is 422.

TOS-3512: returns the trimmed ``AgentSummaryResponse`` shape - no
``system_prompt``/``config`` - since those two fields alone accounted for
~95% of a measured 431KB/56-agent payload. A caller needing either field
fetches ``GET /api/agents/{agent_id}``, which still returns the full
``AgentResponse``.

TOS-3663 follow-up: serialized through ``_agent_list_payloads`` rather than
a FastAPI ``response_model``, so the owner-only omission contract applies
here too. ``list_agents_for`` returns every ``is_global`` agent plus any
agent the caller holds a viewer grant on, so this endpoint hands most of
its rows to a NON-owner; before this it shipped ``model_bundle``,
the since-retired ``reply_style`` and ``autonomy_tier``, ``default_mode``,
``self_improvement_mode`` and the owner's ``listing`` consent record to
each one. Declaring the model here is what bypassed the contract, which is
why ``response_model`` is now pinned to None by a test.

## Query parameters

- `archetype` string, nullable
- `tag` string, nullable

## Headers

- `x-impersonate-identity-id` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/ce2c2ce318b1?raw)