Damage assessment

How much of the plot was damaged after a hail, flood or drought event — with the preliminary step that avoids spending quota on a calculation that cannot be made yet.

Answers: how much of this plot was damaged after this event? It is the most expensive of the three products and the only one with three steps, because it has a problem the others do not: after an event, there may not be usable satellite imagery yet.

Three steps, and why

sequenceDiagram
    participant C as Your system
    participant A as API
    C->>A: POST /v1/damage/feasibility
    A-->>C: 200 · { status: ready | pending_post_imagery | cloud_blocked }
    Note over C: if not ready, do not spend: retry later
    C->>A: POST /v1/damage/assessments
    A-->>C: 202 · job enqueued
    C->>A: POST /v1/damage/reports { assessmentId }
    A-->>C: 202 · job enqueued

The first step consumes no quota and therefore requires no Idempotency-Key: it only queries the scene catalogue. Calling it before assessing saves you from paying for a calculation that would answer "not yet".

1. Can it be assessed yet?

bash

curl -s -X POST "$BASE/v1/damage/feasibility" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "ring": [[-59.95,-35.05],[-59.94,-35.05],[-59.94,-35.06],[-59.95,-35.06],[-59.95,-35.05]],
    "peril": "granizo",
    "eventDate": "2026-02-15"
  }'

peril is given in Spanish: granizo (hail), inundacion (flood) or sequia (drought). Any other value returns unsupported_peril.

`status`	What it means	What to do
`ready`	Usable pre- and post-event scenes exist	Assess
`pending_post_imagery`	The satellite has not passed since the event	Retry after `nextExpectedPass` (revisit is ~5 days)
`cloud_blocked`	Post-event imagery exists but is cloud-covered	Retry after `retryAfter`
`unsupported_peril`	That peril is not assessed by satellite	Do not insist
`invalid_event`	Future date, or inverted window	Fix the request

Drought almost always returns ready: it is computed against a multi-year climatology and needs no specific post-event scene.

2. Compute the damage

Where `aoi_ref` comes from

It references a plot that already exists, not a geometry sent with the request. This is the only place where damage assessment differs from the other two products, which take coordinates in the same call.

demo:lote-1 is a ~123 ha plot present in both environments. Use it to walk the whole flow before you have one of your own — it is what the examples on this page use.

There is no endpoint yet to register a plot on this surface. If you send a reference that does not exist, the job ends failed with aoi_not_found: the request is fine, the plot simply is not there. In the meantime, to assess your own plots, get in touch.

bash

curl -s -X POST "$BASE/v1/damage/assessments" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "parameters": {
      "aoi_ref": "demo:lote-1",
      "aoiVersion": 1,
      "event_ref": "ev-granizo-2026-02-15",
      "peril": "granizo",
      "eventDate": "2026-02-15",
      "threshold": 0.18,
      "licenceTier": "unverified"
    }
  }'

Returns 202. The result carries damaged hectares, affected percentage and the provenance: which windows were compared, how many scenes on each side, and at what cloud cut.

aoiVersion is part of the calculation's identity: redrawing the plot is a different assessment, and it has to be — an assessment over an old geometry would assert something about an area that is no longer the plot.

3. Issue the dossier

bash

curl -s -X POST "$BASE/v1/damage/reports" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"assessmentId":"job_footprint_…","locale":"en-US"}'

assessmentId is the job id from step 2, already succeeded. The dossier cites that assessment: the compared windows and the scenes used come from it, and that is what the document declares.

What breaks

What happens	Response	Why
`peril` in English, or an unsupported one	`unsupported_peril`	It is given in Spanish: `granizo`, `inundacion`, `sequia`
`eventDate` in the future	`invalid_event`	You cannot assess something that has not happened
Assessing without checking feasibility, with the post-event scene still clouded	the job fails	This is exactly why step 1 exists and is free
Missing `Idempotency-Key` on steps 2 or 3	`428`	Both consume quota. Step 1 does not require it
An `assessmentId` for a job that has not finished	the job fails	The dossier cites a closed assessment, not one in flight
The plot does not exist in your organization	`404`	Same answer as a non-existent route, on purpose

The full table of status codes is in Jobs, delivery and errors.

What it asserts, and what it does not

It compares pre- and post-event scenes over the same plot. What it detects is a change in spectral response consistent with damage.
Cloud cover degrades the result. The report states the cut used and how many scenes remained on each side.
Flood is currently detected with optical indices: under persistent cloud, sensitivity drops. Radar (which sees through cloud) is a pending improvement and is declared as a limitation in the document.
Resolution is 10 m: damage in patches smaller than that is not resolved individually.

It is reproducible technical evidence about affected area. It does not replace a field inspection nor set an indemnity amount.

Damage assessment

Three steps, and why

1. Can it be assessed yet?

2. Compute the damage

Where aoi_ref comes from

3. Issue the dossier

What breaks

What it asserts, and what it does not

On this page

Where `aoi_ref` comes from