Skip to navigation

Send a message to the portal agent

Sends a chat message to the portal agent. The agent parses the request, may call read-only tools immediately, and returns a diff preview with an actionId for any mutating tool call. Nothing mutates on a bare chat message — not even when the tenant policy would allow the action. Mutations execute only after the user approves the diff via POST /v1/agent/actions/{actionId}/approve. Requires a session cookie or tenant API key; the tenant must be in the Phase-1 allow-list (WRIT_AGENT_TENANTS). Send Accept: text/event-stream to receive the reply as SSE frames (event: message, then event: done).

Request

This endpoint expects an object.
messagestringRequired
The user's chat request.

Response

Agent reply or diff preview.
typeenumOptional
Allowed values:
messagestringOptional
blockedReasonstringOptional
receiptobjectOptional
suggestionslist of stringsOptional

First-login suggested actions derived from tenant state.

actionslist of objectsOptional
pendingActionslist of objectsOptional

Errors

400
Bad Request Error
403
Forbidden Error
429
Too Many Requests Error
503
Service Unavailable Error