CAI APIAPI Reference

Classifications and Measurements

Processing produces classifications and measurements for uploaded files. Use the endpoints below to review results and apply verification.

List classifications (v1)

Retrieve classifications, optionally filtered by verified.

curl -H "Authorization: Bearer $CAI_TOKEN" \
  "$CAI_BASE_URL/api/v1/classifications/?project_id=$CAI_PROJECT_ID"

curl -H "Authorization: Bearer $CAI_TOKEN" \
  "$CAI_BASE_URL/api/v1/classifications/?project_id=$CAI_PROJECT_ID&verified=true"

Measured classifications

Retrieve classifications that include measurement data.

curl -H "Authorization: Bearer $CAI_TOKEN" \
  "$CAI_BASE_URL/api/v1/classifications/measured?project_id=$CAI_PROJECT_ID"

List classifications (v2)

Use v2 for richer filtering by scope, category, and provider.

curl -H "Authorization: Bearer $CAI_TOKEN" \
  "$CAI_BASE_URL/api/v2/classifications/?project_id=$CAI_PROJECT_ID&scope=Scope%201&category=Purchased%20Electricity"

Verify or un-verify a classification

Verify a single classification with optional overrides.

curl -X PATCH "$CAI_BASE_URL/api/v1/classifications/$CLASSIFICATION_ID/verify" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "Scope 2",
    "category": "Purchased Electricity",
    "activity_verified": {
      "activity": "Electricity",
      "activity_start_date": "2024-01-01",
      "activity_end_date": "2024-01-31",
      "activity_amount": 1200,
      "activity_unit": "kWh",
      "provider": "Utility Co",
      "origin_country": "US",
      "end_country": "US",
      "origin_region": null,
      "end_region": null,
      "subcategory": {}
    }
  }'

Un-verify and return the original object:

curl -X PATCH "$CAI_BASE_URL/api/v1/classifications/$CLASSIFICATION_ID/un-verify" \
  -H "Authorization: Bearer $CAI_TOKEN"

Batch verification and deletion

Batch operations accept an array of classification_ids.

curl -X PATCH "$CAI_BASE_URL/api/v1/classifications/batch/verify" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "classification_ids": [123, 456] }'

curl -X POST "$CAI_BASE_URL/api/v1/classifications/batch/delete" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "classification_ids": [123, 456] }'

Measurements

Retrieve detailed and aggregated measurements.

curl -H "Authorization: Bearer $CAI_TOKEN" \
  "$CAI_BASE_URL/api/v2/measurements/?project_id=$CAI_PROJECT_ID"

curl -H "Authorization: Bearer $CAI_TOKEN" \
  "$CAI_BASE_URL/api/v2/measurements/aggregated?project_id=$CAI_PROJECT_ID"

Use the API Reference for full schemas and advanced measurement endpoints.