API v1.0 to v2.0 Comparison Guide

This guide provides a high-level comparison between ICEYE Constellation API v1.0 and v2.0. Use this to understand the major differences before planning your migration.

For detailed endpoint-by-endpoint migration instructions, see the API Reference Guide.

Overview

ICEYE Constellation API 2.0 introduces significant improvements including new APIs for delivery and notifications, a STAC-like response format, and a more flexible architecture for managing your satellite imagery workflow.

Authentication Requirements

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 the Resource Owner Password flow, you must migrate to Client Credentials before accessing v2.0 endpoints. Contact ICEYE to obtain your Client Credentials (CLIENT_ID and CLIENT_SECRET).

Base URL Changes

API v1.0 Base URL v2.0 Base URL

Tasking

https://platform.iceye.com/api/tasking/v1

https://platform.iceye.com/api/tasking/v2

Catalog

https://platform.iceye.com/api/catalog/v1

https://platform.iceye.com/api/catalog/v2

Company

https://platform.iceye.com/api/company/v1

https://platform.iceye.com/api/company/v1 (unchanged)

Delivery

Not available

https://platform.iceye.com/api/delivery/v1

Notifications

Not available

https://platform.iceye.com/api/notifications/v1

New APIs in v2.0

Delivery API

The Delivery API enables you to request delivery of your tasked products or any products you purchased from the public catalog.

Key capabilities:

  • Request delivery of products to preconfigured locations (AWS S3)

  • Access your complete archive of owned products

  • Track delivery status

  • Deliver to multiple locations in a single request

Notifications API

The Notifications API enables asynchronous communication via webhooks, allowing your applications to receive real-time updates when resources change.

Key capabilities:

  • Register webhooks for callback notifications

  • Receive notifications when task status changes

  • Receive notifications when catalog purchases complete

  • Support for Basic Auth and OAuth2 Client Credentials authentication

Tasking API Changes

What Changed v1.0 → v2.0 Impact

Product types configuration

additionalProductTypes → productTypes (optional)

Your contract defines available product types. Use productTypes to optionally specify which ones you want.

Delivery configuration

deliveryLocations → deliveries

New structure using configID instead of method. Get config IDs from Delivery API.

Notifications

Not available → notifications parameter

Optional webhook callbacks for task status updates.

Task products response

Custom format → STAC-like format

Major change - Update your response parsing logic.

Response schema

Tasks → ListTasks

Schema renamed, structure similar.

eula in response

Optional → Required

Now always present in task responses.

Feasibility check

Not available → Available

Check whether tasking requests can be scheduled before creating tasks.

Catalog API Changes

What Changed v1.0 → v2.0 Impact

Purchase model

By item IDs (itemIds array) → By frame (frameID string)

Breaking change - Purchase single frames instead of multiple items.

Price endpoint

Not available → Available

Check price before purchasing from catalog.

Private images

Not available → Available

Access previously tasked images in catalog.

New filters

Not available → collections, intersects, contractID

More powerful search capabilities.

STAC property naming

Custom names → STAC-standard prefixes

Update property names in queries (e.g., incidence_angle → iceye:incidence_center).

Pagination in search

Query param only → Also in request body

cursor can now be passed in POST body.

Company API Changes

The Company API endpoints remain unchanged between v1.0 and v2.0. The base URL stays at /api/company/v1.

Feature Comparison Matrix

Feature v1.0 v2.0

Client Credentials auth

Yes

Yes (required)

Resource Owner Password auth

Yes

No

Tasking

Yes

Yes

Feasibility check

No

Yes

Task status notifications

No

Yes

Catalog search

Yes

Yes (enhanced)

Catalog purchase

By item

By frame

Price checking

Tasking only

Tasking + Catalog

Private images

No

Yes

Delivery API

No

Yes

Webhooks

No

Yes

STAC-like format

No

Yes

GeoJSON geometry queries

Limited

Full support

Collection filtering

No

Yes

What’s Next

  • API Reference Guide - Detailed endpoint-by-endpoint migration instructions with code examples