curl --request GET \
--url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId} \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}', 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/{agentId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"id": "<string>",
"name": "<string>",
"description": "<string>",
"instructions": "<string>",
"model": "<string>",
"fallback_models": [
"<string>"
],
"temperature": 123,
"icon_url": "<string>",
"skills": [
{}
],
"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,
"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"
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}Get a single agent by ID
Returns the agent record. Owners see the full record (including
published_config). Non-owners with binding receive the record
with published_config stripped. Restricted agents seen by
callers without binding return only public-facing fields.
curl --request GET \
--url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId} \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}', 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/{agentId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"id": "<string>",
"name": "<string>",
"description": "<string>",
"instructions": "<string>",
"model": "<string>",
"fallback_models": [
"<string>"
],
"temperature": 123,
"icon_url": "<string>",
"skills": [
{}
],
"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,
"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"
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}Authorizations
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
64Response
Agent record (Agent or AgentRestrictedView depending on caller's access).
- Option 1
- Option 2
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.
Hide child attributes
Hide child attributes
file_search, mcp, function ^[a-zA-Z0-9_-]+$Required for file_search.
MCP server URL (for mcp).
Required for function.
JSON Schema describing the function tool's parameters.
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
Hide child attributes
auto, always_ask, ask_external, ask_first Hide child attributes
Hide child attributes
auto, always_ask, ask_external, ask_first 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.
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.
public, private, restricted draft, published simple, workflow, agent_light, agent_full, orchestrator Snapshot of runtime fields at last publish (owners only).
Only present on restricted-agent rows in list/discovery views.
granted, none 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 foradmin, 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-modeon the detail endpoint,x-draft-modeor?action=writeon 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.
owner, admin, editor, reader, null 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.
Whether the caller owns this agent. Redundant with role = owner, kept for surfaces that only need that one bit.
Was this page helpful?