WebSocket Chat API

Endpoint

wss://api.misar.dev/ws/chat/v2

Authentication

Pass your API key as a query parameter or request header:

wss://api.misar.dev/ws/chat/v2?api_key=YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Client Message

Send a JSON object to the server after the connection is established:

{
  "user_text": "Fix the null pointer bug in auth.py",
  "workspace_path": "/home/user/my-project",
  "session_id": "abc-123",
  "tool_results": [],
  "max_tokens": 4096,
  "swe_mode": false,
  "swe_phase": null,
  "agent_type": "legacy",
  "persona": "default",
  "system_prompt": "",
  "context_files": [],
  "attachments": []
}

Fields

| Field | Type | Default | Description | |-------|------|---------|-------------| | user_text | string | — | The user's message or instruction | | workspace_path | string | "" | Absolute path to the workspace root on the agent host | | session_id | string | "" | Session identifier for conversation continuity | | tool_results | array | [] | Results from previously requested tool calls | | max_tokens | number | 4096 | Maximum tokens in the model response | | swe_mode | boolean | false | Enable the structured 5-phase SWE bug-fix pipeline | | swe_phase | string|null | null | Current SWE phase when resuming mid-pipeline | | agent_type | string | "legacy" | Agent routing mode: "legacy" or "moe" | | persona | string | "default" | Agent persona preset | | system_prompt | string | "" | Additional system prompt appended after default | | context_files | array | [] | Extra file paths to include in context | | attachments | array | [] | File or image attachments (base64 encoded) |

tool_results item

When the server sends a tool_use event, execute the tool locally and send the result back as a new client message with tool_results populated:

{
  "tool_results": [
    {
      "tool_use_id": "toolu_abc123",
      "content": "File written successfully.",
      "is_error": false
    }
  ]
}

Server Events

The server streams a sequence of JSON events for each response turn:

| Event | Description | |-------|-------------| | content_block_start | A new content block is beginning (text or tool use) | | content_block_delta | A streamed chunk of text content | | content_block_stop | The current content block is complete | | tool_use | The agent is requesting a tool call — client must execute and return result | | message_stop | The full response turn is complete | | usage | Token counts and estimated cost for the turn | | error | A recoverable or fatal error occurred | | swe_phase | SWE pipeline phase transition | | swe_attempt | SWE multi-attempt progress update | | swe_result | Final result of the SWE pipeline | | rag_sources | Workspace file chips retrieved by the RAG system | | ask_user | Agent is pausing and waiting for a user response before continuing |

Event Shapes

// content_block_delta
{ "type": "content_block_delta", "delta": { "type": "text_delta", "text": "Here is the fix..." } }

// tool_use
{ "type": "tool_use", "id": "toolu_abc123", "name": "read_file", "input": { "path": "src/auth.py" } }

// usage
{ "type": "usage", "input_tokens": 1240, "output_tokens": 387, "cost_usd": 0.0021 }

// error
{ "type": "error", "error": { "type": "rate_limit_error", "message": "Rate limit exceeded" } }

// swe_phase
{ "type": "swe_phase", "phase": "locate", "description": "Identifying relevant files..." }

// rag_sources
{ "type": "rag_sources", "sources": [{ "path": "src/auth.py", "score": 0.94 }] }

// ask_user
{ "type": "ask_user", "question": "Which environment should I target — staging or production?" }

Conversation Flow

Client                              Server
  │                                   │
  │── connect ──────────────────────► │
  │── { user_text: "Fix auth bug" } ► │
  │                                   │
  │ ◄── content_block_start ──────── │
  │ ◄── content_block_delta (chunk) ─ │  (repeats)
  │ ◄── content_block_stop ────────── │
  │ ◄── tool_use (read_file) ──────── │
  │                                   │
  │── { tool_results: [...] } ──────► │
  │                                   │
  │ ◄── content_block_start ──────── │
  │ ◄── content_block_delta ────────  │  (repeats)
  │ ◄── content_block_stop ────────── │
  │ ◄── message_stop ──────────────── │
  │ ◄── usage ─────────────────────── │

Error Handling

The server never closes the WebSocket on recoverable errors — it sends an error event instead, allowing the client to retry or surface the message to the user.

| Error Type | Meaning | |------------|---------| | rate_limit_error | Request rate exceeded; back off and retry | | model_error | Upstream model returned an error; may retry with fallback model | | context_length_error | Input exceeded the model's context window | | auth_error | Invalid or expired API key — connection will close |