Update an agent (partial update)

curl --request PATCH \
  --url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "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"
}

PATCH

agents

{agentId}

Update an agent (partial update)

curl --request PATCH \
  --url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

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

Body

application/json

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

name

string

Maximum string length: 256

description

string

Maximum string length: 4096

instructions

string

Maximum string length: 100000

model

string

Maximum string length: 128

fallback_models

string[]

temperature

number

icon_url

string

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; cache keyed per child name unless an MCP parent rule is configured (then cached per parent).

Hide child attributes

tool_permissions.default

enum<string>

default:auto

Available options:

auto,

always_ask,

ask_external,

ask_first

tool_permissions.tools

object[]

Hide child attributes

tool_permissions.tools.tool

string

required

tool_permissions.tools.policy

enum<string>

required

Available options:

auto,

always_ask,

ask_external,

ask_first

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.

tool_permissions.tools.approvers

object[]

Hide child attributes

tool_permissions.tools.approvers.type

enum<string>

required

Available options:

owner,

user,

group

tool_permissions.tools.approvers.id

string

Required for user and group. Ignored for owner.

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

tool_activation.default

enum<string>

default:auto

Available options:

auto,

user_first

tool_activation.tools

object[]

Hide child attributes

tool_activation.tools.tool

string

required

tool_activation.tools.activation

enum<string>

required

Available options:

auto,

user_first

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

Maximum string length: 32

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.

string

name

string

description

string

instructions

string

model

string

fallback_models

string[]

temperature

number

icon_url

string

skills

object[]

tools

object[]

Hide child attributes

tools.id

string

tools.type

enum<string>

Available options:

file_search,

mcp,

function

tools.name

string

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

tools.display_name

string

tools.description

string

tools.catalog_id

string

tools.auth

object

tools.icon_url

string

tools.vector_store_id

string

Required for file_search.

tools.server

string

MCP server URL (for mcp).

tools.headers

object

tools.scope

string

tools.url

string

Required for function.

tools.parameters

object

JSON Schema describing the function tool's parameters.

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

tool_permissions.default

enum<string>

default:auto

Available options:

auto,

always_ask,

ask_external,

ask_first

tool_permissions.tools

object[]

Hide child attributes

tool_permissions.tools.tool

string

required

tool_permissions.tools.policy

enum<string>

required

Available options:

auto,

always_ask,

ask_external,

ask_first

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.

tool_permissions.tools.approvers

object[]

Hide child attributes

tool_permissions.tools.approvers.type

enum<string>

required

Available options:

owner,

user,

group

tool_permissions.tools.approvers.id

string

Required for user and group. Ignored for owner.

tool_activation

object

Hide child attributes

tool_activation.default

enum<string>

default:auto

Available options:

auto,

user_first

tool_activation.tools

object[]

Hide child attributes

tool_activation.tools.tool

string

required

tool_activation.tools.activation

enum<string>

required

Available options:

auto,

user_first

guardrails

object

sub_agents

object[]

Hide child attributes

sub_agents.agent_id

string

sub_agents.name

string

sub_agents.description

string

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