Skip to content

Get Agent

Request

Security
OAuth2(Required scopes: agents.read)
Path
idstring, (uuid)(Id)required
Query
withVersionsboolean(Withversions)

Whether to load versions

Default:false
withVersionsMetadataboolean(Withversionsmetadata)

Whether to load lightweight version metadata (id, version, description, createdAt, createdBy)

Default:false
curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/agents/{id}?withVersions=false&withVersionsMetadata=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

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