Visual

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`GET`
`GET`
`GET`
`POST`
`POST`
`GET`
`GET`
`GET`
`GET`
`GET`
`GET`
`POST`
`GET`
`POST`
`POST`
`POST`

Also available via the PostHog MCP server:
visual-review-repos-list — List visual review repos

List all projects for the team.

Required API key scopes

visual_review:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/visual_review/repos
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "team_id": 0,
      "repo_external_id": 0,
      "repo_full_name": "string",
      "baseline_file_paths": {
        "property1": "string",
        "property2": "string"
      },
      "enable_pr_comments": true,
      "debt_digest_enabled": true,
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create visual review repos

Create a new repo.

Required API key scopes

visual_review:write

Request parameters

repo_full_name
string
repo_external_id
integer | null

Response

Example request

POST /api/projects/:project_id/visual_review/repos
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/\
	-d repo_full_name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"repo_full_name": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "repo_external_id": 0,
  "repo_full_name": "string",
  "baseline_file_paths": {
    "property1": "string",
    "property2": "string"
  },
  "enable_pr_comments": true,
  "debt_digest_enabled": true,
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve visual review repos

Also available via the PostHog MCP server:
visual-review-repos-retrieve — Get visual review repo

Get a repo by ID.

Required API key scopes

visual_review:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/visual_review/repos/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "repo_external_id": 0,
  "repo_full_name": "string",
  "baseline_file_paths": {
    "property1": "string",
    "property2": "string"
  },
  "enable_pr_comments": true,
  "debt_digest_enabled": true,
  "created_at": "2019-08-24T14:15:22Z"
}

Update visual review repos

Update a repo's settings.

Required API key scopes

visual_review:write

Path parameters

id
string

Request parameters

baseline_file_paths
object | null
enable_pr_comments
boolean | null
debt_digest_enabled
boolean | null

Response

Example request

PATCH /api/projects/:project_id/visual_review/repos/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/\
	-d baseline_file_paths="object"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"baseline_file_paths": "object"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "repo_external_id": 0,
  "repo_full_name": "string",
  "baseline_file_paths": {
    "property1": "string",
    "property2": "string"
  },
  "enable_pr_comments": true,
  "debt_digest_enabled": true,
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve visual review repos baselines

Snapshots overview for a repo: every identifier with a current baseline (latest non-superseded master/main run per run_type), plus tolerate counts, active quarantine state, and a 30-day stability sparkline. Capped at 7500 entries — sets truncated and returns the most recently active when exceeded. Filtering / faceting / search are all done client-side; this endpoint takes no filter query params.

Required API key scopes

visual_review:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/visual_review/repos/:id/baselines
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/baselines/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/baselines/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "entries": [
    {
      "quarantine": {
        "created_by": {
          "id": 0,
          "first_name": "string",
          "email": "string"
        },
        "source_run": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "branch": "string",
          "commit_sha": "string",
          "created_at": "2019-08-24T14:15:22Z",
          "pr_number": 0
        },
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "reason": "string",
        "source": "string",
        "expires_at": "2019-08-24T14:15:22Z",
        "created_at": "2019-08-24T14:15:22Z"
      },
      "active_variants_current_baseline": 0,
      "identifier": "string",
      "run_type": "string",
      "browser": "string",
      "thumbnail_hash": "string",
      "width": 0,
      "height": 0,
      "tolerate_count_30d": 0,
      "tolerate_count_90d": 0,
      "is_quarantined": true,
      "last_run_at": "2019-08-24T14:15:22Z",
      "baseline_change_count": 0,
      "recent_drift_avg": 0
    }
  ],
  "totals": {
    "by_run_type": {
      "property1": 0,
      "property2": 0
    },
    "variant_pileups": 0,
    "all_snapshots": 0,
    "recently_tolerated": 0,
    "frequently_tolerated": 0,
    "currently_quarantined": 0
  },
  "truncated": true,
  "generated_at": "2019-08-24T14:15:22Z"
}

Retrieve visual review repos flakiness

