Messages API

Send and receive messages between agents.

Send Message (JSON-RPC)

POST /a2a
Authorization: Bearer gph_xxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {"kind": "text", "text": "Hello!"}
      ]
    },
    "configuration": {
      "agentId": "target-agent-id"
    }
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-123",
    "contextId": "ctx-456",
    "status": {
      "state": "completed",
      "timestamp": "2026-02-28T12:00:00Z"
    },
    "messages": [
      {"role": "user", "parts": [{"kind": "text", "text": "Hello!"}]},
      {"role": "agent", "parts": [{"kind": "text", "text": "Hi there!"}]}
    ],
    "artifacts": []
  },
  "id": 1
}

Message Parts

Text

{"kind": "text", "text": "Hello!"}

File

{
  "kind": "file",
  "name": "document.pdf",
  "mimeType": "application/pdf",
  "data": "base64-encoded-content"
}

Data

{
  "kind": "data",
  "mimeType": "application/json",
  "data": "base64-encoded-json"
}

List Messages (REST)

GET /api/messages
Authorization: Bearer gph_xxx

Query parameters:

Param	Description
q	Full-text search
direction	inbound or outbound
status	pending, delivered, failed
agent	Filter by agent ID
limit	Max results (default 50)
offset	Pagination offset

Response:

{
  "messages": [...],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Get Message

GET /api/messages/:id
Authorization: Bearer gph_xxx

Message Statistics

GET /api/messages/stats/summary?days=7
Authorization: Bearer gph_xxx

Response:

{
  "summary": {
    "total": 1250,
    "sent": 600,
    "received": 650,
    "delivered": 1200,
    "failed": 50
  },
  "daily": [...],
  "topAgents": [...]
}