Skip to main content
v1Stable

​
Send a Message

Send a message to an Apollo-1 agent and receive the complete response, optionally including the symbolic reasoning trace.
cURL
curl -X POST "https://api.aui.io/v1/messaging/messages?include_trace=true" \
  -H "Content-Type: application/json" \
  -H "x-aui-api-key: your-api-key" \
  -d '{
    "type": "message",
    "task_id": "task_68e78d0dc5a4b19a030d03d6",
    "text": "I want to dispute a charge from May 30th"
  }'

​
POST /v1/messaging/messages

Base URL: https://api.aui.io

​
Headers

HeaderRequiredDescription
x-aui-api-keyYesYour API key
Content-TypeYesMust be application/json

​
Query Parameters

​
include_trace
boolean
default:"false"
Include the symbolic reasoning trace in the response. Adds trace_info field.

​
Request Body

​
type
string
required
Message type. Must be "message".
​
task_id
string
required
The task identifier (conversation thread).
​
text
string
required
The message content to send to the agent.
​
agent_settings_bundle
object
Optional agent configuration bundle to test local changes without deploying.

​
Response

Returns a message response object containing the agent’s reply.
​
id
string
Unique message identifier. This is also the interaction ID used for rerun and trace endpoints.
​
text
string
The agent’s response message.
​
followup_suggestions
array
AI-generated follow-up question suggestions.
​
trace_info
object
Symbolic reasoning trace (only included when ?include_trace=true).
{
  "id": "msg_507f1f77bcf86cd799439011",
  "text": "I understand you want to dispute a charge from May 30th. However, our dispute policy allows disputes only within 8 days of the transaction date. Since today is June 9th, that transaction is 10 days old and falls outside our dispute window.",
  "followup_suggestions": [
    "What other options do I have?",
    "Can I speak to a supervisor?",
    "Show me my recent transactions"
  ],
  "trace_info": {
    "intent": "dispute_charge",
    "entities": {
      "transaction_date": "2026-05-30",
      "days_since_transaction": 10
    },
    "rules_evaluated": [
      {
        "rule_id": "rule_dispute_window",
        "predicate": "today - txn.date <= 8 days",
        "result": "blocked",
        "reason": "Transaction exceeds 8-day dispute window"
      }
    ],
    "parameters_extracted": ["transaction_date"],
    "tools_invoked": []
  }
}

​
Code Examples

const response = await fetch(
  "https://api.aui.io/v1/messaging/messages?include_trace=true",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-aui-api-key": "your-api-key"
    },
    body: JSON.stringify({
      type: "message",
      task_id: "task_68e78d0dc5a4b19a030d03d6",
      text: "I want to dispute a charge from May 30th"
    })
  }
);

const message = await response.json();
console.log(message.text);
console.log(message.trace_info);

​
Rerun an Interaction

Regenerate a previous interaction with edited text or updated agent configuration.
cURL
curl -X POST "https://api.aui.io/v1/messaging/messages/rerun?include_trace=true" \
  -H "Content-Type: application/json" \
  -H "x-aui-api-key: your-api-key" \
  -H "x-aui-user-id: user_xyz789" \
  -d '{
    "task_id": "task_123",
    "interaction_id": "msg_507f1f77bcf86cd799439011",
    "text": "Actually, the charge was from June 1st",
    "agent_id": "agent_abc123"
  }'

​
POST /v1/messaging/messages/rerun

​
Headers

HeaderRequiredDescription
x-aui-api-keyYesYour API key
x-aui-user-idYesUser identifier (acting user for this rerun)
Content-TypeYesMust be application/json

​
Query Parameters

​
include_trace
boolean
default:"false"
Include trace info in the regenerated response.

​
Request Body

​
task_id
string
required
The original task identifier.
​
interaction_id
string
required
The message ID to regenerate (from a previous send-message response).
​
text
string
required
The message to replay (can be the original or edited).
​
agent_id
string
required
The agent management ID.
​
version_id
string
Pin to a specific version for this rerun.
​
version_tag
string
Pin to a specific revision tag.
​
agent_settings_bundle
object
Optional agent configuration bundle to test changes.

​
Response

​
regenerated_task_id
string
The new task ID created for the regenerated conversation branch.
​
message
object
The agent’s response in the regenerated branch (same structure as send-message response).
{
  "regenerated_task_id": "task_new_abc789",
  "message": {
    "id": "msg_new_123",
    "text": "I can help you dispute that charge from June 1st. Since that was 8 days ago, it falls within our dispute window. Let me start the process.",
    "followup_suggestions": [
      "What's the dispute amount?",
      "Why are you disputing this charge?",
      "Show me the transaction details"
    ],
    "trace_info": {
      "intent": "dispute_charge",
      "entities": {
        "transaction_date": "2026-06-01",
        "days_since_transaction": 8
      },
      "rules_evaluated": [
        {
          "rule_id": "rule_dispute_window",
          "predicate": "today - txn.date <= 8 days",
          "result": "allowed",
          "reason": "Transaction is within 8-day dispute window"
        }
      ],
      "tools_invoked": ["start_dispute_process"]
    }
  }
}

​
Errors

StatusDescription
401Missing or invalid x-aui-api-key header
422Validation error — invalid request parameters or agent bundle
400Application error — may include moderation or processing details
401
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
422 - Invalid Bundle
{
  "error": "Validation Error",
  "message": "Agent settings bundle failed validation",
  "details": [
    {
      "file": "rules.aui.json",
      "field": "predicate",
      "message": "Invalid predicate syntax"
    }
  ]
}
422 - Missing Parameters
{
  "error": "Validation Error",
  "details": [
    {
      "field": "task_id",
      "message": "task_id is required"
    }
  ]
}