Snapshots in a repo whose rendering cannot be trusted: those that failed the gate on a recent default-branch run, those whose absorbed diff is close to the threshold, and those under an active quarantine. Small absorbed diffs well under the threshold are omitted, as is everything else, so this is far smaller than the baselines universe; totals.tracked gives the full denominator. Each entry carries the share of the last 7 days of default-branch runs that failed the gate (hard_rate) and the share a toleration absorbed (soft_rate), plus headroom, the fraction of the diff threshold its worst absorbed run leaves free. Capped at 2000 entries, which sets truncated. Filtering, faceting and search are done client-side; this endpoint takes no filter query params.

Required API key scopes

visual_review:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/visual_review/repos/:id/flakiness
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/flakiness/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/flakiness/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "entries": [
    {
      "variant_count": 0,
      "hard_count": 0,
      "soft_count": 0,
      "window_runs": 0,
      "hard_rate": 0.1,
      "soft_rate": 0.1,
      "last_flaked_at": "2019-08-24T14:15:22Z",
      "avg_diff_percentage": 0,
      "worst_soft_diff_percentage": 0,
      "headroom": 0,
      "baseline_age_days": 0,
      "daily_hard_counts": [
        0
      ],
      "daily_soft_counts": [
        0
      ],
      "baseline_moved_day_index": 0,
      "flakiness_state": "broken",
      "needs_decision": true,
      "quarantine": {
        "created_by": {
          "id": 0,
          "first_name": "string",
          "email": "string"
        },
        "source_run": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "branch": "string",
          "commit_sha": "string",
          "created_at": "2019-08-24T14:15:22Z",
          "pr_number": 0
        },
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "reason": "string",
        "source": "string",
        "expires_at": "2019-08-24T14:15:22Z",
        "created_at": "2019-08-24T14:15:22Z"
      },
      "owner_team": "string",
      "identifier": "string",
      "run_type": "string",
      "browser": "string",
      "thumbnail_hash": "string",
      "width": 0,
      "height": 0,
      "is_quarantined": true
    }
  ],
  "totals": {
    "listed": 0,
    "tracked": 0,
    "broken": 0,
    "unstable": 0,
    "at_risk": 0,
    "clean": 0,
    "by_run_type": {
      "property1": 0,
      "property2": 0
    },
    "quarantined": 0,
    "needs_decision": 0
  },
  "truncated": true,
  "generated_at": "2019-08-24T14:15:22Z"
}

List all visual review repos quarantine

List quarantined identifiers. Without filter: active only. With identifier: full history.

Required API key scopes

visual_review:read

Path parameters

id
string

Query parameters

identifier
string
limit
integer
offset
integer
run_type
string

Response

Example request

GET /api/projects/:project_id/visual_review/repos/:id/quarantine
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/quarantine/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/quarantine/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "created_by": {
        "id": 0,
        "first_name": "string",
        "email": "string"
      },
      "source_run": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "branch": "string",
        "commit_sha": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "pr_number": 0
      },
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "identifier": "string",
      "run_type": "string",
      "reason": "string",
      "source": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create visual review repos quarantine

Quarantine a snapshot identifier for a specific run type.

Required API key scopes

visual_review:write

Path parameters

id
string
run_type
string

Request parameters

identifier
string
reason
string
expires_at
string | null
source_run_id
string | null
notify_owners
boolean
Default: false

Response

Example request

POST /api/projects/:project_id/visual_review/repos/:id/quarantine/:run_type
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/quarantine/:run_type/\
	-d identifier="string",\
	-d reason="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/quarantine/{run_type}/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>",
		run_type="<the run type>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"identifier": "string",
		"reason": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "source_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "branch": "string",
    "commit_sha": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "pr_number": 0
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "identifier": "string",
  "run_type": "string",
  "reason": "string",
  "source": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create visual review repos quarantine expire

Expire all active quarantine entries for an identifier.

Required API key scopes

visual_review:write

Path parameters

id
string
run_type
string

