API Reference

Hosted review ingestion endpoint for flow capture payloads.

Endpoint

POST /api/v1/analyze

Authentication

Send a bearer token generated in Dashboard → Settings → API Tokens.

Authorization: Bearer occ_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request body (snake_case)

{
  "repository_id": "uuid-optional",
  "repository_name": "owner/repo-optional",
  "pr_number": 123,
  "pr_title": "Improve checkout UX",
  "commit_sha": "abc123def456",
  "flows": [
    {
      "flow_id": "flow_checkout",
      "name": "Checkout flow",
      "steps": [
        {
          "index": 0,
          "action": "navigate",
          "url": "https://staging.example.com/checkout",
          "screenshot_base64": "iVBORw0KGgo...",
          "dom_snapshot": "<html>...</html>",
          "duration_ms": 1840
        }
      ],
      "axe_violations": []
    }
  ]
}

Provide either repository_id or repository_name. Repository lookup is scoped to the token owner.

Successful response

{
  "run_id": "uuid",
  "status": "completed",
  "summary": {
    "total_issues": 7,
    "by_severity": { "high": 2, "medium": 3, "low": 2 },
    "by_category": { "accessibility": 4, "nielsen": 2, "friction": 1 }
  },
  "comment_posted": true,
  "comment_url": "https://github.com/owner/repo/pull/123#issuecomment-..."
}

Plan gating and limits

Hosted PR reviews: free plan has 0, Pro has 300/month, Enterprise is unlimited.

Analysis layers: accessibility always runs; Nielsen + friction run only when enabled by plan features.

Error responses

Status	When
401	Missing bearer auth or invalid/revoked token
404	Repository not found for token owner
429	Hosted review limit reached or plan disallows hosted reviews
500	Run creation/analysis/storage failure