WebSocket Progress

Overview

Instead of polling the GET /api/audit/{audit_id} endpoint, you can open a WebSocket connection to receive real-time progress updates as an audit moves through its stages. This is the recommended approach for UIs and interactive tools that need immediate feedback.

Connection URL

Connect to the following WebSocket endpoint immediately after submitting an audit:

wss://audit-engine.oathe.ai/ws/audit/{audit_id}

Replace {audit_id} with the ID returned by POST /api/submit. The connection stays open until the audit completes or fails.

Message Types

All messages are JSON objects with a type field indicating the kind of update.

Status Update

Sent when the audit transitions between stages.

{
  "type": "status",
  "status": "analyzing",
  "stage_label": "Analyzing skill behavior."
}

The stage_label field is a human-readable description of the current stage. The status field matches the values returned by the REST status endpoint: queued, scanning, analyzing, summarizing, finalizing, complete, failed.

Queue Position

Sent while the audit is waiting in the queue.

{
  "type": "status",
  "status": "queued",
  "queue_position": 3
}

The queue_position value decreases as earlier audits finish. When it reaches 0, the audit begins processing.

Completion

Sent once when the audit finishes successfully. Includes the full report.

{
  "type": "complete",
  "status": "complete",
  "report": {
    "audit_id": "abc123",
    "trust_score": 72,
    "verdict": "CAUTION",
    "recommendation": "INSTALL_WITH_CAUTION",
    "category_scores": { ... },
    "findings": [...]
  },
  "skill_url": "https://github.com/user/repo"
}

The WebSocket connection closes automatically after this message.

Failure

Sent if the audit encounters an unrecoverable error.

{
  "type": "failed",
  "status": "failed",
  "error_message": "Repository not found or inaccessible."
}

The connection closes after this message.

When to Use WebSocket vs Polling

Scenario	Recommended
Browser UI showing live progress	WebSocket
CI/CD pipeline waiting for a result	Polling
MCP server integration	Polling
Dashboard with multiple concurrent audits	WebSocket

Polling is simpler and sufficient for automated pipelines where latency of a few seconds is acceptable. WebSocket is better when you need sub-second updates or want to display stage-by-stage progress to a user.

Connection Handling

• If the audit_id does not exist, the server closes the connection immediately with a 4004 close code.
• If the connection drops, you can reconnect at any time. The server will send the current state as the first message.
• No authentication is required. The audit_id itself acts as an access token for that audit’s progress stream.