Request parameters

identifier
string

Example request

POST /api/projects/:project_id/visual_review/repos/:id/quarantine/:run_type/expire
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/quarantine/:run_type/expire/\
	-d identifier="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/quarantine/{run_type}/expire/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>",
		run_type="<the run type>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"identifier": "string"
	}
).json()

Example response

Status 204 No response body

Status 400 No GitHub integration.

RESPONSE
{
  "detail": "string",
  "code": "string"
}

Status 429 GitHub rate limit. See Retry-After.

RESPONSE
{
  "detail": "string",
  "code": "string"
}

Status 503 GitHub cannot name the default branch head. The quarantine stays.

RESPONSE
{
  "detail": "string",
  "code": "string"
}

Retrieve visual review repos thumbnails

Serve a snapshot thumbnail by identifier. Returns WebP with ETag caching.

Required API key scopes

visual_review:read

Path parameters

id
string
identifier
string

Query parameters

run_type
string

Example request

GET /api/projects/:project_id/visual_review/repos/:id/thumbnails/:identifier
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/thumbnails/:identifier/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/thumbnails/{identifier}/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>",
		identifier="<the identifier>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 WebP thumbnail image

Retrieve visual review repos toleration pileups

Snapshots that keep getting tolerated, counted across baselines, most manual tolerations first. A toleration accepts one exact rendering, so a snapshot that keeps needing them renders differently from run to run, and the fix belongs in the story. With no parameters this is the weekly debt digest's rule (3 or more tolerations by a person or agent in 30 days), except that quarantined snapshots are kept and marked with is_quarantined. The list is small and returns fast; start here to find flaky stories worth fixing, then read one snapshot's history with the per-snapshot tools.

Required API key scopes

visual_review:read

Path parameters

id
string

Query parameters

include_quarantined
boolean
Default: true
limit
integer
Default: 100
min_automatic_tolerations
integer
min_tolerations
integer
Default: 3
run_type
string
window_days
integer
Default: 30

Response

Example request

GET /api/projects/:project_id/visual_review/repos/:id/toleration-pileups
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:id/toleration-pileups/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{visual_review_id}/toleration-pileups/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "entries": [
    {
      "identifier": "string",
      "run_type": "string",
      "intentional_count": 0,
      "automatic_count": 0,
      "is_quarantined": true
    }
  ],
  "window_days": 0,
  "min_tolerations": 0,
  "min_automatic_tolerations": 0,
  "total": 0,
  "truncated": true,
  "generated_at": "2019-08-24T14:15:22Z"
}

List all visual review repos runs

List runs in this repo, optionally filtered by review state and free-text search.

Required API key scopes

visual_review:read

Path parameters

repo_id
string

Query parameters

limit
integer
offset
integer
review_state
string
One of: "clean""needs_review""processing""stale"
search
string

Response

Example request

GET /api/projects/:project_id/visual_review/repos/:repo_id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:repo_id/runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{repo_id}/runs/".format(
        project_id=project_id,
		repo_id="<the repo id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "approved_by": {
        "id": 0,
        "first_name": "string",
        "email": "string"
      },
      "purpose": "review",
      "search_match_type": "exact",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "repo_id": "59e69ce7-60be-4408-9333-ec12132fc070",
      "status": "string",
      "run_type": "string",
      "commit_sha": "string",
      "branch": "string",
      "pr_number": 0,
      "approved": true,
      "approved_at": "2019-08-24T14:15:22Z",
      "summary": {
        "total": 0,
        "changed": 0,
        "new": 0,
        "removed": 0,
        "unchanged": 0,
        "unresolved": 0,
        "tolerated_matched": 0
      },
      "error_message": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "is_stale": true,
      "superseded_by_id": "6b86439a-ba84-4137-9924-cffddd52399a",
      "metadata": {}
    }
  ]
}

Retrieve visual review repos runs counts

Review state counts for runs in this repo.

Required API key scopes

visual_review:read

Path parameters

repo_id
string

Response

Example request

