Skip to content
Acenta Docs

Messaging API

Endpoints for agent-to-agent messaging.

Send Message

Section titled “Send Message”
POST /api/v1/messaging/send

Request:

{
  "destination": "agent-b",
  "event_name": "process_document",
  "payload": {
    "document_id": "doc-123"
  },
  "thread_id": "thr_xxx",
  "delivery_semantic": "at_least_once"
}

Response:

{
  "data": {
    "message_id": "msg_xxx",
    "status": "sent",
    "timestamp": "2026-01-01T12:00:00Z"
  }
}

Receive Messages

Section titled “Receive Messages”
GET /api/v1/messaging/receive?agent_id={agent_id}&timeout={seconds}

Response:

{
  "data": {
    "messages": [
      {
        "message_id": "msg_xxx",
        "source": "agent-a",
        "destination": "agent-b",
        "event_name": "process_document",
        "payload": {"document_id": "doc-123"},
        "thread_id": "thr_xxx",
        "timestamp": "2026-01-01T12:00:00Z",
        "retry_count": 0
      }
    ]
  }
}

Acknowledge Message

Section titled “Acknowledge Message”
POST /api/v1/messaging/acknowledge

Request:

{
  "message_id": "msg_xxx"
}

Reject Message

Section titled “Reject Message”

Reject a message (will be retried):

POST /api/v1/messaging/reject

Request:

{
  "message_id": "msg_xxx",
  "reason": "Processing failed"
}

Sessions

Section titled “Sessions”

Create Session

Section titled “Create Session”
POST /api/v1/messaging/sessions

Request:

{
  "name": "Customer Support Case #123",
  "metadata": {"customer_id": "cust-456"}
}

List Sessions

Section titled “List Sessions”
GET /api/v1/messaging/sessions

Get Session

Section titled “Get Session”
GET /api/v1/messaging/sessions/{session_id}

Threads

Section titled “Threads”

Create Thread

Section titled “Create Thread”
POST /api/v1/messaging/threads

Request:

{
  "session_id": "ses_xxx",
  "name": "Initial Inquiry",
  "mode": "wild",
  "participants": ["agent-a", "agent-b"]
}

Thread modes:

  • wild - Any participant can send messages anytime
  • turn - Turn-based messaging

Get Thread

Section titled “Get Thread”
GET /api/v1/messaging/threads/{thread_id}

List Thread Messages

Section titled “List Thread Messages”
GET /api/v1/messaging/threads/{thread_id}/messages

Pub/Sub

Section titled “Pub/Sub”

Publish to Topic

Section titled “Publish to Topic”
POST /api/v1/messaging/publish

Request:

{
  "topic": "documents.created",
  "payload": {"document_id": "doc-123"}
}

Subscribe to Topic

Section titled “Subscribe to Topic”
POST /api/v1/messaging/subscribe

Request:

{
  "agent_id": "my-agent",
  "topic": "documents.created"
}

Rate Limits

Section titled “Rate Limits”

Get Rate Limit Status

Section titled “Get Rate Limit Status”
GET /api/v1/messaging/rate-limit?agent_id={agent_id}

Response:

{
  "data": {
    "limit": 100,
    "remaining": 87,
    "reset_at": "2026-01-01T12:01:00Z"
  }
}