Skip to content

Hypatos REST API (2.68.0)

Introduction

The Hypatos API is organized around REST. The majority of the endpoints provide CRUD functionality for resources. The API is also exposing Intent Resources which mimic user intents or actions.

The Hypatos API uses OAuth 2.0 Client Credential Grant to authenticate requests. Before making any requests to any endpoint a client must authenticate with the authorization server and requests an access token from the token endpoint.

  POST /auth/token HTTP/1.1
  Host: api.cloud.hypatos.ai
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

  grant_type=client_credentials

Authorization header contains client_id:client_secret encoded as explained in RFC Client Password section.

If the authorization server authenticated the client successfully, an access token is issued. Here is an example successful response:

  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache

  {
    "access_token": "mF_9.B5f-4.1JqM",
    "expires_in": 86400,
    "scope": "enrichment.write files.read",
    "token_type": "Bearer",
  }

This token can be used to authenticate the requests to API endpoints by sending a Bearer token in the Authorization HTTP header. The following example demonstrates how to use the access token to retrieve a list of documents.

  GET /v2/documents HTTP/1.1
  Host: api.cloud.hypatos.ai
  Authorization: Bearer mF_9.B5f-4.1JqM

Versioning

Changes to this API are released regularly. We use Semantic Versioning 2.0.0 scheme for versioning so that the clients can identify any backward-incompatible changes easily. Briefly summarized one can say, if the MAJOR version of the new API version didn't change you can expect the new version to be backward-compatible.

Rate limits

In order to maximise the stability of our API, we institue rate limits for all of API endpoints. Clients who send too many requests over a given period of time will see error responses that show up as status code 429 Too Many Requests.

When you see error responses with status code 429, it means you exhausted your current quota and need to withhold from sending further requests until the quota is reset. We encourage you not to wait until you get a 429 error but to monitor your quota in each request. In each response you receive from the API, you will find HTTP headers providing the details about your current quota. Here is the list of the HTTP headers:

  • x-ratelimit-limit: Indicates the quota associated to the client in the current time-window followed by the description of the quota policy.
  • x-ratelimit-remaining: Indicates the number of remaining requests in the current time-window
  • x-ratelimit-reset: Indicates the number of seconds until quota reset of the current time-window

Please note that IETF is currently in the process of publishing a standard for these headers. Please explore the draft for more details.

A basic technique to gracefully handle rate limits is watch for your quota permanently and increase the time between your request as the quota is decreasing. To recover from a 429 error you need a retry mechanism following an exponential backoff schedule.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License
Apache 2.0
Languages
Servers
API EU
https://api.cloud.hypatos.ai/v2
API US
https://api.cloud.hypatos.com/v2
Mock server
https://hypatos.redocly.app/_mock/openapi

Authorization

Endpoints for handling the OAuth 2.0 Client Credentials Grant flow.

Operations

Files

Endpoints for management of files

Operations

Documents

Endpoints for document management

Operations

Cases

Endpoints for case management

Operations

Enrichment

Endpoints for data enrichment

Operations

Companies

Endpoints for company management

Operations

Projects

Endpoints for project management

Operations

E-Invoices

Endpoints for e-invoices

Operations

Documents XML

Endpoints serving project-scoped documents as XML

Operations

Agent Management

Endpoints for managing agents and agent workflows

Operations

Get Agents

Request

List agents for the authenticated company.

A summary projection: prompt and configuration are returned empty, toolIds null. systemPrompt and outputFormat are returned today but are expected to be omitted in a future release. Retrieve an agent by id for its complete representation. The namesAndVersions lookup returns prompt and configuration populated; toolIds is null in any list response.

Security
OAuth2(Required scopes:
agents.read
)
Query
namesAndVersionsstring or null(Namesandversions)

Comma separated list of names and versions, eg agent1:v1,agent2:v2. At most 50 entries.

limitinteger(Limit)

Maximum number of agents to return. Capped at 50; ignored when namesAndVersions is set.

Default 20
offsetinteger(Offset)>= 0

Number of agents to skip. Ignored when namesAndVersions is set.

Default 0
editorstring or null(Editor)non-empty

Return only agents whose editors contain this value. Cannot be combined with namesAndVersions.

curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/agents?namesAndVersions=string&limit=20&offset=0&editor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful Response

Bodyapplication/json
dataArray of objects(Data)required

The page of results.

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

Prompt used for agent

Example: "Hello GPT, how are you?"
data[].​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"
data[].​systemPromptstring or null(Systemprompt)

System prompt for the agent

Example: "You are a helpful assistant."
data[].​outputFormatobject or null(Dict)

Output format specification for the agent

data[].​createdAtstring or null(date-time)(Createdat)

Date when Agent was added

