Build a STAC Catalog¶
Build a STAC Catalog from individual fields, from a complete JSON object, or from an existing catalog fetched by URL — provided fields override the base. Preview the JSON, or export it as catalog.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/catalog" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
"id": "catalog-1",
"title": "My catalog",
"description": "Root catalog for my datasets.",
"links": [
{"rel": "root", "href": "s3://oidc-<username>/catalog-1/catalog.json"},
{"rel": "child", "href": "s3://oidc-<username>/catalog-1/collection.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):
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/catalog.json",
"title": "Renamed catalog"
}
Export fields (all optional):
{
"bucket": "oidc-myusername",
"target": "catalog-1",
"local_output": false,
"overwrite": false,
"endpoint_url": "https://minio.dive.edito.eu",
"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 catalog 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 |
links |
list[object] | [] |
Standard STAC links; each entry needs non-empty rel and href |
extra_fields |
object | {} |
Arbitrary top-level fields merged in last |
bucket |
string | your oidc-<username> bucket |
Bucket name only — no s3://, no / |
target |
string | — | Destination folder (S3 prefix, or local folder with local_output); omit to preview only |
local_output |
string or false |
false |
Directory on the EPT filesystem to write to instead of S3; false means not set |
overwrite |
bool | false |
Replace an existing target |
endpoint_url / access_key_id / secret_access_key / session_token |
string | service S3_* env |
For s3:// targets; the first three must be given together |
Unknown fields are rejected (extra="forbid").
Response¶
{
"stac_object": {
"type": "Catalog",
"stac_version": "1.1.0",
"id": "catalog-1",
"title": "My catalog",
"description": "Root catalog for my datasets.",
"links": [
{"rel": "root", "href": "s3://oidc-myusername/catalog-1/catalog.json"},
{"rel": "child", "href": "s3://oidc-myusername/catalog-1/collection.json"},
{"rel": "self", "href": "s3://oidc-myusername/catalog-1/catalog.json"}
]
},
"warnings": [],
"exported": true,
"target_uri": "s3://oidc-myusername/catalog-1/catalog.json",
"status": "completed"
}
stac_object— the built catalog as JSON.warnings— structural findings that keep it from being fully spec-compliant (e.g. missing root link, missing child links, description falling back to title/id).exported/target_uri— set whentargetwas given;statusiscompleted, otherwisepreview.
Good to know¶
- Omit
targetfor a pure preview — nothing is written andstatusispreview. - With S3 export (default),
targetis a prefix insidebucket, which defaults to your personal EDITO bucketoidc-<username>derived from your bearer token.catalog.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. - Link hrefs are plain and need not exist yet — create catalog tree can stitch the tree afterwards. Validate the tree before publishing.