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: true and a Link: โ€ฆ; 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

  1. Upload โ€” Send the file with location_type and optional commodity_type/metrics/tags/end_date/assessments/metric_options fields, all as multipart fields.
  2. Validation โ€” The API validates the file format and stores it.
  3. Processing โ€” Task is dispatched to the worker; progresses through pending โ†’ processing โ†’ staged โ†’ completed.
  4. 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.

FieldRequiredMultipart typeEquivalent JSON body fieldEncoding
fileyesfile(none โ€” JSON variant uses signed PUT)Raw file bytes (โ‰ค 100 MB).
location_typeyestextlocation_typePlain string: plot, facility, or shed. See Location Types. Returned as a first-class task attribute, reconciled to the detected type after staging.
commodity_typenotextcommodity_typePlain string, e.g. palm, cocoa. When omitted, the commodity is auto-detected per location during validation and surfaced on the results.
namenotextnamePlain string โ‰ค 255 chars โ€” human-friendly task name. Derived from the tags (joined with , ), falling back to the filename, when omitted.
descriptionnotextdescriptionPlain string โ‰ค 2000 chars โ€” free-form notes. Never derived; null when omitted.
metricsnotextmetrics: string[]Comma-separated list (e.g. deforestation,biodiversity) โ€” multipart can't carry arrays natively.
tagsnotexttags: string[]Comma-separated list (e.g. batch-q1,verified).
end_datenotextend_dateYYYY-MM-DD. Must be Dec 31 of a prior year, or any date in the current year up to today (UTC).
forcenotextforce: boolean"true" to bypass duplicate-upload rejection. Defaults to off. See Duplicate uploads.
assessmentsnotextassessments: objectJSON-stringified object, e.g. {"include_core": true}.
metric_optionsnotextmetric_options: objectJSON-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

The 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 (default false) โ€” persist the core validation row.
  • assessments.include_hazard (default false) โ€” persist the natural-hazard risk row.
  • assessments.include_infrastructure (default false) โ€” persist infrastructure nearest-feature enrichments (nearest_water_km / nearest_port_km / nearest_road_km plus port metadata, subject to the check_* access toggles).
  • metric_options.enhanced_deforestation (default false) โ€” opt into the higher-sensitivity deforestation methodology. Only valid when metrics contains deforestation; 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

StatusCodeCause
400MISSING_FILE / MISSING_LOCATION_TYPERequired multipart field absent.
400VALIDATION_ERRORassessments 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.
409CONFLICTDuplicate upload โ€” identical file + parameters already processed. Original task id in data.details.duplicate_of_asset_task_id. Pass force = "true" to override.
411MISSING_CONTENT_LENGTHContent-Length header required.
413PAYLOAD_TOO_LARGEFile exceeds 100 MB.
415UNSUPPORTED_MEDIA_TYPEFile type not in the supported list.

Required scope: ingestions:write