Example: "2023-10-27T11:38:18.000Z"
data[].​createdBystring or null(Createdby)

Agent creator

Example: "2023-10-27T11:38:18.000Z"
data[].​updatedBystring or null(Updatedby)

Agent updater

Example: "Updater"
data[].​updatedAtstring or null(date-time)(Updatedat)

Date when Agent was last modified

Example: "2023-10-27T12:38:18.000Z"
data[].​editorsArray of strings(Editors)

Editor ids that can edit agent

data[].​versionsArray of objects(Versions)

Other versions of this agent

data[].​versionsMetadataArray of objects(Versionsmetadata)

Lightweight version summaries, populated when withVersionsMetadata=true

data[].​configurationobject or null(Dict)

Additional agent configuration

data[].​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; null in list responses.

data[].​isOotbboolean(Isootb)

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

Default false
data[].​sourceTemplateAgentIdstring or null(uuid)(Sourcetemplateagentid)

Source template agent identifier

data[].​sourceTemplateAgentVersionstring or null(Sourcetemplateagentversion)

Concrete source template agent version used for import

data[].​typestring(Type)required

The type of agent (BASIC, BASIC_V2, AGENTIC, METADATA, PAGE_BY_PAGE, LLM_OCR, STATIC, CASE_CLASSIFICATION, FILE_SUMMARIZATION, SCRIPT). 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"
limitinteger(Limit)required

The limit applied to this page. Equal to the limit query parameter unless it exceeded the maximum allowed value, in which case it is that maximum.

Example: 20
offsetinteger(Offset)required

The offset applied to this page (echoes the offset query parameter).

Example: 0
totalCountinteger(Totalcount)required

The total number of elements across all pages.

Example: 137
Response
application/json
{
  "data": [
    { … }
  ],
  "limit": 20,
  "offset": 0,
  "totalCount": 137
}

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; null in list responses.

typestring(Type)required

