Targets API

The Targets API lets you create, read and update emissions reduction targets and their milestone records programmatically.

List targets

GET /api/v1/targets

Query parameters

Parameter	Type	Description
`type`	string	`absolute`, `intensity`, `net_zero`, `sbti`, `custom`
`status`	string	`active`, `achieved`, `missed`, `archived`
`page`	integer
`pageSize`	integer	Max 100

Response

{
  "data": [
    {
      "id": "tgt_abc123",
      "name": "Net Zero by 2040",
      "type": "net_zero",
      "status": "active",
      "scopeCoverage": [1, 2, 3],
      "baseYear": 2020,
      "baseYearTco2e": 2500.0,
      "targetYear": 2040,
      "reductionPercent": 90.0,
      "trajectoryModel": "linear",
      "currentTco2e": 1240.5,
      "progressPercent": 50.4,
      "createdAt": "2021-01-01T00:00:00Z"
    }
  ]
}

Get a target

GET /api/v1/targets/{targetId}

Returns the full target including milestones and annual budget calculations.

Create a target

POST /api/v1/targets

Request body

{
  "name": "SBTi 1.5°C Near-Term Target",
  "type": "sbti",
  "scopeCoverage": [1, 2],
  "baseYear": 2020,
  "baseYearTco2e": 2500.0,
  "targetYear": 2030,
  "reductionPercent": 50.0,
  "trajectoryModel": "linear",
  "description": "Validated SBTi 1.5°C aligned near-term target",
  "intensityDenominator": null
}

Field	Type	Required	Description
`name`	string	✅	Target label
`type`	string	✅	Target type code
`scopeCoverage`	integer[]	✅	Scope numbers covered
`baseYear`	integer	✅	Reference year
`baseYearTco2e`	decimal	✅	Base year emissions
`targetYear`	integer	✅	Year to achieve reduction
`reductionPercent`	decimal	✅	Required % reduction
`trajectoryModel`	string	✅	`linear`, `front_loaded`, `custom`
`description`	string	Optional
`intensityDenominator`	object	Conditional	Required for `intensity` type

Response (201)

The created target object.

Update a target

PATCH /api/v1/targets/{targetId}

Updates modifiable fields. Base year emissions can be adjusted (recorded as a revision).

Archive a target

POST /api/v1/targets/{targetId}/archive

Archived targets are retained for reporting history but no longer appear in the active target list.

Milestones

List milestones for a target

GET /api/v1/targets/{targetId}/milestones

{
  "data": [
    {
      "id": "ms_001",
      "year": 2025,
      "label": "SBTi 2025 check",
      "requiredReductionPercent": 25.0,
      "allowedTco2e": 1875.0,
      "actualTco2e": 1820.0,
      "status": "achieved",
      "verified": false,
      "verifiedAt": null
    }
  ]
}

Create a milestone

POST /api/v1/targets/{targetId}/milestones

{
  "year": 2027,
  "label": "Mid-point check",
  "requiredReductionPercent": 37.5
}

Update a milestone

PATCH /api/v1/targets/{targetId}/milestones/{milestoneId}

Mark a milestone as verified

POST /api/v1/targets/{targetId}/milestones/{milestoneId}/verify

{
  "notes": "Confirmed by external verifier Smith & Partners",
  "verifiedBy": "external"
}

Delete a milestone

DELETE /api/v1/targets/{targetId}/milestones/{milestoneId}

Target progress endpoint

Returns a computed progress summary suitable for dashboard widgets — no need to calculate trajectories client-side:

GET /api/v1/targets/{targetId}/progress

{
  "data": {
    "targetId": "tgt_abc123",
    "currentYear": 2024,
    "currentTco2e": 1240.5,
    "allowedTco2eThisYear": 1375.0,
    "trajectoryTco2e": 1400.0,
    "progressPercent": 50.4,
    "status": "on_track",
    "nextMilestone": {
      "year": 2025,
      "allowedTco2e": 1875.0,
      "label": "SBTi 2025 check"
    }
  }
}