Ingest Assets Multipart
Deprecated. Prefer the JSON / signed-URL variant documented at Ingest Assets. Existing integrations continue to work; responses on this transport now carry
Deprecation: trueand aLink: โฆ; rel="successor-version"header pointing at the same endpoint.
Legacy: stream the file inline as multipart/form-data in a single request.
The server stores it, then dispatches the ingestion task.
โถHow it works
- Upload โ Send the file with
location_typeand optionalcommodity_type/metrics/tags/end_date/assessments/metric_optionsfields, all as multipart fields. - Validation โ The API validates the file format and stores it.
- Processing โ Task is dispatched to the worker; progresses through
pendingโprocessingโstagedโcompleted. - Poll โ
GET /ingestions/{id}for status.
โถMultipart fields
Each parameter from the JSON variant of Ingest Assets has a 1:1 multipart equivalent. Scalar / list parameters become regular text fields; nested objects are sent as JSON-stringified values inside a single text field.
| Field | Required | Multipart type | Equivalent JSON body field | Encoding |
|---|---|---|---|---|
file | yes | file | (none โ JSON variant uses signed PUT) | Raw file bytes (โค 100 MB). |
location_type | yes | text | location_type | Plain string: plot, facility, or shed. See Location Types. Returned as a first-class task attribute, reconciled to the detected type after staging. |
commodity_type | no | text | commodity_type | Plain string, e.g. palm, cocoa. When omitted, the commodity is auto-detected per location during validation and surfaced on the results. |
name | no | text | name | Plain string โค 255 chars โ human-friendly task name. Derived from the tags (joined with , ), falling back to the filename, when omitted. |
description | no | text | description | Plain string โค 2000 chars โ free-form notes. Never derived; null when omitted. |
metrics | no | text | metrics: string[] | Comma-separated list (e.g. deforestation,biodiversity) โ multipart can't carry arrays natively. |
tags | no | text | tags: string[] | Comma-separated list (e.g. batch-q1,verified). |
end_date | no | text | end_date | YYYY-MM-DD. Must be Dec 31 of a prior year, or any date in the current year up to today (UTC). |
force | no | text | force: boolean | "true" to bypass duplicate-upload rejection. Defaults to off. See Duplicate uploads. |
assessments | no | text | assessments: object | JSON-stringified object, e.g. {"include_core": true}. |
metric_options | no | text | metric_options: object | JSON-stringified object, e.g. {"enhanced_deforestation":true}. Flat shape โ keys are the option names directly, not nested under a metric. |
Anything malformed in the JSON-stringified fields responds 400 VALIDATION_ERROR with the offending path (e.g. assessments.include_core: Expected boolean, received string).
โถWorked example
curl -X POST "https://${API_HOST}/ingestions/assets" \
-H "x-api-key: $API_KEY" \
-F "file=@plots.geojson" \
-F "location_type=plot" \
-F "commodity_type=cocoa" \
-F "metrics=deforestation,biodiversity" \
-F "tags=batch-q1,verified" \
-F "end_date=2025-12-31" \
-F 'assessments={"include_core":true,"include_hazard":true,"include_infrastructure":true,"check_water_access":true}' \
-F 'metric_options={"enhanced_deforestation":true}'
โถassessments and metric_options semantics
assessments and metric_options semanticsThe shape and semantics are identical to the JSON variant โ the
multipart transport just wraps the same object in a string. For the full
reference (defaults, per-group overrides, check_* toggles, resolution
rules, post-hoc filling), see the corresponding sections in
Ingest Assets.
Quick reminder of the most common flags:
assessments.include_core(defaultfalse) โ persist thecorevalidation row.assessments.include_hazard(defaultfalse) โ persist the natural-hazard risk row.assessments.include_infrastructure(defaultfalse) โ persist infrastructure nearest-feature enrichments (nearest_water_km/nearest_port_km/nearest_road_kmplus port metadata, subject to thecheck_*access toggles).metric_options.enhanced_deforestation(defaultfalse) โ opt into the higher-sensitivity deforestation methodology. Only valid whenmetricscontainsdeforestation; the API rejects it otherwise.
EUDR-scope flags (include_eudr / include_art9 / include_art10)
are no longer wired up on ingestion โ the keys are silently stripped
rather than rejected so stale callers don't break. Drive EUDR-scope
assessments from the DDS create path instead.
โถPersistence
The parsed assessments and metric_options objects (after
JSON.parse) are stored on the resulting task's job_parameters.
The worker side rebuilds the dispatch payload
from these at process time โ the multipart transport doesn't change
any downstream behaviour vs. the JSON variant.
โถWhy migrate to the signed-URL flow
- The bytes traverse the API instead of going directly to object storage โ extra latency, extra failure modes, no resumability.
- Multipart parsing is more brittle for MCP / LLM clients than a single JSON POST followed by a single PUT.
โถSupported file formats
CSV, GeoJSON / NDJSON, Parquet, GeoPackage, Shapefile (.zip), Excel
(.xlsx/.xls). Up to 100 MB.
โถDuplicate uploads
An upload is rejected with 409 CONFLICT when its file content and
processing parameters match a task that has already completed for your
organization (or a child org). The original task id is returned in
data.details.duplicate_of_asset_task_id. Labelling fields (name,
description, tags, supplier info) are not part of the match;
end_date is matched separately (exact when set; otherwise a 14-day
recency window). Send force = "true" to bypass the check and process
the upload anyway. This mirrors the signed-URL flow, which surfaces the
same condition asynchronously as a failed task carrying
duplicate_of_asset_task_id โ see
Ingest Assets.
โถErrors
| Status | Code | Cause |
|---|---|---|
| 400 | MISSING_FILE / MISSING_LOCATION_TYPE | Required multipart field absent. |
| 400 | VALIDATION_ERROR | assessments or metric_options field is not valid JSON, or its parsed shape doesn't match the schema (e.g. unknown key, wrong type). The error message names the field path that failed. |
| 409 | CONFLICT | Duplicate upload โ identical file + parameters already processed. Original task id in data.details.duplicate_of_asset_task_id. Pass force = "true" to override. |
| 411 | MISSING_CONTENT_LENGTH | Content-Length header required. |
| 413 | PAYLOAD_TOO_LARGE | File exceeds 100 MB. |
| 415 | UNSUPPORTED_MEDIA_TYPE | File type not in the supported list. |
Required scope:
ingestions:write