Get featured agents and categories

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

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

fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/discovery', 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/discovery"

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

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

print(response.text)

{
  "featured": [
    {
      "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"
    }
  ],
  "categories": [
    {
      "value": "<string>",
      "count": 123
    }
  ]
}

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

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

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

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

GET

agents

discovery

Get featured agents and categories

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

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

fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/discovery', 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/discovery"

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

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

print(response.text)

{
  "featured": [
    {
      "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"
    }
  ],
  "categories": [
    {
      "value": "<string>",
      "count": 123
    }
  ]
}

{
  "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).

Response

Featured agents + categories.

Featured agents + categories for the discovery surface.

featured

object[]

Hide child attributes

featured.id

string

featured.name

string

featured.description

string

featured.instructions

string

featured.model

string

featured.fallback_models

string[]

featured.temperature

number

featured.icon_url

string

featured.skills

object[]

featured.tools

object[]

Hide child attributes

featured.tools.id

string

featured.tools.type

enum<string>

Available options:

file_search,

mcp,

function

featured.tools.name

string

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

featured.tools.display_name

string

featured.tools.description

string

featured.tools.catalog_id

string

featured.tools.auth

object

featured.tools.icon_url

string

featured.tools.vector_store_id

string

Required for file_search.

featured.tools.server

string

MCP server URL (for mcp).

featured.tools.headers

object

featured.tools.scope

string

featured.tools.url

string

Required for function.

featured.tools.parameters

object

JSON Schema describing the function tool's parameters.

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

featured.tool_permissions.default

enum<string>

default:auto

Available options:

auto,

always_ask,

ask_external,

ask_first

featured.tool_permissions.tools

object[]

Hide child attributes

featured.tool_permissions.tools.tool

string

required

featured.tool_permissions.tools.policy

enum<string>

required

Available options:

auto,

always_ask,

ask_external,

ask_first

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

featured.tool_permissions.tools.approvers

object[]

Hide child attributes

featured.tool_permissions.tools.approvers.type

enum<string>

required

Available options:

owner,

user,

group

featured.tool_permissions.tools.approvers.id

string

Required for user and group. Ignored for owner.

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

featured.tool_activation.default

enum<string>

default:auto

Available options:

auto,

user_first

featured.tool_activation.tools

object[]

Hide child attributes

featured.tool_activation.tools.tool

string

required

featured.tool_activation.tools.activation

enum<string>

required

Available options:

auto,

user_first

featured.guardrails

object

featured.sub_agents

object[]

Hide child attributes

featured.sub_agents.agent_id

string

featured.sub_agents.name

string

featured.sub_agents.description

string

featured.starters

object[]

featured.allowed_models

string[]

featured.max_tokens

integer

featured.max_turns

integer

featured.token_budget

integer

featured.tool_call_budget

integer

featured.canvas_enabled

boolean

featured.visibility

enum<string>

Available options:

public,

private,

restricted

featured.category

string

featured.tags

string[]

featured.status

enum<string>

Available options:

draft,

published

featured.profile

enum<string>

Available options:

simple,

workflow,

agent_light,

agent_full,

orchestrator

featured.owner_id

string

featured.orgSlug

string

featured.subscription_id

string

featured.serviceAccountId

string

featured.published_config

object

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

featured.published_at

string<date-time>

featured.has_draft_changes

boolean

featured.rating

number

featured.ratings_count

integer

featured.messages_count

integer

featured.conversations_count

integer

featured.access_status

enum<string>

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

Available options:

granted,

none

featured.createdAt

string<date-time>

featured.updatedAt

string<date-time>

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

Collections API

Get featured agents and categories

Authorizations

Response