🇺🇦

API documentation

Run screenshots and visual checks from CI, tools and webhooks.

Use the API for work that belongs in CI, release hooks or backend jobs. Keep page setup in the dashboard so teams can review baselines, failures and result files.

QuickstartEndpoint reference

What the API covers

8 endpoints
Render outputs
Create screenshots, PDFs, HTML, Markdown and generated files from one API.
Scheduled website checks
Start saved Check Suites from CI and review changed pages in the dashboard.
Results and review
Poll jobs, download artifacts and keep run history tied to baselines.

Base URL

https://renderlog.com

Quickstart

Start a Check Suite run

Create an API token with runs:write, start a saved Check Suite from CI and poll the job until it finishes. Put page setup in the dashboard so API calls stay short.

Download OpenAPI spec
Create runcURL
curl -X POST https://renderlog.com/api/check-suites/suite_01J/runs \
  -H "Authorization: Bearer rl_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "png",
    "labels": {
      "branch": "main",
      "commit": "8f4a7f2"
    }
  }'
Poll jobcURL
curl https://renderlog.com/api/jobs/job_01J \
  -H "Authorization: Bearer rl_live_xxx"

Use cases

Start with the API path that matches the job

Use the dashboard for setup and reuse the API for work that should run from CI, release hooks or server jobs.

One-off render

Create a screenshot, PDF, HTML or Markdown result from one request when the job ends at an artifact.

CI visual check

Run a saved Check Suite after release, poll the job result and review only cases that changed or failed.

Bad result guard

Reject pages that show a CAPTCHA, challenge screen, missing selector or wrong text.

Result files

Fetch the stored result after an async run finishes.

Authentication

API tokens are workspace-scoped. Create narrow tokens in Settings and use short-lived tokens for GET URLs that may land in logs.

Authorization: Bearer rl_live_xxx

Billing rules

A run is billable only when it succeeds and returns a real result. Failed or bad runs without a real result are not billable.

Supported public outputs: screenshot, PDF, HTML, Markdown and generated file. Video is async and priced separately when enabled.

Artifact routing

Send result files to your own S3-compatible storage

RenderLog can keep result files in managed storage or write them to your bucket. Run history, review state and metadata stay in RenderLog.

Fields

Bucket
The exact bucket or container name.
Region
Provider region, for example us-east-1. Some providers do not require it.
Endpoint
Custom S3-compatible endpoint. Leave empty for standard AWS S3.
Prefix
Optional folder path before every file, for example renderlog/.

Before you add it

  1. Create a bucket for RenderLog result files.
  2. Allow the RenderLog storage credentials to write objects to that bucket.
  3. Add the storage destination in workspace settings and select it for future runs.

Methods

GET or POST

Both methods can start a render. GET is convenient for URL-only renders. POST is safer when the request carries secrets, longer flow steps or storage settings.

GET

GET is convenient

Use GET for shareable render URLs and short query parameters. If a URL carries sensitive values, use a narrow short-lived key.

curl "https://renderlog.com/api/render?url=https%3A%2F%2Fexample.com&format=png&width=1366&height=768&dpr=1&selector=%23app" \
  -H "Authorization: Bearer rl_live_xxx"
POST

POST is safer for secrets

Use POST for headers, cookies, HTML, Markdown, longer flow steps, storage settings and webhooks.

curl -X POST https://renderlog.com/api/render \
  -H "Authorization: Bearer rl_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/account",
    "format": "png",
    "headers": { "X-RenderLog-Access": "secret" },
    "failureRules": [
      { "type": "preset", "preset": "cloudflare_challenge" },
      { "type": "selector_missing", "selector": "#app" }
    ]
  }'

Render API

Create one-off renders by GET or POST. GET is convenient. POST is recommended for sensitive values.

GET/api/render

Render by URL

Starts a URL-based render from query parameters. Sensitive values in URLs can appear in logs, browser history and analytics. Use a narrow short-lived token when you intentionally send them through GET.

API token

Job

{
  "id": "job_01J",
  "status": "passed",
  "result": [
    {
      "id": "run_01J",
      "status": "passed",
      "format": "png",
      "billable": true,
      "artifacts": [
        {
          "id": "artifact_01J",
          "url": "/api/runs/run_01J/artifacts/artifact_01J",
          "contentType": "image/png"
        }
      ]
    }
  ]
}

Path and query parameters

urlqueryRequiredTarget URL.
formatqueryOptionalpng, jpeg, webp, pdf, html or markdown. Default: png
widthqueryOptionalViewport width in CSS pixels. Default: 1366
heightqueryOptionalViewport height in CSS pixels. Default: 768
dprqueryOptionalDevice scale factor from 1 to 3. Default: 1
selectorqueryOptionalCSS selector for element capture.
fullPagequeryOptionalSet true for full-page capture. Default: false

Response fields

idRequiredJob id. Use it with GET /api/jobs/.
statusRequiredqueued, running, passed, failed or canceled.
resultOptionalNull while queued or running. Contains result rows after completion. Default: null
POST/api/render

