Items operations

Work with delivered imagery items and their assets.

Each operation below is reachable at POST /v1/op/{operation_id} or the resource path POST /v1/{resource}/{action}, with a Bearer token (a gpra_ API key or a session token). Back to the Operations Reference index.

`items.asset.download`

Issue a signed, egress-tracked download URL for an item’s asset.


Scope	`items:read`
Side-effect	export
HTTP	`POST /v1/op/items.asset.download` · `POST /v1/items/asset/download`
Python / TypeScript	`client.items.asset.download(…)`
CLI	`geopera items asset download …`

Request — AssetDownloadInput

Field	Type	Required	Description
`item_id`	string	yes
`asset_id`	string	yes

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.create`

Create an item within a project (editor/admin on the project).


Scope	`items:write`
Side-effect	compute
HTTP	`POST /v1/op/items.create` · `POST /v1/items/create`
Python / TypeScript	`client.items.create(…)`
CLI	`geopera items create …`

Request — ItemCreateInput

Field	Type	Required	Description
`collection_id`	string	—
`stac_id`	string	—
`type`	ItemType	yes
`geometry`	object	—
`bbox`	array of number	—
`datetime`	string	—	ISO 8601 datetime
`start_datetime`	string	—
`end_datetime`	string	—
`cloud_cover`	number	—
`gsd`	number	—
`name`	string	yes
`description`	string	—
`properties`	object	—
`stac_extensions`	array of string	—
`order_id`	string	—
`upload_id`	string	—
`job_id`	string	—
`project_id`	string	yes

Response — ItemResponse.

`items.delete`

Soft-delete an item (admin/editor on the item’s project required).


Scope	`items:write`
Side-effect	destructive
HTTP	`POST /v1/op/items.delete` · `POST /v1/items/delete`
Python / TypeScript	`client.items.delete(…)`
CLI	`geopera items delete …`

Request — ItemDeleteInput

Field	Type	Required	Description
`item_id`	string	yes	The item to soft-delete.

Response — ItemDeleteOutput.

`items.detect_asset_bands`

Auto-detect band names for an asset from its reflectance statistics.


Scope	`items:read`
Side-effect	compute
HTTP	`POST /v1/op/items.detect_asset_bands` · `POST /v1/items/detect_asset_bands`
Python / TypeScript	`client.items.detect_asset_bands(…)`
CLI	`geopera items detect-asset-bands …`

Request — DetectBandsInput

Field	Type	Required	Description
`item_id`	string	yes
`asset_id`	string	yes

Response — DetectBandsOutput.

`items.duplicate`

Duplicate an item with its assets + viz profiles (admin/editor on the project).


Scope	`items:write`
Side-effect	compute
HTTP	`POST /v1/op/items.duplicate` · `POST /v1/items/duplicate`
Python / TypeScript	`client.items.duplicate(…)`
CLI	`geopera items duplicate …`

Request — ItemDuplicateInput

Field	Type	Required	Description
`item_id`	string	yes
`new_name`	string	—	Name for the copy
`target_collection_id`	string	—
`target_project_id`	string	—

Response — ItemResponse.

`items.get`

Fetch a single catalog item by id.


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.get` · `POST /v1/items/get`
Python / TypeScript	`client.items.get(…)`
CLI	`geopera items get …`

Request — ItemGetInput

Field	Type	Required	Description
`item_id`	string	yes

Response — ItemGetOutput.

`items.get_stac`

Get an item as a full STAC 1.0.0 Feature with embedded assets + links.


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.get_stac` · `POST /v1/items/get_stac`
Python / TypeScript	`client.items.get_stac(…)`
CLI	`geopera items get-stac …`

Request — ItemStacInput

Field	Type	Required	Description
`item_id`	string	yes
`base_url`	string	—

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.lineage`

Get the lineage tree (parents + children) for an item.


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.lineage` · `POST /v1/items/lineage`
Python / TypeScript	`client.items.lineage(…)`
CLI	`geopera items lineage …`

Request — ItemLineageInput

Field	Type	Required	Description
`item_id`	string	yes

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.list`

List a project’s items (optionally filtered by collection).


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.list` · `POST /v1/items/list`
Python / TypeScript	`client.items.list(…)`
CLI	`geopera items list …`

Request — ItemsListInput

Field	Type	Required
`project_id`	string	yes
`collection_id`	string	—
`uncollected`	boolean	—
`limit`	integer	—
`offset`	integer	—

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.list_assets`

List all assets (files) attached to an item.


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.list_assets` · `POST /v1/items/list_assets`
Python / TypeScript	`client.items.list_assets(…)`
CLI	`geopera items list-assets …`

Request — ItemAssetsInput

Field	Type	Required	Description
`item_id`	string	yes

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.list_by_collection`

List items in a collection (access via the collection’s project).


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.list_by_collection` · `POST /v1/items/list_by_collection`
Python / TypeScript	`client.items.list_by_collection(…)`
CLI	`geopera items list-by-collection …`

Request — ItemsByCollectionInput

Field	Type	Required
`collection_id`	string	yes
`limit`	integer	—
`offset`	integer	—

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.search`