The type of agent (BASIC, BASIC_V2, AGENTIC, METADATA, PAGE_BY_PAGE, LLM_OCR, STATIC, CASE_CLASSIFICATION, FILE_SUMMARIZATION, SCRIPT). 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(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

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; null in list responses.

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

typestring(Type)required

The type of agent (BASIC, BASIC_V2, AGENTIC, METADATA, PAGE_BY_PAGE, LLM_OCR, STATIC, CASE_CLASSIFICATION, FILE_SUMMARIZATION, SCRIPT). 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
application/json
{
  "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",
  "type": "BASIC"
}

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(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

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; null in list responses.

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

typestring(Type)required

The type of agent (BASIC, BASIC_V2, AGENTIC, METADATA, PAGE_BY_PAGE, LLM_OCR, STATIC, CASE_CLASSIFICATION, FILE_SUMMARIZATION, SCRIPT). 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
application/json
{
  "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",
  "type": "BASIC"
}

Update Agent

Request

Replace a custom agent. Persisted OOTB agents return HTTP 422; use root PATCH to customize them.

Security
OAuth2(Required scopes:
agents.write
)
Path
idstring(uuid)(Id)required
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; null in list responses.

typestring(Type)required

The type of agent (BASIC, BASIC_V2, AGENTIC, METADATA, PAGE_BY_PAGE, LLM_OCR, STATIC, CASE_CLASSIFICATION, FILE_SUMMARIZATION, SCRIPT). 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 PUT \
  'https://api.cloud.hypatos.ai/v2/agents/{id}' \
  -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(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

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; null in list responses.

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

typestring(Type)required

The type of agent (BASIC, BASIC_V2, AGENTIC, METADATA, PAGE_BY_PAGE, LLM_OCR, STATIC, CASE_CLASSIFICATION, FILE_SUMMARIZATION, SCRIPT). 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
application/json
{
  "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",
  "type": "BASIC"
}

Patch Agent

Request

Patch by persisted kind: OOTB allows prompt/description/editors; 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(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

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; null in list responses.

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

typestring(Type)required

The type of agent (BASIC, BASIC_V2, AGENTIC, METADATA, PAGE_BY_PAGE, LLM_OCR, STATIC, CASE_CLASSIFICATION, FILE_SUMMARIZATION, SCRIPT). 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
application/json
{
  "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",
  "type": "BASIC"
}

Delete Agent

Request

Security
OAuth2(Required scopes:
agents.write
)
Path
idstring(uuid)(Id)required
curl -i -X DELETE \
  'https://api.cloud.hypatos.ai/v2/agents/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful Response

Response
No content

Get Workflows

Request

Security
OAuth2(Required scopes:
agent-workflows.read
)
Query
projectIdstring(Projectid)

The ID of the project

limitinteger(Limit)

Maximum number of workflows to return. Capped at 50.

Default 20
offsetinteger(Offset)>= 0

Number of workflows to skip.

Default 0
editorstring or null(Editor)non-empty

Return only workflows whose editors contain this value.

curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/agent-workflows?projectId=string&limit=20&offset=0&editor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful Response

Bodyapplication/json
dataArray of objects(Data)required

The page of results.

data[].​idstring or null(uuid)(Id)
Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
data[].​companyIdstring(Companyid)required
Example: "6081acde0377a83b93f05a10"
data[].​projectsstring(Projects)required

Comma separated list of projectIds

Example: "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092"
data[].​namestring(Name)required

Name for Workflow

Example: "Some very nice workflow"
data[].​modelstring(Model)required

Model id used for prompting

Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
data[].​descriptionstring or null(Description)

Description of Workflow

Example: "Some more verbose description"
data[].​trainingCompanyIdstring or null(Trainingcompanyid)
Example: "6081acde0377a83b93f05a10"
data[].​trainingProjectsstring or null(Trainingprojects)

Comma separated list of training projectIds used as source documents repository

Example: "6523b5bcac1cb469d7fc1bd9"
data[].​createdAtstring or null(date-time)(Createdat)

Date when Workflow was added

Example: "2023-10-27T11:38:18.000Z"
data[].​createdBystring or null(Createdby)

Id of the caller that created the workflow; an OAuth client id when created via this API

Example: "acme-integration"
data[].​updatedBystring or null(Updatedby)

Id of the caller that last updated the workflow; an OAuth client id when updated via this API

Example: "acme-integration"
data[].​updatedAtstring or null(date-time)(Updatedat)

Date when Workflow was last modified

Example: "2023-10-27T12:38:18.000Z"
data[].​similarityThresholdnumber or null(Similaritythreshold)

Defines the minimum similarity between the uploaded document and context examples from the training project

Example: 0.78
data[].​useOcrTextPagesboolean or null(Useocrtextpages)

Ability to use ocrTextPages (Google OCR) in the prompt

Default false
Example: false
data[].​editorsArray of strings(Editors)

Editor ids that can edit workflow

data[].​similarityApiboolean or null(Similarityapi)

Ability to set similarity service API for document training data

Default true
Example: true
data[].​useImagesboolean or null(Useimages)

Ability to set images usage to workflow

Default true
Example: false
data[].​maxNumTrainingDocumentsinteger(Maxnumtrainingdocuments)

Maximum number of training documents used in the workflow

Default 1
Example: 2
data[].​bboxRegionDetectionModestring or null(BoundingBoxRegionDetectionMode)

The bounding boxes region detection mode of prompting-settings

Enum"WORD_MATCHING""LLM"
Example: "WORD_MATCHING"
data[].​workflowTypestring or null(WorkflowType)

Type of workflow (EXTRACTION returns value-form entities, PREPROCESSING returns raw JSON)

Default "EXTRACTION"
Enum"EXTRACTION""PREPROCESSING"
data[].​workflowConfigurationobject or null(Dict)

The workflow's step configuration: the agents to run and how they are chained

data[].​versionstring or null(Version)

Workflow version

data[].​sourceWorkflowIdstring or null(uuid)(Sourceworkflowid)

Source workflow identifier for imported workflows

data[].​sourceWorkflowVersionstring or null(Sourceworkflowversion)

Concrete source workflow version used for import

data[].​isOotbboolean(Isootb)

Whether persisted import provenance classifies this workflow as OOTB

Default false
limitinteger(Limit)required

The limit applied to this page. Equal to the limit query parameter unless it exceeded the maximum allowed value, in which case it is that maximum.

Example: 20
offsetinteger(Offset)required

The offset applied to this page (echoes the offset query parameter).

Example: 0
totalCountinteger(Totalcount)required

The total number of elements across all pages.

Example: 137
Response
application/json
{
  "data": [
    { … }
  ],
  "limit": 20,
  "offset": 0,
  "totalCount": 137
}

Create Workflow

Request

Create a custom workflow; OOTB identity or source provenance in the request returns HTTP 422.

Security
OAuth2(Required scopes:
agent-workflows.write
)
Bodyapplication/jsonrequired
idstring or null(uuid)(Id)
companyIdstring or null(Companyid)
projectsstring(Projects)required

Comma separated list of projectIds

Example: "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092"
namestring(Name)required

Name for Workflow

Example: "Some very nice workflow"
modelstring(Model)required

Model id used for prompting

Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
descriptionstring or null(Description)

Description of Workflow

Example: "Some more verbose description"
trainingCompanyIdstring or null(Trainingcompanyid)
Example: "6081acde0377a83b93f05a10"
trainingProjectsstring or null(Trainingprojects)

Comma separated list of training projectIds used as source documents repository

Example: "6523b5bcac1cb469d7fc1bd9"
similarityThresholdnumber or null(Similaritythreshold)

Defines the minimum similarity between the uploaded document and context examples from the training project

Example: 0.78
useOcrTextPagesboolean or null(Useocrtextpages)

Ability to use ocrTextPages (Google OCR) in the prompt

Default false
Example: false
editorsArray of strings(Editors)

Editor ids that can edit workflow

similarityApiboolean or null(Similarityapi)

Ability to set similarity service API for document training data

Default true
Example: true
useImagesboolean or null(Useimages)

Ability to set images usage to workflow

Default true
Example: false
maxNumTrainingDocumentsinteger(Maxnumtrainingdocuments)

Maximum number of training documents used in the workflow

Default 1
Example: 2
bboxRegionDetectionModestring or null(BoundingBoxRegionDetectionMode)

The bounding boxes region detection mode of prompting-settings

Enum"WORD_MATCHING""LLM"
Example: "WORD_MATCHING"
workflowTypestring or null(WorkflowType)

Type of workflow (EXTRACTION returns value-form entities, PREPROCESSING returns raw JSON)

Default "EXTRACTION"
Enum"EXTRACTION""PREPROCESSING"
workflowConfigurationobject(Dict)required
curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/agent-workflows \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "companyId": "string",
    "projects": "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092",
    "name": "Some very nice workflow",
    "model": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
    "description": "Some more verbose description",
    "trainingCompanyId": "6081acde0377a83b93f05a10",
    "trainingProjects": "6523b5bcac1cb469d7fc1bd9",
    "similarityThreshold": 0.78,
    "useOcrTextPages": false,
    "editors": [
      "string"
    ],
    "similarityApi": true,
    "useImages": false,
    "maxNumTrainingDocuments": 2,
    "bboxRegionDetectionMode": "WORD_MATCHING",
    "workflowType": "EXTRACTION",
    "workflowConfiguration": {}
  }'

Responses

Successful Response

Bodyapplication/json
idstring or null(uuid)(Id)
Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
companyIdstring(Companyid)required
Example: "6081acde0377a83b93f05a10"
projectsstring(Projects)required

Comma separated list of projectIds

Example: "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092"
namestring(Name)required

Name for Workflow

Example: "Some very nice workflow"
modelstring(Model)required

Model id used for prompting

Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
descriptionstring or null(Description)

Description of Workflow

Example: "Some more verbose description"
trainingCompanyIdstring or null(Trainingcompanyid)
Example: "6081acde0377a83b93f05a10"
trainingProjectsstring or null(Trainingprojects)

Comma separated list of training projectIds used as source documents repository

Example: "6523b5bcac1cb469d7fc1bd9"
createdAtstring or null(date-time)(Createdat)

Date when Workflow was added

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

Id of the caller that created the workflow; an OAuth client id when created via this API

Example: "acme-integration"
updatedBystring or null(Updatedby)

Id of the caller that last updated the workflow; an OAuth client id when updated via this API

Example: "acme-integration"
updatedAtstring or null(date-time)(Updatedat)

Date when Workflow was last modified

Example: "2023-10-27T12:38:18.000Z"
similarityThresholdnumber or null(Similaritythreshold)

Defines the minimum similarity between the uploaded document and context examples from the training project

Example: 0.78
useOcrTextPagesboolean or null(Useocrtextpages)

Ability to use ocrTextPages (Google OCR) in the prompt

Default false
Example: false
editorsArray of strings(Editors)

Editor ids that can edit workflow

similarityApiboolean or null(Similarityapi)

Ability to set similarity service API for document training data

Default true
Example: true
useImagesboolean or null(Useimages)

Ability to set images usage to workflow

Default true
Example: false
maxNumTrainingDocumentsinteger(Maxnumtrainingdocuments)

Maximum number of training documents used in the workflow

Default 1
Example: 2
bboxRegionDetectionModestring or null(BoundingBoxRegionDetectionMode)

The bounding boxes region detection mode of prompting-settings

Enum"WORD_MATCHING""LLM"
Example: "WORD_MATCHING"
workflowTypestring or null(WorkflowType)

Type of workflow (EXTRACTION returns value-form entities, PREPROCESSING returns raw JSON)

Default "EXTRACTION"
Enum"EXTRACTION""PREPROCESSING"
workflowConfigurationobject or null(Dict)

The workflow's step configuration: the agents to run and how they are chained

versionstring or null(Version)

Workflow version

sourceWorkflowIdstring or null(uuid)(Sourceworkflowid)

Source workflow identifier for imported workflows

sourceWorkflowVersionstring or null(Sourceworkflowversion)

Concrete source workflow version used for import

isOotbboolean(Isootb)

Whether persisted import provenance classifies this workflow as OOTB

Default false
Response
application/json
{
  "id": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "companyId": "6081acde0377a83b93f05a10",
  "projects": "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092",
  "name": "Some very nice workflow",
  "model": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "description": "Some more verbose description",
  "trainingCompanyId": "6081acde0377a83b93f05a10",
  "trainingProjects": "6523b5bcac1cb469d7fc1bd9",
  "createdAt": "2023-10-27T11:38:18.000Z",
  "createdBy": "acme-integration",
  "updatedBy": "acme-integration",
  "updatedAt": "2023-10-27T12:38:18.000Z",
  "similarityThreshold": 0.78,
  "useOcrTextPages": false,
  "editors": [
    "string"
  ],
  "similarityApi": true,
  "useImages": false,
  "maxNumTrainingDocuments": 2,
  "bboxRegionDetectionMode": "WORD_MATCHING",
  "workflowType": "EXTRACTION",
  "workflowConfiguration": {},
  "version": "string",
  "sourceWorkflowId": "eb3ffc5d-a273-4862-91d2-41d306d39afe",
  "sourceWorkflowVersion": "string",
  "isOotb": false
}

Get Workflow

Request

Security
OAuth2(Required scopes:
agent-workflows.read
)
Path
idstring(uuid)(Id)required
curl -i -X GET \
  'https://api.cloud.hypatos.ai/v2/agent-workflows/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful Response

Bodyapplication/json
idstring or null(uuid)(Id)
Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
companyIdstring(Companyid)required
Example: "6081acde0377a83b93f05a10"
projectsstring(Projects)required

Comma separated list of projectIds

Example: "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092"
namestring(Name)required

Name for Workflow

Example: "Some very nice workflow"
modelstring(Model)required

Model id used for prompting

Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
descriptionstring or null(Description)

Description of Workflow

Example: "Some more verbose description"
trainingCompanyIdstring or null(Trainingcompanyid)
Example: "6081acde0377a83b93f05a10"
trainingProjectsstring or null(Trainingprojects)

Comma separated list of training projectIds used as source documents repository

Example: "6523b5bcac1cb469d7fc1bd9"
createdAtstring or null(date-time)(Createdat)

Date when Workflow was added

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

Id of the caller that created the workflow; an OAuth client id when created via this API

Example: "acme-integration"
updatedBystring or null(Updatedby)

Id of the caller that last updated the workflow; an OAuth client id when updated via this API

Example: "acme-integration"
updatedAtstring or null(date-time)(Updatedat)

Date when Workflow was last modified

Example: "2023-10-27T12:38:18.000Z"
similarityThresholdnumber or null(Similaritythreshold)

Defines the minimum similarity between the uploaded document and context examples from the training project

Example: 0.78
useOcrTextPagesboolean or null(Useocrtextpages)

Ability to use ocrTextPages (Google OCR) in the prompt

Default false
Example: false
editorsArray of strings(Editors)

Editor ids that can edit workflow

similarityApiboolean or null(Similarityapi)

Ability to set similarity service API for document training data

Default true
Example: true
useImagesboolean or null(Useimages)

Ability to set images usage to workflow

Default true
Example: false
maxNumTrainingDocumentsinteger(Maxnumtrainingdocuments)

Maximum number of training documents used in the workflow

Default 1
Example: 2
bboxRegionDetectionModestring or null(BoundingBoxRegionDetectionMode)

The bounding boxes region detection mode of prompting-settings

Enum"WORD_MATCHING""LLM"
Example: "WORD_MATCHING"
workflowTypestring or null(WorkflowType)

Type of workflow (EXTRACTION returns value-form entities, PREPROCESSING returns raw JSON)

Default "EXTRACTION"
Enum"EXTRACTION""PREPROCESSING"
workflowConfigurationobject or null(Dict)

The workflow's step configuration: the agents to run and how they are chained

versionstring or null(Version)

Workflow version

sourceWorkflowIdstring or null(uuid)(Sourceworkflowid)

Source workflow identifier for imported workflows

sourceWorkflowVersionstring or null(Sourceworkflowversion)

Concrete source workflow version used for import

isOotbboolean(Isootb)

Whether persisted import provenance classifies this workflow as OOTB

Default false
Response
application/json
{
  "id": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "companyId": "6081acde0377a83b93f05a10",
  "projects": "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092",
  "name": "Some very nice workflow",
  "model": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "description": "Some more verbose description",
  "trainingCompanyId": "6081acde0377a83b93f05a10",
  "trainingProjects": "6523b5bcac1cb469d7fc1bd9",
  "createdAt": "2023-10-27T11:38:18.000Z",
  "createdBy": "acme-integration",
  "updatedBy": "acme-integration",
  "updatedAt": "2023-10-27T12:38:18.000Z",
  "similarityThreshold": 0.78,
  "useOcrTextPages": false,
  "editors": [
    "string"
  ],
  "similarityApi": true,
  "useImages": false,
  "maxNumTrainingDocuments": 2,
  "bboxRegionDetectionMode": "WORD_MATCHING",
  "workflowType": "EXTRACTION",
  "workflowConfiguration": {},
  "version": "string",
  "sourceWorkflowId": "eb3ffc5d-a273-4862-91d2-41d306d39afe",
  "sourceWorkflowVersion": "string",
  "isOotb": false
}

Update Workflow

Request

Replace a custom workflow. Persisted OOTB workflows return HTTP 422; use root PATCH to customize them.

Security
OAuth2(Required scopes:
agent-workflows.write
)
Path
idstring(uuid)(Id)required
Bodyapplication/jsonrequired
idstring or null(uuid)(Id)
companyIdstring or null(Companyid)
projectsstring(Projects)required

Comma separated list of projectIds

Example: "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092"
namestring(Name)required

Name for Workflow

Example: "Some very nice workflow"
modelstring(Model)required

Model id used for prompting

Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
descriptionstring or null(Description)

Description of Workflow

Example: "Some more verbose description"
trainingCompanyIdstring or null(Trainingcompanyid)
Example: "6081acde0377a83b93f05a10"
trainingProjectsstring or null(Trainingprojects)

Comma separated list of training projectIds used as source documents repository

Example: "6523b5bcac1cb469d7fc1bd9"
similarityThresholdnumber or null(Similaritythreshold)

Defines the minimum similarity between the uploaded document and context examples from the training project

Example: 0.78
useOcrTextPagesboolean or null(Useocrtextpages)

Ability to use ocrTextPages (Google OCR) in the prompt

Default false
Example: false
editorsArray of strings(Editors)

Editor ids that can edit workflow

similarityApiboolean or null(Similarityapi)

Ability to set similarity service API for document training data

Default true
Example: true
useImagesboolean or null(Useimages)

Ability to set images usage to workflow

Default true
Example: false
maxNumTrainingDocumentsinteger(Maxnumtrainingdocuments)

Maximum number of training documents used in the workflow

Default 1
Example: 2
bboxRegionDetectionModestring or null(BoundingBoxRegionDetectionMode)

The bounding boxes region detection mode of prompting-settings

Enum"WORD_MATCHING""LLM"
Example: "WORD_MATCHING"
workflowTypestring or null(WorkflowType)

Type of workflow (EXTRACTION returns value-form entities, PREPROCESSING returns raw JSON)

Default "EXTRACTION"
Enum"EXTRACTION""PREPROCESSING"
workflowConfigurationobject(Dict)required
versionstring or null(Version)
curl -i -X PUT \
  'https://api.cloud.hypatos.ai/v2/agent-workflows/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "companyId": "string",
    "projects": "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092",
    "name": "Some very nice workflow",
    "model": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
    "description": "Some more verbose description",
    "trainingCompanyId": "6081acde0377a83b93f05a10",
    "trainingProjects": "6523b5bcac1cb469d7fc1bd9",
    "similarityThreshold": 0.78,
    "useOcrTextPages": false,
    "editors": [
      "string"
    ],
    "similarityApi": true,
    "useImages": false,
    "maxNumTrainingDocuments": 2,
    "bboxRegionDetectionMode": "WORD_MATCHING",
    "workflowType": "EXTRACTION",
    "workflowConfiguration": {},
    "version": "string"
  }'

Responses

Successful Response

Bodyapplication/json
idstring or null(uuid)(Id)
Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
companyIdstring(Companyid)required
Example: "6081acde0377a83b93f05a10"
projectsstring(Projects)required

Comma separated list of projectIds

Example: "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092"
namestring(Name)required

Name for Workflow

Example: "Some very nice workflow"
modelstring(Model)required

Model id used for prompting

Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
descriptionstring or null(Description)

Description of Workflow

Example: "Some more verbose description"
trainingCompanyIdstring or null(Trainingcompanyid)
Example: "6081acde0377a83b93f05a10"
trainingProjectsstring or null(Trainingprojects)

Comma separated list of training projectIds used as source documents repository

Example: "6523b5bcac1cb469d7fc1bd9"
createdAtstring or null(date-time)(Createdat)

Date when Workflow was added

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

Id of the caller that created the workflow; an OAuth client id when created via this API

Example: "acme-integration"
updatedBystring or null(Updatedby)

Id of the caller that last updated the workflow; an OAuth client id when updated via this API

Example: "acme-integration"
updatedAtstring or null(date-time)(Updatedat)

Date when Workflow was last modified

Example: "2023-10-27T12:38:18.000Z"
similarityThresholdnumber or null(Similaritythreshold)

Defines the minimum similarity between the uploaded document and context examples from the training project

Example: 0.78
useOcrTextPagesboolean or null(Useocrtextpages)

Ability to use ocrTextPages (Google OCR) in the prompt

Default false
Example: false
editorsArray of strings(Editors)

Editor ids that can edit workflow

similarityApiboolean or null(Similarityapi)

Ability to set similarity service API for document training data

Default true
Example: true
useImagesboolean or null(Useimages)

Ability to set images usage to workflow

Default true
Example: false
maxNumTrainingDocumentsinteger(Maxnumtrainingdocuments)

Maximum number of training documents used in the workflow

Default 1
Example: 2
bboxRegionDetectionModestring or null(BoundingBoxRegionDetectionMode)

The bounding boxes region detection mode of prompting-settings

Enum"WORD_MATCHING""LLM"
Example: "WORD_MATCHING"
workflowTypestring or null(WorkflowType)

Type of workflow (EXTRACTION returns value-form entities, PREPROCESSING returns raw JSON)

Default "EXTRACTION"
Enum"EXTRACTION""PREPROCESSING"
workflowConfigurationobject or null(Dict)

The workflow's step configuration: the agents to run and how they are chained

versionstring or null(Version)

Workflow version

sourceWorkflowIdstring or null(uuid)(Sourceworkflowid)

Source workflow identifier for imported workflows

sourceWorkflowVersionstring or null(Sourceworkflowversion)

Concrete source workflow version used for import

isOotbboolean(Isootb)

Whether persisted import provenance classifies this workflow as OOTB

Default false
Response
application/json
{
  "id": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "companyId": "6081acde0377a83b93f05a10",
  "projects": "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092",
  "name": "Some very nice workflow",
  "model": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "description": "Some more verbose description",
  "trainingCompanyId": "6081acde0377a83b93f05a10",
  "trainingProjects": "6523b5bcac1cb469d7fc1bd9",
  "createdAt": "2023-10-27T11:38:18.000Z",
  "createdBy": "acme-integration",
  "updatedBy": "acme-integration",
  "updatedAt": "2023-10-27T12:38:18.000Z",
  "similarityThreshold": 0.78,
  "useOcrTextPages": false,
  "editors": [
    "string"
  ],
  "similarityApi": true,
  "useImages": false,
  "maxNumTrainingDocuments": 2,
  "bboxRegionDetectionMode": "WORD_MATCHING",
  "workflowType": "EXTRACTION",
  "workflowConfiguration": {},
  "version": "string",
  "sourceWorkflowId": "eb3ffc5d-a273-4862-91d2-41d306d39afe",
  "sourceWorkflowVersion": "string",
  "isOotb": false
}

Patch Workflow

Request

Patch by persisted kind after ownership is established.

OOTB workflows accept only workflowConfiguration.steps, name, description, projects, and editors; a protected field sent to an OOTB workflow is rejected with 422. Custom workflows keep their existing partial-update contract.

Security
OAuth2(Required scopes:
agent-workflows.write
)
Path
idstring(uuid)(Id)required
Bodyapplication/jsonrequired
Any of:

Partial-update body for a workflow; send only the fields to change. companyId is immutable.

companyIdstring or null(Companyid)
projectsstring or null(Projects)

Comma separated list of projectIds

namestring or null(Name)

Name for Workflow

modelstring or null(Model)

Model id used for prompting

descriptionstring or null(Description)

Description of Workflow

trainingCompanyIdstring or null(Trainingcompanyid)
trainingProjectsstring or null(Trainingprojects)

Comma separated list of training projectIds

similarityThresholdnumber or null(Similaritythreshold)
useOcrTextPagesboolean or null(Useocrtextpages)
editorsArray of strings or null(Editors)

Editor ids that can edit workflow

similarityApiboolean or null(Similarityapi)
useImagesboolean or null(Useimages)
maxNumTrainingDocumentsinteger or null(Maxnumtrainingdocuments)
bboxRegionDetectionModestring or null(BoundingBoxRegionDetectionMode)
Enum"WORD_MATCHING""LLM"
workflowTypestring or null(WorkflowType)
Enum"EXTRACTION""PREPROCESSING"
workflowConfigurationobject or null(Dict)
curl -i -X PATCH \
  'https://api.cloud.hypatos.ai/v2/agent-workflows/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "companyId": "string",
    "projects": "string",
    "name": "string",
    "model": "string",
    "description": "string",
    "trainingCompanyId": "string",
    "trainingProjects": "string",
    "similarityThreshold": 0,
    "useOcrTextPages": true,
    "editors": [
      "string"
    ],
    "similarityApi": true,
    "useImages": true,
    "maxNumTrainingDocuments": 0,
    "bboxRegionDetectionMode": "WORD_MATCHING",
    "workflowType": "EXTRACTION",
    "workflowConfiguration": {}
  }'

Responses

Successful Response

Bodyapplication/json
idstring or null(uuid)(Id)
Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
companyIdstring(Companyid)required
Example: "6081acde0377a83b93f05a10"
projectsstring(Projects)required

Comma separated list of projectIds

Example: "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092"
namestring(Name)required

Name for Workflow

Example: "Some very nice workflow"
modelstring(Model)required

Model id used for prompting

Example: "dcbc075f-a99c-4199-86ed-fb4ed5684dd9"
descriptionstring or null(Description)

Description of Workflow

Example: "Some more verbose description"
trainingCompanyIdstring or null(Trainingcompanyid)
Example: "6081acde0377a83b93f05a10"
trainingProjectsstring or null(Trainingprojects)

Comma separated list of training projectIds used as source documents repository

Example: "6523b5bcac1cb469d7fc1bd9"
createdAtstring or null(date-time)(Createdat)

Date when Workflow was added

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

Id of the caller that created the workflow; an OAuth client id when created via this API

Example: "acme-integration"
updatedBystring or null(Updatedby)

Id of the caller that last updated the workflow; an OAuth client id when updated via this API

Example: "acme-integration"
updatedAtstring or null(date-time)(Updatedat)

Date when Workflow was last modified

Example: "2023-10-27T12:38:18.000Z"
similarityThresholdnumber or null(Similaritythreshold)

Defines the minimum similarity between the uploaded document and context examples from the training project

Example: 0.78
useOcrTextPagesboolean or null(Useocrtextpages)

Ability to use ocrTextPages (Google OCR) in the prompt

Default false
Example: false
editorsArray of strings(Editors)

Editor ids that can edit workflow

similarityApiboolean or null(Similarityapi)

Ability to set similarity service API for document training data

Default true
Example: true
useImagesboolean or null(Useimages)

Ability to set images usage to workflow

Default true
Example: false
maxNumTrainingDocumentsinteger(Maxnumtrainingdocuments)

Maximum number of training documents used in the workflow

Default 1
Example: 2
bboxRegionDetectionModestring or null(BoundingBoxRegionDetectionMode)

The bounding boxes region detection mode of prompting-settings

Enum"WORD_MATCHING""LLM"
Example: "WORD_MATCHING"
workflowTypestring or null(WorkflowType)

Type of workflow (EXTRACTION returns value-form entities, PREPROCESSING returns raw JSON)

Default "EXTRACTION"
Enum"EXTRACTION""PREPROCESSING"
workflowConfigurationobject or null(Dict)

The workflow's step configuration: the agents to run and how they are chained

versionstring or null(Version)

Workflow version

sourceWorkflowIdstring or null(uuid)(Sourceworkflowid)

Source workflow identifier for imported workflows

sourceWorkflowVersionstring or null(Sourceworkflowversion)

Concrete source workflow version used for import

isOotbboolean(Isootb)

Whether persisted import provenance classifies this workflow as OOTB

Default false
Response
application/json
{
  "id": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "companyId": "6081acde0377a83b93f05a10",
  "projects": "6299d91c04dd5dd5d81c99bb,63bc7bf22b5bc8f3d0625092",
  "name": "Some very nice workflow",
  "model": "dcbc075f-a99c-4199-86ed-fb4ed5684dd9",
  "description": "Some more verbose description",
  "trainingCompanyId": "6081acde0377a83b93f05a10",
  "trainingProjects": "6523b5bcac1cb469d7fc1bd9",
  "createdAt": "2023-10-27T11:38:18.000Z",
  "createdBy": "acme-integration",
  "updatedBy": "acme-integration",
  "updatedAt": "2023-10-27T12:38:18.000Z",
  "similarityThreshold": 0.78,
  "useOcrTextPages": false,
  "editors": [
    "string"
  ],
  "similarityApi": true,
  "useImages": false,
  "maxNumTrainingDocuments": 2,
  "bboxRegionDetectionMode": "WORD_MATCHING",
  "workflowType": "EXTRACTION",
  "workflowConfiguration": {},
  "version": "string",
  "sourceWorkflowId": "eb3ffc5d-a273-4862-91d2-41d306d39afe",
  "sourceWorkflowVersion": "string",
  "isOotb": false
}

Delete Workflow

Request

Security
OAuth2(Required scopes:
agent-workflows.write
)
Path
idstring(uuid)(Id)required
curl -i -X DELETE \
  'https://api.cloud.hypatos.ai/v2/agent-workflows/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful Response

Response
No content

Emails

Operations

Document Routing

Operations

Enrichment workflows

Operations

Users

Operations