API v1.0 to v2.0 Reference Guide

This guide provides detailed, endpoint-by-endpoint migration instructions for moving from ICEYE Constellation API v1.0 to v2.0.

Authentication

API v2.0 requires Client Credentials authentication.

The Resource Owner Password flow (username/password) is not supported for v2.0 APIs. If you are currently using username and password authentication, you must migrate to Client Credentials before accessing v2.0 endpoints.

Contact ICEYE to obtain your Client Credentials (CLIENT_ID and CLIENT_SECRET).

See Authentication for details on the Client Credentials flow.

Tasking API

POST /tasks - Create Task

v1.0 v2.0

v1.0	v2.0
`POST /api/tasking/v1/tasks`	`POST /api/tasking/v2/tasks`

POST /api/tasking/v1/tasks

POST /api/tasking/v2/tasks

Request Body Changes

Field v1.0 v2.0

Field	v1.0	v2.0
`additionalProductTypes`	Array of `SIDD`, `SICD`	Removed - Use `productTypes` to optionally select which products you want from your contract-allowed list
`deliveryLocations`	Array with `method`, `path`, `subPath`	Removed - Use `deliveries` instead
`deliveries` (optional)	Not available	Array with `locations` containing `configID`, `path`, `subPath`
`notifications` (optional)	Not available	Object with `webhook.id` for callback notifications
`productTypes` (optional)	Not available	Specify which product types to receive from your contract-allowed list

additionalProductTypes

Array of SIDD, SICD

Removed - Use productTypes to optionally select which products you want from your contract-allowed list

deliveryLocations

Array with method, path, subPath

Removed - Use deliveries instead

deliveries (optional)

Not available

Array with locations containing configID, path, subPath

notifications (optional)

Not available

Object with webhook.id for callback notifications

productTypes (optional)

Not available

Specify which product types to receive from your contract-allowed list

v1.0 Request Example

{
  "contractID": "550e8400-e29b-41d4-a716-446655440000",
  "pointOfInterest": {
    "lat": 60.1699,
    "lon": 24.9384
  },
  "acquisitionWindow": {
    "start": "2025-01-15T00:00:00Z",
    "end": "2025-01-17T00:00:00Z"
  },
  "imagingMode": "SPOTLIGHT",
  "exclusivity": "PRIVATE",
  "priority": "COMMERCIAL",
  "sla": "SLA_8H",
  "eula": "STANDARD",
  "additionalProductTypes": ["SIDD"],
  "deliveryLocations": [
    {
      "method": "sftp",
      "path": "/data/imagery",
      "subPath": "tasking"
    }
  ]
}

v2.0 Request Example

{
  "contractID": "550e8400-e29b-41d4-a716-446655440000",
  "pointOfInterest": {
    "lat": 60.1699,
    "lon": 24.9384
  },
  "acquisitionWindow": {
    "start": "2025-01-15T00:00:00Z",
    "end": "2025-01-17T00:00:00Z"
  },
  "imagingMode": "SPOTLIGHT",
  "exclusivity": "PRIVATE",
  "priority": "COMMERCIAL",
  "sla": "SLA_8H",
  "eula": "STANDARD",
  "deliveries": [
    {
      "locations": [
        {
          "configID": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "path": "/data/imagery",
          "subPath": "tasking"
        }
      ]
    }
  ]
}

The configID is a UUID referencing a pre-configured delivery location (e.g., S3 bucket). Retrieve available config IDs using GET /api/delivery/v1/deliveries/location-configs. The deliveries parameter is optional.

Response Changes

The response includes new fields in v2.0:

New Field Required Description

New Field	Required	Description
`deliveries`	Optional	Array of delivery objects with `id`, `locations`, and `status`. Present if delivery was configured.
`notifications`	Optional	Webhook configuration object. Present if notifications were configured.
`productTypes`	Required	Array of product types to be delivered
`eula`	Required	EULA field is now always present in the response.

deliveries

Optional

Array of delivery objects with id, locations, and status. Present if delivery was configured.