Search a project’s items with STAC-compatible filters (project member access).


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.search` · `POST /v1/items/search`
Python / TypeScript	`client.items.search(…)`
CLI	`geopera items search …`

Request — ProjectItemSearchInput

Field	Type	Required	Description
`bbox`	array of number	—
`datetime`	string	—
`limit`	integer	—
`offset`	integer	—
`collections`	array of string	—
`type`	ItemType	—
`query`	object	—
`sortby`	array of object	—
`project_id`	string	yes
`format`	string	—	‘stac’ for full STAC features
`base_url`	string	—	Base URL for STAC links (stac format only)

Response — FeatureCollectionOutput.

`items.search_org`

Search all items across the caller’s organization (STAC-compatible).


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.search_org` · `POST /v1/items/search_org`
Python / TypeScript	`client.items.search_org(…)`
CLI	`geopera items search-org …`

Request — OrgItemSearchInput

Field	Type	Required
`bbox`	array of number	—
`datetime`	string	—
`limit`	integer	—
`offset`	integer	—
`collections`	array of string	—
`type`	ItemType	—
`query`	object	—
`sortby`	array of object	—
`format`	string	—
`base_url`	string	—

Response — FeatureCollectionOutput.

`items.set_asset_band_names`

Rename the bands on an item’s asset (project member access).


Scope	`items:write`
Side-effect	compute
HTTP	`POST /v1/op/items.set_asset_band_names` · `POST /v1/items/set_asset_band_names`
Python / TypeScript	`client.items.set_asset_band_names(…)`
CLI	`geopera items set-asset-band-names …`

Request — SetBandNamesInput

Field	Type	Required
`item_id`	string	yes
`asset_id`	string	yes
`band_names`	array of string	yes

Response — AssetOutput.

`items.tile.render`

Render a map tile for one of our catalog items (profile or direct-param).


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.tile.render` · `POST /v1/items/tile/render`
Python / TypeScript	`client.items.tile.render(…)`
CLI	`geopera items tile render …`

Request — ItemTileRenderInput

Field	Type	Required
`item_id`	string	yes
`z`	integer	yes
`x`	integer	yes
`y`	integer	yes
`format`	string	—
`profile`	string	—
`asset_key`	string	—
`expression`	string	—
`bands`	string	—
`rescale`	string	—
`colormap`	string	—
`quality`	integer	—

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.tile.statistics`

Global expression statistics (p2/p98 rescale) from the smallest COG overview.


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.tile.statistics` · `POST /v1/items/tile/statistics`
Python / TypeScript	`client.items.tile.statistics(…)`
CLI	`geopera items tile statistics …`

Request — ItemStatisticsInput

Field	Type	Required
`item_id`	string	yes
`expression`	string	yes
`asset_key`	string	—
`profile`	string	—

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.tile.tilejson`

TileJSON metadata for one of our catalog items.


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.tile.tilejson` · `POST /v1/items/tile/tilejson`
Python / TypeScript	`client.items.tile.tilejson(…)`
CLI	`geopera items tile tilejson …`

Request — ItemTilejsonInput

Field	Type	Required
`item_id`	string	yes
`profile`	string	—
`asset_key`	string	—

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.tile.wmts_capabilities`

OGC WMTS 1.0.0 GetCapabilities XML for one of our items.


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.tile.wmts_capabilities` · `POST /v1/items/tile/wmts_capabilities`
Python / TypeScript	`client.items.tile.wmts_capabilities(…)`
CLI	`geopera items tile wmts-capabilities …`

Request — ItemWmtsCapabilitiesInput

Field	Type	Required
`item_id`	string	yes
`base_url`	string	yes
`key`	string	—
`profile`	string	—

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.tile.wmts_get_tile`

OGC WMTS GetTile (KVP) for one of our items.


Scope	`items:read`
Side-effect	read
HTTP	`POST /v1/op/items.tile.wmts_get_tile` · `POST /v1/items/tile/wmts_get_tile`
Python / TypeScript	`client.items.tile.wmts_get_tile(…)`
CLI	`geopera items tile wmts-get-tile …`

Request — ItemWmtsGetTileInput

Field	Type	Required
`item_id`	string	yes
`z`	integer	yes
`x`	integer	yes
`y`	integer	yes
`profile`	string	—

Response — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

`items.update`

Update an item’s mutable metadata (editor/admin on its project).


Scope	`items:write`
Side-effect	compute
HTTP	`POST /v1/op/items.update` · `POST /v1/items/update`
Python / TypeScript	`client.items.update(…)`
CLI	`geopera items update …`

Request — ItemUpdateInput

Field	Type	Required
`collection_id`	string	—
`name`	string	—
`description`	string	—
`geometry`	object	—
`bbox`	array of number	—
`datetime`	string	—
`cloud_cover`	number	—
`gsd`	number	—
`properties`	object	—
`lifecycle_state`	LifecycleState	—
`item_id`	string	yes

Response — ItemResponse.