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

Aspectv1 (SCo2-API)v2 (Epoch API)
AuthenticationOAuth2 Bearer token (JWT) via Authorization headerAPI key via x-api-key header
Base URLhttps://epoch-sco2-api.com/https://api.epoch.blue/v2/
Request formatQuery parameters with WKT geometryFile upload (multipart/form-data) or JSON body
Response formatFlat JSON or streaming NDJSON GeoJSONEnvelope format (meta, links, data) or NDJSON
Real-time (Core) endpointsDirect single-plot queries (/deforestation_check, /biomass_emissions, etc.)Not available โ€” all processing goes through the ingestion pipeline
Batch workflowUpload โ†’ Stage โ†’ Batch Process (3 separate calls)Upload โ†’ (auto-validate) โ†’ Process (2 calls)
Result retrievalDedicated /fetch_* endpoints per metricUnified /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 Endpointv2 EquivalentNotes
POST /data_normalizationPOST /ingestions/assetsNormalization happens automatically during ingestion validation
POST /plot_validationPOST /ingestions/assetsPlot validation is part of the ingestion pipeline
POST /facility_validationPOST /ingestions/assetsSet location_type: facility
POST /deforestation_checkUpload + PUT /ingestions/assets with metrics: ["deforestation"], then GET /metrics/plots/deforestationAsync; poll GET /ingestions/:id/summary for progress
POST /biomass_emissionsUpload + PUT /ingestions/assets with metrics: ["emissions"], then GET /metrics/plots/emissions
POST /biodiversityUpload + PUT /ingestions/assets with metrics: ["biodiversity"], then GET /metrics/plots/biodiversity
POST /water_useUpload + PUT /ingestions/assets with metrics: ["water"], then GET /metrics/plots/water_stress
POST /waterUpload + PUT /ingestions/assets with metrics: ["water"], then GET /metrics/plots/water_stress
POST /vector (isochrones)Not yet available in v2Travel-time isochrones are used internally for supply shed generation
POST /non_biomass_emissionsNot yet available in v2

Batch API โ†’ Ingestion Pipeline

v1 Endpointv2 EquivalentNotes
POST /upload_plotsPOST /ingestions/assetsSingle upload endpoint for all location types
POST /stage_plots(automatic)Staging happens automatically after upload validation
POST /batch_processPUT /ingestions/assets with metrics bodyFilter by task ID: filter[asset_task_id]=eq:<id>
POST /batch_supply_shedPOST /ingestions/assets with facility pointsSupply shed analysis is triggered during facility processing
POST /batch_zonal_statsPUT /ingestions/assets with metrics bodyZonal stats computed as part of batch processing
GET /batch_progressGET /ingestions/:id/summaryReturns by_status counts for progress tracking
POST /sampling_designNot 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 Endpointv2 EquivalentNotes
GET /fetch_deforestation_checkGET /metrics/plots/deforestationSupports pagination, filtering, NDJSON streaming
GET /fetch_biomass_emissionsGET /metrics/plots/emissions
GET /fetch_biodiversityGET /metrics/plots/biodiversity
GET /fetch_water_stressGET /metrics/plots/water_stress
GET /fetch_plotsGET /locations/plots
GET /fetch_stat_regionsGET /metrics/facilities/deforestation (facility-level aggregates)Statistical regions are now facility-scoped
GET /fetch_supply_shedGET /locations/facilities/:id/shedsSheds are linked to facilities
GET /fetch_samplesNot yet available in v2
GET /fetch_eudr_risk_assessmentGET /metrics/plots/deforestation with appropriate filters
GET /export_eudr_ddsGET /regulations/eudr/audit-trail/:recordId/report.geojsonExport inline; submission is a separate step
POST /submit_eudr_ddsPOST /regulations/eudr/dds/:recordId/submitDDSv2 record-scoped submit (async task)
GET /retrieve_eudr_ddsGET /regulations/eudr/audit-trail/:recordId/tasks/:taskIdPoll the submit task envelope for TRACES identifiers

EUDR Workflow

v1 Workflowv2 Equivalent
Upload file โ†’ batch_process with eudr_deforestation stat โ†’ export_eudr_dds โ†’ submit_eudr_ddsPOST /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)

EndpointDescription
GET /auth/meCurrent user/org info
GET /locations/facilities, GET /locations/facilities/:idList/get facilities with filtering, pagination
GET /locations/sheds, GET /locations/sheds/:idList/get supply sheds
GET /metrics/facilities/*Facility-level metrics (deforestation, emissions, biodiversity, water stress)
GET /metrics/sheds/*Shed-level metrics
GET /metrics/plots/:metric/aggregatePlot 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/entitiesCreate 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.