Skip to main content
GET
/
v1
/
agents
/
{agentId}
Get a single agent by ID
curl --request GET \
  --url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId} \
  --header 'Authorization: Bearer <token>'
{
  "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"
}

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

Path Parameters

agentId
string
required
Maximum string length: 64

Response

Agent record (Agent or AgentRestrictedView depending on caller's access).

Agent record (full view). Owners see this complete record including published_config. Non-owners with binding receive the same shape with published_config stripped server-side. Restricted-agent rows additionally carry access_status (granted or none) when seen in list/discovery views.

id
string
name
string
description
string
instructions
string
model
string
fallback_models
string[]
temperature
number
icon_url
string
skills
object[]
tools
object[]
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).
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.

guardrails
object
sub_agents
object[]
starters
object[]
allowed_models
string[]
max_tokens
integer
max_turns
integer
token_budget
integer
tool_call_budget
integer
canvas_enabled
boolean
visibility
enum<string>
Available options:
public,
private,
restricted
category
string
tags
string[]
status
enum<string>
Available options:
draft,
published
profile
enum<string>
Available options:
simple,
workflow,
agent_light,
agent_full,
orchestrator
owner_id
string
orgSlug
string
subscription_id
string
serviceAccountId
string
published_config
object

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

published_at
string<date-time>
has_draft_changes
boolean
rating
number
ratings_count
integer
messages_count
integer
conversations_count
integer
access_status
enum<string>

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

Available options:
granted,
none
createdAt
string<date-time>
updatedAt
string<date-time>