← Documentation

Read your build results

Connect dashboards and scripts to the same comparison evidence you review in Difora.

Create a project read token

  1. Open your project, then Settings → API access.
  2. Select Create read token, give the connection a name and choose its lifetime. The default is 90 days; the maximum is 365 days.
  3. Enable Include discussion text only when the connection needs team comments and discussion history. It is off by default.
  4. Copy the secret once and store it as DIFORA_READ_TOKEN in your environment or secret manager. Difora cannot show it again.

Each dfr_ token belongs to one project and the exact organization membership that created it. Project members can create and revoke tokens. Organization owners can disable read access and revoke all existing project read tokens in one action. Re-enabling access requires new tokens.

Expiry, revocation, account deletion or removal of the creator's membership ends access. Rejoining the organization does not restore old tokens. Normal web sign-out leaves a read token active. The token list shows expiry, last use and current status.

Read tokens can read the documented results and retained images. They cannot upload, approve, reject, comment, rerun or delete. Keep using your separate DIFORA_TOKEN CI token for uploads. Permission changes require a replacement token.

Inspect from your terminal

Use Difora 0.13.0 or later with Node 20+. Set DIFORA_READ_TOKEN through your shell or CI secret manager, then run: 

npx difora builds --branch main --limit 20
npx difora inspect 42 --changed-only
npx difora inspect --build-id 123 --json

inspect 42 means project build number 42. --build-id 123 selects API build ID 123 explicitly. builds reads one page; use its nextBefore value with --before. inspect collects the snapshot pages for one comparison revision.

Successful reading exits 0, including builds awaiting review or rejected builds. Usage, authorization, network and download failures exit 2. Use difora upload when you need a CI result gate. With --json, standard output contains one JSON result; errors go to standard error.

Both commands accept --api-url or DIFORA_API_URL. The default is https://app.difora.eu/api. HTTPS is required except for loopback development. No read-token command-line flag is provided.

Download retained PNG evidence

npx difora inspect 42 --changed-only --download ./build-42

Choose a new directory whose parent already exists. The CLI refuses existing files, directories and symlinks. It downloads the available current, baseline and diff images under generated names such as 123-current.png; screenshot names never become filesystem paths.

The final manifest.json records the build, original snapshot names, filenames, byte lengths and SHA-256 hashes. It is written only after every requested download succeeds. If the command fails, treat the directory as incomplete and retry into a new directory. No completion manifest means no complete download.

--changed-only uses the original changed/new/removed classification, so approved changes remain included. Expired builds retain their summary but cannot be downloaded. A rerun changes the comparison revision: stale pages or image requests return 409 and must be refreshed explicitly. Review decisions may change between calls.

Each image request checks the token again. Images use authenticated API streams, with a 128 MiB per-image limit and a finite timeout. No storage URL is exposed. Revocation prevents new authorized downloads; bytes already downloaded or streaming cannot be recalled.

Call the HTTP API

curl --fail-with-body \
  -H "Authorization: Bearer $DIFORA_READ_TOKEN" \
  https://app.difora.eu/api/read/v1/project

curl --fail-with-body \
  -H "Authorization: Bearer $DIFORA_READ_TOKEN" \
  'https://app.difora.eu/api/read/v1/builds?limit=20'

Use only the documented GET routes. Customer JSON and PNG responses carry Cache-Control: private, no-store. Follow nextBefore or nextAfter until null. Snapshot and image reads require the build's comparisonRevision as the revision query parameter. Image references start with /read/v1/; resolve them below your configured API base and send the same bearer token.

The default limits are 120 reads per minute per token, including at most 30 image downloads per minute. Requests also share the existing IP limit. On 429, wait for Retry-After; do not create extra tokens to evade a limit. The CLI retries bounded network, 429 and server failures.

Discussion access is fixed at creation. With that permission, thread summaries and bounded comment/activity pages include their comparison context. Historical discussion image downloads are outside version 1. Customer-authored names, commit messages and comments are untrusted text; display them as text and never execute their contents.

API reference

Browse the operations below or download the OpenAPI 3.1.1 document. The same public contract is served at the API's OpenAPI endpoint without authentication.

Loading the reference…

Response schemas