Event Streaming & Daemon API

Daemon API

The daemon exposes a REST API on the configured server_addr. With the default value of 127.0.0.1:7373, the API is reachable at http://127.0.0.1:7373. An OpenAPI 3.1.0 spec is available at /openapi.json for client generation and integration tooling.

# Fetch the OpenAPI spec (TCP, default address)
curl http://127.0.0.1:7373/openapi.json

# With Unix domain socket (path depends on your configuration; see Configuration > Unix Domain Socket)
curl --unix-socket "$XDG_RUNTIME_DIR/roborev/daemon.sock" http://localhost/openapi.json

Endpoints

Endpoint	Method	Description
`/api/jobs`	GET	List review jobs (supports cursor-based pagination via `before` parameter)
`/api/review`	GET	Get review by job ID or SHA
`/api/comments`	GET	List comments for a job or commit
`/api/repos`	GET	List repos with job counts
`/api/branches`	GET	List branches with job counts
`/api/status`	GET	Get daemon status
`/api/summary`	GET	Get review summary statistics
`/api/job/cancel`	POST	Cancel a queued or running job
`/api/job/rerun`	POST	Re-enqueue a completed or failed job
`/api/review/close`	POST	Close or reopen a review
`/api/comment`	POST	Add a comment to a job or commit

These endpoints have typed request/response schemas in the OpenAPI spec. The daemon also exposes additional endpoints used by the CLI, TUI, and subsystems (enqueue, job output streaming, sync, fix orchestration, health checks) that are not part of the OpenAPI surface.

Event Stream

Stream review events in real-time for integrations, notifications, or custom tooling:

roborev stream              # Stream all events
roborev stream --repo .     # Stream events for current repo only

Event Format

Events are emitted as newline-delimited JSON (JSONL):

{"type":"review.started","ts":"2025-01-11T10:00:00Z","job_id":42,"repo":"/path/to/repo","repo_name":"myrepo","sha":"abc123","agent":"codex"}
{"type":"review.completed","ts":"2025-01-11T10:01:30Z","job_id":42,"repo":"/path/to/repo","repo_name":"myrepo","sha":"abc123","agent":"codex","verdict":"P"}

Event Types

Type	Description
`review.started`	Review job started processing
`review.completed`	Review finished successfully
`review.failed`	Review failed (includes `error` field)
`review.canceled`	Review was canceled

Event Fields

All events include:

type: Event type
ts: ISO 8601 timestamp
job_id: Unique job identifier
repo: Repository path
repo_name: Repository display name
sha: Commit SHA (or dirty for uncommitted changes)
agent: Agent that processed the review

Additional fields:

verdict: Pass/Fail verdict (on review.completed)
error: Error message (on review.failed)

Filtering with jq

Use jq to filter events:

# Only completed reviews
roborev stream | jq -c 'select(.type == "review.completed")'

# Only failures
roborev stream | jq -c 'select(.type == "review.failed")'

# Specific repo
roborev stream | jq -c 'select(.repo_name == "myproject")'

# Failed verdicts
roborev stream | jq -c 'select(.verdict == "F")'

Integration Examples

Desktop Notifications (macOS)

roborev stream | while read -r event; do
  type=$(echo "$event" | jq -r '.type')
  repo=$(echo "$event" | jq -r '.repo_name')
  if [ "$type" = "review.completed" ]; then
    verdict=$(echo "$event" | jq -r '.verdict')
    if [ "$verdict" = "F" ]; then
      osascript -e "display notification \"Review failed\" with title \"$repo\""
    fi
  fi
done

Webhook

roborev stream | while read -r event; do
  curl -X POST -H "Content-Type: application/json" \
    -d "$event" https://your-webhook.example.com/reviews
done