WebSocket Events

Real-time events over Socket.IO on the /v1 namespace.

Connection Configuration

Property	Value
Transport	WebSocket (Socket.IO protocol)
Namespace	/v1
URL	{baseUrl}/v1
Auth	Same Firebase JWT headers as REST
Query params	workspaceId=<id>
Auto-reconnect	Enabled

Client-to-Server Events

workspace.subscribe

Subscribe to real-time events for one or more workspaces.

{ "workspace_ids": ["string"] }

workspace.unsubscribe

Unsubscribe from workspace events.

{ "workspace_ids": ["string"] }

message.send

Send a message via WebSocket (alternative to the REST POST .../messages endpoint).

{
  "workspace_id": "string",
  "conversation_id": "string",
  "local_id": "string",
  "content": { "type": "text", "text": "string" },
  "mentions": [
    { "agent_id": "string", "agent_name": "string", "offset": 0, "length": 0 }
  ],
  "attachments": []
}

The server responds with message.send.ack on success or message.send.error on failure.

Server-to-Client Events

message.new

New message in any conversation within the connected workspace.

{
  "message": {
    "id": "string",
    "conversation_id": "string",
    "role": "user | agent | system",
    "content": "MessageContent",
    "status": "pending | sent | delivered | read | failed",
    "created_at": "ISO8601",
    "updated_at": "ISO8601",
    "local_id": "string | null",
    "agent": "AgentData | null",
    "attachments": ["AttachmentData"],
    "mentions": ["MentionData"]
  }
}

message.updated

Message modified (e.g., action card resolved, status changed). Same payload shape as message.new.

message.chunk

Streamed text token during agent response generation. Emitted for each partial text delta.

{
  "message_id": "string",
  "conversation_id": "string",
  "agent_id": "string",
  "chunk": "string"
}

message.done

Signals that streaming is complete for a message.

{
  "message_id": "string",
  "conversation_id": "string",
  "agent_id": "string",
  "status": "delivered | failed"
}

message.status

Delivery status transition for a message (e.g., pending to delivered, delivered to read).

{
  "message_id": "string",
  "conversation_id": "string",
  "local_id": "string | null",
  "status": "sent | delivered | read"
}

agent.status

Agent status changed. conversation_id is set when the status is tied to a specific conversation (e.g., thinking, writing). Omitted for workspace-wide statuses like online.

{
  "agent_id": "string",
  "status": "online | reading | thinking | writing | pending | error | offline",
  "conversation_id": "string | omitted"
}

agent.tool

Agent tool call activity during streaming.

{
  "agent_id": "string",
  "conversation_id": "string",
  "tool": "string",
  "status": "running | done",
  "query": "string | omitted",
  "args": "object | omitted",
  "created_at": "ISO8601 | omitted"
}

agent.delegation

Agent-to-agent delegation activity. Emitted when one agent hands off work to another.

{
  "from": {
    "id": "string",
    "name": "string",
    "role": "string",
    "slug": "string",
    "avatar": "string",
    "status": "string"
  },
  "to": {
    "id": "string",
    "name": "string",
    "role": "string",
    "slug": "string",
    "avatar": "string",
    "status": "string"
  },
  "conversation_id": "string",
  "status": "running | completed | failed",
  "message_preview": "string | omitted",
  "message_id": "string | omitted",
  "created_at": "ISO8601 | omitted"
}

artifact.updated

Artifact creation, update, or review activity.

{
  "artifact_id": "string",
  "conversation_id": "string | omitted",
  "title": "string",
  "version": 0,
  "action": "created | updated | reviewed",
  "agent_id": "string",
  "agent_slug": "string"
}

usage.update

Per-LLM-call token usage update. Emitted inline during streaming so the mobile app can show real-time token counters.

{
  "agent_id": "string",
  "conversation_id": "string",
  "message_id": "string",
  "model": "string",
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "total_tokens": 0,
  "call_sequence": 0
}

Workflow Events

Workflow execution progress events. All share the same payload shape.

Event names: workflow.started, workflow.step.started, workflow.step.completed, workflow.step.approval_required, workflow.completed, workflow.failed

{
  "workflow_id": "string",
  "execution_id": "string",
  "workflow_name": "string",
  "conversation_id": "string | omitted",
  "status": "string",
  "step_index": 0,
  "step_name": "string | omitted",
  "agent_slug": "string | omitted",
  "error": "string | omitted"
}

message.send.ack

Acknowledgment after a message.send is persisted.

{
  "local_id": "string",
  "message_id": "string",
  "conversation_id": "string",
  "status": "sent"
}

message.send.error

Error response when a message.send fails.

{
  "local_id": "string",
  "conversation_id": "string",
  "error": "string"
}

workspace.subscribed

Acknowledgment after a workspace.subscribe succeeds.

{ "workspace_ids": ["string"] }

Event Summary

Event	Direction	Description
workspace.subscribe	Client to Server	Subscribe to workspace events
workspace.unsubscribe	Client to Server	Unsubscribe from workspace events
message.send	Client to Server	Send message via WebSocket
message.new	Server to Client	New message created
message.updated	Server to Client	Message modified
message.chunk	Server to Client	Streamed text token
message.done	Server to Client	Stream complete
message.status	Server to Client	Delivery status change
message.send.ack	Server to Client	Message send acknowledged
message.send.error	Server to Client	Message send failed
agent.status	Server to Client	Agent status change
agent.tool	Server to Client	Tool call activity
agent.delegation	Server to Client	Agent-to-agent delegation
artifact.updated	Server to Client	Artifact created/updated
usage.update	Server to Client	Token usage update
workspace.subscribed	Server to Client	Subscription confirmed
workflow.*	Server to Client	Workflow progress events