Tags

When you PUT /ingestions/assets, you can include tags in the JSON body. At least one of stats or tags must be provided.

Tags with stats — triggers batch processing and applies tags:

{
  "stats": ["deforestation"],
  "tags": ["batch-q1", "priority"]
}

Tags only — applies tags to the filtered set without triggering batch processing:

{
  "tags": ["batch-q1", "priority"]
}

When only tags is provided (no stats), tags are applied to the matching asset task and its asset entities (pivot rows) and the endpoint returns 200. When stats is included, batch processing is triggered in the background and the endpoint returns 202.

For the default path (cross-task filtering), tags are applied after rows are copied into the new task.

You can also tag rows individually by including a tags column in your uploaded file (CSV, GeoJSON, etc.). The value should be a comma-separated list of tag names:

name,latitude,longitude,tags
Farm A,52.1,-1.2,"verified,q1-2025"
Farm B,48.8,2.3,high-risk

Per-row tags are additive — if you also supply request-level tags, both sets are applied.

Instead of adding a dedicated tags column, you can turn any existing column into per-row tags directly from the request-level tags field, using a {Column Header} placeholder:

tags: partno:{Part Number}

At ingestion, the placeholder is replaced with each row's cell value for that column — so a row whose Part Number is 12345 gets a partno:12345 tag, the next row gets partno:678, and so on. This is the easiest way to create one namespaced tag per row without pre-splitting your file.

Rules:

• Namespace is whatever precedes the first colon (partno above). Several templates can share a namespace, and you choose it via the prefix.
• Missing column or blank cell → that tag is simply skipped for that row (no empty partno: tag is created).
• Multi-value cells — a placeholder cell containing a comma-separated list (12345,678) produces one tag per value (partno:12345, partno:678).
• Literal braces — a {...} that doesn't match any column header is treated as a plain literal tag, not a template, so it is never silently dropped.
• Static + template can be mixed: tags=verified,partno:{Part Number} applies verified to every row and the derived partno:* per row.

GET /locations/groups/partno

Returns one group per distinct value under the partno namespace, each listing the facilities and sheds that carry it — answering "where does part X come from?". Groups are paginated. You can narrow to specific values with the tag filter, e.g. GET /locations/groups/partno?filter[tags]=in:partno:12345,partno:678.

The equivalent view over ingestion assets groups the uploaded rows (before location resolution) by the same namespace:

GET /ingestions/assets/groups/partno

Add tag_prefix to a locations listing to return only the locations carrying a tag under that namespace, each annotated with a part_numbers array (the sorted distinct values under the prefix) — answering "which parts does this location supply?":

GET /locations/facilities?tag_prefix=partno
GET /locations/sheds?tag_prefix=partno

Each returned facility/shed includes part_numbers: ["12345", "90012"] alongside its usual attributes, ready to render as chips. Plots are never returned by this view.

Listing every group in a namespace scans all of that namespace's members (across your whole catchment) before paginating — for a namespace that spans a large catalogue this can be slow. When you know the values you care about, narrow with the tag filter so the query touches only those tags:

GET /locations/groups/partno?filter[tags]=in:partno:12345,partno:678
GET /ingestions/assets/groups/partno?filter[tags]=in:partno:12345

A filtered request is dramatically cheaper than an unfiltered full-namespace listing, and pages are bounded — always page (page[size]) rather than pulling a whole large namespace at once.

GET /tags

Returns your organization's tags, ordered alphabetically. The response is paginated like other list endpoints (page / page_size, default page size 500, maximum 1000) with meta.total and links.next — page through it if your org holds more tags than one page.

PATCH /tags/:name
{ "name": "new-tag-name" }

Renames a tag across all resource associations. Any resource that had the old tag name will now reflect the new name. Returns 409 if the new name already exists.

PATCH /tags/namespaces/:namespace
{ "namespace": "new-namespace" }

Renames (and merges) every tag under a namespace in one call — e.g. move all partno:* tags to part_number:*, preserving each value. If a target tag name already exists, the associations are merged onto it. Useful for correcting a namespace choice after a large upload without re-tagging every resource.

DELETE /tags/:name

Permanently deletes a tag and removes it from all resources (facilities, plots, sheds, etc.) via cascading delete.