<!-- Source: https://docs.geopera.com/api-reference/operations/items · Markdown for LLMs -->

<!-- AUTO-GENERATED by scripts/generate-api-reference.cjs from the committed OpenAPI spec. Do not edit by hand. -->

# 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](/api-reference/operations) 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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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 | Description |
|---|---|---|---|
| `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`.