Build a STAC Item¶
Build a STAC Item from individual fields, from a complete JSON object, or from an existing item fetched by URL — provided fields override the base. Preview the JSON, or export it as item.json to S3 or a local folder, ready for create catalog tree to stitch into a tree.
Endpoint¶
POST /v1/stac/objects/item # build (create from fields, or overlay a base)
PUT /v1/stac/objects/item # edit (replace an existing item; base required)
Authentication: Authorization: Bearer <access_token>.
Usage¶
curl -X POST "${EPT_API_URL}/v1/stac/objects/item" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
"id": "observations-2025-01",
"bbox": [2.5, 51.0, 4.5, 51.6],
"datetime": "2025-01-15T10:30:00Z",
"collection": "observations-2025",
"properties": {"platform": "sentinel-3a"},
"assets": {
"data": {
"href": "s3://oidc-<username>/catalog-1/observations-2025-01.zarr",
"type": "application/vnd+zarr",
"roles": ["data"]
}
},
"links": [
{"rel": "root", "href": "s3://oidc-<username>/catalog-1/catalog.json"},
{"rel": "parent", "href": "s3://oidc-<username>/catalog-1/collection.json"}
],
"target": "catalog-1"
}'
Request¶
Build from fields — id plus temporal and spatial info are what the STAC spec demands:
{
"id": "observations-2025-01",
"bbox": [2.5, 51.0, 4.5, 51.6],
"datetime": "2025-01-15T10:30:00Z"
}
For a time interval instead of an instant, use start_datetime + end_datetime (each requires the other). geometry is derived from bbox automatically, and vice versa.
Edit mode — start from an existing object; explicitly provided fields override it:
{
"source_url": "https://minio.dive.edito.eu/oidc-myusername/project-id/catalog-1/item.json",
"title": "Revised title"
}
Export fields are identical to the catalog builder: bucket, target (item.json is appended 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 item 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 / description |
string | — | Stored in item properties |
geometry |
object | from bbox |
GeoJSON geometry |
bbox |
list[float] | from geometry |
4 or 6 coordinates |
datetime |
string | — | ISO 8601 instant |
start_datetime / end_datetime |
string | — | ISO 8601 interval; must be given as a pair |
properties |
object | {} |
Extra STAC properties; explicit title/description/datetime fields win on conflict |
collection |
string | — | Id of the collection this item belongs to |
assets |
object | {} |
Named assets; each value needs at least href |
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": "Feature",
"stac_version": "1.1.0",
"id": "observations-2025-01",
"geometry": {
"type": "Polygon",
"coordinates": [[[2.5, 51.0], [4.5, 51.0], [4.5, 51.6], [2.5, 51.6], [2.5, 51.0]]]
},
"bbox": [2.5, 51.0, 4.5, 51.6],
"properties": {
"datetime": "2025-01-15T10:30:00Z",
"platform": "sentinel-3a"
},
"collection": "observations-2025",
"assets": {
"data": {
"href": "s3://oidc-myusername/catalog-1/observations-2025-01.zarr",
"type": "application/vnd+zarr",
"roles": ["data"]
}
},
"links": [
{"rel": "root", "href": "s3://oidc-myusername/catalog-1/catalog.json"},
{"rel": "parent", "href": "s3://oidc-myusername/catalog-1/collection.json"},
{"rel": "collection", "href": "./collection.json"},
{"rel": "self", "href": "s3://oidc-myusername/catalog-1/item.json"}
]
},
"warnings": [],
"exported": true,
"target_uri": "s3://oidc-myusername/catalog-1/item.json",
"status": "completed"
}
stac_object— the built item as JSON.warnings— structural findings (e.g. no root link, no temporal info, neither geometry nor bbox,bboxwith other than 4 or 6 coordinates).exported/target_uri— set whentargetwas given;statusiscompleted, otherwisepreview.
Editing with PUT¶
PUT /v1/stac/objects/item is the edit form of the same route: the base item
comes from source_url (fetched, SSRF-guarded) or inline stac_json, and the
provided fields override it with a shallow merge — provided fields win, the
base's other fields survive, null does not delete. Omit target to preview
the replacement; set target/local_output to write it. A PUT without a base
(stac_json/source_url) fails with 400; an existing target without
overwrite=true fails with 409.
curl -X PUT "${EPT_API_URL}/v1/stac/objects/item" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
"source_url": "https://minio.dive.edito.eu/<bucket>/<workspace>/items/item-1.json",
"title": "Updated title",
"target": "<workspace>/items"
}'
Good to know¶
- An item needs
datetimeorstart_datetime+end_datetime. Building from fields without any temporal info fails with400; an overlaid base item without temporal info is accepted but warned about. - Setting only
geometryderives thebbox(and vice versa); neither is required at request time, but an item with neither gets a warning. - If
collectionis set but norel=collectionlink is, acollection.jsonsibling link is synthesized — the STAC 1.1 schema requires it. title,descriptionand the datetime fields are stored insideproperties.datetimegiven as an instant is normalized by pystac; interval fields go into properties directly.- Non-ISO 8601 timestamps, malformed assets/geometry, or an unusable
targetreturn400. An existing target returns409unlessoverwrite=true; a failed base-object fetch returns502. - Link hrefs are plain and need not exist yet — create catalog tree can stitch the tree afterwards. Validate the tree before publishing.