Render with body

Starts a render with full settings such as headers, cookies, HTML, Markdown, flow steps, storage and failure rules.

API token

Render request

{
  "url": "https://example.com/account",
  "format": "png",
  "headers": {
    "X-RenderLog-Access": "secret"
  },
  "failureRules": [
    {
      "type": "preset",
      "preset": "cloudflare_challenge"
    },
    {
      "type": "selector_missing",
      "selector": "#app"
    }
  ]
}

Job

{
  "id": "job_01J",
  "status": "passed",
  "result": [
    {
      "id": "run_01J",
      "status": "passed",
      "format": "png",
      "billable": true,
      "artifacts": [
        {
          "id": "artifact_01J",
          "url": "/api/runs/run_01J/artifacts/artifact_01J",
          "contentType": "image/png"
        }
      ]
    }
  ]
}

Request fields

urlRequiredPage URL to render. Required unless you send HTML or Markdown content.
formatOptionalResult format: png, jpeg, webp, pdf, html, markdown, file or webm. Default: png
headersOptionalExtra request headers. Use POST for secrets. Default: {}
cookiesOptionalCookies sent before opening the page. Default: []
failureRulesOptionalRules that mark a result as bad, such as CAPTCHA, Cloudflare challenge or missing selector. Default: []
asyncOptionalReturn immediately and poll GET /api/jobs/ when the result may take longer. Default: false

Response fields

idRequiredJob id. Use it with GET /api/jobs/.
statusRequiredqueued, running, passed, failed or canceled.

Check Runs

Start saved Check Suites or one Check Case from CI, deploy hooks or internal tools.

POST/api/check-suites/{id}/runs

Run suite

Starts all active Check Cases in a saved suite. Use labels for branch, build or environment context.

API token

Run suite

{
  "format": "png",
  "labels": {
    "environment": "production",
    "build": "142",
    "commit": "8f4a7f2"
  },
  "delaySeconds": 30
}

Job

{
  "id": "job_01J",
  "status": "queued",
  "result": null
}

Path and query parameters

idpathRequiredCheck Suite id.

Request fields

formatOptionalResult format for every Check Case in this run. Default: png
labelsOptionalKey/value labels for filtering later, such as branch, build or environment. Default: {}
delaySecondsOptionalWait before starting the run. Useful after deploys that need warm-up time. Default: 0
asyncOptionalReturn immediately and poll GET /api/jobs/. Default: false
POST/api/check-cases/{id}/runs

Run one Check Case

Starts one saved target. Use this when a deploy changed only one page or component.

API token

Run case

{
  "format": "png",
  "labels": {
    "branch": "main",
    "commit": "8f4a7f2"
  },
  "delaySeconds": 0
}

Job

{
  "id": "job_01J",
  "status": "passed",
  "summary": {
    "total": 1,
    "passed": 1,
    "failed": 0,
    "errored": 0,
    "skipped": 0
  },
  "result": [
    {
      "id": "run_01J",
      "status": "passed",
      "format": "png",
      "billable": true
    }
  ]
}

Path and query parameters

idpathRequiredCheck Case id.

Request fields

formatOptionalResult format for this Check Case. Default: png
labelsOptionalKey/value labels for filtering later. Default: {}
delaySecondsOptionalWait before starting the run. Default: 0

Results

Poll jobs, inspect runs and download generated files.

GET/api/runs

List runs

Returns recent Runs with labels, result files and billing state.

API token

Runs

{
  "runs": [
    {
      "id": "run_01J",
      "status": "passed",
      "format": "png",
      "billable": true,
      "bytes": 128420
    }
  ]
}
GET/api/jobs/{id}

Get job

Returns status and result rows for one render or suite run.

API token

Job

{
  "id": "job_01J",
  "status": "passed",
  "summary": {
    "total": 4,
    "passed": 4,
    "failed": 0,
    "errored": 0,
    "skipped": 0
  },
  "result": [
    {
      "id": "run_01J",
      "status": "passed",
      "format": "png",
      "billable": true,
      "artifacts": [
        {
          "id": "artifact_01J",
          "url": "/api/runs/run_01J/artifacts/artifact_01J",
          "contentType": "image/png"
        }
      ]
    }
  ]
}

Path and query parameters

idpathRequiredJob id returned when you start a render or Check Suite run.
GET/api/runs/{id}

Get Run

Returns status, labels and result file links for one run.

API token

Run

{
  "id": "run_01J",
  "status": "passed",
  "format": "png",
  "billable": true,
  "artifacts": [
    {
      "id": "artifact_01J",
      "kind": "primary",
      "contentType": "image/png",
      "url": "/api/runs/run_01J/artifacts/artifact_01J"
    }
  ]
}

Path and query parameters

idpathRequiredRun id.
GET/api/runs/{id}/artifacts/{artifactId}

Download result file

Downloads a generated screenshot, PDF, HTML, Markdown, file or video.

API token

Result file

"Binary artifact response with the stored content type."

Path and query parameters

idpathRequiredRun id.
artifactIdpathRequiredResult file id.