Agent

Manage Agents

Listing agents

get

Retrieves agent templates based on the provided query.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Query parameters

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard Practices - Query parameter

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

expandstring · enumOptional

Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response.

Possible values:

Header parameters

Accept-LanguagestringOptional

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

• If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
• If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
• If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Responses

200

List of agents.

application/json

or

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

get

/ai-service/{tenant}/agentic/agents

HTTPcURLJavaScriptPython

GET /ai-service/{tenant}/agentic/agents HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "123",
    "name": {
      "en": "Complaint Agent"
    },
    "description": {
      "en": "Complaint agent"
    },
    "type": "complaint",
    "enabled": true,
    "templatePrompt": "You are an complaint agent for checking emails and do some action.",
    "userPrompt": "Use get-order tool to fetch order.",
    "llmConfig": {
      "model": "GPT-4.1",
      "apiKey": "secureApiKey",
      "provider": "openai",
      "maxTokens": 100000,
      "temperature": 0.2
    },
    "triggers": [
      {
        "type": "endpoint"
      }
    ],
    "maxRecursionLimit": 20,
    "enabledMemory": true,
    "tags": [
      "productivity"
    ],
    "icon": "fa-productivity",
    "mcpServers": [
      {
        "domain": "order",
        "type": "predefined",
        "tools": [
          "get-orders",
          "get-order"
        ]
      }
    ],
    "nativeTools": [
      {
        "name": "slack",
        "config": {
          "teamId": "T0445953"
        }
      }
    ]
  }
]

Searching agents

post

Searches for agents based on the provided query.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Query parameters

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

expandstring · enumOptional

Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response.

Possible values:

Header parameters

Accept-LanguagestringOptional

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

• If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
• If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
• If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Body

application/json

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard Practices - Query parameter

Responses

200

List of agents.

application/json

or

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

post

/ai-service/{tenant}/agentic/agents/search

HTTPcURLJavaScriptPython

POST /ai-service/{tenant}/agentic/agents/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "q": "name:~Support"
}

[
  {
    "id": "123",
    "name": {
      "en": "Complaint Agent"
    },
    "description": {
      "en": "Complaint agent"
    },
    "type": "complaint",
    "enabled": true,
    "templatePrompt": "You are an complaint agent for checking emails and do some action.",
    "userPrompt": "Use get-order tool to fetch order.",
    "llmConfig": {
      "model": "GPT-4.1",
      "apiKey": "secureApiKey",
      "provider": "openai",
      "maxTokens": 100000,
      "temperature": 0.2
    },
    "triggers": [
      {
        "type": "endpoint"
      }
    ],
    "maxRecursionLimit": 20,
    "enabledMemory": true,
    "tags": [
      "productivity"
    ],
    "icon": "fa-productivity",
    "mcpServers": [
      {
        "domain": "order",
        "type": "predefined",
        "tools": [
          "get-orders",
          "get-order"
        ]
      }
    ],
    "nativeTools": [
      {
        "name": "slack",
        "config": {
          "teamId": "T0445953"
        }
      }
    ]
  }
]

Retrieving agent by ID

get

Retrieves the agent by given ID.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

agentIdstringRequired

Query parameters

fieldsstringOptional

Fields to be returned in the response.

expandstring · enumOptional

Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response.

Possible values:

Header parameters

Accept-LanguagestringOptional

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

• If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
• If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
• If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

Responses

200

A single agent.

application/json

or

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

404

Example response

application/json

get

/ai-service/{tenant}/agentic/agents/{agentId}

HTTPcURLJavaScriptPython

GET /ai-service/{tenant}/agentic/agents/{agentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "123",
  "name": {
    "en": "Complaint Agent"
  },
  "description": {
    "en": "Complaint agent"
  },
  "type": "complaint",
  "enabled": true,
  "templatePrompt": "You are an complaint agent for checking emails and do some action.",
  "userPrompt": "Use get-order tool to fetch order.",
  "llmConfig": {
    "model": "GPT-4.1",
    "apiKey": "secureApiKey",
    "provider": "openai",
    "maxTokens": 100000,
    "temperature": 0.2
  },
  "triggers": [
    {
      "type": "endpoint"
    }
  ],
  "maxRecursionLimit": 20,
  "enabledMemory": true,
  "tags": [
    "productivity"
  ],
  "icon": "fa-productivity",
  "mcpServers": [
    {
      "domain": "order",
      "type": "predefined",
      "tools": [
        "get-orders",
        "get-order"
      ]
    }
  ],
  "nativeTools": [
    {
      "name": "slack",
      "config": {
        "teamId": "T0445953"
      }
    }
  ]
}

Upserting agent

put

