Skip to content

Patch Agent

Request

Patch by persisted kind: OOTB allows prompt/description/editors/outputFormat; custom keeps partial-update semantics.

For custom agents, omitted fields stay unchanged, explicit null clears nullable fields, and companyId and name are immutable. A custom-only or otherwise protected field sent to an OOTB agent is rejected with 422.

Security
OAuth2(Required scopes: agents.write)
Path
idstring, (uuid)(Id)required
Bodyapplication/jsonrequired
Any of:

Partial-update body for an agent; send only the fields to change. name and companyId are immutable.

companyIdstring or null(Companyid)
namestring or null(Name)
descriptionstring or null(Description)
promptstring or null(Prompt)

Prompt used for agent

modelstring or null(Model)

Model UID used for this agent

systemPromptstring or null(Systemprompt)

System prompt for the agent

outputFormatobject or null(Dict)

Output format specification for the agent

configurationobject or null(Dict)

Additional agent configuration

editorsArray of strings or null(Editors)

Editor ids that can edit agent

typestring or null(Type)

The type of agent

toolIdsArray of strings or null, (uuid)(Toolids)

Ids of the tools assigned to this agent. Omitted or null leaves the assignments unchanged; [] removes them all; a list replaces them with exactly this set (a change creates a new agent version).

curl -i -X PATCH \
  'https://api.cloud.hypatos.ai/v2/agents/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "companyId": "string",
    "name": "string",
    "description": "string",
    "prompt": "string",
    "model": "string",
    "systemPrompt": "string",
    "outputFormat": {},
    "configuration": {},
    "editors": [
      "string"
    ],
    "type": "string",
    "toolIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  }'

Responses

Successful Response

Bodyapplication/json
idstring, (uuid)(Id)required
Example:"dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
rootAgentIdstring or null, (uuid)(Rootagentid)
Example:"dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
companyIdstring(Companyid)required
Example:"6081acde0377a83b93f05a10"
namestring(Name)required
Example:"Agent name"
versionstring(Version)required
Example:"Agent version"
descriptionstring(Description)required
Example:"Some description"
promptstring or null(Prompt)

Prompt used for agent. Null in a lean list row — request full=true to load it.

Example:"Hello GPT, how are you?"
modelstring or null(Model)

Model UID used for this agent. If not specified, the default model will be used.

Example:"b099cb97-4a5c-458f-8dcf-91139e731214"
systemPromptstring or null(Systemprompt)

System prompt for the agent

Example:"You are a helpful assistant."
outputFormatobject or null(Dict)

Output format specification for the agent

createdAtstring or null, (date-time)(Createdat)

Date when Agent was added

Example:"2023-10-27T11:38:18.000Z"
createdBystring or null(Createdby)

Agent creator

Example:"2023-10-27T11:38:18.000Z"
updatedBystring or null(Updatedby)

Agent updater

Example:"Updater"
updatedAtstring or null, (date-time)(Updatedat)

Date when Agent was last modified

Example:"2023-10-27T12:38:18.000Z"
editorsArray of strings(Editors)

Editor ids that can edit agent

versionsArray of objects(Versions)

Other versions of this agent

versionsMetadataArray of objects(Versionsmetadata)

Lightweight version summaries, populated when withVersionsMetadata=true

configurationobject or null(Dict)

Additional agent configuration

toolIdsArray of strings or null, (uuid)(Toolids)

Ids of the tools assigned to this agent. On create/update: null or omitted leaves the assignments unchanged (a new agent starts with none), [] removes them all, and a list replaces them with exactly this set (a change creates a new agent version). Populated on by-id reads and on a list with full=true; null in a list otherwise.

isOotbboolean(Isootb)

Whether the agent is an out-of-the-box agent

Default:false
sourceTemplateAgentIdstring or null, (uuid)(Sourcetemplateagentid)

Source template agent identifier

sourceTemplateAgentVersionstring or null(Sourcetemplateagentversion)

Concrete source template agent version used for import

predefinedOutputFormatobject or null(Dict)

Read-only. The predefined output format of an OOTB agent, which customization may only extend with new properties: the template's, or the stored one when the template is gone. Populated on by-id reads; null when nothing is predefined, for custom agents, and for types whose output format is managed by Hypatos. Ignored on create and update.

typestring(Type)required

The type of agent (BASIC, BASIC_V2, AGENTIC, METADATA, PAGE_BY_PAGE, LLM_OCR, STATIC, CASE_CLASSIFICATION, FILE_SUMMARIZATION, SCRIPT, AGENTIC_DECISION). SCRIPT runs author-provided TypeScript (from the prompt field, rendered with full mustache context) in a sandbox and returns JSON instead of calling an LLM.

Example:"BASIC"
Response
{
  "id": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "rootAgentId": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "companyId": "6081acde0377a83b93f05a10",
  "name": "Agent name",
  "version": "Agent version",
  "description": "Some description",
  "prompt": "Hello GPT, how are you?",
  "model": "b099cb97-4a5c-458f-8dcf-91139e731214",
  "systemPrompt": "You are a helpful assistant.",
  "outputFormat": {},
  "createdAt": "2023-10-27T11:38:18.000Z",
  "createdBy": "2023-10-27T11:38:18.000Z",
  "updatedBy": "Updater",
  "updatedAt": "2023-10-27T12:38:18.000Z",
  "editors": [
    "string"
  ],
  "versions": [
    { … }
  ],
  "versionsMetadata": [
    { … }
  ],
  "configuration": {},
  "toolIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "isOotb": false,
  "sourceTemplateAgentId": "ab8eaaa7-db02-4453-a2db-8710c57d56dd",
  "sourceTemplateAgentVersion": "string",
  "predefinedOutputFormat": {},
  "type": "BASIC"
}