Gateway sessions represent active agent contexts running on an OpenClaw gateway. These endpoints allow you to inspect session state, view chat history, and send messages.
Authentication
All endpoints require organization admin authentication via Authorization: Bearer <token> header.
List Gateway Sessions
GET /api/v1/gateways/sessions
List all active sessions for gateways associated with a board.
Query Parameters
Filter sessions by board ID
Response
Array of session objects from the gateway runtime
The gateway’s main agent session (if present)
Example Request
curl -X GET "https://api.example.com/api/v1/gateways/sessions?board_id=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer your-token-here"
Example Response
{
"sessions": [
{
"id": "agent:mc-c91361ef-6d85-439c-82e1-8f388a302e6a:main",
"agentId": "mc-c91361ef-6d85-439c-82e1-8f388a302e6a",
"status": "active",
"created": "2026-03-05T10:00:00Z",
"lastActivity": "2026-03-05T11:30:00Z"
}
],
"main_session": {
"id": "agent:main:main",
"agentId": "main",
"status": "active"
}
}
Get Gateway Session
GET /api/v1/gateways/sessions/
Fetch details of a specific gateway session.
Path Parameters
Session identifier (e.g., agent:mc-{uuid}:main)
Query Parameters
Board context for session lookup
Response
Session details from the gateway runtime
Example Request
curl -X GET "https://api.example.com/api/v1/gateways/sessions/agent:mc-c91361ef-6d85-439c-82e1-8f388a302e6a:main" \
-H "Authorization: Bearer your-token-here"
Get Session History
GET /api/v1/gateways/sessions//history
Fetch the conversation history for a gateway session.
Path Parameters
Query Parameters
Board context for session lookup
Response
Array of conversation messages from the sessionEach message typically includes:
role - “user”, “assistant”, or “system”content - Message texttimestamp - When the message was created
Example Request
curl -X GET "https://api.example.com/api/v1/gateways/sessions/agent:mc-c91361ef-6d85-439c-82e1-8f388a302e6a:main/history" \
-H "Authorization: Bearer your-token-here"
Example Response
{
"history": [
{
"role": "system",
"content": "You are a CFO agent...",
"timestamp": "2026-03-05T10:00:00Z"
},
{
"role": "user",
"content": "Please review the Q1 budget",
"timestamp": "2026-03-05T10:15:00Z"
},
{
"role": "assistant",
"content": "I'll review the Q1 budget now. Let me fetch the latest numbers...",
"timestamp": "2026-03-05T10:15:30Z"
}
]
}
Send Session Message
POST /api/v1/gateways/sessions//message
Send a message into a specific gateway session.
Path Parameters
Query Parameters
Board context for session lookup
Request Body
Message text to send to the agent
Response
Returns a success indicator:
Example Request
curl -X POST "https://api.example.com/api/v1/gateways/sessions/agent:mc-c91361ef-6d85-439c-82e1-8f388a302e6a:main/message" \
-H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-d '{
"content": "Please prioritize the budget review task"
}'
Gateway Status
GET /api/v1/gateways/status
Check gateway connectivity and session health.
Query Parameters
Board ID to resolve gateway
Direct gateway URL to check
Gateway authentication token
gateway_disable_device_pairing
Device pairing mode
gateway_allow_insecure_tls
TLS validation mode
Response
Whether the gateway is reachable
Number of active sessions
Array of active session objects
Gateway main session details
Error message if main session lookup failed
Connection error message if gateway is unreachable
Example Request
curl -X GET "https://api.example.com/api/v1/gateways/status?board_id=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer your-token-here"
Example Response (Success)
{
"connected": true,
"gateway_url": "ws://72.62.201.147:18789",
"sessions_count": 5,
"sessions": [
{
"id": "agent:mc-c91361ef:main",
"status": "active"
}
],
"main_session": {
"id": "agent:main:main",
"status": "active"
}
}
Example Response (Error)
{
"connected": false,
"gateway_url": "ws://72.62.201.147:18789",
"sessions_count": null,
"sessions": null,
"main_session": null,
"error": "Connection refused"
}
Gateway Commands
GET /api/v1/gateways/commands
Returns the supported gateway protocol methods and events.
Response
Gateway RPC protocol version
Array of supported RPC method names
Array of supported event types
Example Response
{
"protocol_version": 1,
"methods": [
"agents.create",
"agents.update",
"agents.delete",
"agents.list",
"agents.files.get",
"agents.files.set",
"sessions.list",
"sessions.history",
"sessions.send"
],
"events": [
"agent.created",
"agent.updated",
"session.started",
"session.ended"
]
}
Use Cases
Monitoring Active Agents
List all sessions to see which agents are currently active:
curl "$BASE_URL/api/v1/gateways/sessions" \
-H "Authorization: Bearer $TOKEN"
Debugging Agent Behavior
Review session history to understand agent decisions:
curl "$BASE_URL/api/v1/gateways/sessions/$SESSION_ID/history" \
-H "Authorization: Bearer $TOKEN"
Direct Agent Communication
Send urgent messages directly to agent sessions:
curl -X POST "$BASE_URL/api/v1/gateways/sessions/$SESSION_ID/message" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "URGENT: Production incident detected"}'
Health Checks
Verify gateway connectivity before operations:
curl "$BASE_URL/api/v1/gateways/status?board_id=$BOARD_ID" \
-H "Authorization: Bearer $TOKEN"
- Agent sessions:
agent:{agent-key}:main
- Main agent:
agent:main:main
- MC agents:
agent:mc-{uuid}:main
Examples:
agent:mc-c91361ef-6d85-439c-82e1-8f388a302e6a:mainagent:main:mainagent:cfo:main (manually configured agent)
