Endpoints available for ICR App installation and Organization access tokens

Your ICR App can make requests to the following REST endpoints with an installation access token.

Who can use these endpoints

You can use an installation access token to access these endpoints using your ICR App. For more information, see "Authenticating as an ICR App installation." And you can also use an organization access token, see "Authenticating as an ICR organization".

Organization warehouse

The organization warehouse is where an organization can deposit their credits and give apps access to the warehouse inventory where they can transfer them without asking for permission to do so each time.

But to move credits from the warehouse they first need to be put into the reservation queue, where they are reserved for the app that put them in the queue. This is so that the app can verify off platform data / actions before finalizing a transfer / retirement action. This can be very handy for marketplaces that do not wish to hold the credits themselves and instead use the warehouse system to reserve and transfer the credits when an actual buyer / retiree has been found.

list all credits in the warehouse inventory

This returns a list of all the credits in the organization's warehouse. Ids for the projects that issued those credits are also in place so using this endpoint in conjunction with the projects or project endpoints is handy.

Callable by any access token with permissions "organization_warehouse:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

inventory reservations

Returns a paginated list of all reservations, and the state of those reservations, made against the organization's warehouse.

Callable by any access token with permissions "organization_warehouse:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

reserve credits

Reserving credits from a warehouse for later transfer. They are reserved for up to 10 minutes before they are moved back into the warehouse.

Callable by any access token with permissions "organization_warehouse:write".

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 10,
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"
}'

specific reservation

Gets a specific reservation made.

Callable by any access token with permissions "organization_warehouse:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

cancel specific reservation

Cancels an outstanding reservation your app made.

Callable by any access token with permissions "organization_warehouse:write".

curl -X 'DELETE' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

finish outstanding reservation

This can only be called withing 10minutes from the creation of the reservation.

Callable by any access token with permissions "organization_warehouse:write".

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}/{ACTION}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "receiverId": "123e4567-e89b-12d3-a456-426614174000",
  "receiverAddress": "0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "transferComment": "This is a comment",
  "retirementData": {
    "reason": "Retirement reason",
    "beneficiaryName": "John Doe",
    "comment": "This is a comment"
  }
}'

Organization info

Metadata for organization.

organization info

Gets base information on a specific organization.

Callable by any access token with permissions "organization_info:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

organization addresses

Gets the public evm addresses of an organization. Mainly used for getting addresses to deposit credits into.

Callable by any access token with permissions "organization_info:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/addresses' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

organization stakeholders

Gets the stakeholders of an organization.

Callable by any access token with permissions "organization_members:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/members' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Organization retirements

For getting information on retirements made / held by organizations.

list organization retirements

Gets a paginated list of all retirements made by an organization.

Callable by any access token with permissions "organization_info:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/retirements' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

specific retirement made by organization

Gets data from a specific retirement made by an organization.

Callable by any access token with permissions "organization_info:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/retirements/{RETIREMENT_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

retirement pdf

Downloads the official retirement pdf.

Callable by any access token with permissions "organization_info:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/retirements/{RETIREMENT_ID}/pdf' \
  -H 'accept: application/octet-stream' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Organization inventory

This is the main inventory of an organization. Currently only "read" and "read and request" access are available for the inventory. The "read and request" access gives an app the permission to make transfer / retirement requests toward the credits in the organization's inventory.

organization's inventory

This returns all the credits in an organization's inventory.

Callable by any access token with permissions "organization_inventory:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

inventory requests

A paginated list of all requests made toward the credits in this particular organization's inventory.

Callable by any access token with permissions "organization_inventory:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/requests' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

specific inventory request

Gets a specific inventory request.

Callable by any access token with permissions "organization_inventory:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/requests/{REQUEST_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

create an inventory request

Creates a "transfer" / "retire" / "transfer_retire" inventory request which the organization's admin can review and accept / decline.

Callable by any access token with permissions "organization_inventory:read_request".

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/requests/{REQUEST_ACTION}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "creditId": "exPost-2-0x1234567890abcdef",
  "amount": 100,
  "toOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "toAddress": "0x1234567890abcdef",
  "retirementData": {
    "reason": "Retirement reason",
    "beneficiaryName": "John Doe",
    "comment": "This is a comment"
  }
}'

Transfer / Retire credits from inventory

Creates a "transfer" / "retire" / "transfer_retire" transaction and puts it in the processing queue. To monitor the state of the transaction you can query the transaction endpoint.

Callable by any access token with permissions "organization_inventory:read_write".

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/action/{REQUEST_ACTION}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "creditId": "exPost-2-0x1234567890abcdef",
  "amount": 100,
  "toOrganizationId": "123e4567-e89b-12d3-a456-426614174000",
  "toAddress": "0x1234567890abcdef",
  "retirementData": {
    "reason": "Retirement reason",
    "beneficiaryName": "John Doe",
    "comment": "This is a comment"
  }
}'

read specific transaction

Gets a specific transaction.

Callable by any access token with permissions "organization_inventory:read".

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/inventory/transactions/{TRANSACTION_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Testing endpoints

friendbot - test credits

To get some test credits into your organization on the sandbox you can use this endpoint with and organization Id that you control. It will deposit a 100 credits into your organization.

Callable by any access token regardless of permissions.

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/friendbot' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'
PreviousEndpoints available for ICR appsNextEndpoints available for access tokens

Last updated