Skip to content

API · CONSULTANT & BROKER TIER

Screening & verification API.

Run EUDR plot screenings from your own tooling. Every result is stored with a custody hash — so the deliverables you hand clients inherit the same verifiable provenance as the EUDR Clear console.

WHY AN API

Your outputs inherit custody hashes

Verifiable by third parties

Every screening returns a custody hash anyone can resolve on the public /verify page — no account needed. Your client can independently confirm what was rendered, by which engine version, and when.

Same engine, same discipline

The API runs the identical screening kernel, custody hashing and verification manifest as the console. There is no second implementation to drift.

Stored in your account

API screenings land in your EUDR Clear vault under an auto-named plot — they verify, corroborate and retain like any other record.

AUTHENTICATION

One header: x-api-key

Send your key with every request. Keys are created in the EUDR Clear console — self-service on the Scale plan, or issued by us — and shown exactly once: only a SHA-256 of the key is stored, so a lost key is revoked and replaced, never recovered.

x-api-key: ec_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

QUICKSTART

Four endpoints, curl-first

POST/api/v1/screeningscope: screening

Run a screening on one plot ({geometryType, coordinates, commodity}). Stores the plot + full custody record under the key owner’s account and returns verdict, loss by year, dataset versions, convergence, and the custody hash.

curl -X POST https://eudr.adversedays.com/api/v1/screening \
  -H "x-api-key: $EUDRCLEAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "geometryType": "point",
    "coordinates": "-1.234500,12.345600",
    "commodity": "cocoa"
  }'
GET/api/v1/verify/:hashOrRefscope: verify

Look up a custody hash (64-hex) or evidence-pack reference code (EUDRC-YYYY-NNNN). Same manifest as the public /verify page: integrity self-check, k-anonymous corroboration, anchoring status.

curl "https://eudr.adversedays.com/api/v1/verify/<custodyHash>" \
  -H "x-api-key: $EUDRCLEAR_API_KEY"
GET/api/v1/benchmarksscope: benchmarks

Live-only aggregate verdict mixes by commodity and country — demo screenings excluded, buckets with fewer than five screenings withheld.

curl "https://eudr.adversedays.com/api/v1/benchmarks" \
  -H "x-api-key: $EUDRCLEAR_API_KEY"
GET/api/v1/mescope: any

Integration debugging: the key’s name, granted scopes, and request count over the last 30 days.

curl "https://eudr.adversedays.com/api/v1/me" \
  -H "x-api-key: $EUDRCLEAR_API_KEY"

SCOPES & LIMITS

Least privilege, honest limits

API key scopes and the endpoints each grants
SCOPEGRANTS
screeningPOST /api/v1/screening
verifyGET /api/v1/verify/:hashOrRef
benchmarksGET /api/v1/benchmarks

A key carries only the scopes it was issued with — hitting an endpoint without the right scope returns 403 insufficient_scope.

API error codes, HTTP status and meaning
CODEHTTPMEANING
invalid_api_key401Missing, invalid, or revoked x-api-key header.
insufficient_scope403The key is valid but does not carry the scope this endpoint requires.
rate_limited429Too many requests — 120/hour per key by default, with a per-address ceiling for unauthenticated traffic.
invalid_request400Malformed body or path parameter (validated against the schemas above).
live_bad_input · live_validation · live_too_large400The plot itself could not be screened — coordinates out of range, a geometry the engine rejected, or an area too large for one request. The message says which; fix the plot and resubmit.
live_rate_limited429The upstream screening engine is busy. Wait and retry — the request was not charged.
live_timeout · live_unreachable · live_server_error · live_auth · live_not_configured503The screening engine could not produce a result. Nothing is returned rather than a substitute figure: a demo number is never served in live mode. Retry shortly.

Errors are always JSON: {"error":{"code","message"}}. Rate limit: 120 requests/hour per key (adjustable per deployment), plus a per-address ceiling on unauthenticated traffic.

DEMO MODE — HONEST BY DEFAULT

Until live datasets are switched on for a deployment, screening responses carry isDemo: true and dataset versions marked (demo). The custody discipline is identical — deterministic engine, reproducible hashes — but the figures are generated, not measured. The isDemo flag is always in the response so you can label your own deliverables honestly. Read the methodology →

API ACCESS · SCALE PLAN

API access is included on the Scale plan.

Consultants and brokers: bring your own tooling, inherit our custody network. Talk to us and we will set your key up today.

Talk to us

Indicative screening for decision-support only — not a compliance determination.