notifications

Optional

Webhook configuration object. Present if notifications were configured.

productTypes

Required

Array of product types to be delivered

eula

Required

EULA field is now always present in the response.

GET /tasks - List Tasks

v1.0 v2.0

v1.0	v2.0
`GET /api/tasking/v1/tasks`	`GET /api/tasking/v2/tasks`

GET /api/tasking/v1/tasks

GET /api/tasking/v2/tasks

Request Parameters

No changes to query parameters.

Response Changes

Aspect v1.0 v2.0

Aspect	v1.0	v2.0
Schema name	`Tasks`	`ListTasks`
Item schema	`Task`	`ListTask`
`deliveryLocations`	Present	Replaced by `deliveries`
`productTypes`	Not present	Added
`eula`	Optional	Required

Schema name

Tasks

ListTasks

Item schema

Task

ListTask

deliveryLocations

Present

Replaced by deliveries

productTypes

Not present

Added

eula

Optional

Required

GET /tasks/{taskID} - Get Task

v1.0 v2.0

v1.0	v2.0
`GET /api/tasking/v1/tasks/{taskID}`	`GET /api/tasking/v2/tasks/{taskID}`

GET /api/tasking/v1/tasks/{taskID}

GET /api/tasking/v2/tasks/{taskID}

Response Changes

Same as Create Task response changes.

PATCH /tasks/{taskID} - Cancel Task

v1.0 v2.0

v1.0	v2.0
`PATCH /api/tasking/v1/tasks/{taskID}`	`PATCH /api/tasking/v2/tasks/{taskID}`

PATCH /api/tasking/v1/tasks/{taskID}

PATCH /api/tasking/v2/tasks/{taskID}

Changes

No functional changes. Update base URL only.

GET /tasks/{taskID}/products - List Task Products

v1.0 v2.0

v1.0	v2.0
`GET /api/tasking/v1/tasks/{taskID}/products`	`GET /api/tasking/v2/tasks/{taskID}/products`

GET /api/tasking/v1/tasks/{taskID}/products

GET /api/tasking/v2/tasks/{taskID}/products

Request Parameters

Parameter v1.0 v2.0

Parameter	v1.0	v2.0
`cursor`	Not available	Pagination support

cursor

Not available

Pagination support

Response Changes

Complete schema change from custom format to STAC-like format.

v1.0 Response Format

[
  {
    "type": "GRD",
    "assets": [
      {
        "title": "GRD Image",
        "contentType": "application/octet-stream",
        "downloadURL": "https://cdn.example.com/grd-image.tif"
      }
    ]
  }
]

v2.0 Response Format

{
  "data": [
    {
      "id": "ICEYE_GRD_123456",
      "type": "Feature",
      "stac_version": "1.0.0",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[24.9, 60.1], [25.0, 60.1], [25.0, 60.2], [24.9, 60.2], [24.9, 60.1]]]
      },
      "bbox": [24.9, 60.1, 25.0, 60.2],
      "properties": {
        "frame_id": "frame_123",
        "created": "2025-01-15T12:00:00Z",
        "start_datetime": "2025-01-15T10:00:00Z",
        "end_datetime": "2025-01-15T10:00:30Z",
        "sar:instrument_mode": "spotlight",
        "sar:product_type": "GRD",
        "sar:polarizations": ["VV"],
        "iceye:incidence_center": 35.5,
        "sat:orbit_state": "descending"
      },
      "collection": "tasking",
      "assets": {
        "data": {
          "href": "https://cdn.example.com/grd-image.tif",
          "title": "GRD Image",
          "type": "image/tiff",
          "roles": ["data"]
        }
      }
    }
  ],
  "cursor": "next_page_token"
}

Migration Steps

Update response parsing to expect CatalogItems wrapper with data array
Access products via data array instead of root array
Update asset URL access: assets.<name>.href instead of assets[].downloadURL
Handle pagination via cursor field
Update property access to use new STAC property names (see Property Name Migration)

