The agent dock is built on this API. Use it to drive multi-step actions on a board from anywhere.
Open a session
POST /api/agents/session
{
"board_id": "…",
"agent_type": "board-helper" | "prompt-suggestor" | "terminal",
"model": "anthropic/claude-sonnet"
}Returns:
{ "session_id": "…", "started_at": "…" }Sessions are stored in-memory by the backend. They expire after 60 minutes of inactivity.
Chat
POST /api/agents/chat
{
"session_id": "…",
"messages": [
{ "role": "user", "content": "Generate three variants of @hero with a winter palette." }
],
"references": [ … ] // optional selection + mentioned elements
}Returns a streamed response with:
- Assistant message — the agent’s reasoning and per-step explanations.
- Action cards — proposed actions awaiting approval.
{
"message": "I'll generate three winter variants…",
"actions": [
{
"id": "action_1",
"type": "generate_image",
"params": { … },
"preview": { … }
},
…
]
}For board agents the response is sent as Server-Sent Events to support streaming.
Apply an action
POST /api/agents/apply-action
{
"session_id": "…",
"action_id": "action_1"
}Executes the action (generate, place, group, render, etc.). Returns the resulting element(s) and the updated board state.
Reject an action
POST /api/agents/reject-action
{
"session_id": "…",
"action_id": "action_1"
}Drops the action without executing.
Auto-apply
POST /api/agents/auto-apply
{
"session_id": "…",
"enabled": true
}Subsequent action cards execute immediately. Reset on session close.
End a session
POST /api/agents/end-session
{ "session_id": "…" }Frees backend memory.
Leave a Reply