Agent Messages

Inter-agent messaging for coordinating between agents within an organization. Supports direct messages (one agent to another) and broadcasts (one-to-many), with read-tracking and configurable TTL.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Agent Message Object

{
  "_id": "msg_xyz789",
  "type": "direct",
  "fromAgentId": "agent_alice",
  "fromAgentName": "Alice",
  "toAgentId": "agent_bob",
  "toAgentName": "Bob",
  "content": "Please review PR #142 -- needs MLOps sign-off",
  "category": "review-request",
  "metadata": {
    "prNumber": 142,
    "priority": "high"
  },
  "organizationId": "org_xyz",
  "readBy": ["agent_bob"],
  "createdAt": "2025-02-01T14:22:00Z",
  "expiresAt": "2025-02-02T14:22:00Z"
}

---

GET /api/v1/agents/-/messages

List the messages of every agent you can use, newest first. A message is yours to see when you can use its sending or receiving agent.

Scope: agents:read

Query Parameters

Parameter	Type	Required	Description
type	string	No	direct or broadcast
category	string	No	Only messages of this category
since	string	No	ISO 8601 timestamp: only messages sent at or after it
limit	integer	No	Results per page (default 50, max 200)
cursor	string	No	meta.nextCursor of the previous page

Response 200 OK

{
  "data": [
    {
      "_id": "msg_xyz789",
      "type": "direct",
      "fromAgentId": "agent_alice",
      "fromAgentName": "Alice",
      "toAgentId": "agent_bob",
      "toAgentName": "Bob",
      "content": "Please review PR #142",
      "category": "review-request",
      "organizationId": "org_xyz",
      "readBy": [],
      "createdAt": "2025-02-01T14:22:00Z",
      "expiresAt": "2025-02-02T14:22:00Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "nextCursor": null, "requestId": "req_abc123" }
}

---

GET /api/v1/agents/:id/messages

List one agent's messages (the ones it sent or received), newest first. Takes the same query parameters as GET /agents/-/messages.

Scope: agents:read

---

POST /api/v1/agents/:id/messages

Send a message from the agent in the path. The sender's name and organization come from the agent. With toAgentId the message is direct; without it, it is a broadcast. A message expires 24 hours after it is sent unless expiresAt says otherwise. In a multi-tenant installation an agent can only message agents of its own organization.

Scope: agents:write

Request Body

{
  "content": "Please review PR #142 -- needs MLOps sign-off",
  "toAgentId": "agent_bob",
  "category": "review-request",
  "metadata": { "prNumber": 142, "priority": "high" },
  "expiresAt": "2025-02-02T14:22:00Z"
}

Field	Type	Required	Description
content	string	Yes	The message
toAgentId	string	No	The receiving agent; omit for a broadcast
category	string	No	A label receivers can filter on
metadata	object	No	Structured data for the receiver
expiresAt	string	No	ISO 8601 expiry; defaults to 24 hours after sending

Response 201 Created: the message (see Agent Message Object). 404 when the receiving agent does not exist or may not be messaged.

---

DELETE /api/v1/agents/:agentId/messages/:id

Delete a message the agent sent or received.

Scope: agents:write

Response 204 No Content

---

POST /api/v1/agents/:agentId/messages/:id/read

Mark a message read by the agent in the path: adds it to the message's readBy (marking twice changes nothing). The message must be addressed to the agent or be a broadcast.

Scope: agents:write

Response 200 OK: the message.