Send Messages

Send messages to Apollo-1 agents and receive complete responses with traces.

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

Header	Required	Description
x-aui-api-key	Yes	Your API key
Content-Type	Yes	Must 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.

Show bundle structure

{
  "agent": { /* agent.aui.json */ },
  "parameters": [ /* parameters.aui.json */ ],
  "entities": [ /* entities.aui.json */ ],
  "rules": [ /* rules.aui.json */ ],
  "tools": [ /* tools/*.aui.json */ ],
  "integrations": [ /* integrations.aui.json */ ]
}

The bundle is validated before execution. Invalid configurations return a 422 error.

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).

Show trace structure

trace_info.intent · string

The parsed user intent.

trace_info.entities · object

Entities extracted from the conversation.

trace_info.rules_evaluated · array

Rules that were evaluated, including predicates and results.

trace_info.parameters_extracted · array

Parameters collected during the interaction.

trace_info.tools_invoked · array

Tools that were called to fulfill the request.

200

{
  "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

Node.js

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);

import requests

response = requests.post(
    "https://api.aui.io/v1/messaging/messages",
    params={"include_trace": "true"},
    headers={
        "Content-Type": "application/json",
        "x-aui-api-key": "your-api-key"
    },
    json={
        "type": "message",
        "task_id": "task_68e78d0dc5a4b19a030d03d6",
        "text": "I want to dispute a charge from May 30th"
    }
)

message = response.json()
print(message["text"])
print(message["trace_info"])

curl -X POST "https://api.aui.io/v1/messaging/messages" \
  -H "Content-Type: application/json" \
  -H "x-aui-api-key: your-api-key" \
  -d '{
    "type": "message",
    "task_id": "task_123",
    "text": "Test message",
    "agent_settings_bundle": {
      "agent": {
        "name": "Test Agent",
        "description": "Testing configuration"
      },
      "rules": [
        {
          "id": "rule_test",
          "type": "policy",
          "predicate": "amount < 100",
          "action": "allow"
        }
      ]
    }
  }'

---

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

Header	Required	Description
x-aui-api-key	Yes	Your API key
x-aui-user-id	Yes	User identifier (acting user for this rerun)
Content-Type	Yes	Must 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).

200

{
  "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

Status	Description
401	Missing or invalid x-aui-api-key header
422	Validation error — invalid request parameters or agent bundle
400	Application 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"
    }
  ]
}