GET /tasks/{taskID}/products/{productType} - Get Task Product

v1.0 v2.0

v1.0	v2.0
`GET /api/tasking/v1/tasks/{taskID}/products/{productType}`	`GET /api/tasking/v2/tasks/{taskID}/products/{productType}`

GET /api/tasking/v1/tasks/{taskID}/products/{productType}

GET /api/tasking/v2/tasks/{taskID}/products/{productType}

Request Parameters

Parameter v1.0 v2.0

Parameter	v1.0	v2.0
`productType` path param	String (untyped)	Enum: GRD, GRD-COG, SLC, SLC-COG, QLK, SICD, SIDD, CSI, VID
`cursor` query param	Not available	Pagination support

productType path param

String (untyped)

Enum: GRD, GRD-COG, SLC, SLC-COG, QLK, SICD, SIDD, CSI, VID

cursor query param

Not available

Pagination support

Response Changes

Same as List Task Products - returns CatalogItems instead of single Product.

GET /tasks/{taskID}/scene - Get Task Scene

v1.0 v2.0

v1.0	v2.0
`GET /api/tasking/v1/tasks/{taskID}/scene`	`GET /api/tasking/v2/tasks/{taskID}/scene`

GET /api/tasking/v1/tasks/{taskID}/scene

GET /api/tasking/v2/tasks/{taskID}/scene

Response Changes

New field in v2.0:

footprint - Estimated footprint area for the scheduled task as a GeoJSON Polygon, visualizing the planned acquisition area before imaging occurs.

GET /price - Get Task Price

v1.0 v2.0

v1.0	v2.0
`GET /api/tasking/v1/price`	`GET /api/tasking/v2/price`

GET /api/tasking/v1/price

GET /api/tasking/v2/price

Request Parameters

No changes to request parameters.

Response

No changes to response schema (Price object).

Migration

Update the base URL from /v1 to /v2. No other changes required.

POST /feasibility - Check Feasibility (NEW)

v1.0 v2.0

v1.0	v2.0
Not available	`POST /api/tasking/v2/feasibility`

Not available

POST /api/tasking/v2/feasibility

New endpoint to validate whether tasking requests can be scheduled by the ICEYE constellation before creating tasks. See the Check Feasibility documentation for full details.

Catalog API

GET /items - List Catalog Items

v1.0 v2.0

v1.0	v2.0
`GET /api/catalog/v1/items`	`GET /api/catalog/v2/items`

GET /api/catalog/v1/items

GET /api/catalog/v2/items

Request Parameters

Existing parameters (limit, cursor, ids, bbox, datetime) are unchanged.

Parameter Status Notes

Parameter	Status	Notes
`sortby`	Enhanced	More properties available, use STAC-prefixed names (see Property Name Migration)
`collections`	New in v2.0	Filter by collection IDs
`contractID`	New in v2.0	Access control based on contract

sortby

Enhanced

More properties available, use STAC-prefixed names (see Property Name Migration)

collections

New in v2.0

Filter by collection IDs

contractID

New in v2.0

Access control based on contract

Response Changes

collection field is now required on each item
Property names changed to STAC-prefixed format (see Property Name Migration)

POST /search - Search Catalog Items

v1.0 v2.0

v1.0	v2.0
`POST /api/catalog/v1/search`	`POST /api/catalog/v2/search`

POST /api/catalog/v1/search

POST /api/catalog/v2/search

Request Body Changes

Existing fields (bbox, datetime, ids, limit) are unchanged.

Field Status Notes

Field	Status	Notes
`query`	Enhanced	Use STAC-prefixed property names (see Property Name Migration)
`sortby`	Enhanced	More properties available
`intersects`	New in v2.0	GeoJSON geometry filter
`collections`	New in v2.0	Filter by collection IDs
`contractID`	New in v2.0	Access control
`cursor`	New in v2.0	Pagination in request body

query

Enhanced

Use STAC-prefixed property names (see Property Name Migration)

sortby

Enhanced

More properties available