Updates or creates a specified product by replacing all of its existing data with data from the request body. If the metadata.version is provided then optimistic locking is enabled and version must match the version in the database.

Required scopes

This endpoint requires the following scopes:

• : Needed to manage AI agents.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

agentIdstringRequired

Header parameters

Content-LanguagestringOptional

List of languages in which localized fields in the request body are provided.

• If the header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
• If the header is set to a specific language, the localized fields should be provided as strings.
• If the header is empty, the endpoint assumes that the localized fields are provided in the default language defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request is rejected.

Body

application/json

userPromptstringRequired

LLM Prompt which describes how agent should work in a detailed way, which tools it could use to solve problems etc; it can contain examples and step by step guidance.

iconstringOptional

The fa class of react icon.

tagsstring[]Optional

Markers that allow you to categorize the agent.

enabledbooleanOptional

Indicates whether the agent is enabled.

Default: false

maxRecursionLimitinteger · min: 1 · max: 50Optional

Defines the maximum number of reasoning steps or internal calls an AI agent is allowed to perform during a single task. Helps prevent infinite loops or excessive resource usage.

Default: 20Example: 10

enabledMemorybooleanOptional

Defines whether the session memory should be stored between different agent calls.

Default: false

llmConfigone ofRequired

or

or

Responses

201

ID of created agent.

application/json

204

The resource has been successfully updated.

400

The request was syntactically incorrect.

application/json

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

404

Example response

application/json

409

There are three possible reasons:

1. Resource with given code already exists, please choose unique code for your resource
2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated resource in the time user was performing his changes). User should retrieve the latest product data and retry the request.
3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.

application/json

put

/ai-service/{tenant}/agentic/agents/{agentId}

HTTPcURLJavaScriptPython

PUT /ai-service/{tenant}/agentic/agents/{agentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 536

{
  "name": {
    "en": "Complaint Agent"
  },
  "description": {
    "en": "Complaint agent"
  },
  "enabled": true,
  "userPrompt": "You are an complaint agent for checking emails and do some action.",
  "llmConfig": {
    "model": "GPT-4.1",
    "token": {
      "id": "openai-token"
    },
    "provider": "openai",
    "maxTokens": 100000,
    "temperature": 0.2
  },
  "triggers": [
    {
      "type": "endpoint"
    }
  ],
  "maxRecursionLimit": 20,
  "enabledMemory": true,
  "tags": [
    "productivity"
  ],
  "icon": "fa-productivity",
  "mcpServers": [
    {
      "domain": "order",
      "type": "predefined",
      "tools": [
        "get-orders",
        "get-order"
      ]
    }
  ],
  "nativeTools": [
    {
      "id": "slack-1"
    }
  ]
}

{
  "id": "a81bc81b-dead-4e5d-abff-90865d1e13b1"
}

Deleting agent

delete

Deletes agent by given ID.

Important: If an agent is being used by another agent as collaboration agent then delete operation is not possible without force flag set to true.

Required scopes

This endpoint requires the following scopes:

• : Needed to manage AI agents.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

agentIdstringRequired

Query parameters

forcebooleanOptional

Allows you to remove a given entity even if it is used as a dependency in other entries. In that case, the removed entity is unassigned from other entries.

Example: false

Responses

204

Given agent has been deleted.

400

The request was syntactically incorrect.

application/json

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

404

Example response

application/json

delete

/ai-service/{tenant}/agentic/agents/{agentId}

HTTPcURLJavaScriptPython

DELETE /ai-service/{tenant}/agentic/agents/{agentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Partially updating agent

patch

Partially updates a single agent document with given information. Single update may contain multiple partial updates in the form of an array. It contains the allowed operations list:

• add (adding an item to the items list)

• remove (removing an item from the items list)

• replace (replacing an item with given ID with new definition)

Required scopes

This endpoint requires the following scopes:

• : Needed to manage AI agents.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

agentIdstringRequired

Bodyobject[]

application/json

Partial update operation list.

opany ofRequired

undefined · enumOptionalPossible values:

pathstringRequiredExample: /name

valueany ofOptional

stringOptional

Value of the string type.

or

objectOptional

Any part of the details object.

Responses

204

No Content

400

The request was syntactically incorrect.

application/json

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

404

Example response

application/json

patch

/ai-service/{tenant}/agentic/agents/{agentId}

HTTPcURLJavaScriptPython

PATCH /ai-service/{tenant}/agentic/agents/{agentId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 130

[
  {
    "op": "REPLACE",
    "path": "/description",
    "value": "New agent description"
  },
  {
    "op": "REPLACE",
    "path": "/name",
    "value": "Complaint Agent"
  }
]

Multiple update listChange model of the LLM

No content