---
updatedAt: 2025-09-23T16:26:01.000Z
agentTools:
projectIndex: https://docs.canopy.umbra.space/llms.txt
---
# Migrate to STAC API v2
Users are strongly encouraged to migrate to [STAC API v2](https://docs.canopy.umbra.space/reference/overview-1) since the original [STAC API](https://docs.canopy.umbra.space/reference/overview) is deprecated and will be discontinued in the near future.
Note that STAC API v2 is fully compliant with [stac-spec v1.0.0](https://github.com/radiantearth/stac-spec/tree/v1.0.0).
## How to Migrate
Use the [Collects API](https://docs.canopy.umbra.space/reference/collects) for retrieving Umbra-specific metadata, including collect lifecycle information like status/status history.
Use [STAC API v2](https://docs.canopy.umbra.space/reference/search-2) to search and retrieve assets and metadata.
## Breaking Changes
### URL
The STAC API v2 base URL includes a `/v2` prefix.
(DEPRECATED)
becomes
### Endpoints
> ⚠️ Collection ID Change
>
> The collection id is no longer the organization id. All items are now listed under a single collection id of **umbra-sar**.
> ⚠️ Item ID Change
>
> The Item ID is no longer the Collect ID. It is a new Item ID to allow for a single Collect to be referenced by multiple Items in the STAC API.
>
> See the "Get Assets for a Collect by Collect ID" Example below.
The API paths are consistent between versions in accordance with the the [STAC API specification](https://github.com/radiantearth/stac-api-spec).
For v2, fetching collect items follows a familiar path pattern of `/collections/{collection_id}/items/{item_id}` *however* the collection id for v2 is always `umbra-sar`, giving a path of:
`/collections/umbra-sar/items/{item_id}`
Simple and advanced searching continues to be available via the `/search` endpoint using CQL2.
Please see the [STAC API v2 reference](https://docs.canopy.umbra.space/reference/search-2) for more details.
### Metadata
STAC item metadata has changed to remove Umbra-specific metadata now available via the [Collects API](https://docs.canopy.umbra.space/reference/collects).
Fields **added**:
* `start_datetime`
* `end_datetime`
* `sar:frequency_band`
Fields **renamed**:
* `umbra:grazing_angle` → `umbra:grazing_angle_degrees`
* `umbra:squint_angle` → `umbra:squint_angle_degrees`
* `umbra:target_azimuth_angle` → `umbra:target_azimuth_angle_degrees`
Field **removed**:
* `umbra:auxiliary_properties`
* `umbra:ipr`
* `umbra:status`
* `umbra:status_history`
* `umbra:target_ipr`
* `umbra:task_name`
* `umbra:user_email`
* `umbra:user_id`
* `umbra:vehicle_id`
> 📘 Resolution
>
> Note that the `target_ipr` and `ipr` fields are functionally replaced by `sar:range_resolution` and `sar:azimuth_resolution`, respectively.
>
> All four fields were present in the previous version of STAC API whereas in STAC API v2 only `sar:range_resolution` and `sar:azimuth_resolution` are present.
## Examples
### Get STAC Item by ID
A GET request for a STAC item with an id of `d395379e-5184-4aaa-9300-2a9725c593f3` might looks like this:
```curl
curl 'https://api.canopy.umbra.space/v2/stac/collections/umbra-sar/items/d395379e-5184-4aaa-9300-2a9725c593f3'
-H 'authorization: Bearer '
```
The `properties` object in the STAC item JSON response should contain an `umbra:collect_id` field that can then be used to [fetch a collect](https://docs.canopy.umbra.space/reference/get_collect).
Here is an example of a STAC item `properties` object that might be returned:
```json
{
"id": "d395379e-5184-4aaa-9300-2a9725c593f3",
"created": "2024-03-12T20:04:34.922116+00:00",
"updated": "2024-03-12T20:04:34.922126+00:00",
"datetime": "2024-03-13T08:22:19.379609+00:00",
"platform": "Umbra-04",
"end_datetime": "2024-03-13T08:22:20.295710+00:00",
"umbra:task_id": "dad4f93f-071d-4ec1-a244-8168e91b997c",
"start_datetime": "2024-03-13T08:22:18.463509+00:00",
"sar:looks_range": 1,
"sar:product_type": "GEC",
"umbra:collect_id": "682a9306-c72b-4b77-a656-d33031a0d8d2",
"sar:looks_azimuth": 1,
"sar:polarizations": [
"VV"
],
"sar:frequency_band": "X",
"sar:instrument_mode": "SPOTLIGHT",
"sar:resolution_range": 1,
"view:incidence_angle": 39.724300384521484,
"umbra:organization_id": "org_OPKOgEGORTS4AlfT",
"sar:resolution_azimuth": 1,
"umbra:squint_angle_degrees": 44.93043899536133,
"umbra:squint_angle_engineering_degrees": 45.06956100463867,
"umbra:squint_angle_exploitation_degrees": 44.93043899536133,
"umbra:squint_angle_degrees_off_broadside": 44.93043899536133,
"umbra:grazing_angle_degrees": 50.275699615478516,
"umbra:slant_range_kilometers": 613.1199340820312,
"umbra:target_azimuth_angle_degrees": 214.4052734375
}
```
With that `umbra:collect_id` of `682a9306-c72b-4b77-a656-d33031a0d8d2`, we can make a request for that collect's information like so:
```
curl 'https://api.canopy.umbra.space/tasking/collects/682a9306-c72b-4b77-a656-d33031a0d8d2'
-H 'authorization: Bearer '
```
### Get Assets for a Collect by Collect ID
If you want to go in the other direction — you have a collect id and want the STAC item to get the asset download links — you can POST to the search endpoint like so:
```Text cURL
curl -H 'Content-Type: application/json' \
-d '{
"filter-lang": "cql2-json",
"filter": {
"op": "=",
"args": [
{ "property": "umbra:collect_id" },
"06280b3f-0114-4c41-8381-c63a4b6b7a98"
]
}
}' \
-H 'authorization: Bearer ' \
-X POST \
'https://api.canopy.umbra.space/v2/stac/search'
```
Note that as of STAC API v2 you are no longer required to make requests to a separate endpoint to get signed URLs, provided that the result set is small (currently set to 5 items or less), since signed URLs are automatically returned when searching or fetching specific STAC items.
Here is an example of what the `assets` object may look like (note the `alternate` property with the signed URL already included):
```json
{
"2022-10-29-05-34-18_UMBRA-03.tif": {
"alternate": {
"s3_signed": {
"description": "Expires at: 2024-03-13T16:27:03+00:00",
"href": "https://dev-test-processed-sar-data.s3.amazonaws.com/2023-06-20/d41a5f76-86e0-4e33-972f-9fa36ac5d0eb/2022-10-29-05-34-18_UMBRA-03.tif?AWSAccessKeyId=ASIAZUHGNVNLFSHTWTOP&Signature=Azaey8PcoS0kxZn6xuIjZ65vmI0%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEFgaCXVzLXdlc3QtMiJHMEUCIQCEU%2B2RbtpxohZXWMi%2Bc46rMk9%2F4WjQQU9zVHlK34MadgIgSRS6%2FbAoARupxYmvs3mi9S61gIxwCzRT38A%2F2Wd%2FWIsq%2FAQIYRACGgw2NjE5MDgyMDQzNzQiDL8hXRWxKVrkuRHxlCrZBEn6osiQg%2Fv4rz%2B1OpbhcoQJW0q%2BVgmXLuKuaNOMejPUe4OjBUThiC7WVQN6Wei3vfwnJGpVEj%2BLC22BO1PYrUqXGUN6uyqpl%2FoRvLx11Q3ymuQknvxg4FjZsbyDmEfttjkeQ7ldWQiw%2FcAkCEEfSU2tNxKEU4UZvBiVl3hkQDnw566%2FiS9p7hEjbR0geuSyLNSaGye11lR1Tlc1lAH9SxzfO6DUv%2FSbOk%2B%2BaLZuTVDMEBErSCN0URFvkePU8DD5wkec1Y%2BD6cjUwdSdJA4fGa3jdaXL6tapEmahy%2FcMMjEFDg%2FJ6tdjKC3pfvDPtSOWiTa5KoPMt%2FAHfgSEl2iunVL%2BS75fuisq2pdAvMnFV2E7BQdBqfspikHQ%2FPQNnFGDAT2g4gY2o1OXzxyVI%2BFKGZE92ZjcFUj8hzbKoJUgReDl5C%2F3qPmqMtIN%2BmhyW9R%2F%2FsQKE6uvNQSNHjutrImjZ2RHij42bfEkpZtlE16OfJ6ylPR3nAWqv2a01oK%2FHuCVCPz3%2BclMRGtXVcvhsS%2BttWvGbNMGGlTiccwzj7qoNaqJvq%2Bg943DYb%2FOW2BmEcHLv1JUiRrJsguc2smGghpjVYo%2BZowhvJAf0qJoYHyUe9%2F%2FOGeU1l4xKbdx5MmMKK9%2BGfY3AS2s3IU%2BWPNoYEItc9hKpTLdbKfwlt3RySP3%2FE2uesGyBJfX4UH8JBl3eef9e%2Fx1t9v06MfJedrPRNuOcx4Iv2Npiik5A7PTWo2TfhyEU2rjJPKv%2Bl5JWCwSkXg9LHfTw2Lm9fcBVzBUQ5xmL3qfeQ6jSFo6k3wwx4vHrwY6mgFW%2Bd47nTiSY%2FUPPUdwSILgEkCb8ovGS1FcJR0fAqsgctkhgTMlbZZsXCYuYnu%2BXVy27RLh67FJi%2B5db08FNGUa7Kn2HsBUNHkF9uxtZBiyG7lwLXMpobhzNepa5AwItyGsUBeQCdMDlZe%2FGcOUeQixQfIoHccQrFmhYSEE31xSAVoIJ%2F8OcKdl9PAlx3Wx5ZKwav6NpVfgF9DL&Expires=1710347223",
"title": "S3 signed url for direct download"
}
},
"created": "2024-03-13T13:48:05Z",
"description": "GEC",
"href": "s3://dev-test-processed-sar-data/2023-06-20/d41a5f76-86e0-4e33-972f-9fa36ac5d0eb/2022-10-29-05-34-18_UMBRA-03.tif",
"roles": [],
"title": "GEC",
"type": "image/tiff; application=geotiff; profile=cloud-optimized"
},
"2022-10-29-05-34-18_UMBRA-03_METADATA.json": {
"alternate": {
"s3_signed": {
"description": "Expires at: 2024-03-13T16:27:03+00:00",
"href": "https://dev-test-processed-sar-data.s3.amazonaws.com/2023-06-20/d41a5f76-86e0-4e33-972f-9fa36ac5d0eb/2022-10-29-05-34-18_UMBRA-03_METADATA.json?AWSAccessKeyId=ASIAZUHGNVNLFSHTWTOP&Signature=bovS%2FZ4B8pJpfA4rk57kFyzLv9c%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEFgaCXVzLXdlc3QtMiJHMEUCIQCEU%2B2RbtpxohZXWMi%2Bc46rMk9%2F4WjQQU9zVHlK34MadgIgSRS6%2FbAoARupxYmvs3mi9S61gIxwCzRT38A%2F2Wd%2FWIsq%2FAQIYRACGgw2NjE5MDgyMDQzNzQiDL8hXRWxKVrkuRHxlCrZBEn6osiQg%2Fv4rz%2B1OpbhcoQJW0q%2BVgmXLuKuaNOMejPUe4OjBUThiC7WVQN6Wei3vfwnJGpVEj%2BLC22BO1PYrUqXGUN6uyqpl%2FoRvLx11Q3ymuQknvxg4FjZsbyDmEfttjkeQ7ldWQiw%2FcAkCEEfSU2tNxKEU4UZvBiVl3hkQDnw566%2FiS9p7hEjbR0geuSyLNSaGye11lR1Tlc1lAH9SxzfO6DUv%2FSbOk%2B%2BaLZuTVDMEBErSCN0URFvkePU8DD5wkec1Y%2BD6cjUwdSdJA4fGa3jdaXL6tapEmahy%2FcMMjEFDg%2FJ6tdjKC3pfvDPtSOWiTa5KoPMt%2FAHfgSEl2iunVL%2BS75fuisq2pdAvMnFV2E7BQdBqfspikHQ%2FPQNnFGDAT2g4gY2o1OXzxyVI%2BFKGZE92ZjcFUj8hzbKoJUgReDl5C%2F3qPmqMtIN%2BmhyW9R%2F%2FsQKE6uvNQSNHjutrImjZ2RHij42bfEkpZtlE16OfJ6ylPR3nAWqv2a01oK%2FHuCVCPz3%2BclMRGtXVcvhsS%2BttWvGbNMGGlTiccwzj7qoNaqJvq%2Bg943DYb%2FOW2BmEcHLv1JUiRrJsguc2smGghpjVYo%2BZowhvJAf0qJoYHyUe9%2F%2FOGeU1l4xKbdx5MmMKK9%2BGfY3AS2s3IU%2BWPNoYEItc9hKpTLdbKfwlt3RySP3%2FE2uesGyBJfX4UH8JBl3eef9e%2Fx1t9v06MfJedrPRNuOcx4Iv2Npiik5A7PTWo2TfhyEU2rjJPKv%2Bl5JWCwSkXg9LHfTw2Lm9fcBVzBUQ5xmL3qfeQ6jSFo6k3wwx4vHrwY6mgFW%2Bd47nTiSY%2FUPPUdwSILgEkCb8ovGS1FcJR0fAqsgctkhgTMlbZZsXCYuYnu%2BXVy27RLh67FJi%2B5db08FNGUa7Kn2HsBUNHkF9uxtZBiyG7lwLXMpobhzNepa5AwItyGsUBeQCdMDlZe%2FGcOUeQixQfIoHccQrFmhYSEE31xSAVoIJ%2F8OcKdl9PAlx3Wx5ZKwav6NpVfgF9DL&Expires=1710347223",
"title": "S3 signed url for direct download"
}
},
"created": "2024-03-13T13:48:06Z",
"description": "METADATA",
"href": "s3://dev-test-processed-sar-data/2023-06-20/d41a5f76-86e0-4e33-972f-9fa36ac5d0eb/2022-10-29-05-34-18_UMBRA-03_METADATA.json",
"roles": ["metadata"],
"title": "Metadata",
"type": "application/json"
}
}
```