tilebox · lukasbindreiter · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -25,6 +25,7 @@ When adding or moving pages:
 3. Keep pages grouped by product area (`datasets/`, `workflows/`, `sdks/`, `guides/`, `api-reference/`).
 4. Keep the User Guides nav and the [Tilebox Cookbook](/guides/cookbook) in sync. Whenever you add, remove, rename, or move a `guides/**` page in `docs.json`, update `guides/cookbook.mdx` with the same guide metadata, and vice versa.
 5. Preserve the current pattern where high-level landing pages link to deeper pages via `Card`/`HeroCard` blocks.
+6. Give overview and landing pages an icon distinct from the icon of their containing navigation group.
 
 ## Diátaxis Mapping
 

diff --git a/api-reference/python/tilebox.datasets.assets/Asset.mdx b/api-reference/python/tilebox.datasets.assets/Asset.mdx
@@ -0,0 +1,70 @@
+---
+title: Asset
+icon: file
+---
+
+```python
+class Asset(
+    key: str,
+    primary: AssetLocation,
+    alternates: Mapping[str, AssetLocation] = {},
+    media_type: MediaType | str | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    roles: frozenset[KnownAssetRole | str] = frozenset(),
+    gsd: float | None = None,
+    bands: tuple[Band, ...] = (),
+    data_type: DataType = DataType.UNSPECIFIED,
+    nodata: float | None = None,
+    statistics: Statistics | None = None,
+    unit: str | None = None,
+    eo: EOProperties | None = None,
+    raster: RasterProperties | None = None,
+    projection: Projection | None = None,
+    view: View | None = None,
+    classes: tuple[ClassificationClass, ...] = (),
+    file: File | None = None,
+    sar: SARProperties | None = None,
+    satellite: SatelliteProperties | None = None,
+    product: ProductProperties | None = None,
+)
+```
+
+Describe an asset and its primary and alternate locations.
+
+## Fields
+
+<ParamField path="key" type="str">
+  The asset's unique key within its datapoint.
+</ParamField>
+<ParamField path="primary" type="AssetLocation">
+  The primary asset location.
+</ParamField>
+<ParamField path="alternates" type="Mapping[str, AssetLocation]">
+  Alternate locations keyed by their STAC alternate-assets key.
+</ParamField>
+<ParamField path="media_type" type="MediaType | str | None">
+  The exact media type.
+</ParamField>
+<ParamField path="roles" type="frozenset[KnownAssetRole | str]">
+  Known or custom STAC asset roles.
+</ParamField>
+<ParamField path="bands" type="tuple[Band, ...]">
+  Ordered band metadata.
+</ParamField>
+
+The other fields contain optional STAC metadata defined by extensions such as [Electro-Optical](https://github.com/stac-extensions/eo), [Projection](https://github.com/stac-extensions/projection), and [Raster](https://github.com/stac-extensions/raster).
+
+## Media types
+
+Import `MediaType` with the authoring types from `tilebox.datasets.assets`. Its members are strings, such as `MediaType.GEOTIFF`, `MediaType.CLOUD_OPTIMIZED_GEOTIFF`, `MediaType.PNG`, and `MediaType.NETCDF`. You can also pass a custom media type string.
+
+```python Python
+from tilebox.datasets.assets import Asset, AssetLocation, MediaType
+
+asset = Asset(
+    key="image",
+    primary=AssetLocation("s3://bucket/image.tif"),
+    media_type=MediaType.CLOUD_OPTIMIZED_GEOTIFF,
+)
+```
diff --git a/api-reference/python/tilebox.datasets.assets/AssetCollection.from_assets.mdx b/api-reference/python/tilebox.datasets.assets/AssetCollection.from_assets.mdx
@@ -0,0 +1,23 @@
+---
+title: AssetCollection.from_assets
+icon: folder-open
+---
+
+```python
+@classmethod
+def AssetCollection.from_assets(
+    assets: Iterable[Asset],
+) -> AssetCollection
+```
+
+Create a normalized semantic asset collection.
+
+## Parameters
+
+<ParamField path="assets" type="Iterable[Asset]">
+  Assets with nonempty, unique keys.
+</ParamField>
+
+## Returns
+
+A read-only `AssetCollection` keyed by each asset's key.
diff --git a/api-reference/python/tilebox.datasets.assets/AssetCollection.from_datapoint.mdx b/api-reference/python/tilebox.datasets.assets/AssetCollection.from_datapoint.mdx
@@ -0,0 +1,29 @@
+---
+title: AssetCollection.from_datapoint
+icon: folder-open
+---
+
+```python
+@classmethod
+def AssetCollection.from_datapoint(
+    datapoint: xarray.Dataset,
+    *,
+    fields: AssetFieldNames | None = None,
+) -> AssetCollection
+```
+
+Resolve the assets attached to exactly one scalar xarray datapoint.
+
+## Parameters
+
+<ParamField path="datapoint" type="xarray.Dataset">
+  A scalar dataset containing exactly one datapoint.
+</ParamField>
+<ParamField path="fields" type="AssetFieldNames | None">
+  Optional names for the `assets`, `storage`, and `authentication` variables
+  when automatic discovery is ambiguous.
+</ParamField>
+
+## Returns
+
+An `AssetCollection` keyed by asset key.
diff --git a/api-reference/python/tilebox.datasets.assets/AssetCollection.mdx b/api-reference/python/tilebox.datasets.assets/AssetCollection.mdx
@@ -0,0 +1,12 @@
+---
+title: AssetCollection
+icon: folder-open
+---
+
+```python
+class AssetCollection(Mapping[str, Asset])
+```
+
+Represent the assets belonging to one dataset datapoint as a read-only mapping keyed by asset key.
+
+Create a collection with `AssetCollection.from_assets`, resolve one from a scalar datapoint with `AssetCollection.from_datapoint`, or convert it to ingestion fields with `AssetCollection.to_fields`.
diff --git a/api-reference/python/tilebox.datasets.assets/AssetCollection.to_fields.mdx b/api-reference/python/tilebox.datasets.assets/AssetCollection.to_fields.mdx
@@ -0,0 +1,31 @@
+---
+title: AssetCollection.to_fields
+icon: folder-open
+---
+
+```python
+def AssetCollection.to_fields(
+    *,
+    fields: AssetFieldNames | None = None,
+    storage: Storage | None = None,
+    authentication: Authentication | None = None,
+) -> dict[str, Assets | Storage | Authentication]
+```
+
+Convert the collection to fields ready for dataset ingestion.
+
+## Parameters
+
+<ParamField path="fields" type="AssetFieldNames | None">
+  Optional output names for the assets, storage, and authentication fields.
+</ParamField>
+<ParamField path="storage" type="Storage | None">
+  Additional storage registry entries to retain.
+</ParamField>
+<ParamField path="authentication" type="Authentication | None">
+  Additional authentication registry entries to retain.
+</ParamField>
+
+## Returns
+
+A field-name mapping containing `Assets` and any nonempty `Storage` or `Authentication` fields.
diff --git a/api-reference/python/tilebox.datasets.assets/AssetLocation.mdx b/api-reference/python/tilebox.datasets.assets/AssetLocation.mdx
@@ -0,0 +1,33 @@
+---
+title: AssetLocation
+icon: location-dot
+---
+
+```python
+class AssetLocation(
+    href: str,
+    alternate_name: str | None = None,
+    storage_schemes: Mapping[str, StorageScheme] = {},
+    authentication_schemes: Mapping[str, AuthenticationScheme] = {},
+)
+```
+
+Describe an asset URL and the storage and authentication schemes that apply to it.
+
+## Fields
+
+<ParamField path="href" type="str">
+  The fully resolved asset URL.
+</ParamField>
+<ParamField path="alternate_name" type="str | None">
+  The optional STAC alternate-assets display name.
+</ParamField>
+<ParamField path="storage_schemes" type="Mapping[str, StorageScheme]">
+  Storage schemes keyed by their exact registry keys.
+</ParamField>
+<ParamField
+  path="authentication_schemes"
+  type="Mapping[str, AuthenticationScheme]"
+>
+  Authentication schemes keyed by their exact registry keys.
+</ParamField>
diff --git a/api-reference/python/tilebox.datasets.assets/Band.mdx b/api-reference/python/tilebox.datasets.assets/Band.mdx
@@ -0,0 +1,40 @@
+---
+title: Band
+icon: layer-group
+---
+
+```python
+class Band(
+    name: str | None = None,
+    description: str | None = None,
+    data_type: DataType = DataType.UNSPECIFIED,
+    nodata: float | None = None,
+    unit: str | None = None,
+    eo: EOProperties | None = None,
+    raster: RasterProperties | None = None,
+    classes: tuple[ClassificationClass, ...] = (),
+    sar: SARProperties | None = None,
+)
+```
+
+Describe one asset band, with unspecified values inherited from the asset when an `AssetCollection` is created.
+
+## Fields
+
+<ParamField path="name" type="str | None">
+  The band name.
+</ParamField>
+<ParamField path="description" type="str | None">
+  A human-readable description.
+</ParamField>
+<ParamField path="data_type" type="DataType">
+  The raster data type.
+</ParamField>
+<ParamField path="nodata" type="float | None">
+  The nodata value.
+</ParamField>
+<ParamField path="unit" type="str | None">
+  The unit name.
+</ParamField>
+
+The `eo`, `raster`, `classes`, and `sar` fields hold generated extension metadata.
diff --git a/api-reference/python/tilebox.datasets/Client.create_or_update_dataset.mdx b/api-reference/python/tilebox.datasets/Client.create_or_update_dataset.mdx
@@ -75,6 +75,24 @@ a new queryable field is only supported while the dataset is empty.
 <ParamField path="shapely.Geometry" type="type">
   A geometry field
 </ParamField>
+<ParamField path="Assets" type="type">
+  STAC asset metadata. Import from `tilebox.datasets.schema`.
+</ParamField>
+<ParamField path="Authentication" type="type">
+  STAC authentication metadata. Import from `tilebox.datasets.schema`.
+</ParamField>
+<ParamField path="Links" type="type">
+  STAC link metadata. Import from `tilebox.datasets.schema`.
+</ParamField>
+<ParamField path="ProcessingSoftware" type="type">
+  STAC processing software metadata. Import from `tilebox.datasets.schema`.
+</ParamField>
+<ParamField path="Provider" type="type">
+  STAC provider metadata. Import from `tilebox.datasets.schema`.
+</ParamField>
+<ParamField path="Storage" type="type">
+  STAC storage metadata. Import from `tilebox.datasets.schema`.
+</ParamField>
 
 Note that the type can also be a list of one of the types, indicating that the field is an array, e.g. `list[str]`.
 

diff --git a/api-reference/python/tilebox.datasets/Collection.ingest.mdx b/api-reference/python/tilebox.datasets/Collection.ingest.mdx
@@ -24,10 +24,13 @@ Ingest data into a collection.
   The data to ingest.
 
   Supported `IngestionData` data types are:
-  - A `pandas.DataFrame`, mapping the column names to dataset fields.
-  - An `xarray.Dataset`, mapping variables and coordinates to dataset fields.
-  - An `Iterable`, `dict` or `nd-array`: ingest any object that can be converted to a `pandas.DataFrame` using
-    its constructor, equivalent to `ingest(pd.DataFrame(data))`.
+  - An iterable of mappings, with one mapping per datapoint.
+  - A mapping from field names to ordered sequences, `numpy.ndarray` objects, or `pandas.Series` objects.
+  - A `pandas.DataFrame`, with column names mapped to dataset fields.
+  - An `xarray.Dataset`, with variables and coordinates mapped to dataset fields.
+
+  A mapping is always interpreted as column-oriented data. Wrap a single record in an iterable, such as `[record]`.
+  Every datapoint must include `time`. Tilebox generates `id` and `ingestion_time`. Missing optional values leave their corresponding fields unset.
 </ParamField>
 <ParamField path="allow_existing" type="bool">
   Datapoint fields are used to generate a deterministic unique `UUID` for each
@@ -47,16 +50,18 @@ List of datapoint IDs that were ingested, including the IDs of existing data poi
 
 <RequestExample>
 ```python Python
-import pandas as pd
-
-collection.ingest(pd.DataFrame({
-    "time": [
-      "2023-05-01T12:00:00Z",
-      "2023-05-02T12:00:00Z",
-    ],
-    "value": [1, 2],
-    "sensor": ["A", "B"],
-}))
+collection.ingest([
+    {
+        "time": "2023-05-01T12:00:00Z",
+        "value": 1,
+        "sensor": "A",
+    },
+    {
+        "time": "2023-05-02T12:00:00Z",
+        "value": 2,
+        "sensor": "B",
+    },
+])
 ```
 </RequestExample>
 

diff --git a/api-reference/python/tilebox.storage.aio/AssetAccessPolicy.mdx b/api-reference/python/tilebox.storage.aio/AssetAccessPolicy.mdx
@@ -0,0 +1,20 @@
+---
+title: AssetAccessPolicy
+icon: list-ol
+---
+
+```python
+class AssetAccessPolicy(
+    preferred_schemes: tuple[str, ...] = (
+        "file", "s3", "gs", "az", "https", "http"
+    ),
+)
+```
+
+Control the order in which `Client.resolve` considers asset location schemes.
+
+## Fields
+
+<ParamField path="preferred_schemes" type="tuple[str, ...]">
+  URI schemes in descending preference order.
+</ParamField>
diff --git a/api-reference/python/tilebox.storage.aio/Client.download.mdx b/api-reference/python/tilebox.storage.aio/Client.download.mdx
@@ -0,0 +1,31 @@
+---
+title: Client.download
+icon: download
+---
+
+```python
+async def Client.download(
+    asset: Asset,
+    destination: str | PathLike[str],
+    *,
+    overwrite: bool = False,
+) -> Path
+```
+
+Atomically download an asset to an exact local path.
+
+## Parameters
+
+<ParamField path="asset" type="Asset">
+  The asset to resolve and download.
+</ParamField>
+<ParamField path="destination" type="str | PathLike[str]">
+  The destination path. Missing parent directories are created.
+</ParamField>
+<ParamField path="overwrite" type="bool">
+  Whether to replace an existing destination. Defaults to `False`.
+</ParamField>
+
+## Returns
+
+The destination as a `Path`.