The chat endpoint uses Server-Sent Events (SSE) for streaming. Responses are not standard JSON — they arrive as a stream of events.
Chat Modes
| Mode | Description |
|---|
| ask | Query and analyze without making changes |
| agent | AI makes direct edits to schematic or PCB |
| plan | Multi-step planning with approval workflow |
Stream Chat
POST /chat/stream
Request Body
| Field | Type | Required | Description |
|---|
message | string | Yes | The user’s message |
session_id | string | Yes | Conversation session ID |
mode | string | No | ask, agent, or plan |
app_type | string | No | schematic or pcb |
project_path | string | No | Path to the project |
schematic_content | string | No | Current schematic file content |
pcb_content | string | No | Current PCB file content |
SSE Event Types
| Event | Description |
|---|
text | AI response text chunk |
tool_call | AI requesting a tool execution |
tool_result | Result from a tool execution |
question | AI asking for clarification |
plan | Multi-step plan for approval |
status | Status update message |
error | Error message |
done | Stream complete |
Example
curl -N -X POST "https://api.buildwithtrace.com/api/v2/chat/stream" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"message": "Add a 10uF decoupling capacitor to U1",
"session_id": "session-uuid",
"mode": "agent",
"app_type": "schematic"
}'
POST /tools/result
After the AI requests a tool execution (e.g., modifying a file locally), submit the result back:
curl -X POST "https://api.buildwithtrace.com/api/v2/tools/result" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tool_call_id": "call_id",
"result": "Tool execution output"
}'
Task Status
GET /task/{task_id}/status
Check the status of an async task:
curl -X GET "https://api.buildwithtrace.com/api/v2/task/TASK_ID/status" \
-H "Authorization: Bearer YOUR_TOKEN"
Error Responses
| Status | Description |
|---|
| 402 | Quota exceeded |
| 403 | Plan doesn’t support this mode |
| 429 | Rate limited |
