List agents

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "instructions": "<string>",
      "model": "<string>",
      "fallback_models": [
        "<string>"
      ],
      "temperature": 123,
      "icon_url": "<string>",
      "skills": [
        {}
      ],
      "attachments": {
        "upload": {
          "workspaceId": "<string>",
          "url": "<string>",
          "method": "POST"
        }
      },
      "tools": [
        {
          "id": "<string>",
          "type": "file_search",
          "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>",
            "policy": "auto",
            "conditions": {},
            "approvers": [
              {
                "type": "owner",
                "id": "<string>"
              }
            ]
          }
        ]
      },
      "tool_activation": {
        "default": "auto",
        "tools": [
          {
            "tool": "<string>",
            "activation": "auto"
          }
        ]
      },
      "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,
      "effective_defaults": {
        "temperature": 123,
        "temperature_ignored": true,
        "max_tokens": 123,
        "max_turns": 123,
        "token_budget": 123,
        "tool_call_budget": 123
      },
      "canvas_enabled": true,
      "visibility": "public",
      "category": "<string>",
      "tags": [
        "<string>"
      ],
      "status": "draft",
      "profile": "simple",
      "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,
      "access_status": "granted",
      "role": "owner",
      "access_reason": "<string>",
      "is_owner": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123,
  "page": 123,
  "limit": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Agents

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. The shared scope also lists agents with no published version that were explicitly shared with the caller, served as their draft at the role the share carries. An agent from another organization is listed under shared only when someone else created it and shared it with the caller; agents the caller created in another organization stay in that organization’s lists.

GET

agents

List agents

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "instructions": "<string>",
      "model": "<string>",
      "fallback_models": [
        "<string>"
      ],
      "temperature": 123,
      "icon_url": "<string>",
      "skills": [
        {}
      ],
      "attachments": {
        "upload": {
          "workspaceId": "<string>",
          "url": "<string>",
          "method": "POST"
        }
      },
      "tools": [
        {
          "id": "<string>",
          "type": "file_search",
          "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>",
            "policy": "auto",
            "conditions": {},
            "approvers": [
              {
                "type": "owner",
                "id": "<string>"
              }
            ]
          }
        ]
      },
      "tool_activation": {
        "default": "auto",
        "tools": [
          {
            "tool": "<string>",
            "activation": "auto"
          }
        ]
      },
      "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,
      "effective_defaults": {
        "temperature": 123,
        "temperature_ignored": true,
        "max_tokens": 123,
        "max_turns": 123,
        "token_budget": 123,
        "tool_call_budget": 123
      },
      "canvas_enabled": true,
      "visibility": "public",
      "category": "<string>",
      "tags": [
        "<string>"
      ],
      "status": "draft",
      "profile": "simple",
      "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,
      "access_status": "granted",
      "role": "owner",
      "access_reason": "<string>",
      "is_owner": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123,
  "page": 123,
  "limit": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Authorizations

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

Response

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.attachments

object

read-only

Where to upload an attachment before referencing it in message.parts[].url: POST {url} in multipart, then put the returned file url in the part. This is the storage workspace, the one the web chat uploads to; clients should read it here rather than hardcode a workspace.

Hide child attributes

items.attachments.upload

object

Hide child attributes

items.attachments.upload.workspaceId

string

Workspace reference usable as-is in a /workspaces/{workspaceId} path. Currently the slug form slug:storage, not a raw id.

items.attachments.upload.url

string<uri>

items.attachments.upload.method

enum<string>

Available options:

POST

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, then auto-approve that tool for the rest of the session. The approval is cached per tool (the namespaced <parent>__<child> name for an MCP child) whatever level the rule is written at: under an MCP server rule, approving one child does not approve its siblings. When the matched rule carries conditions, the approval is also scoped to those conditions (e.g. records with action: delete is approved apart from records itself).

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. A matching conditional rule beats a rule without conditions on the same tool, whatever their order in the array; when no conditional rule matches, the call falls through to the tool's rule without conditions, then to a legacy rule on the bare tool name, then to the server's rule, then to default.

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.effective_defaults

object

Editor view only (x-draft-mode, caller with edit rights). The values the runtime applies when an advanced field is left empty: profile limits first, then the workspace defaults (max_turns and tool_call_budget have no profile default: the workspace default applies, 50 and 100 respectively); max_tokens is the model's declared response limit, or null when the provider drops max_tokens (its own default applies). temperature_ignored is true when the model's provider drops the temperature parameter.

Hide child attributes

items.effective_defaults.temperature

number

items.effective_defaults.temperature_ignored

boolean

items.effective_defaults.max_tokens

integer | null

items.effective_defaults.max_turns

integer

items.effective_defaults.token_budget

integer

items.effective_defaults.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.role

enum<string> | null

The CALLER's effective rights on this agent, computed at read time. It has the same shape as role on knowledge bases. Returned by GET /v1/agents/{agent_id} and by the list endpoint.

owner - owns the agent.
admin - platform admin, agent-factory admin in the agent's org, or a share carrying the owner/admin role. Implies publish rights.
editor - may write but NOT publish. A surface rendering a publish button must check for admin, not merely "not reader".
reader - a decision was taken and it grants no write.
null - UNDETERMINED, not a refusal: for a caller who is neither owner nor admin, the write decision is only taken when the request asks for it - x-draft-mode on the detail endpoint, x-draft-mode or ?action=write on the list. A consumer read (chat, embed, A2A, MCP) pays for no probe and gets null. Render no access screen on null - re-ask with the header, or show the consumer view.

Reading an agent is much wider than editing it (a published+public agent is readable org-wide), which is why Agent Creator gates its UI on this rather than on the global agent-factory:agents:write scope. Informational - write endpoints still authorize on their own.

Available options:

owner,

admin,

editor,

reader,

null

items.access_reason

string

Which access path granted the read: owner, admin, public, published, trusted-source:<workspace>, binding:<principal>[:<role>], wildcard-scope, scope or permission. Diagnostic companion to role, and internal authorization topology - so it rides with the editor surface only: GET /v1/agents/{agent_id} returns it when the request carries x-draft-mode, and never on a consumer read or in the list.

The binding: prefix carries a second job: it is what lets an agent with no published version be served to someone it was explicitly shared with - never published or withdrawn alike, since withdrawing empties the catalogue and not the shares. A public consumer (public), an admin (admin) and an RBAC scope (wildcard-scope, scope) do not match it and keep the refusal.

items.is_owner

boolean

Whether the caller owns this agent. Redundant with role = owner, kept for surfaces that only need that one bit.

items.createdAt

string<date-time>

items.updatedAt

string<date-time>

total

integer

page

integer

limit

integer

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

Collections API

List agents

Authorizations

Query Parameters

Response