v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

List agents

Returns a paginated list of agents visible to the authenticated caller. Results are ordered by creation time descending.

Use search to filter by name, org, team, or owner fields. Use user or org_id to scope the list to a specific owner. Use template_config to find agents whose last applied template matches a given config ID.

Pagination is page-based: pass page and page_size to navigate through large result sets. When called under a developer app scope, only agents belonging to that app are returned.

get/api/v1/agents

Query parameters

template_configstring

Config ID (cfg_...) or lookup_key of an AgentTemplate. Returns only agents whose last applied template matches.

searchstring

Free-text search string matched against the agent name, org, team, and owner fields.

page_sizeinteger

Number of agents to return per page. Defaults to 25.

org_idstring

Organization ID (org_...) to filter by. Returns only agents owned by this org.

pageinteger

Page number to retrieve, 1-indexed. Defaults to 1.

userstring

User ID (usr_...) to filter by. Returns only agents owned by this user.

Response

Successful response

has_nextboolean

true when a subsequent page of results exists.

has_prevboolean

true when a previous page of results exists.

pageinteger

Current page number, starting at 1.

page_sizeinteger

Maximum number of agents returned per page.

total_entriesinteger

Total number of agents matching the query across all pages.

total_pagesinteger

Total number of pages available given the current page_size.

Example response

{
  "data": [
    {
      "acl": {
        "add": [
          {
            "actions": [
              "read",
              "write"
            ],
            "principal": "string",
            "principal_type": "user"
          }
        ],
        "grants": [
          {
            "actions": [
              "read",
              "write"
            ],
            "principal": "string",
            "principal_type": "user"
          }
        ],
        "remove": [
          {
            "principal": "string",
            "principal_type": "user"
          }
        ]
      },
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "default_model": "claude-3-7-sonnet-latest",
      "email": "user@example.com",
      "id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "identity": "You are a helpful assistant that answers questions about ArchAstro products.",
      "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
      "lookup_key": "string",
      "metadata": {
        "key": "value"
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "org_name": "Example Name",
      "originator": "deploy-pipeline",
      "phone_number": "+15555550123",
      "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
      "source_solution": {
        "solution": {
          "category_keys": [
            "string"
          ],
          "created_at": "2024-01-01T00:00:00Z",
          "description": "An example description.",
          "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "kind": "Solution",
          "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "latest_version": "1.0.0",
          "lookup_key": "string",
          "metadata": {
            "key": "value"
          },
          "name": "Example Name",
          "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
          "org_logo": {
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "height": 600,
            "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
            "mime_type": "application/json",
            "refresh_url": "https://example.com",
            "url": "https://example.com",
            "width": 800
          },
          "org_name": "Example Name",
          "org_slug": "example-slug",
          "owners": [
            "string"
          ],
          "readme_url": "https://example.com",
          "solution_id": "01234567-89ab-cdef-0123-456789abcdef",
          "solution_version": "1.2.0",
          "tag_keys": [
            "string"
          ],
          "template_kind": "AgentTemplate",
          "templates": [
            {
              "description": "An example description.",
              "display_name": "Example Name",
              "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
              "kind": "AgentTemplate",
              "lookup_key": "string",
              "name": "Example Name",
              "readme_url": "https://example.com",
              "virtual_path": "string"
            }
          ],
          "updated_at": "2024-01-01T00:00:00Z",
          "upgrade_available": true,
          "virtual_path": "string"
        },
        "template": {
          "created_at": "2024-01-01T00:00:00Z",
          "description": "An example description.",
          "display_name": "Example Name",
          "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "kind": "agent_tool_template",
          "lookup_key": "string",
          "name": "Example Name",
          "updated_at": "2024-01-01T00:00:00Z",
          "virtual_path": "string"
        }
      },
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
    }
  ],
  "has_next": true,
  "has_prev": true,
  "page": 1,
  "page_size": 20,
  "total_entries": 42,
  "total_pages": 1
}