Coach Agent API
Invoke the VisualQ Coach AI from CI pipelines, IDE agents, or custom tools.
Coach Agent API
Run the VisualQ Coach programmatically — without opening the in-app chat panel. Typical uses: CI summaries, IDE plugins, or internal quality bots.
Coach Agent v2 (recommended)
POST /api/coach/v2/agent is the recommended path. Authenticate with a project API key:
X-API-Key: vq_live_…The route can run a short tool loop (read project health, latest failures, etc.) using the same tool catalog as the MCP gateway.
When calling from the signed-in dashboard (browser session), the same endpoint accepts your VisualQ account session instead of an API key.
Request
{
"message": "What is blocking release on staging?",
"project": "my-website",
"environment": "staging",
"maxTurns": 4
}| Field | Required | Description |
|---|---|---|
message | yes | User goal or question |
project | no | Project slug (optional with project-scoped key) |
environment | no | Environment slug |
feature / action | no | Coach feature routing hints |
context | no | Extra context object |
maxTurns | no | Tool loop cap (default 8, max 8) |
Response
{
"ok": true,
"reply": "…",
"model": "anthropic/claude-sonnet-4",
"toolCalls": 2
}Read-only tools may run automatically within maxTurns. Mutating tools still require explicit confirmation through MCP — the v2 route does not bypass those gates.
Coach Agent v1 (legacy)
POST /api/coach/v1/agent remains for older integrations that use a dedicated Coach agent key:
Authorization: Bearer $COACH_AGENT_API_KEYContact support if you need a v1 key issued or migrated to v2 + project API keys.
Request
{
"orgId": "org_123",
"projectId": "project_123",
"message": "Analyze the latest failed visual run and summarize the likely causes.",
"feature": "vrt",
"action": "analysis",
"context": {
"lastRunResults": true
}
}orgId and message are required. projectId, userId, feature, action, and context are optional.
Response
{
"reply": "The most likely cause is dynamic content in the hero carousel...",
"feature": "vrt",
"action": "analysis",
"model": "anthropic/claude-sonnet-4",
"key": "a1b2c3d4"
}The API returns JSON only. UI navigation tools are not executed from this endpoint.