Migration Guide: v1 โ v2
This guide maps the old SCo2-API (v1) endpoints to their equivalents in the new Epoch API (v2). The new API uses a unified ingestion-based workflow, API key authentication (instead of OAuth2/JWT), and a standardized envelope response format.
โถKey Differences
| Aspect | v1 (SCo2-API) | v2 (Epoch API) |
|---|---|---|
| Authentication | OAuth2 Bearer token (JWT) via Authorization header | API key via x-api-key header |
| Base URL | https://epoch-sco2-api.com/ | https://api.epoch.blue/v2/ |
| Request format | Query parameters with WKT geometry | File upload (multipart/form-data) or JSON body |
| Response format | Flat JSON or streaming NDJSON GeoJSON | Envelope format (meta, links, data) or NDJSON |
| Real-time (Core) endpoints | Direct single-plot queries (/deforestation_check, /biomass_emissions, etc.) | Not available โ all processing goes through the ingestion pipeline |
| Batch workflow | Upload โ Stage โ Batch Process (3 separate calls) | Upload โ (auto-validate) โ Process (2 calls) |
| Result retrieval | Dedicated /fetch_* endpoints per metric | Unified /metrics/{resource}/{metric} endpoints with filtering |
โถAuthentication Migration
โถv1: OAuth2 Bearer Token
headers = {
"Authorization": "Bearer <jwt_token>",
"Accept": "application/json"
}
Tokens were obtained via /refresh_token (email/password, now POST with a JSON body โ the legacy GET variant is deprecated and slated for removal once partners are migrated) or /refresh_token_with_client_credentials (client credentials).
โถv2: API Key
headers = {
"x-api-key": "sk-epoch-<your-key>",
"Accept": "application/json"
}
Keys are created in the Epoch app under Settings > API Keys. See Generating an API key.
โถEndpoint Mapping
โถCore API (real-time single-plot) โ Ingestion Pipeline
The v1 Core API provided synchronous, single-plot analysis. In v2, all analysis goes through the asynchronous ingestion pipeline.
| v1 Endpoint | v2 Equivalent | Notes |
|---|---|---|
POST /data_normalization | POST /ingestions/assets | Normalization happens automatically during ingestion validation |
POST /plot_validation | POST /ingestions/assets | Plot validation is part of the ingestion pipeline |
POST /facility_validation | POST /ingestions/assets | Set location_type: facility |
POST /deforestation_check | Upload + PUT /ingestions/assets with metrics: ["deforestation"], then GET /metrics/plots/deforestation | Async; poll GET /ingestions/:id/summary for progress |
POST /biomass_emissions | Upload + PUT /ingestions/assets with metrics: ["emissions"], then GET /metrics/plots/emissions | |
POST /biodiversity | Upload + PUT /ingestions/assets with metrics: ["biodiversity"], then GET /metrics/plots/biodiversity | |
POST /water_use | Upload + PUT /ingestions/assets with metrics: ["water"], then GET /metrics/plots/water_stress | |
POST /water | Upload + PUT /ingestions/assets with metrics: ["water"], then GET /metrics/plots/water_stress | |
POST /vector (isochrones) | Not yet available in v2 | Travel-time isochrones are used internally for supply shed generation |
POST /non_biomass_emissions | Not yet available in v2 |
โถBatch API โ Ingestion Pipeline
| v1 Endpoint | v2 Equivalent | Notes |
|---|---|---|
POST /upload_plots | POST /ingestions/assets | Single upload endpoint for all location types |
POST /stage_plots | (automatic) | Staging happens automatically after upload validation |
POST /batch_process | PUT /ingestions/assets with metrics body | Filter by task ID: filter[asset_task_id]=eq:<id> |
POST /batch_supply_shed | POST /ingestions/assets with facility points | Supply shed analysis is triggered during facility processing |
POST /batch_zonal_stats | PUT /ingestions/assets with metrics body | Zonal stats computed as part of batch processing |
GET /batch_progress | GET /ingestions/:id/summary | Returns by_status counts for progress tracking |
POST /sampling_design | Not yet available in v2 |
batch_process could be called again with the same metrics. A PUT /ingestions/assets naming one task cannot: a repeat of a metric already run on that ingestion, with the same end_date and metric_options, returns 409 INGESTION_ALREADY_RUN. That includes an upload sent with metrics followed by a PUT of the same metrics. Send the PUT without those metrics, or change the end_date or options. See Running the same metrics twice.
โถFetch API โ Metrics & Locations Endpoints
| v1 Endpoint | v2 Equivalent | Notes |
|---|---|---|
GET /fetch_deforestation_check | GET /metrics/plots/deforestation | Supports pagination, filtering, NDJSON streaming |
GET /fetch_biomass_emissions | GET /metrics/plots/emissions | |
GET /fetch_biodiversity | GET /metrics/plots/biodiversity | |
GET /fetch_water_stress | GET /metrics/plots/water_stress | |
GET /fetch_plots | GET /locations/plots | |
GET /fetch_stat_regions | GET /metrics/facilities/deforestation (facility-level aggregates) | Statistical regions are now facility-scoped |
GET /fetch_supply_shed | GET /locations/facilities/:id/sheds | Sheds are linked to facilities |
GET /fetch_samples | Not yet available in v2 | |
GET /fetch_eudr_risk_assessment | GET /metrics/plots/deforestation with appropriate filters | |
GET /export_eudr_dds | GET /regulations/eudr/audit-trail/:recordId/report.geojson | Export inline; submission is a separate step |
POST /submit_eudr_dds | POST /regulations/eudr/dds/:recordId/submit | DDSv2 record-scoped submit (async task) |
GET /retrieve_eudr_dds | GET /regulations/eudr/audit-trail/:recordId/tasks/:taskId | Poll the submit task envelope for TRACES identifiers |
โถEUDR Workflow
| v1 Workflow | v2 Equivalent |
|---|---|
Upload file โ batch_process with eudr_deforestation stat โ export_eudr_dds โ submit_eudr_dds | POST /ingestions/assets (with metrics: ["deforestation"]) โ POST /regulations/eudr/audit-trail (create record from plot filter) โ POST /regulations/eudr/audit-trail/:recordId/tasks (cut version) โ POST /regulations/eudr/dds/:recordId/submit |
โถNew in v2 (no v1 equivalent)
| Endpoint | Description |
|---|---|
GET /auth/me | Current user/org info |
GET /locations/facilities, GET /locations/facilities/:id | List/get facilities with filtering, pagination |
GET /locations/sheds, GET /locations/sheds/:id | List/get supply sheds |
GET /metrics/facilities/* | Facility-level metrics (deforestation, emissions, biodiversity, water stress) |
GET /metrics/sheds/* | Shed-level metrics |
GET /metrics/plots/:metric/aggregate | Plot metric aggregations |
Tags CRUD (GET /tags, PATCH /tags/:name, DELETE /tags/:name) | Organization-scoped resource tagging |
Webhooks (/webhooks/*) | Real-time HTTP notifications for ingestion and processing events |
Notifications (/notifications/*) | In-app notification management |
PUT /regulations/eudr/entities | Create EUDR task from existing entities without re-uploading |
โถFiltering Migration
โถv1: Query Parameters
GET /fetch_deforestation_check?filename=my_collection&monitoring_start=2020-12-31&limit=100
โถv2: Structured Filters
GET /metrics/plots/deforestation?filter[commodity]=eq:cocoa&filter[country_code]=eq:BR&page[size]=100
See Query Parameters for the full filter syntax.
โถResponse Format Migration
โถv1: Flat JSON / Streaming NDJSON GeoJSON
{
"noncompliance_area": 12.5,
"forest_area": 890.2,
"deforestation_alert": "critical",
"thumbnail_url": "https://..."
}
โถv2: Envelope format
{
"meta": { "total": 48, "units": { "area": "ha" } },
"links": { "self": "/metrics/plots/deforestation" },
"data": [
{
"type": "deforestation",
"id": "shed-abc:2025-12-31T00:00:00.000Z",
"attributes": {
"noncompliance_area": 12.5,
"forest_area": 890.2,
"annual_defor": { "2022": 3.1, "2023": 2.8 }
},
"relationships": {
"supply_shed": { "data": "shed-abc" },
"plot": { "data": "plot-456" }
}
}
]
}
โถWebhook Migration
โถv1: Polling or email-based
v1 used polling via GET /batch_progress or optional email/webhook notifications configured per-user.
โถv2: First-class webhook subscriptions
v2 provides a full webhook system with subscriptions, signature verification, delivery logs, and retry logic. See Webhooks.