Retirements

Endpoints that return retirement certificates carbonregistry.com has issued

Get all retirements

get

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitnumberOptional

Limit the number of results returned

pagenumberOptional

Page number for pagination

Responses

200Success

application/json

get

/v1/retirements

HTTPcURLJavaScriptPython

GET /v1/retirements HTTP/1.1
Host: api.carbonregistry.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

{
  "retirements": [
    {
      "createdAt": "2025-12-14T11:34:38.006Z",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "isClaimed": true,
      "reason": "Reached retirement age",
      "comment": "Congratulations on your retirement!",
      "beneficiary": "John Doe",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "organizationOwner": {
        "fullName": "John Doe",
        "logo": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRzKakVt-GHFNrAN9xFd8B26vYVFLyWoUds8w&usqp=CAU",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "publicUrl": "https://www.carbonregistry.com/explore/organizations/62ffdcad-bd0d-42f7-b8ff-28785a929ed0"
      },
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "vintage": "2020",
      "amount": 1000,
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      }
    }
  ],
  "pagination": {
    "total": 100,
    "currentPage": 1,
    "pageCount": 10,
    "nextPage": 2,
    "prevPage": 0
  }
}

Get a specific retirement by ID

get

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

The ID of the retirement

Responses

200Success

application/json

get

/v1/retirements/{id}

HTTPcURLJavaScriptPython

GET /v1/retirements/{id} HTTP/1.1
Host: api.carbonregistry.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

{
  "retirement": {
    "createdAt": "2025-12-14T11:34:38.006Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "isClaimed": true,
    "reason": "Reached retirement age",
    "comment": "Congratulations on your retirement!",
    "beneficiary": "John Doe",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "organizationOwner": {
      "fullName": "John Doe",
      "logo": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRzKakVt-GHFNrAN9xFd8B26vYVFLyWoUds8w&usqp=CAU",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "publicUrl": "https://www.carbonregistry.com/explore/organizations/62ffdcad-bd0d-42f7-b8ff-28785a929ed0"
    },
    "serialization": "ICR-ISL-354-78040-14-R-0-2021",
    "vintage": "2020",
    "amount": 1000,
    "project": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "fullName": "Project 1",
      "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
      "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
      "num": "713"
    }
  }
}

Get retirements for an entity

get

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Entity ID

Responses

200Success

application/json

get

/v1/{id}/retirements

HTTPcURLJavaScriptPython

GET /v1/{id}/retirements HTTP/1.1
Host: api.carbonregistry.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

{
  "retirements": [
    {
      "createdAt": "2025-12-14T11:34:38.006Z",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "isClaimed": true,
      "reason": "Reached retirement age",
      "comment": "Congratulations on your retirement!",
      "beneficiary": "John Doe",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "organizationOwner": {
        "fullName": "John Doe",
        "logo": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRzKakVt-GHFNrAN9xFd8B26vYVFLyWoUds8w&usqp=CAU",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "publicUrl": "https://www.carbonregistry.com/explore/organizations/62ffdcad-bd0d-42f7-b8ff-28785a929ed0"
      },
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "vintage": "2020",
      "amount": 1000,
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      }
    }
  ]
}