Skip to content

Create Agent

Request

Create a custom agent; non-default OOTB identity or source provenance returns HTTP 422.

Security
OAuth2(Required scopes: agents.write)
Bodyapplication/jsonrequired
idstring or null, (uuid)(Id)
companyIdstring or null(Companyid)
namestring(Name)required
Example:"Agent name"
versionstring or null(Version)
descriptionstring(Description)required
Example:"Some description"
promptstring(Prompt)required

Prompt used for agent

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

editorsArray of strings(Editors)

Editor ids that can edit agent

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.

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"
curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/agents \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "companyId": "string",
    "name": "Agent name",
    "version": "string",
    "description": "Some description",
    "prompt": "Hello GPT, how are you?",
    "model": "b099cb97-4a5c-458f-8dcf-91139e731214",
    "systemPrompt": "You are a helpful assistant.",
    "outputFormat": {},
    "editors": [
      "string"
    ],
    "configuration": {},
    "toolIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "type": "BASIC"
  }'

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