Skip to main content
PATCH
Update an agent (partial update)

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

Body

application/json

Partial agent update payload. Any subset of the writable Agent fields.

name
string
Maximum string length: 256
description

Plain string, or an object of per-locale strings.

Maximum string length: 4096
instructions
string
Maximum string length: 100000
model
string
Maximum string length: 128
fallback_models
string[]
temperature
number | null

Send null to reset to the default temperature.

tools
object[]
icon_url
string | null

Send null or an empty string to remove the icon.

skills
object[]
guardrails
object
sub_agents
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, 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).
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.

allowed_models
string[]
max_tokens
integer | null

Send null to remove the per-agent limit (the LLM Gateway limit applies).

max_turns
integer | null

Send null to reset to the workspace default (max_turns has no profile default). 0 and negative values are rejected.

Required range: x >= 1
token_budget
integer | null

Send null to reset to the profile or platform default.

tool_call_budget
integer | null

Send null or 0 to reset to the workspace default (tool_call_budget has no profile default). Negative values are rejected.

Required range: x >= 0
canvas_enabled
boolean
visibility
enum<string>
Available options:
public,
private,
restricted
Maximum string length: 32
category
string
Maximum string length: 128
tags
string[] | null

Send null or an empty array to remove all tags.

starters
object[]
status
enum<string>
Available options:
draft,
published
Maximum string length: 32
profile
enum<string>
Available options:
simple,
workflow,
agent_light,
agent_full,
orchestrator
Maximum string length: 64

Response

Updated agent record.

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

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

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

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>