intersects

New in v2.0

GeoJSON geometry filter

collections

New in v2.0

Filter by collection IDs

contractID

New in v2.0

Access control

cursor

New in v2.0

Pagination in request body

v1.0 Query Example

{
  "bbox": [-5, 28, 56, 44],
  "datetime": "2024-01-01T00:00:00Z/2024-12-31T23:59:59Z",
  "query": {
    "incidence_angle": { "gt": 15, "lt": 35 },
    "product_type": { "in": ["SLC", "GRD"] },
    "orbit_state": { "startsWith": "asc" }
  },
  "limit": 50
}

v2.0 Query Example

{
  "bbox": [-5, 28, 56, 44],
  "datetime": "2024-01-01T00:00:00Z/2024-12-31T23:59:59Z",
  "query": {
    "iceye:incidence_center": { "gt": 15, "lt": 35 },
    "sar:product_type": { "in": ["SLC", "GRD"] },
    "sat:orbit_state": { "startsWith": "asc" }
  },
  "intersects": {
    "type": "Polygon",
    "coordinates": [[[-5, 28], [56, 28], [56, 44], [-5, 44], [-5, 28]]]
  },
  "collections": ["curated", "tasking"],
  "contractID": "550e8400-e29b-41d4-a716-446655440000",
  "limit": 50,
  "cursor": "previous_page_token"
}

POST /purchases - Purchase

v1.0 v2.0

v1.0	v2.0
`POST /api/catalog/v1/purchases`	`POST /api/catalog/v2/purchases`

POST /api/catalog/v1/purchases

POST /api/catalog/v2/purchases

Major breaking change: v2.0 purchases by frame, not by item IDs.

v1.0 Request

{
  "itemIds": ["item1", "item2", "item3"],
  "contractId": "550e8400-e29b-41d4-a716-446655440000",
  "companyName": "ACME Corp",
  "contactPerson": "John Doe",
  "reference": "Project Alpha"
}

v2.0 Request

{
  "frameID": "frame_123456",
  "contractID": "550e8400-e29b-41d4-a716-446655440000",
  "eula": "STANDARD",
  "reference": "Project Alpha"
}

Request Field Mapping

v1.0 Field v2.0 Field Notes

v1.0 Field	v2.0 Field	Notes
`itemIds` (array)	`frameID` (string)	Breaking: Single frame instead of multiple items
`contractId`	`contractID`	Casing change (camelCase consistency)
`companyName`	Removed	No longer needed
`contactPerson`	Removed	No longer needed
(not available)	`eula`	New: License type (STANDARD, GOVERNMENT, MULTI)

itemIds (array)

frameID (string)

Breaking: Single frame instead of multiple items

contractId

contractID

Casing change (camelCase consistency)

companyName

Removed

No longer needed

contactPerson

Removed

No longer needed

(not available)

eula

New: License type (STANDARD, GOVERNMENT, MULTI)

Response Changes

v1.0 Response v2.0 Response

v1.0 Response	v2.0 Response
`{ "purchaseId": "purchase-uuid" }`	`{ "id": "purchase-uuid", "frameID": "frame_123456", "contractID": "contract-uuid", "createdAt": "2025-01-15T12:00:00Z", "status": "received", "reference": "Project Alpha", "eula": "STANDARD" }`

{
  "purchaseId": "purchase-uuid"
}

{
  "id": "purchase-uuid",
  "frameID": "frame_123456",
  "contractID": "contract-uuid",
  "createdAt": "2025-01-15T12:00:00Z",
  "status": "received",
  "reference": "Project Alpha",
  "eula": "STANDARD"
}

HTTP Status Code

v1.0: 202 Accepted
v2.0: 200 OK

GET /purchases - List Purchases

v1.0 v2.0

v1.0	v2.0
`GET /api/catalog/v1/purchases`	`GET /api/catalog/v2/purchases`

GET /api/catalog/v1/purchases

GET /api/catalog/v2/purchases

Request Parameters

