# Models

## The AddDatasetResponse object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"}},"type":"object","required":["dataset_id","dataset_version_id"],"title":"AddDatasetResponse"}}}}
```

## The AddImageDatasetRequest object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddImageDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"image","title":"Type","default":"image"},"urls":{"items":{"type":"string"},"type":"array","title":"Urls","description":"List of URLs or wildcards to the image files. Wildcards are supported using the ``*`` character. e.g. ``gs://example-bucket/image_*.tif``"},"bands":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Bands","description":"List of bands to add to the dataset. If not provided, all bands will be added."},"groupby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Groupby","description":"[DEPRECATED] Will be ignored. If `filename_date_pattern` or `filename_band_pattern` are provided, those will be used as group keys for a time dimension and variables respectively. Otherwise, this defaults to putting all images onto the same plane.","deprecated":true},"filename_date_pattern":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename Date Pattern","description":"Pattern to extract the date from the filename."},"filename_band_pattern":{"anyOf":[{"items":{"$ref":"#/components/schemas/FilenameBandPattern"},"type":"array"},{"type":"null"}],"title":"Filename Band Pattern","description":"Pattern to extract the band from the filename."}},"type":"object","required":["name","urls"],"title":"AddImageDatasetRequest","description":"Request to add an image dataset"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"FilenameBandPattern":{"properties":{"pattern":{"type":"string","title":"Pattern"},"band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Band"},"band_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Band Mapping"}},"type":"object","required":["pattern"],"title":"FilenameBandPattern","description":"Pattern for mapping filename patterns to band names"}}}}
```

## The AddTileServerDatasetRequest object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddTileServerDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"tileserver","title":"Type","default":"tileserver"},"url":{"type":"string","title":"Url","description":"URL to an XYZ tile server."}},"type":"object","required":["name","url"],"title":"AddTileServerDatasetRequest"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}}
```

## The AddVectorDatasetRequest object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddVectorDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"vector","title":"Type","default":"vector"},"url":{"type":"string","title":"Url","description":"URL to the vector dataset."},"coordinate_precision":{"type":"string","enum":["auto","1250m","600m","300m","150m","80m","40m","20m","10m","5m","2m","1m","50cm","25cm","15cm","8cm"],"title":"Coordinate Precision","description":"Controls the approximate precision of coordinates in the optimized dataset. 'auto' tries to detect an appropriate precision. Other values specify the desired coordinate precision explicitly.","default":"auto"}},"type":"object","required":["name","url"],"title":"AddVectorDatasetRequest","description":"Request to add a vector dataset"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}}
```

## The AddZarrDatasetRequest object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddZarrDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"zarr","title":"Type","default":"zarr"},"urls":{"items":{"type":"string"},"type":"array","title":"Urls","description":"List of URLs to the Zarr files. Currently only supports 1 URL. Can contain a placeholder for the dimension name. If specified, this concatenates multiple Zarrs along either an existing or new dimension as named in the pattern."},"rename":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Rename"}},"type":"object","required":["name","urls"],"title":"AddZarrDatasetRequest","description":"Request to add a Zarr dataset"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}}
```

## The DatasetLabel object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}}
```

## The DatasetResponse object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"DatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"variables":{"additionalProperties":{"$ref":"#/components/schemas/Variable"},"type":"object","title":"Variables"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"visualization_optimization":{"$ref":"#/components/schemas/Optimization"},"pixel_info_optimizations":{"additionalProperties":{"$ref":"#/components/schemas/Optimization"},"type":"object","title":"Pixel Info Optimizations"},"dynamic_tile_server":{"$ref":"#/components/schemas/TileServer"},"optimized_tile_server":{"anyOf":[{"$ref":"#/components/schemas/TileServer"},{"type":"null"}]}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","visualization_optimization","dynamic_tile_server","optimized_tile_server"],"title":"DatasetResponse"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"Variable":{"properties":{"sampled_min":{"type":"number","title":"Sampled Min"},"sampled_max":{"type":"number","title":"Sampled Max"}},"type":"object","required":["sampled_min","sampled_max"],"title":"Variable","description":"Estimated statistics for a variable in the dataset, useful for visualization"},"Optimization":{"properties":{"status":{"type":"string","enum":["not_started","pending","running","success","error"],"title":"Status"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["status"],"title":"Optimization"},"TileServer":{"properties":{"tile_url":{"type":"string","title":"Tile Url"},"pixel_url":{"type":"string","title":"Pixel Url"},"min_zoom":{"type":"integer","title":"Min Zoom"},"max_zoom":{"type":"integer","title":"Max Zoom"}},"type":"object","required":["tile_url","pixel_url","min_zoom","max_zoom"],"title":"TileServer"}}}}
```

## The DatasetType object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"}}}}
```

## The DeleteDatasetResponse object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"DeleteDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"}},"type":"object","required":["dataset_id","dataset_version_id"],"title":"DeleteDatasetResponse"}}}}
```

## The ErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"properties":{"message":{"type":"string","title":"Message"},"error_class":{"type":"string","title":"Error Class"}},"type":"object","required":["message","error_class"],"title":"ErrorResponse"}}}}
```

## The FilenameBandPattern object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"FilenameBandPattern":{"properties":{"pattern":{"type":"string","title":"Pattern"},"band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Band"},"band_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Band Mapping"}},"type":"object","required":["pattern"],"title":"FilenameBandPattern","description":"Pattern for mapping filename patterns to band names"}}}}
```

## The HTTPValidationError object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## The ListDatasetResponse object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"ListDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","updated_at"],"title":"ListDatasetResponse","description":"Single entry in the list of datasets with a subset of information"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}}
```

## The Optimization object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"Optimization":{"properties":{"status":{"type":"string","enum":["not_started","pending","running","success","error"],"title":"Status"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["status"],"title":"Optimization"}}}}
```

## The PaginatedListDatasetResponse object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"PaginatedListDatasetResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ListDatasetResponse"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data"],"title":"PaginatedListDatasetResponse","description":"Paginated list of datasets with cursor-based pagination"},"ListDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","updated_at"],"title":"ListDatasetResponse","description":"Single entry in the list of datasets with a subset of information"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}}
```

## The TileServer object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"TileServer":{"properties":{"tile_url":{"type":"string","title":"Tile Url"},"pixel_url":{"type":"string","title":"Pixel Url"},"min_zoom":{"type":"integer","title":"Min Zoom"},"max_zoom":{"type":"integer","title":"Max Zoom"}},"type":"object","required":["tile_url","pixel_url","min_zoom","max_zoom"],"title":"TileServer"}}}}
```

## The ValidationError object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## The Variable object

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"Variable":{"properties":{"sampled_min":{"type":"number","title":"Sampled Min"},"sampled_max":{"type":"number","title":"Sampled Max"}},"type":"object","required":["sampled_min","sampled_max"],"title":"Variable","description":"Estimated statistics for a variable in the dataset, useful for visualization"}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.earthscale.ai/http-api/earthscale-http-api/models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.