Migration Decision Matrix
Not sure which API to use? Use this decision tree to find the right path for your use case.
Quick decision tree
Start here: What are you trying to do?
1. I'm a new user or team starting fresh
→ Use Aleph V2 (Orders API) - Modern, unified interface - Single learning curve - Best for greenfield projects - Next step: Aleph V2 Quickstart
2. I'm using V1 Tasking API and want to stay up-to-date
→ Migrate to Aleph V2 Orders API - Same capabilities, better observability - Multi-product support in one API - See V1 vs. V2 feature matrix - Next step: POI Tasking (V2) or AOI Tasking (V2)
3. I'm a V1 Archive API user
→ Consider migrating to Aleph V2 Orders API - Archive ordering moves from web-only to API-first - Any processing level available (not just L1B) - Automatic clipping and stitching - Monthly consumption tracked as Orders - See Archive Products (V2) - Next step: Archive Consumption (V1 to V2) to understand the mapping
4. I have a large production system with V1 integrations
→ Staged migration recommended - Phase 1: Monitor existing V1 orders via V2 API (read-only) - Phase 2: New projects in V2 while keeping V1 running - Phase 3: Full migration when V2 is stable - Next step: Adoption Guide - Staged strategy
5. I need specific features only in V1
→ Stay with V1, but plan for migration - Confirm with support that your feature is not planned for V2 - Use Phase 1 (monitoring) to get familiar with V2 model - Revisit quarterly as V2 evolves - Next step: Contact support with your specific needs
Detailed decision matrix by use case
Archive workflows
| Use case | V1 solution | V2 solution | Recommendation |
|---|---|---|---|
| Discover and download L1B tiles | STAC API + Delivery API | Archive Explorer + V2 API | V2 for web UI; both APIs supported |
| Order custom processing level (L1C, L1D) | Web UI only | V2 API + web UI | Migrate to V2 (API support added) |
| Clip archive to custom area | Manual (post-download gdalwarp) | Auto-clipped in V2 order | Migrate to V2 (huge UX improvement) |
| Track archive orders | Manual / spreadsheet | V2 Orders API + events | Migrate to V2 (full observability) |
| Monthly consumption reporting | Tile counting script | Deliverables endpoint | Migrate to V2 (automated) |
Tasking workflows
| Use case | V1 solution | V2 solution | Recommendation |
|---|---|---|---|
| POI tasking (single point) | Analysis API + Tasking API | V2 Orders API (TSKPOI-M) | V2 is direct replacement |
| AOI tasking (polygon) | Analysis API + Tasking API | V2 Orders API (TSKARE-M) | V2 is direct replacement |
| Rush tasking | Tasking API (product_id) | V2 Orders API (TSKRSH-M.NN.NN) | V2 is direct replacement |
| Monitor task status | Tasking API (limited visibility) | V2 Orders API (rich events) | V2 has better visibility |
| Opportunity preview before tasking | Analysis API | V2 Orders API (same capabilities) | Both supported; V2 simpler |
Cross-product workflows
| Use case | V1 solution | V2 solution | Recommendation |
|---|---|---|---|
| Mix archive + tasking in one system | Multiple APIs (complex) | V2 Orders API (unified) | Migrate to V2 (huge simplification) |
| Unified consumption tracking | Manual aggregation | V2 Deliverables endpoint | Migrate to V2 (automated) |
| Single order tracking dashboard | Custom (per API) | V2 Orders API (unified) | Migrate to V2 (built-in) |
Migration checklist
Before you migrate
- [ ] Understand your current V1 usage: which APIs, which products, which features
- [ ] Identify integration points: where V1 APIs are called in your code
- [ ] Define success criteria: what V2 must support for your team
- [ ] Plan timeline: when you want to be fully migrated
- [ ] Estimate effort: how many code changes, how many test cycles
Phase 1: Read-only monitoring (low risk)
- [ ] Get Orders API credentials and access
- [ ] Write test queries:
GET /orders?task_id={your_v1_task_id} - [ ] Verify you can see your existing V1 orders as V2 Orders
- [ ] Build monitoring dashboard using Deliverables endpoint
- [ ] Keep all V1 production code running unchanged
- [ ] Duration: 2–4 weeks, parallel run
Phase 2: New projects in V2 (medium risk)
- [ ] Start 1–2 new projects using V2 API
- [ ] Rewrite code using Orders API patterns
- [ ] Test against V2 specs and examples
- [ ] Run parallel with V1 production
- [ ] Monitor and iterate
- [ ] Duration: 4–12 weeks, depending on complexity
Phase 3: Full migration (production)
- [ ] Migrate existing integrations one at a time
- [ ] Update all API calls to V2 patterns
- [ ] Retire V1 API calls gradually
- [ ] Monitor for issues; rollback plan ready
- [ ] Sunset V1 code when stable
- [ ] Duration: 4–16 weeks, depends on portfolio size
Support and questions
What does your team need? - Technical help: See Orders API Examples - Concept clarification: See Orders API Introduction - Custom migration plan: Contact support with your use case - Timeline questions: See FAQ in Adoption Guide