AI TCP API¶

The TCP transport addresses a module method by command name. It is the entry point for the trading terminal and for server-to-server integrations that already hold a persistent platform connection.

The same methods are available over HTTP — see REST API. The command name and the HTTP path are two addresses of one method.

TCP has one capability REST does not: the streamed answer arrives on the same connection, so the assistant can be shown typing.

Request envelope¶

{
  "command": "AIChatSendMessage",
  "extID": "8f2a1c",
  "data": {
    "conversationId": "cnv_8f3a…",
    "content": "Why was my position closed?",
    "requestId": "b1f0-…"
  }
}

Field	Type	Description
`command`	string	Method name, exactly as published by the module
`extID`	string	Caller-generated correlation id; the response carries it back
`data`	object	Method parameters

Response¶

{
  "extID": "8f2a1c",
  "status": 200,
  "data": {
    "runId": "run_55b…",
    "messageId": "msg_1c7…",
    "state": "queued",
    "idempotent": false
  }
}

The reply confirms that the question was accepted, not answered: generation takes tens of seconds. The answer arrives as events, or is read later with AIChatGetRun.

Streamed events¶

While a run is being processed, the module sends messages through the platform delivery channel. They arrive on the same connection as module:event:

{
  "event": "module:event",
  "type": "ai.run.delta",
  "event_id": "evt-…",
  "schema_version": 1,
  "created_at": 1789080000,
  "data": {
    "runId": "run_55b…",
    "conversationId": "cnv_8f3a…",
    "sequence": 7,
    "delta": "…text fragment…"
  }
}

`type`	Meaning
`ai.run.queued`	accepted, waiting for a slot
`ai.run.started`	generation began
`ai.run.delta`	a fragment of the answer
`ai.run.tool.started`	the assistant is reading platform data
`ai.run.tool.completed`	the tool answered
`ai.run.completed`	the answer is ready; carries a short preview, not the full text
`ai.run.cancelled`	the run was cancelled
`ai.run.failed`	the run failed; carries `errorCode`

Events are addressed to the session that asked: a manager session receives them as a manager, a client session as its account. There is no per-conversation subscription.

Delivery is fire-and-forget — no acknowledgement, no storage, no redelivery. Use sequence to notice a gap and read the result with AIChatGetRun instead of assembling the text from fragments. The full reasoning behind this is in Chat integration.

Commands¶

Chat¶

Command	Description
AIChatCreateConversation	Start a conversation
AIChatGetConversations	Conversation list
AIChatGetConversation	Messages page and the active run
AIChatUpdateConversation	Rename or archive
AIChatDeleteConversation	Delete
AIChatSendMessage	Ask a question
AIChatGetRun	Run state and result
AIChatCancelRun	Stop a run
AIFeedbackAdd	Rate an answer
AIGetAgents	Agents available to this session
AIKnowledgeSearch	Knowledge search without the model

Notifications¶

Command	Description
MngGetAINotificationsByFilter	Approval queue and journal
MngApproveAINotification	Approve, optionally with an edited text
MngRejectAINotification	Reject with a reason
MngRetryAINotification	Retry delivery

Administration¶

Command	Description
MngGetAIAgentsByFilter, MngAddAIAgent, MngUpdateAIAgent, MngDeleteAIAgent	Agent configurations
MngGetAIModels, MngGetAITools	Model catalogue and tool availability
MngGetAIPromptTemplatesByFilter, MngAddAIPromptTemplate, MngUpdateAIPromptTemplate, MngDeleteAIPromptTemplate, MngTestAIPromptTemplate	Prompt templates
MngGetAIKnowledgeStatus, MngGetAIKnowledgeDocuments, MngReloadAIKnowledge	Knowledge base
MngGetAIWorkflowEvents, MngGetAIWorkflowBindingsByFilter, MngAddAIWorkflowBinding, MngUpdateAIWorkflowBinding, MngDeleteAIWorkflowBinding, MngTestAIWorkflowBinding	Events and bindings
MngGetAIUsageByFilter, MngGetAIRunsByFilter, MngGetAIRunDetails, MngGetAIFeedbackByFilter	Spend and audit
AIPing, AIHealth	Service state

Errors¶

An error keeps the envelope; the outcome is in status and the module code is in the body:

{
  "extID": "8f2a1c",
  "status": 409,
  "data": {
    "error": "AI_CONVERSATION_BUSY",
    "message": "This conversation already has a running request"
  }
}

AI_CONVERSATION_BUSY is the one worth handling before it happens: one run per conversation, so the input should be disabled while an answer is being written. The full table is in Chat integration.