List agents

List agents with multi-scope filter. Supported scopes (comma-separated): own, shared, published, all. Default own. The reserved action ?action=explore returns all public+restricted published agents in the caller’s organization.

GET /v1/agents

List agents

cURL

curl --request GET \
  --url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents \
  --header 'Authorization: Bearer <token>'

200

{
  "items": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "instructions": "<string>",
      "model": "<string>",
      "fallback_models": [
        "<string>"
      ],
      "temperature": 123,
      "icon_url": "<string>",
      "skills": [
        {}
      ],
      "tools": [
        {
          "id": "<string>",
          "name": "<string>",
          "display_name": "<string>",
          "description": "<string>",
          "catalog_id": "<string>",
          "auth": {},
          "icon_url": "<string>",
          "vector_store_id": "<string>",
          "server": "<string>",
          "headers": {},
          "scope": "<string>",
          "url": "<string>",
          "parameters": {}
        }
      ],
      "tool_permissions": {
        "default": "auto",
        "tools": [
          {
            "tool": "<string>",
            "conditions": {},
            "approvers": [
              {
                "id": "<string>"
              }
            ]
          }
        ]
      },
      "tool_activation": {
        "default": "auto",
        "tools": [
          {
            "tool": "<string>"
          }
        ]
      },
      "guardrails": {},
      "sub_agents": [
        {
          "agent_id": "<string>",
          "name": "<string>",
          "description": "<string>"
        }
      ],
      "starters": [
        {}
      ],
      "allowed_models": [
        "<string>"
      ],
      "max_tokens": 123,
      "max_turns": 123,
      "token_budget": 123,
      "tool_call_budget": 123,
      "canvas_enabled": true,
      "category": "<string>",
      "tags": [
        "<string>"
      ],
      "owner_id": "<string>",
      "orgSlug": "<string>",
      "subscription_id": "<string>",
      "serviceAccountId": "<string>",
      "published_config": {},
      "published_at": "2023-11-07T05:31:56Z",
      "has_draft_changes": true,
      "rating": 123,
      "ratings_count": 123,
      "messages_count": 123,
      "conversations_count": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123,
  "page": 123,
  "limit": 123
}

Authorizations

BearerAuthOrgApiKeyAuth

Authorization · string · header · required

User-bound credential carrying an identity: either a session JWT or a user access token (at:*) generated from the user settings UI. Send as Authorization: Bearer <token>. Org API keys (iak_*) are not accepted here - they carry no user identity. Use the x-prismeai-api-key header instead (see OrgApiKeyAuth).

Query Parameters

scope · string

Comma-separated list (own, shared, published, all).

Maximum string length: 64

action · enum<string>

Reserved action (explore for store-style discovery, write to filter to writable scope).

Available options: explore, write

Maximum string length: 32

status · string

Maximum string length: 32

category · string

Maximum string length: 128

search · string

Maximum string length: 200

sort · enum<string>

Available options: updatedAt, createdAt

Maximum string length: 32

limit · string

Page size (max 100, default 20).

page · string

1-indexed page number.

Response

200

application/json

Page of agents (with published_config stripped on list rows).

Page of agents (with published_config stripped on list rows).

items · object[]

Hide child attributes

items. id · string

items. name · string

items. description · string

items. instructions · string

items. model · string

items. fallback_models · string[]

items. temperature · number

items. icon_url · string

items. skills · object[]

items. tools · object[]

Hide child attributes

items.tools. id · string

items.tools. type · enum<string>

Available options: file_search, mcp, function

items.tools. name · string

Pattern: ^[a-zA-Z0-9_-]+$

items.tools. display_name · string

items.tools. description · string

items.tools. catalog_id · string

items.tools. auth · object

items.tools. icon_url · string

items.tools. vector_store_id · string

Required for file_search.

items.tools. server · string

MCP server URL (for mcp).

items.tools. headers · object

items.tools. scope · string

items.tools. url · string

Required for function.

items.tools. parameters · object

JSON Schema describing the function tool's parameters.

items. tool_permissions · object

Human-in-the-Loop configuration. Sets a default policy plus optional per-tool overrides. Policies:

• auto: run immediately (default).
• always_ask: halt every call on approval.
• ask_external: halt only on MCP tool calls.
• ask_first: halt the first time a tool runs in a session; cache keyed per child name unless an MCP parent rule is configured (then cached per parent).

Hide child attributes

items.tool_permissions. default · enum<string> · default: auto

Available options: auto, always_ask, ask_external, ask_first

items.tool_permissions. tools · object[]

Hide child attributes

items.tool_permissions.tools. tool · string · required

items.tool_permissions.tools. policy · enum<string> · required

Available options: auto, always_ask, ask_external, ask_first

items.tool_permissions.tools. conditions · object

Optional jsonmatch pattern compared against the tool call's arguments. The rule's policy only fires when the pattern matches; otherwise the call runs without prompting.

items.tool_permissions.tools. approvers · object[]

Hide child attributes

items.tool_permissions.tools.approvers. type · enum<string> · required

Available options: owner, user, group

items.tool_permissions.tools.approvers. id · string

Required for user and group. Ignored for owner.

items. tool_activation · object

Controls whether the model can use a given tool on a given turn. user_first tools are replaced by a same-named, schema-less stub with a "disabled" description on each turn, unless the user explicitly summons the tool from the chat input via metadata.tool_choice. Eligible tool types: function and mcp. file_search, skill, guardrail, and system types are exempt and always behave as auto.

Hide child attributes

items.tool_activation. default · enum<string> · default: auto

Available options: auto, user_first

items.tool_activation. tools · object[]

Hide child attributes

items.tool_activation.tools. tool · string · required

items.tool_activation.tools. activation · enum<string> · required

Available options: auto, user_first

items. guardrails · object

items. sub_agents · object[]

Hide child attributes

items.sub_agents. agent_id · string

items.sub_agents. name · string

items.sub_agents. description · string

items. starters · object[]

items. allowed_models · string[]

items. max_tokens · integer

items. max_turns · integer

items. token_budget · integer

items. tool_call_budget · integer

items. canvas_enabled · boolean

items. visibility · enum<string>

Available options: public, private, restricted

items. category · string

items. tags · string[]

items. status · enum<string>

Available options: draft, published

items. profile · enum<string>

Available options: simple, workflow, agent_light, agent_full, orchestrator

items. owner_id · string

items. orgSlug · string

items. subscription_id · string

items. serviceAccountId · string

items. published_config · object

Snapshot of runtime fields at last publish (owners only).

items. published_at · string<date-time>

items. has_draft_changes · boolean

items. rating · number

items. ratings_count · integer

items. messages_count · integer

items. conversations_count · integer

items. access_status · enum<string>

Only present on restricted-agent rows in list/discovery views.

Available options: granted, none

items. createdAt · string<date-time>

items. updatedAt · string<date-time>

total · integer

page · integer

limit · integer