Skip to main content
GET
Get a single agent by ID

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

  • 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 an editor UI gates 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
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 is returned by GET /v1/agents/{agent_id} only when the request carries x-draft-mode, never on a consumer read or in the list.

is_owner
boolean

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

createdAt
string<date-time>
updatedAt
string<date-time>