Real-time streaming chat endpoint that powers the Misar Code agent loop — send messages, receive streamed content blocks, and handle tool invocations.

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

Pass as a subprotocol header on the WebSocket upgrade request.

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 ─────────────────────── │

The connection stays open after message_stop. Send another client message to continue the conversation in the same session.

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

On auth_error the server closes the WebSocket with code 4001. Reconnect with a valid API key.

WebSocket Chat API