API Overview

The EmWise API lets your TMS, ERP, or integration layer submit transport jobs and receive NGER Method 1 emission calculations in real time.

Base URL

https://<project-ref>.supabase.co/functions/v1/jobs-api

Contact your EmWise administrator for the exact <project-ref> for your deployment. All endpoint paths below are relative to this base URL.

Authentication

All endpoints (except GET /emission-factor-types) require a Bearer token.

Authorization: Bearer ew_<your-api-key>

API keys are created by Org Admins in the EmWise dashboard under Settings → API Keys. Each key is organisation-scoped — it can only create jobs for the organisation it belongs to.

Keys are stored as SHA-256 hashes. The plaintext key is shown exactly once at creation time. If you lose it, delete the key and create a new one.

Key rotation

If an API key was created before hashing was enabled, it will be flagged as requires_rotation in the dashboard. Rotate it as soon as practical — old unhashed keys will not be accepted by the API.

Rate limiting

1,000 requests per rolling hour per API key, applied to POST operations only. GET requests are not rate-limited.

When the limit is exceeded the API returns 429 Too Many Requests with the following headers:

Header	Description
Retry-After	Seconds until the rate limit window resets
X-RateLimit-Limit	Maximum requests per hour (1000)
X-RateLimit-Remaining	Always 0 when rate-limited
X-RateLimit-Reset	Unix timestamp when the window resets

Error response format

All errors return JSON with this structure:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "details": {}
}

Error codes

HTTP status	code	Meaning
400	VALIDATION_ERROR	A required field is missing, has the wrong type, or is out of range
401	UNAUTHORIZED	Missing or invalid API key
404	NOT_FOUND	Endpoint path not recognised
405	METHOD_NOT_ALLOWED	HTTP method not supported for this endpoint
422	FACTOR_NOT_FOUND	No emission factor exists for the requested transport mode / fuel type / vehicle class / reporting year combination
422	VEHICLE_CLASS_REQUIRED	The transport mode and fuel type combination has multiple emission factor rows — a vehicle_class must be specified
429	RATE_LIMITED	Rate limit exceeded
500	INTERNAL_ERROR	Unexpected server error

Idempotency

The reference_number field on job submissions acts as an idempotency key. If you submit a job with a reference_number that already exists in your organisation, the API returns the original calculation result with "idempotent": true — no duplicate record is created and the response status is 200 (not 201).

This makes it safe to retry failed requests. Include your TMS trip or job ID as the reference_number.

Public endpoint

GET /emission-factor-types returns the available transport modes and fuel types and does not require authentication. Useful for populating dropdowns or validating inputs before submission.

curl https://<project-ref>.supabase.co/functions/v1/jobs-api/emission-factor-types

Available endpoints

Method	Path (relative to base URL)	Auth	Description
GET	/emission-factor-types	None	List available transport modes and fuel types
GET	/clients	Bearer	List clients in your organisation
POST	/jobs	Bearer	Submit a job and receive emission results