Using this Documentation

Use the environment selector in the top navigation bar to choose which server your requests are sent to. Each environment sets the baseUrl variable used in all request URLs.

Environment	Base URL	Use for
Sandbox v1	https://sandbox-api.epoch.blue/v1	Testing and development with sample data
Sandbox v0	https://sandbox-api.epoch.blue/v0	The frozen v0 major, for integrations that still call it
Live	https://api.epoch.blue/v1	Production requests against your real data

Switching environments updates all request URLs automatically. Variables like {{baseUrl}} are resolved before each request is sent.

---

The API uses API keys sent in the x-api-key header. To authenticate your requests:

1. Open the Auth panel (click the lock icon or navigate to the authentication settings).
2. Enter your API key in the value field. The key format is sk-epoch-....
3. The x-api-key header is inherited by all endpoints automatically — you only need to set it once.

If you don't have a key yet, see Generating an API Key for setup instructions.

---

Endpoints are organized by domain in the left sidebar:

• Endpoints — All available API routes grouped by resource (Locations, Ingestion, Metrics, Regulations/EUDR, Cadastral, Discovery, etc.). If you only have a company or supplier name, start with the Discovery group (/discovery/source and /discovery/validate), which powers first-mile discovery.
• Workflows — Guided multi-step sequences that walk through common tasks end-to-end. New to the API? Begin with First-Mile Discovery, which goes from a bare company name all the way through to ingested, analysis-ready locations.
• Docs — Reference guides organised into sections: Getting Started, API Conventions, Locations & Data, Metrics & Assessments, EUDR Compliance, and Integrations

Each endpoint page shows the HTTP method, URL, documentation, and an interactive playground.

---

Each endpoint page includes an API Playground where you can send real requests:

1. URL bar — Shows the full request URL with environment variables resolved. You can edit path parameters directly (e.g. replace {{asset_task_id}} with a real ID).
2. Params tab — Edit query parameters. Toggle parameters on/off using the checkbox. Disabled parameters are saved but not sent.
3. Headers tab — View and modify request headers. The x-api-key and Accept headers are inherited from the collection.
4. Body tab — For POST/PUT/PATCH requests, edit the request body (JSON, multipart form data, etc.).
5. Send button — Click to execute the request against the selected environment.
6. Response panel — After sending, view the response status code, headers, body (formatted JSON), and response time.

---

Each endpoint includes a saved Example Response showing the expected response shape without needing to send a request. Click the Examples dropdown above the playground to view it.

Examples include realistic sample data so you can understand the response structure before making your first request.

---

The Workflows section contains guided multi-step sequences for common tasks:

Workflow	Description
First-Mile Discovery	Start from a company name — discover candidate supply locations, validate them, and ingest for analysis
Plot Ingestion	Upload plot geometry, review staged plots, then opt into assessments + metrics
Facility / Supplier Ingestion	Upload facilities with supplier fields, validate, trigger metrics, retrieve results
Quick Ingestion	Simplified one-shot upload with metrics included
Shed Ingestion	Upload and process supply shed (sourcing area) locations
EUDR	Build an audit-trail record (fast path or explicit), then authorise and file the DDS with EU TRACES
Parcel Search	Search cadastral parcels by coordinates, view results, ingest as plots

Each step in a workflow is a standalone request that builds on the previous step. Post-response scripts automatically extract IDs and other values from responses and store them as variables for the next step — so you can run through an entire workflow sequentially without manually copying IDs.

To run a workflow:

1. Navigate to the workflow in the sidebar.
2. Start with Step 1 and click Send.
3. The response script stores the task ID (e.g. asset_task_id) as a variable.
4. Move to Step 2 — the URL automatically includes the stored variable.
5. Continue through each step in order.

---

The playground can generate ready-to-use code for the current request configuration. Look for the code snippet option to copy the request as:

• cURL — command-line HTTP request
• JavaScript — using fetch
• Python — using requests

The generated code includes your current parameters, headers, body, and authentication — ready to paste into your application.

---

Every request you send is saved in your browser's local storage. Access your Request History to:

• Review previous requests and their responses
• Re-send a past request with one click
• Compare responses across different parameters or environments

History is stored locally in your browser and is not shared or uploaded.

---

The Collection Runner lets you execute an entire workflow or folder of requests sequentially:

1. Navigate to a workflow folder in the sidebar.
2. Click the Run button to execute all steps in order.
3. The runner displays pass/fail status for each step, including response validation.
4. Variables flow between steps automatically, so the full end-to-end flow works without intervention.

Use the collection runner to verify that a complete workflow works against your environment, or to quickly set up test data.