Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.svantic.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Messages

​
What They Are

A message is the durable record of a single agent interaction within a session. When you call POST /send (via message/send or message/stream), the mesh runtime creates a message, updates it as execution progresses, and persists snapshots through the gateway. Dashboards and clients can list messages, inspect status, and cancel work that is still running. The gateway stores each message in PostgreSQL (messages) with a stable message_id, tenant isolation, the current state, user input, assistant output, trace data, and the full A2A task payload in task_data.

​
Lifecycle

Messages move through a set of state values aligned with the A2A execution model:
  1. submitted — accepted and queued.
  2. working — actively executing.
  3. input-required — blocked waiting for human input (approval, form data, confirmation). See Notifications & Approvals.
  4. completed — finished successfully.
  5. failed — finished with an error.
  6. canceled — stopped by operator or API.
Terminal states are completed, failed, and canceled. Cancellation is only applied when the message is not already in one of those states.

​
Relation to Sessions

Every message belongs to a session via session_id. One session can have many messages over time — each POST /send call creates a new message. Filter listings by session_id to show messages for a single session.

​
API

EndpointPurpose
POST /sendSend a new message (A2A JSON-RPC — message/send or message/stream)
POST /messages/getPaginated list for the tenant; optional state and session_id filters
POST /messages/get_by_idFull detail for one message_id
POST /messages/cancelCancel a running message (409 if already terminal)
POST /messages/pendingList messages in input-required state (the Approval Queue)
POST /messages/{id}/resolveSubmit a human resolution for a pending message

​
Canceling Messages

Call POST /messages/cancel with { "message_id": "<id>" }. Success returns { "ok": true, "message_id": "<id>" }. If the message is already completed, failed, or canceled, the gateway responds with 409.

​
Resolving Pending Messages

When a message enters input-required, it appears in the Approval Queue. Resolution can come from:
  • Dashboard: click Approve/Deny or submit a form
  • API: POST /messages/{id}/resolve with resolution data
  • Slack: interactive buttons → /integrations/slack/interactive
  • Webhook callback: POST /messages/{id}/resolve with callback_token
See Notifications & Approvals for the full resolution flow.

​
Further Reading