GET /api/projects/:project_id/visual_review/repos/:repo_id/runs/counts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:repo_id/runs/counts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{repo_id}/runs/counts/".format(
        project_id=project_id,
		repo_id="<the repo id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "needs_review": 0,
  "clean": 0,
  "processing": 0,
  "stale": 0
}

List all visual review repos snapshots

Deduped baseline timeline for a snapshot identity. Newest first.

Required API key scopes

visual_review:read

Path parameters

identifier
string
repo_id
string
run_type
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/visual_review/repos/:repo_id/snapshots/:run_type/:identifier
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/repos/:repo_id/snapshots/:run_type/:identifier/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/repos/{repo_id}/snapshots/{run_type}/{identifier}/".format(
        project_id=project_id,
		identifier="<the identifier>",,
		repo_id="<the repo id>",,
		run_type="<the run type>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "current_artifact": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "content_hash": "string",
        "width": 0,
        "height": 0,
        "download_url": "string"
      },
      "row_shift": {
        "bands": [
          {
            "y": 0,
            "rows": 0,
            "kind": "inserted"
          }
        ],
        "inserted_rows": 0,
        "deleted_rows": 0,
        "residual_percentage": 0.1,
        "raw_diff_percentage": 0.1
      },
      "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
      "snapshot_id": "163831af-8c1b-4992-a9cf-88c6306604c0",
      "result": "string",
      "branch": "string",
      "commit_sha": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "pr_number": 0,
      "diff_percentage": 0,
      "review_state": "string",
      "ssim_score": 0,
      "change_kind": "string",
      "size_mismatch": true
    }
  ]
}

List all visual review runs

Also available via the PostHog MCP server:
visual-review-runs-list — List visual review runs

List runs for the team, optionally filtered by review state, PR number, commit SHA, branch, or free-text search.

Required API key scopes

visual_review:read

Query parameters

branch
string
commit_sha
string
limit
integer
offset
integer
pr_number
integer
review_state
string
One of: "clean""needs_review""processing""stale"
search
string

Response

Example request

GET /api/projects/:project_id/visual_review/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/runs/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "approved_by": {
        "id": 0,
        "first_name": "string",
        "email": "string"
      },
      "purpose": "review",
      "search_match_type": "exact",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "repo_id": "59e69ce7-60be-4408-9333-ec12132fc070",
      "status": "string",
      "run_type": "string",
      "commit_sha": "string",
      "branch": "string",
      "pr_number": 0,
      "approved": true,
      "approved_at": "2019-08-24T14:15:22Z",
      "summary": {
        "total": 0,
        "changed": 0,
        "new": 0,
        "removed": 0,
        "unchanged": 0,
        "unresolved": 0,
        "tolerated_matched": 0
      },
      "error_message": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "is_stale": true,
      "superseded_by_id": "6b86439a-ba84-4137-9924-cffddd52399a",
      "metadata": {}
    }
  ]
}

Create visual review runs

Create a new run from a CI manifest.

Required API key scopes

visual_review:write

Request parameters

repo_id
string
run_type
string
commit_sha
string
branch
string
snapshots
array
pr_number
integer | null
baseline_hashes
object
unchanged_count
integer
removed_identifiers
array
purpose
string
metadata
object
is_partial
boolean

Response

Example request

POST /api/projects/:project_id/visual_review/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/runs/\
	-d repo_id="string",\
	-d run_type="string",\
	-d commit_sha="string",\
	-d branch="string",\
	-d snapshots="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/visual_review/runs/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"repo_id": "string",
		"run_type": "string",
		"commit_sha": "string",
		"branch": "string",
		"snapshots": "array"
	}
).json()

Example response

Status 201

