Skip to content

Adopting Aleph V2: Migration Guide

This guide helps you understand why Aleph V2 (Orders API) exists, when to migrate from V1 APIs, and how to start.

Why Aleph V2?

Aleph V1 (legacy APIs) was built as a collection of specialized products: Tasking API for tasking, Archive API for archive, Analysis API for feasibility, Delivery API for asset retrieval. This worked well for single-product workflows, but had limitations:

  • Fragmented UX: Archive discovery used STAC; ordering used web-only; tracking was limited
  • Cross-product complexity: Users working with both archive and tasking needed to learn multiple APIs
  • Limited visibility: Task states didn't capture multi-deliverable scenarios or detailed failure reasons
  • Scaling pain: Each product had different patterns, making new products harder to add

Aleph V2 (Orders API) solves these: - Single, unified interface for all products (archive, tasking, future products) - Complete order lifecycle: order → capture → deliverable, with detailed events at each stage - Same patterns everywhere: consistent entity model, state machines, event tracking - Better observability: see why a capture failed, why a deliverable didn't deliver, etc.

Decision: Should you migrate?

Migrate to V2 if…

  • You're a new user or team starting fresh
  • You want to integrate archive and tasking in one system
  • You need detailed order tracking and event history
  • You want to simplify your codebase (one API vs. many)
  • You're ready to adopt modern patterns (Orders instead of Tasks)

Stay with V1 if…

  • You have existing production integrations that work well
  • You're using specialized V1 features not yet in V2
  • You need to minimize code changes right now
  • Note: We recommend creating a migration plan for when V2 features mature

Migration paths

For Tasking API users

Current workflow (V1): 1. Analyze feasibility: POST /analysis 2. Create task: POST /tasks 3. Monitor task and captures: GET /tasks/{task_id} 4. Retrieve deliverables: Use Delivery API

New workflow (V2): 1. Analyze feasibility: Integrated into order creation 2. Create order: POST /orders with SKU (e.g., TSKPOI-M for POI tasking) 3. Monitor order, captures, deliverables: GET /orders/{order_id} with nested entities 4. Retrieve deliverables: Same Delivery API or Orders API endpoints

Side-by-side example: 

V1: POST /tasks/poi with {"geometry": {...}, "parameters": {...}}
V2: POST /orders with {"type": "Feature", "geometry": {...}, "properties": {"sku": "TSKPOI-M", "parameters": {...}}}

For Archive API users

Current workflow (V1): 1. Discover tiles: Search STAC catalogs or use web UI 2. Download L1B: Direct download via Delivery API (tile-by-tile) 3. Order higher processing levels: Web UI only; no tracking

New workflow (V2): 1. Discover tiles: Use Archive Explorer web UI or search API 2. Order any processing level: Create an order with ARCIMG-M.NN.NN SKU 3. Track order: Full order lifecycle with events 4. Retrieve deliverables: Clipped, processed, stitched automatically

Key improvement: V1 archive.consumption is now tracked as monthly orders with individual tile deliverables. See Archive Consumption (V1 to V2) for details.

For mixed workflows (archive + tasking)

V1 pain point: Different API patterns, discovery methods, and delivery workflows.
V2 solution: Same order model, state tracking, and event history for both.

V1: Mix of STAC discovery + Tasking API + Delivery API
V2: Unified Orders API + consistent web UI

Staged adoption strategy

Phase 1: Read-only monitoring (Low risk)

Start tracking your existing V1 tasks and archive consumption as Orders without changing your creation workflow: - Use Orders API to query and monitor orders created by V1 workflows - Use Deliverables endpoint to track consumption and billing - Get familiar with the Orders model while keeping V1 production running

API calls: - GET /orders?task_id={old_task_id} — See your V1 task as an order - GET /orders/{order_id}/captures — Track captures - GET /orders/{order_id}/deliverables — Monitor deliverables - GET /deliverables?order_id={order_id} — Track consumption by deliverable

Phase 2: New projects in V2 (Medium risk)

Start new projects using V2 Orders API while keeping existing V1 integrations running: - Create new tasking and archive orders via V2 API or web UI - Use Orders API for monitoring and analytics - Parallel run: V1 and V2 coexist for a transition period

Phase 3: Full migration (Production)

When V2 is stable and meets all your needs: - Migrate existing V1 integrations to V2 - Retire V1 API calls gradually - Benefit from unified product experience

V1 vs. V2 feature matrix

Feature V1 V2 Migration Path
POI Tasking ✅ Analysis + Tasking API ✅ Orders API (SKU: TSKPOI-M) Use TSKPOI-M SKU
AOI Tasking ✅ Analysis + Tasking API ✅ Orders API (SKU: TSKARE-M) Use TSKARE-M SKU
Archive discovery ✅ STAC / web UI ✅ Archive Explorer / web UI No change to discovery
Archive ordering ✅ Web UI only ✅ API + web UI Use ARCIMG SKU in Orders API
Order tracking ⚠️ Limited (task + captures) ✅ Rich (order + captures + deliverables + events) Read orders via Orders API
Consumption tracking ⚠️ Manual (per tile) ✅ Automated (deliverables) Use Deliverables endpoint
Multi-deliverable capture ⚠️ One at a time ✅ Native Automatic in Orders API

What stays the same between V1 and V2

  • Authentication: OAuth 2.0 flow identical. See API Authentication.
  • Processing levels: L0, L1A, L1B, L1C, L1D, L1D_SR unchanged. See Imagery Products.
  • Delivery API: Asset retrieval and management unchanged.
  • Web UI login: Login flow identical for both web experiences.

Getting started with V2

For API-first users

  1. Read Orders API Introduction to understand the entity model
  2. Review API Specifications to see endpoints and parameters
  3. Try Python Examples to create your first order
  4. Use Staged adoption strategy to plan your migration

For web UI users

  1. Start with Aleph V2 Quickstart
  2. Read Core Concepts (V2) to learn terminology
  3. Follow the workflow for your product:
  4. Archive Products (V2)
  5. POI Tasking (V2)
  6. AOI Tasking (V2)

For customers with questions

Contact support with: - Your current V1 API usage (which endpoints, which products) - Your business needs (throughput, SLAs, integration frequency) - Your timeline (when you need V2 production-ready)

We'll help you plan a safe, staged migration specific to your use case.

FAQ

Q: Will V1 APIs go away?
A: Not immediately. V1 APIs will be supported for existing integrations, but new features will be V2-only. We recommend planning a migration.

Q: Can I use V1 and V2 APIs at the same time?
A: Yes. Phase 1 of our staged adoption strategy relies on this. You can create orders via V1 and monitor them via V2 APIs.

Q: Does my existing code break when I upgrade to V2?
A: No. V2 is a parallel API. Your existing V1 code will continue to work. Adoption is opt-in.

Q: How long is the migration expected to take?
A: Depends on your current complexity. Simple integrations: weeks. Complex multi-product workflows: months. We recommend Phase 1 (read-only) to start, then Phase 2 (new projects), then Phase 3 (full migration).

Q: What about my existing orders/tasks?
A: Existing V1 orders are automatically represented in V2 as Orders entities. You can query and monitor them via Orders API without recreating anything.