List Plots
List the plots that the DDS package will actually use — i.e. plots in the record's current version that the operator has not excluded.
Each row carries any matching justification, so the UI can render the operator's evidence inline without a second round-trip. (Justifications can attach to either included or excluded plots; this endpoint returns whichever ones happen to apply.)
▶Path params
| Param | Description |
|---|---|
recordId | DDS record id |
▶Query params
| Name | Default | Notes |
|---|---|---|
page[number] | 1 | 1-indexed. Also accepted as page. Capped at 10,000 — deeper paging is clamped, not rejected. |
page[size] | 20 | max 100. Also accepted as page_size. An over-large value clamps to 100 rather than erroring. |
filter[plot_resolution] | — | Narrow to plots in a given review state. eq:<value> or in:<a>,<b>. Values: pending_review, mitigate_risk. An unknown value answers 400 rather than silently matching nothing, and a repeated key is rejected rather than one being dropped. |
filter[plot_id] | — | eq:<uuid>: narrow the list to one plot. Any other form answers 400. |
filter[needs_resolution] | false | true drops plots that are compliant with no justification, leaving the plots an operator may still need to act on. Any other value than true or false answers 400. |
▶Filtering the human-review queue
filter[plot_resolution]=eq:pending_review returns only the plots where the
automated adjudicator proposed a verdict and a human has still to confirm it.
meta.count reflects the filtered set, so it can drive an
"N outstanding / N resolved" progress display without a second call.
Resolve a plot by writing a plot_compliance verdict override
(PUT /regulations/eudr/audit-trail/:recordId/verdict-overrides): overriding
to compliant accepts the proposal, non_compliant rejects it. Either way
the override retires the pending state, and the plot leaves this queue.
suggested_outcome says what accepting means: compliant clears the plot,
and exempt is accepted by also sending exemption_driver, so the plot
reads exempt with that cause.
An active override removes a plot from this filter for every value, not
only pending_review. The filter answers "which plots still need an
operator decision", so a plot the operator has already decided is out of
scope. An expired override puts the plot back.
This endpoint lists only plots still in the filing. A submit attempt
withholds every pending-review plot, so after a failed submit those plots
move to /plots/excluded and this list answers zero. Read both surfaces to
show the full outstanding set.
▶Response
| Field | Notes |
|---|---|
data[].id | Plot UUID |
data[].attributes.commodity | Plot commodity (matches the record's stamped commodity) |
data[].attributes.country_code | ISO 3166-1 alpha-2 (matches the record's stamped country) |
data[].attributes.area_ha | Plot area in hectares; null when source data didn't supply it |
data[].attributes.producer_name | Producer name from the plot row; null when absent |
data[].attributes.production_place | Free-text production place (region / cooperative name / facility); null when absent |
data[].attributes.geometry | Plot geometry as GeoJSON (Polygon, MultiPolygon, …). Null when the plot has no geometry. |
data[].attributes.deforestation | Deforestation snapshot pinned per plot via the version's plot_for_job_id. Null when no EUDR-valid metric was available at snapshot time (rolls into current_version.completeness.missing_deforestation_metric). See deforestation block reference below. |
data[].attributes.excluded | Always false on this endpoint |
data[].attributes.justification | { text, evidence_urls, compliance_override, exemption_driver } or null. exemption_driver is set when the operator's compliant override records an exemption. |
data[].attributes.suggested_outcome | compliant or exempt: what accepting the adjudicator's suggestion makes the plot. null unless plot_assessment is non_compliant_pending_adjudication with a known cause. |
data[].attributes.plot_resolution | Review state of the pinned metric: pending_review when a human has still to confirm the adjudicator's proposal, mitigate_risk when the plot is flagged for mitigation, null when neither applies. A plain string, not a closed enum — new values can appear without a breaking change, so treat an unrecognised one as "not actionable by this client" rather than failing. |
▶deforestation block
deforestation blockSourced from the deforestation metric pinned via the version's
plot_for_job_id. Every field is independently nullable; an
all-nulls block is still distinct from deforestation: null (the
former means "metric ran but produced no detection", the latter
means "no EUDR-valid metric was pinned").
| Field | Type | Source |
|---|---|---|
noncompliance_area | number | null | Non-compliant area (hectares) |
noncompliance_area_perc | number | null | Non-compliant area (% of plot area) |
agreement | object | null | Per-overlay agreement metadata (passthrough) |
overlap | object | null | Per-overlay overlap (wdpa, naturalForest, …) (passthrough) |
thumbnail_url | string | null | Thumbnail image URL |
monitoring_start | ISO 8601 | null | Monitoring window start (EUDR Article 2 cutoff: 2020-12-31 for compliant plots) |
monitoring_end | ISO 8601 | null | Monitoring window end |
deforestation_start | ISO 8601 | null | Detected deforestation window start |
deforestation_end | ISO 8601 | null | Detected deforestation window end |
When the record has no current version yet (defensive), the response
is 200 with meta.count: 0 and an empty data array.
▶Companion endpoints
| Path | Returns |
|---|---|
/dds/:recordId/plots/excluded | The complement: plots the operator marked excluded |
/dds/:recordId/plots/unaccounted | Plots that satisfy the filter today but aren't yet in the snapshot |
▶Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing/invalid API key |
| 404 | NOT_FOUND | Record isn't visible to the caller |
Required scope:
ingestions:read