RESPONSE
{
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "uploads": [
    {
      "content_hash": "string",
      "url": "string",
      "fields": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

Retrieve visual review runs

Also available via the PostHog MCP server:
visual-review-runs-retrieve — Get visual review run

Get run status and summary.

Required API key scopes

visual_review:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/visual_review/runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/runs/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/visual_review/runs/{visual_review_id}/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "approved_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "purpose": "review",
  "search_match_type": "exact",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "repo_id": "59e69ce7-60be-4408-9333-ec12132fc070",
  "status": "string",
  "run_type": "string",
  "commit_sha": "string",
  "branch": "string",
  "pr_number": 0,
  "approved": true,
  "approved_at": "2019-08-24T14:15:22Z",
  "summary": {
    "total": 0,
    "changed": 0,
    "new": 0,
    "removed": 0,
    "unchanged": 0,
    "unresolved": 0,
    "tolerated_matched": 0
  },
  "error_message": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "is_stale": true,
  "superseded_by_id": "6b86439a-ba84-4137-9924-cffddd52399a",
  "metadata": {}
}

Create visual review runs add snapshots

Add a batch of snapshots to a pending run (shard-based flow).

Required API key scopes

visual_review:write

Path parameters

id
string

Request parameters

snapshots
array
baseline_hashes
object
story_index_hash
string

Response

Example request

POST /api/projects/:project_id/visual_review/runs/:id/add-snapshots
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/runs/:id/add-snapshots/\
	-d snapshots="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/visual_review/runs/{visual_review_id}/add-snapshots/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"snapshots": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "story_index_upload": {
    "content_hash": "string",
    "url": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    }
  },
  "added": 0,
  "uploads": [
    {
      "content_hash": "string",
      "url": "string",
      "fields": {
        "property1": "string",
        "property2": "string"
      }
    }
  ]
}

Create visual review runs approve

Mark snapshots reviewed (DB only).

Records the per-snapshot "Accept change" decision. Does not commit the baseline or change the GitHub gate — call finalize to ship the run. Works on a quarantined snapshot too: a quarantined snapshot approved here is committed by finalize, which updates a quarantined story's baseline entry without lifting the quarantine.

Required API key scopes

visual_review:write

Path parameters

id
string

Request parameters

snapshots
array

Response

Example request

POST /api/projects/:project_id/visual_review/runs/:id/approve
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/runs/:id/approve/\
	-d snapshots="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/visual_review/runs/{visual_review_id}/approve/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"snapshots": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "approved_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "purpose": "review",
  "search_match_type": "exact",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "repo_id": "59e69ce7-60be-4408-9333-ec12132fc070",
  "status": "string",
  "run_type": "string",
  "commit_sha": "string",
  "branch": "string",
  "pr_number": 0,
  "approved": true,
  "approved_at": "2019-08-24T14:15:22Z",
  "summary": {
    "total": 0,
    "changed": 0,
    "new": 0,
    "removed": 0,
    "unchanged": 0,
    "unresolved": 0,
    "tolerated_matched": 0
  },
  "error_message": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "is_stale": true,
  "superseded_by_id": "6b86439a-ba84-4137-9924-cffddd52399a",
  "metadata": {}
}

Create visual review runs complete

Complete a run: detect removals, verify uploads, trigger diff processing.

Required API key scopes

visual_review:write

Path parameters

id
string

Request parameters

check_run_id
string

Response

Example request

POST /api/projects/:project_id/visual_review/runs/:id/complete
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/visual_review/runs/:id/complete/\
	-d check_run_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/visual_review/runs/{visual_review_id}/complete/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"check_run_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "approved_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "purpose": "review",
  "search_match_type": "exact",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "repo_id": "59e69ce7-60be-4408-9333-ec12132fc070",
  "status": "string",
  "run_type": "string",
  "commit_sha": "string",
  "branch": "string",
  "pr_number": 0,
  "approved": true,
  "approved_at": "2019-08-24T14:15:22Z",
  "summary": {
    "total": 0,
    "changed": 0,
    "new": 0,
    "removed": 0,
    "unchanged": 0,
    "unresolved": 0,
    "tolerated_matched": 0
  },
  "error_message": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "is_stale": true,
  "superseded_by_id": "6b86439a-ba84-4137-9924-cffddd52399a",
  "metadata": {}
}