Build a STAC Collection¶
Build a STAC Collection from individual fields, from a complete JSON object, or from an existing collection fetched by URL — provided fields override the base. Preview the JSON, or export it as collection.json to S3 or a local folder, ready for create catalog tree to stitch into a tree.
Endpoint¶
Authentication: Authorization: Bearer <access_token>.
Usage¶
curl -X POST "${EPT_API_URL}/v1/stac/objects/collection" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
"id": "observations-2025",
"description": "Observations collected in 2025.",
"license": "CC-BY-4.0",
"extent": {
"spatial": {"bbox": [[2.5, 51.0, 4.5, 51.6]]},
"temporal": {"interval": [["2025-01-01T00:00:00Z", null]]}
},
"links": [
{"rel": "root", "href": "s3://oidc-<username>/catalog-1/catalog.json"},
{"rel": "parent", "href": "s3://oidc-<username>/catalog-1/catalog.json"},
{"rel": "child", "href": "s3://oidc-<username>/catalog-1/observations-2025-01.json"}
],
"target": "catalog-1"
}'
Request¶
Build from fields — id is the only required field (it may be omitted only when stac_json or source_url provides the base):
{
"id": "observations-2025",
"description": "Observations collected in 2025.",
"extent": {
"spatial": {"bbox": [[2.5, 51.0, 4.5, 51.6]]},
"temporal": {"interval": [["2025-01-01T00:00:00Z", null]]}
},
"license": "CC-BY-4.0",
"providers": [{"name": "VLIZ", "roles": ["producer"], "url": "https://www.vliz.be"}]
}
Edit mode — start from an existing object; explicitly provided fields override it:
{
"stac_json": {"type": "Collection", "id": "observations-2025", "stac_version": "1.0.0"},
"title": "Observations 2025 (revised)"
}
Export fields are identical to the catalog builder: bucket, target (append collection.json to it automatically; omit to preview only), local_output (false), overwrite (false), and the optional S3 connection fields endpoint_url, access_key_id, secret_access_key, session_token.
| Field | Type | Default | Notes |
|---|---|---|---|
id |
string | — | Required without a base object; pattern ^[A-Za-z0-9._\-~]+$ |
stac_json |
object | — | Complete collection used as the base object |
source_url |
URL | — | Fetch the base object (max 2048 chars, SSRF-guarded, public http(s) only) |
stac_extensions |
list[string] | [] |
Extension schema URLs |
title |
string | — | Human-readable title |
description |
string | — | Falls back to title, then id when omitted |
extent |
object | — | Spatial/temporal extent; without it a world-wide placeholder is used (with a warning) |
license |
string | proprietary |
SPDX license identifier or proprietary |
providers |
list[object] | [] |
e.g. {"name": ..., "roles": [...], "url": ...} |
links |
list[object] | [] |
Standard STAC links; each entry needs non-empty rel and href |
extra_fields |
object | {} |
Arbitrary top-level fields merged in last |
Unknown fields are rejected (extra="forbid").
Response¶
{
"stac_object": {
"type": "Collection",
"stac_version": "1.1.0",
"id": "observations-2025",
"description": "Observations collected in 2025.",
"license": "CC-BY-4.0",
"extent": {
"spatial": {"bbox": [[2.5, 51.0, 4.5, 51.6]]},
"temporal": {"interval": [["2025-01-01T00:00:00Z", null]]}
},
"links": [
{"rel": "root", "href": "s3://oidc-myusername/catalog-1/catalog.json"},
{"rel": "parent", "href": "s3://oidc-myusername/catalog-1/catalog.json"},
{"rel": "child", "href": "s3://oidc-myusername/catalog-1/observations-2025-01.json"},
{"rel": "self", "href": "s3://oidc-myusername/catalog-1/collection.json"}
]
},
"warnings": [],
"exported": true,
"target_uri": "s3://oidc-myusername/catalog-1/collection.json",
"status": "completed"
}
stac_object— the built collection as JSON.warnings— structural findings (e.g. missing extent, missing root link, description falling back to title/id).exported/target_uri— set whentargetwas given;statusiscompleted, otherwisepreview.
Good to know¶
- With S3 export,
targetis a prefix insidebucket(default: your personaloidc-<username>bucket from your bearer token);collection.jsonis appended automatically; atargetending in.jsonoverrides the file name instead of getting the suffix appended. - Exporting to an existing path returns
409unlessoverwrite=true. Bad input returns400; a failed base-object fetch returns502. - When
source_urlpoints at the EDITO STAC API, your bearer token is attached to the fetch automatically; for other URLs the fetch is anonymous. - The schema also requires
license— set an SPDX identifier such asCC-BY-4.0, or leave theproprietarydefault. - Link hrefs are plain and need not exist yet — create catalog tree can stitch the tree afterwards. Validate the tree before publishing.