# Datasets

## List Datasets

> List datasets with optional filtering.\
> \
> Returns a flat list of datasets with offset-based pagination.\
> For iterating over large or unbounded result sets, prefer\
> \`\`GET /v1/datasets/cursor\`\` which uses cursor-based pagination\
> and guarantees stable ordering across pages.\
> \
> All filters are combined with AND logic. When multiple tags are\
> specified, only datasets matching \*\*all\*\* of them are returned.

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"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"},"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"}}},"paths":{"/datasets":{"get":{"tags":["Datasets","Datasets"],"summary":"List Datasets","description":"List datasets with optional filtering.\n\nReturns a flat list of datasets with offset-based pagination.\nFor iterating over large or unbounded result sets, prefer\n``GET /v1/datasets/cursor`` which uses cursor-based pagination\nand guarantees stable ordering across pages.\n\nAll filters are combined with AND logic. When multiple tags are\nspecified, only datasets matching **all** of them are returned.","operationId":"List_datasets_datasets_get","parameters":[{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive substring search on dataset name.","title":"Name"},"description":"Case-insensitive substring search on dataset name."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter datasets created after this ISO 8601 timestamp.","title":"Created After"},"description":"Filter datasets created after this ISO 8601 timestamp."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter datasets created before this ISO 8601 timestamp.","title":"Created Before"},"description":"Filter datasets created before this ISO 8601 timestamp."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"bbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bounding box as comma-separated values: 'min_lon,min_lat,max_lon,max_lat'. If you want to query a single location, you can use the same value for min and max. All values should be in EPSG:4326 coordinates.","title":"Bbox"},"description":"Bounding box as comma-separated values: 'min_lon,min_lat,max_lon,max_lat'. If you want to query a single location, you can use the same value for min and max. All values should be in EPSG:4326 coordinates."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use '\\:' for a literal colon, '\\\\' for a literal backslash. Datasets must match ALL specified tags.","title":"Tag"},"description":"Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use '\\:' for a literal colon, '\\\\' for a literal backslash. Datasets must match ALL specified tags."},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ListDatasetResponse"},"title":"Response List Datasets Datasets Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /datasets

> Add Dataset

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"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"},"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"},"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"},"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"},"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"},"ErrorResponse":{"properties":{"message":{"type":"string","title":"Message"},"error_class":{"type":"string","title":"Error Class"}},"type":"object","required":["message","error_class"],"title":"ErrorResponse"}}},"paths":{"/datasets":{"post":{"tags":["Datasets","Datasets"],"summary":"Add Dataset","operationId":"Add_dataset_datasets_post","parameters":[{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AddImageDatasetRequest"},{"$ref":"#/components/schemas/AddZarrDatasetRequest"},{"$ref":"#/components/schemas/AddVectorDatasetRequest"},{"$ref":"#/components/schemas/AddTileServerDatasetRequest"}],"title":"Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddDatasetResponse"}}}},"422":{"description":"Unable to process the request (e.g. unsupported dataset type, source files not accessible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete Dataset

> Soft-delete a dataset.\
> \
> Deletion works by creating a new dataset version that marks the dataset\
> as deleted. This hides the dataset from the catalog and listing APIs,\
> but tiling requests for existing versions are still accepted. Optionally\
> removes the dataset from all maps.\
> \
> Both dataset IDs and dataset version IDs are accepted — it does not\
> matter which is passed, the entire dataset is deleted either way.\
> \
> Returns the dataset ID and the ID of the newly created deletion marker\
> version.

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"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"},"ErrorResponse":{"properties":{"message":{"type":"string","title":"Message"},"error_class":{"type":"string","title":"Error Class"}},"type":"object","required":["message","error_class"],"title":"ErrorResponse"},"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"}}},"paths":{"/datasets/{dataset_id}":{"delete":{"tags":["Datasets","Datasets"],"summary":"Delete Dataset","description":"Soft-delete a dataset.\n\nDeletion works by creating a new dataset version that marks the dataset\nas deleted. This hides the dataset from the catalog and listing APIs,\nbut tiling requests for existing versions are still accepted. Optionally\nremoves the dataset from all maps.\n\nBoth dataset IDs and dataset version IDs are accepted — it does not\nmatter which is passed, the entire dataset is deleted either way.\n\nReturns the dataset ID and the ID of the newly created deletion marker\nversion.","operationId":"Delete_dataset_datasets__dataset_id__delete","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Dataset Id"}},{"name":"remove_from_maps","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Remove From Maps"}},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteDatasetResponse"}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Dataset is already deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List Datasets (Cursor Pagination)

> List datasets with cursor-based pagination (recommended).\
> \
> This is the preferred endpoint for iterating over datasets. It\
> returns a paginated response with a \`\`next\_cursor\`\` token. Pass the\
> token back as the \`\`cursor\`\` query parameter to fetch the next page.\
> When \`\`next\_cursor\`\` is \`\`null\`\`, all results have been returned.\
> \
> Supports the same filters as \`\`GET /v1/datasets\`\`. All filters are\
> combined with AND logic. When multiple tags are specified, only\
> datasets matching \*\*all\*\* of them are returned.\
> \
> Results are ordered by \`\`updated\_at\`\` descending, then by dataset\
> version ID for stable ordering across pages.

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"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"},"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"}}},"paths":{"/datasets/cursor":{"get":{"tags":["Datasets","Datasets"],"summary":"List Datasets (Cursor Pagination)","description":"List datasets with cursor-based pagination (recommended).\n\nThis is the preferred endpoint for iterating over datasets. It\nreturns a paginated response with a ``next_cursor`` token. Pass the\ntoken back as the ``cursor`` query parameter to fetch the next page.\nWhen ``next_cursor`` is ``null``, all results have been returned.\n\nSupports the same filters as ``GET /v1/datasets``. All filters are\ncombined with AND logic. When multiple tags are specified, only\ndatasets matching **all** of them are returned.\n\nResults are ordered by ``updated_at`` descending, then by dataset\nversion ID for stable ordering across pages.","operationId":"List_datasets__cursor_pagination__datasets_cursor_get","parameters":[{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive substring search on dataset name.","title":"Name"},"description":"Case-insensitive substring search on dataset name."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter datasets created after this ISO 8601 timestamp.","title":"Created After"},"description":"Filter datasets created after this ISO 8601 timestamp."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter datasets created before this ISO 8601 timestamp.","title":"Created Before"},"description":"Filter datasets created before this ISO 8601 timestamp."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor token from a previous paginated response.","title":"Cursor"},"description":"Opaque cursor token from a previous paginated response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"bbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bounding box as comma-separated values: 'min_lon,min_lat,max_lon,max_lat'. If you want to query a single location, you can use the same value for min and max. All values should be in EPSG:4326 coordinates.","title":"Bbox"},"description":"Bounding box as comma-separated values: 'min_lon,min_lat,max_lon,max_lat'. If you want to query a single location, you can use the same value for min and max. All values should be in EPSG:4326 coordinates."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use '\\:' for a literal colon, '\\\\' for a literal backslash. Datasets must match ALL specified tags.","title":"Tag"},"description":"Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use '\\:' for a literal colon, '\\\\' for a literal backslash. Datasets must match ALL specified tags."},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedListDatasetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Latest Dataset Version

> Get the latest version of a dataset by dataset ID.

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"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"},"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"}}},"paths":{"/datasets/{dataset_id}/latest":{"get":{"tags":["Datasets","Datasets"],"summary":"Get Latest Dataset Version","description":"Get the latest version of a dataset by dataset ID.","operationId":"Get_latest_dataset_version_datasets__dataset_id__latest_get","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Dataset Id"}},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Dataset Version By Id

> Get a dataset version by version ID.

```json
{"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"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"},"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"}}},"paths":{"/dataset-versions/{version_id}":{"get":{"tags":["Datasets","Datasets"],"summary":"Get Dataset Version By Id","description":"Get a dataset version by version ID.","operationId":"Get_dataset_version_by_id_dataset_versions__version_id__get","parameters":[{"name":"version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Version Id"}},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```