Existing parameters (limit, cursor) are unchanged.

Parameter Status Notes

Parameter	Status	Notes
`contractID`	New in v2.0	Filter by contract

contractID

New in v2.0

Filter by contract

Response Changes

v1.0 (PurchasedItem) v2.0 (PurchaseObject)

v1.0 (`PurchasedItem`)	v2.0 (`PurchaseObject`)
`id`	`id`
`customerName`	Removed
`contractName`	Removed
`createdAt`	`createdAt`
`status`	`status`
`reference`	`reference`
(not present)	`frameID` Added
(not present)	`contractID` Added
(not present)	`eula` Added

id

customerName

Removed

contractName

Removed

createdAt

status

reference

(not present)

frameID Added

(not present)

contractID Added

(not present)

eula Added

GET /purchases/{purchaseID} - Get Purchase

v1.0 v2.0

v1.0	v2.0
`GET /api/catalog/v1/purchases/{purchaseID}`	`GET /api/catalog/v2/purchases/{purchaseID}`

GET /api/catalog/v1/purchases/{purchaseID}

GET /api/catalog/v2/purchases/{purchaseID}

Response Changes

Same as List Purchases - returns PurchaseObject instead of PurchasedItem.

GET /purchases/{purchaseID}/products - List Purchase Products

v1.0 v2.0

v1.0	v2.0
`GET /api/catalog/v1/purchases/{purchaseID}/products`	`GET /api/catalog/v2/purchases/{purchaseID}/products`

GET /api/catalog/v1/purchases/{purchaseID}/products

GET /api/catalog/v2/purchases/{purchaseID}/products

Response Changes

Property names changed to STAC-prefixed format (see Property Name Migration)
collection field now required

GET /price - Get Frame Price (NEW)

v1.0 v2.0

v1.0	v2.0
Not available	`GET /api/catalog/v2/price`

Not available

GET /api/catalog/v2/price

Request Parameters

Parameter Description

Parameter	Description
`frameID` (required)	Frame ID to price
`contractID` (required)	Contract for pricing
`eula` (required)	License type

frameID (required)

Frame ID to price

contractID (required)

Contract for pricing

eula (required)

License type

Response

{
  "amount": 50000,
  "currency": "EUR"
}

Amount is in currency minor units (cents for EUR/USD).

Property Name Migration

v1.0 Property v2.0 Property

v1.0 Property	v2.0 Property
`start_time`	`start_datetime`
`end_time`	`end_datetime`
`instrument_mode`	`sar:instrument_mode`
`product_type`	`sar:product_type`
`observation_direction`	`sar:observation_direction`
`orbit_state`	`sat:orbit_state`
`incidence_angle`	`iceye:incidence_center`
`satellite_look_angle`	`iceye:satellite_look_angle`
`polarizations`	`sar:polarizations`
`image_mode`	Removed - Use `sar:instrument_mode`

start_time

start_datetime

end_time

end_datetime

instrument_mode

sar:instrument_mode

product_type

sar:product_type

observation_direction

sar:observation_direction

orbit_state

sat:orbit_state

incidence_angle

iceye:incidence_center

satellite_look_angle

iceye:satellite_look_angle

polarizations

sar:polarizations

image_mode

Removed - Use sar:instrument_mode

Example Query Migration

v1.0:

{
  "query": {
    "incidence_angle": { "gt": 20 },
    "product_type": { "eq": "GRD" },
    "orbit_state": { "eq": "descending" }
  }
}

v2.0:

{
  "query": {
    "iceye:incidence_center": { "gt": 20 },
    "sar:product_type": { "eq": "GRD" },
    "sat:orbit_state": { "eq": "descending" }
  }
}

Delivery API (NEW)

All endpoints are new in v2.0. See the Delivery API documentation for full details.

Notifications API (NEW)

All endpoints are new in v2.0. The Notifications API enables webhook callbacks when task or purchase status changes. See the Notifications API documentation for full details.

Error Response Format

Error responses remain unchanged between v1.0 and v2.0.