curl --request PATCH \
  --url https://api.neoagent.io/public-api/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Triage agent (v2)"
}
'

{
  "data": {
    "created_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "name": "<string>",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "timings_ms": {},
    "pagination": {
      "has_more": true,
      "next_cursor": "<string>"
    },
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Agents

Update an agent

Accepts PUT or PATCH (identical partial-merge semantics). Partial-patches an agent — only the fields you send change. autonomy_type and entity_type are immutable. Send updated ticket_conditions / time_entry_conditions to change the entity filter; the server rebuilds the FIND_ENTITIES action. actions is the pipeline AFTER FIND_ENTITIES (CHAINED_ACTIONS only) — patching actions on an AGENTIC agent or conditions on a CONVERSATIONAL agent returns 400. An actions patch MERGES per-action: each entry targets one existing action by id (or unique action_type) and its input_as_dict is merged key-by-key, so changing one setting preserves the rest; unreferenced actions are kept and unmatched entries are appended. There is no wholesale-replace mode — a PUT can never drop or reorder an action (do structural pipeline edits in the dashboard). A toolbox patch also MERGES per tool: each entry under tool_settings_by_type is merged key-by-key onto that tool’s current settings (lists like allowed_users replace; null for a tool key disables it), so changing one tool’s setting no longer requires resending the whole toolbox. agent_settings, integrations, schedule, and callback_settings MERGE the same way: send only the fields you’re changing — e.g. {"agent_settings": {"custom_instructions": "…"}} edits only the instructions and leaves test_mode/model/til_channel intact, sending one integration’s permissions leaves the others connected, and {"schedule": {"timezone": "…"}} leaves the run cadence and business-hours windows intact. Refuses Neo-managed agents (403 agent_managed_by_neo). Editing actions, agent_settings, toolbox, integrations, or the conditions is a destructive change (triggers a TIL approval when an agent makes the call via NEO_API_REQUEST). 409 agent_update_conflict on a concurrent edit.

PATCH

public-api

agents

{agent_id}

curl --request PATCH \
  --url https://api.neoagent.io/public-api/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Triage agent (v2)"
}
'

{
  "data": {
    "created_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "name": "<string>",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "timings_ms": {},
    "pagination": {
      "has_more": true,
      "next_cursor": "<string>"
    },
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Authorizations

Authorization

string

header

required

Authorization: Bearer <token> where <token> is either a neo_sk_<env>_<secret> API key (service account) or a Microsoft Entra ID access token (dashboard user).

Path Parameters

agent_id

string

required

Body

application/json

PUT /public-api/agents/<id> body — a partial patch. Only the fields you send are changed; everything else keeps its current value. autonomy_type and entity_type are immutable. Editing actions, agent_settings, toolbox, integrations, or the conditions is a destructive change and triggers a TIL approval when an agent makes the call via NEO_API_REQUEST.

The intent-shape applies on update too: send updated ticket_conditions / time_entry_conditions to change the entity filter; the server rebuilds the FIND_ENTITIES action. actions is the pipeline AFTER FIND_ENTITIES (CHAINED_ACTIONS only) — do not include FIND_ENTITIES yourself.

actions MERGES (ENG-5712): each entry targets one existing action by id (preferred — read it from GET /agents/<id>) or, when id is omitted, by action_type if exactly one existing action has that type. The targeted action keeps its other config — its input_as_dict is merged key-by-key with what you send (nested objects merged, an explicit null deletes a key, scalars/lists replace), so changing one dispatch setting no longer wipes the technician pool, instructions, or calendar settings you didn't resend. Entries that match nothing are appended as new actions; existing actions you don't mention are left untouched. There is deliberately no wholesale-replace mode: a PUT can never drop or reorder an action — do structural pipeline edits (remove/reorder) in the dashboard.

toolbox, agent_settings, integrations, schedule, and callback_settings all MERGE the same way (RFC 7396) — send only what you're changing, and everything you omit keeps its current value:

toolbox merges per tool under tool_settings_by_type (nested objects merge; scalars and lists — e.g. allowed_users — replace wholesale; a null tool key disables that tool).
agent_settings merges per field, so {"agent_settings": {"custom_instructions": "…"}} changes only the instructions and leaves test_mode, model, reasoning_effort, til_channel, etc. untouched (a partial send used to silently reset them to defaults, e.g. flipping an agent out of test mode).
integrations merges per integration, so sending one integration's permissions leaves every other connected integration untouched (a partial send used to disable them all).
schedule merges per field, so {"schedule": {"timezone": "…"}} changes only the timezone and leaves the run cadence / business-hours windows / weekend-skip intact.
callback_settings merges per field (target_changes is still required). Nested objects merge key-by-key, scalars/lists replace wholesale, and an explicit null deletes that key. An explicit top-level "toolbox": null still clears the whole toolbox.

actions

Actions · object[] | null

agent_settings

Agent Settings · object | null

callback_settings

Callback Settings · object | null

description

string | null

group_name

string | null

group_order

integer | null

integrations

Integrations · object | null

name

string | null

process_entities_sequentially

boolean | null

process_sub_entities_only_once

boolean | null

schedule

Schedule · object | null

show_in_psa_pod

boolean | null

state

enum<string> | null

Available options:

ENABLED,

DISABLED,

DELETED

ticket_conditions

PsaTicketConditions · object | null

Trigger/entity filter for TICKET agents — which tickets this agent fires on. Send it at the top level to set or change the filter; the server (re)builds the FIND_ENTITIES action from it (do not put the filter in actions). Use time_entry_conditions instead for TIME_ENTRY agents. Shape: conditions holds a combinator (and/or) and a rules list of leaves (field/operator/value) and/or nested groups (rules + combinator). A rule's position in the tree changes the logic — a company exclusion belongs as a top-level rule under the root and, not nested inside an or, or it only excludes when the other branches also miss.

Show child attributes

time_entry_conditions

PsaConditions · object | null

Trigger/entity filter for TIME_ENTRY agents — the analogue of ticket_conditions. Ignored for TICKET agents.

Show child attributes

toolbox

Toolbox · object | null

trigger_type

enum<string> | null

Available options:

SCHEDULED,

TRIGGERED,

NONE

Response

Success.

data

Agent · object

required

Lean summary of a workflow row — the per-item shape GET /public-api/agents (list) returns. The single-resource GET /public-api/agents/<id> returns the richer AgentDetail; historical snapshots come back as AgentVersion.

Show child attributes