Damage assessment

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?

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.

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.

There are three demo plots, adjacent to one another, in both environments:

They are adjacent on purpose: hail does not respect fence lines, and assessing two neighbouring plots for the same event is the case you will want to try. Each has its own area, so the two assessments return different results and content-based deduplication does not conflate them.

A reference outside that table — demo:lote-9, say — ends failed with aoi_not_found: the request is fine, that plot simply does not exist.

Registering your own plots

curl -s -X POST "$BASE/v1/aois" \
  -H "Authorization: Bearer $UCOTRON_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Campo El Ombú",
    "ring": [[-59.724109,-34.121614],[-59.722668,-34.121166],
             [-59.720789,-34.122512],[-59.722606,-34.123115]],
    "labels": ["season-2026", "soy"]
  }'

It returns the aoiRef you assess with:

{
  "aoiRef": "org:campo-el-ombu-a1b2c3",
  "version": 1,
  "hectares": 3.29,
  "ring": [[-59.724109,-34.121614], "…", [-59.724109,-34.121614]]
}

The ring does not need to be closed: if the last point does not repeat the first, we close it on save. What does matter is the order — [lng, lat], longitude first, with the same Google Maps trap described in the buildings guide.

Three things worth knowing about registration:

• We compute the area from the polygon, and that is the figure the assessment reports. A client-supplied value is not accepted: if the declared area and the geometry disagreed, every damage percentage would be wrong.
• Plots are versioned. version starts at 1 and increments on every geometry edit. An assessment cites the plot and its version, so an already-issued dossier keeps showing the plot it measured even if you redraw it later.
• Idempotency-Key is required. Without it, a retry after a timeout would create two plots with the same polygon and different references, and you would not know which to cite.

Registration does not run in the sandbox. That environment has no database, so a plot loaded there would not exist for the assessment citing it. It answers 501 saying so. Register your plots against production.

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

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 the dossier contains

In this order, because it is the one an assessor follows to support a conclusion:

1. Summary — plot, event, net affected area and predominant severity.
2. Event and method — index, sensor, threshold, compared windows and scenes.
3. Map — the plot in orange and the damage footprint in red, vectorised pixel by pixel over the satellite image.
4. Spectral indices — the mean index before and after, with its change. The sign matters: negative is a drop, which is what damage produces.
5. Severity by zone — how much area fell into severe, moderate and light damage. A plot with 40 % affected is not adjusted the same way if it is all light as if a third of it is lost.
6. Differential diagnosis — the breakdown that explains the figure.
7. Observables, legal framework and methodology, and provenance with hash and signature.

The raw / control / net breakdown

The step 2 result carries damageBreakdown, and the dossier prints it:

The correction is not cosmetic. In a frost, much of the index drop is the crop drying down as it does every year, and the figure worth assessing is the excess: reporting the raw number can overstate the claim several times over.

When controlFound is false there was no baseline to compare against. That is not a control of zero: net equals raw and the document says so explicitly, so it reads as an upper bound rather than a measurement.

What breaks

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.
• For hail and frost it also applies an interannual control at matched phenology: the same window one year earlier over the same plot. A pixel counts as damaged only if it dropped this year and did not drop the year before, so the crop's normal evolution is discounted rather than added to the claim.
• The differential diagnosis may include an interpretation written automatically over the report's figures. That text stays outside the content hash and the document says so: the signature covers the figures, which are the part that can be reproduced.
• 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.