Create Collection Tree¶
Create a STAC Collection tree from a set of items — no hand-written links: the extent is the union of the items' bboxes and datetimes, the id is proposed so it is unique and flat, and license/providers/description are carried over from the base. All root/parent/collection/item links are wired by EPT. Preview by default; give it target/local_output (or source_prefix) and it also exports — fetching item JSONs from URLs, S3, or the EPT filesystem when needed.
Endpoint¶
Authentication: Authorization: Bearer <access_token>.
Usage¶
curl -X POST "${EPT_API_URL}/v1/stac/collections/tree" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
"items": [
{
"type": "Feature",
"id": "item-1",
"bbox": [2.5, 51.0, 3.5, 52.0],
"properties": {"datetime": "2024-06-01T00:00:00Z"}
}
],
"title": "North Sea Bathymetry"
}' | jq .
Request¶
Provide at least one item source — items, item_links, or source_prefix — or a base collection. source_prefix is mutually exclusive with items/item_links and with the export fields. Unknown fields are rejected (extra="forbid"), as are malformed requests (422).
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
items |
array of objects | no | [] |
STAC Items to derive the extent from (spatial union of bboxes, temporal union of datetimes). Every entry must have type == "Feature". Optional when base is given; the base extent is kept as-is when no items are provided. |
item_links |
array of strings | no | [] |
STAC Item JSON locations to fetch and derive from — http(s) URLs, s3:// URIs, or paths on the EPT service filesystem. Unreadable links are reported as warnings and skipped. Combined with any inline items. |
source_prefix |
string | no | null |
Local directory or s3://bucket/prefix whose *.json files are the collection's items. Mutually exclusive with items/item_links and with the export fields. Always exports: collection.json is written inside the prefix and the item files are re-linked in place (collection id, root/parent/collection links). |
base |
object | no | null |
Existing STAC Collection to copy metadata from (title, description, license, providers). Must have type == "Collection" and an id. Its id's last segment prefixes the proposed id; its extent is recomputed when items are given. |
id |
string | no | null |
Explicit collection id. Ids are flat: no / or \, no empty/./.. segments. When omitted, one is proposed (see below). |
title |
string | no | null |
Human-readable title; also seeds the id slug. |
description |
string | no | null |
Collection description. |
license |
string | no | null |
SPDX license identifier; defaults to the base's, the items' shared license, or other. |
bucket |
string | no | null |
Destination S3 bucket. Defaults to your personal EDITO bucket oidc-<username> derived from your bearer token; other buckets you can access, e.g. project buckets project-<projectid>, are equally valid. Must be a bucket name without s3:// or an object key. Only valid with target. |
target |
string | no | null |
Destination folder: an S3 prefix within bucket. collection.json plus one file per item is written inside it. Omit to preview only. |
local_output |
string | no | null |
Write to this directory on the EPT filesystem instead of S3. Takes precedence over target/bucket. |
overwrite |
bool | no | false |
Replace an existing collection.json. With source_prefix, item files are always re-linked in place; overwrite only guards collection.json. |
endpoint_url, access_key_id, secret_access_key, session_token |
string | no | null |
Request-scoped S3 credentials for s3:// sources/targets; falls back to the service-level S3_* environment when omitted. Provide all three credential fields or none. |
Id proposal: an explicit id always wins. With a base it is <base id>-<slug>; otherwise <username>-<slug> from your bearer token. The slug is the title (or base title, or first item id) lowercased with non-alphanumeric runs collapsed to -, falling back to collection.
Response¶
{
"stac_object": {
"type": "Collection",
"stac_version": "1.1.0",
"id": "myusername-north-sea-bathymetry",
"title": "North Sea Bathymetry",
"description": "North Sea Bathymetry",
"license": "other",
"extent": {
"spatial": {"bbox": [[2.5, 51.0, 3.5, 52.0]]},
"temporal": {"interval": [["2024-06-01T00:00:00Z", "2024-06-01T00:00:00Z"]]}
},
"links": []
},
"warnings": [
"id proposed from your username and title slug: 'myusername-north-sea-bathymetry' — it must be unique within your catalog",
"license 'other' derived from the items",
"description fell back to title/id: set an explicit description in the builder form"
],
"status": "preview",
"exported": false,
"collection_uri": null,
"item_uris": []
}
stac_object— the derived collection:type,stac_version1.1.0,id,description,license,extent(union of the items), andtitle/providers/stac_extensionscarried over from the base when present.warnings— derivation notes: how the id was proposed, where the license came from, and what fell back to defaults.status—preview(nothing written) orcompleted(exported). When exporting,exportedis true andcollection_uri/item_uriscarry the full locations of the written (or re-linked)collection.jsonand item files.
Good to know¶
- Export names are safe:
collection.jsongoes to the target root and each item to<item-id>/<item-id>.json; ids that are unsafe as file/folder names (spaces,/,.., …) are slugified for the export (with a warning) while the item id itself stays untouched. Two items slugging to the same name are rejected. - Extent is a union:
bboxvalues of 4 or 6 are accepted (mixed 2D/3D items are projected to 2D), and datetimes come fromproperties.datetimeorproperties.start_datetime/end_datetime. Unparseable datetimes are ignored with a warning. - With no item geometry or datetime, the extent is copied from the base — or becomes a world-wide placeholder (
[-180,-90,180,90], open temporal interval) with a warning. - License is scanned per item in order of authority: top-level or
properties.license,properties.licenses[].id, then SPDX ids recovered fromproperties.constraints[].text. Items disagreeing on the license cannot be merged — the conflict is reported and the default (other) is used unless you passlicenseexplicitly. - In preview mode the exported
linksarray is empty: the catalog tree route wires root and item links when it copies the collection into a tree. - Malformed requests (bad base, invalid explicit id, unknown fields) fail with
422; service-level errors use400(derivation failure, e.g. no username in the token),409(target exists,overwritefalse), and404(missing source). Upstream fetch failures surface their HTTP status, or502when unreachable.