Latest Records Upload Facilities

Step 1: Upload the facility file

POST /ingestions/assets with location_type: facility and end_date: 2024-12-31. Upload a small facility CSV โ€” a name, a country and a coordinate per row is enough. Captures latest_records_task_id.

What this step does

It creates an ingestion task and returns a signed URL. The task is the container; the file bytes travel separately as a PUT, which the docs UI's Upload tab performs from meta.client_actions[0].

Every row of that file becomes an uploaded record. This step is the baseline the rest of the workflow supersedes.

Why end_date matters here

end_date sets the record's monitoring window, and the window is key 2 of the six-key precedence that decides which record is current. Setting it now โ€” to an early value โ€” is what lets step 3 win with a later one.

Leave it out and both uploads share a null window, so which record ends up current is decided by the lower-precedence keys instead of by you.

metrics is required here, not decorative

Record currency is stamped only in a task's terminal sweep, gated on overall_status reaching completed or completed_with_errors. A plain facility upload with no metrics or assessments never leaves staged โ€” there is nothing to process, so the sweep never runs, and its records would never be stamped. Both uploads would stay "live duplicates" forever, and step 5 would never see a superseded_count.

metrics: ["deforestation"] folds processing into the upload, the same way Quick Ingestion does, so the task reaches completed on its own and the currency stamp runs. It also means step 7's include=metrics.deforestation has a real run to show, not an empty relationship.

Next Step

โ†’ Step 2: Wait For First Upload โ€” the records must exist before a second upload can replace them.