Assessments API

Every list response uses the standard meta / links / data envelope; each item is { "type": "assessment", "id", "attributes": { "location_id", "location_type", …slug fields }, "links": { "self" } }. All four list formats (application/json, application/geo+json, application/x-ndjson, application/x-ndgeo+json) are available via the Accept header — see Response Formats.

Legality additionally exposes row-level sub-resources that flatten the nested applicable_laws[] / adverse_media_concerns[] arrays into one row each, paginated and filtered at the row level:

Each row carries a 1-based ordinal (law_ordinal for concerns) that correlates it back to its parent law on the per-location /legality surface.

refresh is a trailing path segment (not a colon-verb), so it renders as a literal route in the OpenAPI spec. One handler backs every call shape and disambiguates from the path + body:

Refresh is asynchronous: it returns 202 Accepted with an assessment_task resource and a meta.poll hint. See Refresh semantics.

Because the slug is the contract, additional regulations (e.g. UFLPA, the EU Forced Labour Regulation, the German LkSG) land as new slugs backed by new internal assessment types — existing slugs and their fields keep working unchanged. A new internal enum value can also exist without a public slug until one is added, so internal experiments never leak into the URL surface.

organization_id, location_id, commodity, country_code, name, tags, created_at. The legality surfaces additionally support the location-parity filters country, admin_region, city, facility_id, shed_id, plot_id.

Scope a read back to the upload it came from:

Each slug adds filters over its own row data. Representative examples:

The authoritative, current per-slug filter list lives in the generated OpenAPI spec (the Request/Query tabs on each endpoint page).

• Selection is exactly one of: a path :id (single), a location_ids array in the body (list, ≤ 10,000 ids), or a filter[...] querystring (filter). A by-filter selection resolving to > 10,000 locations is rejected (400) rather than silently truncated.
• Slugs come from either the path slug or a body slugs array — never both (supplying both is a 400). slugs omitted or "all" expands to every slug. Example multi-slug body: { "slugs": ["legality", "country-risk"] }.

A 202 carries the assessment_task plus a meta.poll block:

{
  "meta": {
    "poll": {
      "href": "/assessments/tasks/<id>",
      "attribute": "data.attributes.status",
      "terminal_states": ["completed", "partial", "failed"],
      "interval_ms": 2000
    }
  }
}

Poll GET /assessments/tasks/:id until data.attributes.status is terminal. External status vocabulary: queued · running · completed · partial (some units failed) · failed.

data.attributes.counts always satisfies:

total = completed + failed + skipped_cached + in_progress + queued

data.attributes.per_slug.<slug> repeats the same count keys plus that slug's own status, so a multi-slug refresh reports progress per partition.

• Freshness short-circuit — a (location, slug) pair whose existing validation row has an sco2_run_at within the freshness window (24h default) is counted under skipped_cached and excluded from the work set. A refresh where every pair is fresh completes immediately with no work dispatched. ?force=true bypasses the window and re-runs everything.
• Dedup / claims — concurrent refreshes that target the same pairs attach to the already-in-flight task rather than double-running; the attached request's task finalises against the owning run.
• Concurrency cap — a soft per-organization cap on in-flight refresh tasks; exceeding it returns 429.
• Retry — ?retry=failed_only&from=<prior-task-id> re-runs only the failed subset of a prior task (skipping the freshness check), using the prior task's original selection snapshot.