API Documentation

Getting Started

The ClauseHub Energy API provides standardised access to UK energy tariff data in JSON:API format. All requests and responses use the application/vnd.api+json content type.

Authentication

All authenticated endpoints require a valid Supabase JWT token passed as a Bearer token in the Authorization header. Tokens are issued by the ClauseHub authentication service and encode the user's role and permissions.

Roles

The API enforces role-based access control with three roles:

• admin — Full read/write access to all resources, including lookup tables and system configuration. Rate limited to 120 requests per minute.
• supplier — Read/write access to their own supplier record and tariffs. Rate limited to 60 requests per minute.
• consumer — Read-only access to published tariff data and public search endpoints. Rate limited to 120 requests per minute.

Example Request

GET /energy/suppliers HTTP/1.1
Host: api.clausehub.net
Accept: application/vnd.api+json
Authorization: Bearer <your-jwt-token>

If the token is missing or invalid, the API returns a 401 Unauthorized error. If the token is valid but the user lacks permission for the requested operation, the API returns 403 Forbidden.

Endpoints

All endpoints are relative to the base URL https://api.clausehub.net/energy.

Response Format

All responses conform to the JSON:API specification. List endpoints return a top-level links object for pagination alongside a data array.

{
  "links": {
    "self": "/energy/suppliers?page[number]=1&page[size]=20",
    "first": "/energy/suppliers?page[number]=1&page[size]=20",
    "last": "/energy/suppliers?page[number]=3&page[size]=20",
    "next": "/energy/suppliers?page[number]=2&page[size]=20",
    "prev": null
  },
  "data": [
    {
      "type": "suppliers",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "attributes": {
        "name": "Octopus Energy",
        "version": 1,
        "status": "active",
        "createdAt": "2025-10-15T09:30:00Z",
        "updatedAt": "2025-10-15T09:30:00Z"
      }
    }
  ]
}

Single-resource endpoints return the same structure, but data is an object rather than an array.

Versioning

The Energy API implements immutable versioning for full audit traceability. Every resource carries a version field that increments on each change.

How It Works

• Create — A new resource is created at version 1 with status active.
• Update (PATCH) — The existing row is preserved as-is. A new row is inserted with an incremented version number and the updated fields. The previous version remains accessible via the /versions endpoint.
• Delete (DELETE) — A new version is created with status archived. No data is physically deleted. The full history remains available.

Accessing History

Every resource type exposes a /versions endpoint that returns the complete version history, ordered by version number descending. This provides a full audit trail of every change made to the resource.

GET /energy/suppliers/a1b2c3d4/versions

# Returns all versions of this supplier, newest first

Errors

Errors follow the JSON:API error format. The response body contains an errors array with one or more error objects:

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "The field 'name' is required.",
      "source": {
        "pointer": "/data/attributes/name"
      }
    }
  ]
}

Status Codes