Skip to main content

​
GET /api/sessions/:id/messages

Get paginated messages for a session. Authentication: Required

​
Path Parameters

​
id
string
required
Session ID

​
Query Parameters

​
limit
number
default:"50"
Number of messages to return (1-200)
​
beforeSeq
number
Return messages before this sequence number (for pagination)

​
Response

​
messages
array
Array of messages in reverse chronological order
​
hasMore
boolean
Whether there are more messages available

​
Example

curl -H "Authorization: Bearer <token>" \
  "http://127.0.0.1:3006/api/sessions/abc123/messages?limit=20"

{
  "messages": [
    {
      "id": "msg_xyz789",
      "seq": 42,
      "content": {
        "type": "text",
        "text": "Hello from the agent"
      },
      "createdAt": 1709856000000
    },
    {
      "id": "msg_abc456",
      "seq": 41,
      "localId": "local-123",
      "content": {
        "type": "text",
        "text": "User message"
      },
      "createdAt": 1709855000000
    }
  ],
  "hasMore": true
}

​
Pagination

To fetch older messages, use the beforeSeq parameter with the lowest seq from the current page: 
curl -H "Authorization: Bearer <token>" \
  "http://127.0.0.1:3006/api/sessions/abc123/messages?limit=20&beforeSeq=41"

​
Errors

  • 403 - Access denied (session belongs to different namespace)
  • 404 - Session not found
  • 503 - Hub not connected

​
POST /api/sessions/:id/messages

Send a message to an active session. Authentication: Required

​
Path Parameters

​
id
string
required
Session ID

​
Request Body

​
text
string
required
Message text (required if no attachments)
​
localId
string
Client-generated ID for optimistic updates
​
attachments
array
Array of attachment metadata objects

​
Response

{"ok": true}

​
Example: Text Message

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Please add a new feature",
    "localId": "local-456"
  }' \
  http://127.0.0.1:3006/api/sessions/abc123/messages

​
Example: Message with Attachment

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Here is the design",
    "attachments": [
      {
        "id": "att_123",
        "filename": "design.png",
        "mimeType": "image/png",
        "size": 102400,
        "path": "/tmp/hapi-upload-abc123-design.png"
      }
    ]
  }' \
  http://127.0.0.1:3006/api/sessions/abc123/messages

​
Errors

  • 400 - Invalid body or missing text/attachments
  • 403 - Access denied
  • 404 - Session not found
  • 409 - Session not active
  • 503 - Hub not connected

​
Message Flow

  1. Upload file (if needed): POST /api/sessions/:id/upload
  2. Send message: POST /api/sessions/:id/messages with attachment metadata
  3. Receive response: Agent processes and responds via WebSocket/SSE

Build docs developers (and LLMs) love

Get started for freeTalk to us