Kwindexa API Reference

The Kwindexa REST API lets you manage organizations, campuses, facilities, impact metrics, and sustainability snapshots — then compute a unified KWI score for any facility.

BASE URL /api/v1

Organizations

GET /api/v1/organizations List all organizations

Returns all organizations. No query parameters required.

Response · 200

{
  "status": "success",
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Meridian Data Centers",
      "slug": "meridian-data-centers",
      "industry": "colocation",
      "headquartersCountry": "US",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

GET /api/v1/organizations/:id Get one organization

Returns a single organization by UUID.

Path Parameters

Name	Type	Required	Description
id	uuid	Required	Organization UUID

Response · 200

{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Meridian Data Centers",
    "slug": "meridian-data-centers",
    "industry": "colocation",
    "headquartersCountry": "US",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

POST /api/v1/organizations Create organization

Creates a new organization.

Request Body

Field	Type	Required	Description
name	string	Required	1–255 characters
slug	string	Required	Lowercase alphanumeric with hyphens, 1–100 chars
industry	string	Optional	Up to 255 characters
headquartersCountry	string	Optional	Up to 100 characters

Request Example

{
  "name": "Meridian Data Centers",
  "slug": "meridian-data-centers",
  "industry": "colocation",
  "headquartersCountry": "US"
}

Response · 201

{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Meridian Data Centers",
    "slug": "meridian-data-centers",
    "industry": "colocation",
    "headquartersCountry": "US",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

PATCH /api/v1/organizations/:id Update organization

Partially updates an organization. Include only the fields you want to change.

Path Parameters

Name	Type	Required	Description
id	uuid	Required	Organization UUID

Request Body

Field	Type	Required	Description
name	string	Optional	1–255 characters
slug	string	Optional	Lowercase alphanumeric with hyphens, 1–100 chars
industry	string	Optional	Up to 255 characters
headquartersCountry	string	Optional	Up to 100 characters

Request Example

{
  "industry": "hyperscale"
}

Response · 200

{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Meridian Data Centers",
    "slug": "meridian-data-centers",
    "industry": "hyperscale",
    "headquartersCountry": "US",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-20T08:00:00.000Z"
  }
}

DELETE /api/v1/organizations/:id Delete organization

Deletes an organization by UUID. Returns no content on success.

Path Parameters

Name	Type	Required	Description
id	uuid	Required	Organization UUID

Response · 204 No Content

(empty body)

Campuses

POST /api/v1/campuses Create campus

Creates a new campus under an organization.

Request Body

Field	Type	Required	Description
organizationId	uuid	Required	Parent organization UUID
name	string	Required	1–255 characters
location	string	Optional	Up to 255 characters
region	string	Optional	Up to 100 characters

Request Example

{
  "organizationId": "a1b2c3d4-...",
  "name": "Portland Campus",
  "location": "Portland, OR",
  "region": "us-west"
}

Response · 201

{
  "status": "success",
  "data": {
    "id": "b2c3d4e5-...",
    "organizationId": "a1b2c3d4-...",
    "name": "Portland Campus",
    "location": "Portland, OR",
    "region": "us-west",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

GET /api/v1/campuses/:id Get one campus

Returns a single campus by UUID, including its facilities.

Path Parameters

Name	Type	Required	Description
id	uuid	Required	Campus UUID

Response · 200

{
  "status": "success",
  "data": {
    "id": "b2c3d4e5-...",
    "organizationId": "a1b2c3d4-...",
    "name": "Portland Campus",
    "location": "Portland, OR",
    "region": "us-west",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Facilities

GET /api/v1/facilities List facilities

Returns all facilities. Optionally filter by campus.

Query Parameters

Name	Type	Required	Description
campusId	uuid	Optional	Filter by parent campus UUID

Response · 200

{
  "status": "success",
  "data": [
    {
      "id": "c3d4e5f6-...",
      "campusId": "b2c3d4e5-...",
      "name": "PDX-01",
      "type": "data_center",
      "designCapacityMW": 12.5,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

GET /api/v1/facilities/:id Get one facility

Returns a single facility by UUID.

Path Parameters

Name	Type	Required	Description
id	uuid	Required	Facility UUID

Response · 200

{
  "status": "success",
  "data": {
    "id": "c3d4e5f6-...",
    "campusId": "b2c3d4e5-...",
    "name": "PDX-01",
    "type": "data_center",
    "designCapacityMW": 12.5,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

POST /api/v1/facilities Create facility

Creates a new facility under a campus.

Request Body

Field	Type	Required	Description
campusId	uuid	Required	Parent campus UUID
name	string	Required	1–255 characters
type	enum	Optional	`data_center` (default), `edge`, or `other`
designCapacityMW	number	Optional	Positive number (megawatts)

Request Example

{
  "campusId": "b2c3d4e5-...",
  "name": "PDX-01",
  "type": "data_center",
  "designCapacityMW": 12.5
}

Response · 201

{
  "status": "success",
  "data": {
    "id": "c3d4e5f6-...",
    "campusId": "b2c3d4e5-...",
    "name": "PDX-01",
    "type": "data_center",
    "designCapacityMW": 12.5,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Impact Metrics

GET /api/v1/impact-metrics List all metrics

Returns all defined impact metrics (e.g. PUE, WUE, carbonIntensity, communityInvestment).

Response · 200

{
  "status": "success",
  "data": [
    {
      "id": "d4e5f6a7-...",
      "key": "PUE",
      "unit": "ratio",
      "description": "Power Usage Effectiveness",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

GET /api/v1/impact-metrics/:id Get one metric

Returns a single impact metric definition by UUID.

Path Parameters

Name	Type	Required	Description
id	uuid	Required	Impact metric UUID

Response · 200

{
  "status": "success",
  "data": {
    "id": "d4e5f6a7-...",
    "key": "PUE",
    "unit": "ratio",
    "description": "Power Usage Effectiveness",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

POST /api/v1/impact-metrics Create metric

Defines a new impact metric that can be used in snapshots.

Request Body

Field	Type	Required	Description
key	string	Required	Alphanumeric, starts with letter (e.g. `PUE`, `carbonIntensity`), 1–100 chars
unit	string	Required	Unit label, 1–100 chars (e.g. `ratio`, `L/kWh`)
description	string	Optional	Up to 500 characters

Request Example

{
  "key": "PUE",
  "unit": "ratio",
  "description": "Power Usage Effectiveness"
}

Response · 201

{
  "status": "success",
  "data": {
    "id": "d4e5f6a7-...",
    "key": "PUE",
    "unit": "ratio",
    "description": "Power Usage Effectiveness",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Impact Snapshots

GET /api/v1/impact-snapshots Query snapshots

Query time-series snapshot data for a specific facility and metric. Supports time-range filtering, pagination, and sort order.

Query Parameters

Name	Type	Required	Description
facilityId	uuid	Required	Facility UUID
metricKey	string	Required	Metric key (e.g. `PUE`)
from	ISO-8601	Optional	Start of time range
to	ISO-8601	Optional	End of time range
limit	integer	Optional	1–5000 (default: 500)
order	enum	Optional	`asc` or `desc` (default: `desc`)

Response · 200

{
  "status": "success",
  "data": [
    {
      "id": "e5f6a7b8-...",
      "facilityId": "c3d4e5f6-...",
      "metricId": "d4e5f6a7-...",
      "timestamp": "2025-01-15T12:00:00.000Z",
      "value": 1.35,
      "createdAt": "2025-01-15T12:00:05.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "limit": 500,
    "order": "desc"
  }
}

POST /api/v1/impact-snapshots Create snapshot

Ingests a single metric snapshot for a facility.

Request Body

Field	Type	Required	Description
facilityId	uuid	Required	Target facility UUID
metricKey	string	Required	Metric key (e.g. `PUE`)
timestamp	ISO-8601	Required	Measurement timestamp
value	number	Required	Finite numeric value

Request Example

{
  "facilityId": "c3d4e5f6-...",
  "metricKey": "PUE",
  "timestamp": "2025-01-15T12:00:00.000Z",
  "value": 1.35
}

Response · 201

{
  "status": "success",
  "data": {
    "id": "e5f6a7b8-...",
    "facilityId": "c3d4e5f6-...",
    "metricId": "d4e5f6a7-...",
    "timestamp": "2025-01-15T12:00:00.000Z",
    "value": 1.35,
    "createdAt": "2025-01-15T12:00:05.000Z"
  }
}

POST /api/v1/impact-snapshots/bulk Bulk create snapshots

Ingests multiple snapshots in a single request. Accepts 1–5,000 snapshots per batch.

Request Body

Field	Type	Required	Description
snapshots	array	Required	Array of 1–5000 snapshot objects (same schema as single create)

Request Example

{
  "snapshots": [
    {
      "facilityId": "c3d4e5f6-...",
      "metricKey": "PUE",
      "timestamp": "2025-01-15T12:00:00.000Z",
      "value": 1.35
    },
    {
      "facilityId": "c3d4e5f6-...",
      "metricKey": "WUE",
      "timestamp": "2025-01-15T12:00:00.000Z",
      "value": 0.45
    }
  ]
}

Response · 200

{
  "status": "success",
  "data": {
    "count": 2
  }
}

KWI Score

GET /api/v1/kwi/facility/:facilityId Compute KWI score

Computes the Kwindexa Sustainability Index for a facility. Averages all snapshot values per metric within the optional time range, normalizes each against best/worst benchmarks, and produces a weighted composite score (0–100).

Default weights: PUE 35%, WUE 25%, Carbon Intensity 25%, Community Investment 15%. Weights are re-normalized if any metrics are missing.

Path Parameters

Name	Type	Required	Description
facilityId	uuid	Required	Facility UUID

Query Parameters

Name	Type	Required	Description
from	ISO-8601	Optional	Start of time range
to	ISO-8601	Optional	End of time range

Response · 200

{
  "status": "success",
  "data": {
    "facilityId": "c3d4e5f6-...",
    "from": "2025-01-01T00:00:00.000Z",
    "to": "2025-01-31T23:59:59.000Z",
    "metrics": {
      "avgPUE": 1.35,
      "avgWUE": 0.45,
      "avgCarbonIntensity": 0.18,
      "avgCommunityInvestment": 320000
    },
    "subscores": {
      "PUE": 81.25,
      "WUE": 80.77,
      "carbonIntensity": 76.36,
      "communityInvestment": 64.0
    },
    "kwiScore": 77.12,
    "evaluated": ["PUE", "WUE", "carbonIntensity", "communityInvestment"],
    "missing": [],
    "benchmarks": {
      "PUE": { "best": 1.2, "worst": 2.0 },
      "WUE": { "best": 0.2, "worst": 1.5 },
      "carbonIntensity": { "best": 0.05, "worst": 0.6 },
      "communityInvestment": { "best": 500000, "worst": 0 }
    },
    "weights": {
      "PUE": 0.35,
      "WUE": 0.25,
      "carbonIntensity": 0.25,
      "communityInvestment": 0.15
    }
  }
}

Error Reference

All errors follow a consistent JSON structure.

400 Validation Error

Returned when the request body or parameters fail Zod schema validation.

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "name",
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

404 Not Found

Returned when a referenced resource does not exist.

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "Facility not found: c3d4e5f6-..."
}

500 Internal Server Error

Returned for unexpected server-side failures.

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred"
}