Visual API Reference

Visual

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`GET`
`GET`
`POST`
`POST`
`GET`
`GET`
`GET`
`GET`
`GET`
`POST`
`GET`
`POST`
`POST`
`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,
      "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
integernull

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,
  "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,
  "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
objectnull
enable_pr_comments
booleannull

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","null"]
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",
			"null"
		]
	}
).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,
  "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 5000 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",
        "expires_at": "2019-08-24T14:15:22Z",
        "created_at": "2019-08-24T14:15:22Z"
      },
      "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
    },
    "all_snapshots": 0,
    "recently_tolerated": 0,
    "frequently_tolerated": 0,
    "currently_quarantined": 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",
      "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
source_run_id
stringnull
expires_at
stringnull

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",
  "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
reason
string
source_run_id
stringnull
expires_at
stringnull

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",\
	-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}/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",
		"reason": "string"
	}
).json()

Example response

Status 204 No response body

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

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

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
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"
      },
      "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"
      },
      "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
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"
      },
      "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
integernull
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"
  },
  "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

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
{
  "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.

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"
  },
  "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

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/
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)},
).json()

Example response

Status 200

RESPONSE
{
  "approved_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "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 finalize

Finalize a fully-reviewed run: commit the approved baseline and green the gate.

Commits exactly the snapshots approved in the DB (tolerated ones keep their baseline) and only succeeds once every changed/new snapshot is resolved. With approve_all=true, any still-pending changed/new snapshot is approved first. With commit_to_github=false the server returns the signed baseline YAML instead of committing it.

Required API key scopes

visual_review:write

Path parameters

id
string

Request parameters

approve_all
boolean
Default: false
commit_to_github
boolean
Default: true
add_images_to_comment_on_pr
boolean
Default: false

Response

Example request

POST /api/projects/:project_id/visual_review/runs/:id/finalize
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/finalize/\
	-d approve_all="boolean"
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}/finalize/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"approve_all": "boolean"
	}
).json()

Example response

Status 200

RESPONSE
{
  "run": {
    "approved_by": {
      "id": 0,
      "first_name": "string",
      "email": "string"
    },
    "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": {}
  },
  "baseline_content": "string"
}

Create visual review runs recompute

Re-evaluate quarantine and counts, update commit status, and optionally rerun the CI job.

Required API key scopes

visual_review:write

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/visual_review/runs/:id/recompute
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/recompute/
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}/recompute/".format(
        project_id=project_id,
		visual_review_id="<the visual review id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "run": {
    "approved_by": {
      "id": 0,
      "first_name": "string",
      "email": "string"
    },
    "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": {}
  },
  "counts_changed": true,
  "unresolved": 0,
  "ci_rerun_triggered": true,
  "ci_rerun_error": "string"
}