WebSocket Reference

Endpoint

/api/ws

Description: Real-time endpoint for project sync and generation updates. One connection receives every update visible to the authenticated user. There is no subscribe or filter command.

// Same-origin browser session
const ws = new WebSocket('wss://docs.example.com/api/ws')

// Direct token auth
const wsWithToken = new WebSocket('wss://docs.example.com/api/ws?token=<API_KEY>')

Return value/effect:

• Successful connections are accepted and immediately receive a sync message.
• Admins receive updates for all variants.
• Other authenticated users receive updates for owned variants plus variants shared with them.
• Access grants and revocations trigger a new sync for the affected user.

Note: /api/ws authenticates with the token query parameter or the docsfy_session cookie. It does not read Authorization headers.

Note: See Manage Users, Roles, and Access for access assignment and role details.

Warning: ?token= places credentials in the URL.

Message Reference

sync

Description: Full replacement snapshot for the authenticated user's visible project list and lookup maps.

sync.projects[] object

{
  "type": "sync",
  "projects": [
    {
      "name": "docsfy",
      "branch": "main",
      "ai_provider": "cursor",
      "ai_model": "gpt-5.4-xhigh-fast",
      "owner": "alice",
      "repo_url": "https://github.com/myk-org/docsfy",
      "status": "ready",
      "current_stage": null,
      "last_commit_sha": "abc123def456",
      "last_generated": "2026-04-17 12:34:56",
      "page_count": 14,
      "error_message": null,
      "plan_json": "{\"project_name\":\"docsfy\",\"navigation\":[...]}",
      "created_at": "2026-04-17 12:10:00",
      "updated_at": "2026-04-17 12:34:56"
    }
  ],
  "known_models": {
    "cursor": ["gpt-5.4-xhigh-fast"]
  },
  "known_branches": {
    "docsfy": ["main"]
  }
}

Return value/effect:

• Sent immediately after a successful connection.
• Sent again after server-side resync events, including terminal status updates, deletes, variant replacement, and access changes.
• Replace local state with the new payload instead of patching individual fields.

Warning: sync.projects[] uses ai_provider and ai_model. progress and status_change use provider and model.

progress

Description: Variant-scoped in-flight update while generation is still running.

current_stage values

{
  "type": "progress",
  "name": "docsfy",
  "branch": "main",
  "provider": "cursor",
  "model": "gpt-5.4-xhigh-fast",
  "owner": "alice",
  "status": "generating",
  "current_stage": "generating_pages",
  "page_count": 3,
  "plan_json": "{\"project_name\":\"docsfy\",\"navigation\":[...]}"
}

Return value/effect:

• Apply this message to the variant identified by name, branch, provider, model, and owner.
• During generating_pages, page_count increments as pages are generated.
• During later stages, page_count carries the generated page total.
• plan_json is a JSON string, not a parsed object.

Tip: Match progress messages by name, branch, provider, model, and owner.

status_change

Description: Variant-scoped terminal update.

status values

{
  "type": "status_change",
  "name": "docsfy",
  "branch": "main",
  "provider": "cursor",
  "model": "gpt-5.4-xhigh-fast",
  "owner": "alice",
  "status": "ready",
  "page_count": 14,
  "last_generated": "2026-04-17 12:34:56",
  "last_commit_sha": "abc123def456"
}

Return value/effect:

• Emitted only for ready, error, and aborted.
• Every status_change is followed by a fresh sync.
• When a variant is reused without regeneration, the terminal message still uses status: "ready". The following sync.projects[] record may show current_stage: "up_to_date".

Heartbeat

ping

Description: Server heartbeat probe.

{
  "type": "ping"
}

Return value/effect:

• Sent every 30 seconds.
• The server waits 10 seconds for the matching pong.

pong

Description: Client heartbeat reply.

{
  "type": "pong"
}

Return value/effect:

• Resets the missed-heartbeat counter for the current connection.
• After 2 missed pong replies, the server closes the socket with code 1001.
• Client messages other than valid JSON {"type":"pong"} are ignored.

Related Pages

• Track Generation Progress
• HTTP API Reference
• Manage Users, Roles, and Access
• Fix Setup and Generation Problems
• Manage docsfy from the CLI