Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grantiva.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Create a run

POST /api/v1/vrt/runs/:project

​
Headers

HeaderRequiredDescription
X-API-KeyYesYour API key

​
Body (multipart/form-data)

FieldTypeRequiredDescription
branchstringYesGit branch name
commit_shastringNoGit commit SHA
triggerstringYesWhat triggered the run (e.g., “ci”, “manual”)
durationdoubleNoRun duration in seconds
screensjsonNoScreen metadata array
capturesfile[]NoScreenshot PNG files
diffsfile[]NoDiff image PNG files

​
Response

{
  "run_id": "uuid",
  "status": "passed",
  "url": "https://grantiva.io/dashboard/vrt/runs/uuid",
  "screen_count": 8,
  "passed_count": 8,
  "failed_count": 0,
  "new_count": 0
}

​
Complete a run

PATCH /api/v1/vrt/runs/:project/:runId
Upload final results (screens, captures, diffs) to complete a running test.

​
List runs

GET /api/v1/vrt/runs/:project

​
Response

{
  "runs": [
    {
      "id": "uuid",
      "branch": "main",
      "commit_sha": "abc123",
      "status": "passed",
      "screen_count": 8,
      "passed_count": 8,
      "failed_count": 0,
      "created_at": "2025-03-10T12:00:00Z"
    }
  ]
}

​
Get run details

GET /api/v1/vrt/runs/:project/:runId

​
Response

{
  "run": { ... },
  "screens": [
    {
      "name": "Home",
      "status": "passed",
      "pixel_diff": 0.001,
      "perceptual_distance": 1.2
    }
  ],
  "logs": "Build output..."
}

​
Download images

GET /api/v1/vrt/runs/:project/:runId/screens/:screen/capture
GET /api/v1/vrt/runs/:project/:runId/screens/:screen/diff
Returns PNG image data.

​
Append logs

POST /api/v1/vrt/runs/:project/:runId/logs

​
Body

{
  "lines": "Log output to append..."
}