AI REST API¶
The REST transport addresses a module method by HTTP method and path. It is the entry point for the trading terminal, the backoffice and the CRM interface.
The same methods are available over TCP by command name — see TCP API. Request fields and results are identical; only the addressing differs.
Base URL¶
https://{broker_domain}/ai/...
All paths of the module live under ai/.
Authorization¶
Every endpoint requires a session token:
Authorization: <JWT_TOKEN>
The platform resolves the token and passes the identity to the module in __access. The
module then asks the platform who this is — brand, desks and permissions are never taken
from the request body.
Three session kinds reach the module, and they see different things:
| Session | __access |
What it may do |
|---|---|---|
| Client, single account | { login, type: 0 } |
chat about its own account |
| Client, account owner | { customer_id, type: 9 } |
chat about one of its accounts; must pass accountLogin |
| Employee | { id, type: 1 \| 2 \| 3 \| 10 \| 11 } |
chat, and administration if the manager is an administrator |
There is no separate switch for the client chat: the session type decides the audience, the available tools and which knowledge documents may be used.
Endpoints¶
Chat¶
| Method | Endpoint | Access |
|---|---|---|
| AIChatCreateConversation | POST ai/chat/conversation |
client, manager, admin |
| AIChatGetConversations | GET ai/chat/conversations |
client, manager, admin |
| AIChatGetConversation | GET ai/chat/conversation |
client, manager, admin |
| AIChatUpdateConversation | PUT ai/chat/conversation |
client, manager, admin |
| AIChatDeleteConversation | DELETE ai/chat/conversation |
client, manager, admin |
| AIChatSendMessage | POST ai/chat/message |
client, manager, admin |
| AIChatGetRun | GET ai/chat/run |
client, manager, admin |
| AIChatCancelRun | POST ai/chat/run/cancel |
client, manager, admin |
| AIFeedbackAdd | POST ai/chat/feedback |
client, manager, admin |
| AIGetAgents | GET ai/chat/agents |
client, manager, admin |
Notifications¶
| Method | Endpoint | Access |
|---|---|---|
| MngGetAINotificationsByFilter | GET ai/notifications |
admin |
| MngApproveAINotification | POST ai/notification/approve |
manager, admin |
| MngRejectAINotification | POST ai/notification/reject |
manager, admin |
| MngRetryAINotification | POST ai/notification/retry |
admin |
Agents, prompts and knowledge¶
| Method | Endpoint | Access |
|---|---|---|
| MngGetAIAgentsByFilter | GET ai/agents |
admin |
| MngAddAIAgent | POST ai/agent |
admin |
| MngUpdateAIAgent | PUT ai/agent |
admin |
| MngDeleteAIAgent | DELETE ai/agent |
admin |
| MngGetAIModels | GET ai/models |
admin |
| MngGetAITools | GET ai/tools |
admin |
| MngGetAIPromptTemplatesByFilter | GET ai/prompts |
admin |
| MngAddAIPromptTemplate | POST ai/prompt |
admin |
| MngUpdateAIPromptTemplate | PUT ai/prompt |
admin |
| MngDeleteAIPromptTemplate | DELETE ai/prompt |
admin |
| MngTestAIPromptTemplate | POST ai/prompt/test |
admin |
| MngGetAIKnowledgeStatus | GET ai/knowledge/status |
admin |
| MngGetAIKnowledgeDocuments | GET ai/knowledge/documents |
admin |
| MngReloadAIKnowledge | POST ai/knowledge/reload |
admin |
| AIKnowledgeSearch | POST ai/knowledge/search |
client, manager, admin |
Events, spend and service¶
| Method | Endpoint | Access |
|---|---|---|
| MngGetAIWorkflowEvents | GET ai/workflow/events |
admin |
| MngGetAIWorkflowBindingsByFilter | GET ai/workflow/bindings |
admin |
| MngAddAIWorkflowBinding | POST ai/workflow/binding |
admin |
| MngUpdateAIWorkflowBinding | PUT ai/workflow/binding |
admin |
| MngDeleteAIWorkflowBinding | DELETE ai/workflow/binding |
admin |
| MngTestAIWorkflowBinding | POST ai/workflow/test |
admin |
| MngGetAIUsageByFilter | GET ai/usage |
admin |
| MngGetAIRunsByFilter | GET ai/runs |
admin |
| MngGetAIRunDetails | GET ai/run |
admin |
| MngGetAIFeedbackByFilter | GET ai/feedback |
admin |
| AIPing | GET ai/ping |
any session |
| AIHealth | GET ai/health |
any session |
AIPing and AIHealth read no customer data and check no session, so they can be used by
monitoring with any token.
List queries¶
MngGetAIAgentsByFilter, MngGetAIPromptTemplatesByFilter,
MngGetAIWorkflowBindingsByFilter, MngGetAIRunsByFilter and
MngGetAINotificationsByFilter accept the shared list contract:
| Field | Type | Description |
|---|---|---|
limit |
int | Page size, default 50–100 depending on the method, maximum 500 |
offset |
int | Rows to skip |
orderBy |
array | ["createdAt", "DESC"] |
groupBy |
array | Grouping, including date grouping |
where, whereIn, whereBetween, … |
object | Filters, as in Table filter syntax |
Rows come back as objects, not as positional arrays. Unlike the core table methods,
these lists have no structure field: every row is a plain object with named fields. A
table component written for the core format needs a second mode here.
count is present everywhere except MngGetAIAgentsByFilter,
MngGetAIPromptTemplatesByFilter and MngGetAIWorkflowBindingsByFilter, where the page is
returned without a total.
Status codes¶
| Code | When |
|---|---|
200 |
The method completed |
400 |
Invalid parameters, or a client session without accountLogin |
402 |
The agent's daily budget is spent |
403 |
The session may not do this |
404 |
Conversation, run, agent or notification not found in this scope |
409 |
A run is already active in this conversation, or the notification is in another state |
429 |
Rate limit |
502, 503, 504 |
The model or a platform dependency is unavailable |
Error bodies carry the module code in error and a human-readable message. The full list
with what to show the user is in Chat integration.