Management

⚠️

Preview Feature

This feature is currently in preview. That means that we believe the feature is good enough to start using, but:

There might still be bugs or edge cases we haven't covered.
The documentation and error messages might be less detailed.
We might need to make further changes in the API surface.

We need the ability to iterate quickly on preview versions, so we offer less guarantees of stability. When we make changes to the preview version, we will release a new version, and you must migrate to this new version within one month. Read more about API versioning at Climatiq here.For this reason, preview endpoints are not available without explicitly opting in. If you would like to opt-in to this preview feature, please contact us.

For most users, the easiest way to get started is by creating projects and API keys through the Climatiq dashboard (opens in a new tab). For some use-cases you might need to manage many projects and API keys, and then clicking through the UI can become unwieldy and time-consuming.

For cases like these, Climatiq offers a management API to programmatically create, read, update and delete your projects and API keys.

Authentication

These API endpoints are authenticated by a user-level management API key, not a regular API key. While a regular API key is scoped to one particular project, a management API key is scoped to a user, and allows management of resources as that user.

Currently, there is no way to create one of these keys in the UI. If you need one of these keys, please reach out (opens in a new tab).

The management API key is used via the Authorization header, in the same position as a regular API key.

Project

One Climatiq user can have several projects. Projects have a name, and contain one or more API Keys. These are several endpoints that help you manage projects.

All endpoints operate on projects that belong to the user the provided management API key is attached to.

List

GET Returns the list of projects associated with the owner of the provided management API key.

https://preview.api.climatiq.io/management/v1-preview1/project

Request

curl --request GET \
  --url https://preview.api.climatiq.io/management/v1-preview1/project \
  --header "Authorization: Bearer $CLIMATIQ_MANAGEMENT_API_KEY"

Response

The response is an array of project that belong to the user that the used management API key is attached to.

[
    {
        "id": "1234",
        "project_name": "Your project name",
        "owner": {
            "id": "5678"
        }
    }
]

Create

POST Creates a new project belonging to the owner of the used management API key.

https://preview.api.climatiq.io/management/v1-preview1/project

Request

Request parametersShould be sent as a JSON object in the body

project_namerequired string
The name of the newly created project.

curl --request POST \
  --url https://preview.api.climatiq.io/management/v1-preview1/project \
  --header "Authorization: Bearer $CLIMATIQ_MANAGEMENT_API_KEY" \
  --data '{
	"project_name": "My New Project"
}'

Response

The API returns the newly created project.

{
    "id": "1234",
    "project_name": "My New project",
    "owner": {
        "id": "5678"
    }
}

Update

PATCH Updates a specific project.

https://preview.api.climatiq.io/management/v1-preview1/project/:project_id

The project is selected by replacing :project_id in the URL above with the ID of the specific project.

Request

Request parametersShould be sent as a JSON object in the body

project_namerequired string
The new name for the project

curl --request PATCH \
  --url https://preview.api.climatiq.io/management/v1-preview1/project/1234 \
  --header "Authorization: Bearer $CLIMATIQ_MANAGEMENT_API_KEY" \
  --data '{
	"project_name": "New name"
}'

Response

The endpoint returns the updated project.

{
    "id": "1234",
    "project_name": "New name",
    "owner": {
        "id": "5678"
    }
}

Delete

DELETE Deletes a specific project. This will also delete all API Keys that belong to the project. This action cannot be undone.

https://preview.api.climatiq.io/management/v1-preview1/project/:project_id

The project is selected by replacing :project_id in the URL above with the ID of the specific project.

Request

curl --request DELETE \
  --url https://preview.api.climatiq.io/management/v1-preview1/project/1234 \
  --header "Authorization: Bearer $CLIMATIQ_MANAGEMENT_API_KEY"

Response

The endpoint returns a message explaining that the project was deleted successfully.

Response parameters

messagestring
A message concerning the deletion status of the project

{
    "message": "Project deleted"
}

API Keys

API Keys are used to authenticate with the Climatiq API to perform estimations, search for emission factors and more. API keys always belong to a project, and a project can have multiple API keys. Keep in mind that while these endpoints require a management API key, they do not allow for creation, updating or deleting management API keys - only regular ones.

⚠️

Sensitive Information

Responses from this API contain API Keys. This means that anyone who can read the response bodies will be able to see and use your Climatiq API keys. You should treat the response of this API as sensitive, when considering e.g. whether to log them or not.

List

GET Returns a list of API keys that belong to a given project.

https://preview.api.climatiq.io/management/v1-preview1/project/:project_id/api-key

The project is selected by replacing :project_id in the URL above with the ID of the specific project.

Request

curl --request GET \
  --url https://preview.api.climatiq.io/management/v1-preview1/project/1234/api-key \
  --header "Authorization: Bearer $CLIMATIQ_MANAGEMENT_API_KEY"

Response

Returns an array of API keys that belongs to the specified project.

[
    {
        "id": "8888",
        "key_name": "Autogenerated Test key",
        "key": "YOUR_API_KEY_HERE",
        "project": {
            "id": "1234"
        }
    }
]

Create

POST Creates a new API key that belongs to a specific project.

https://preview.api.climatiq.io/management/v1-preview1/project/:project_id/api-key

The project is selected by replacing :project_id in the URL above with the ID of the specific project.

Request

Request parametersShould be sent as a JSON object in the body

key_namerequired string
The name of the API key

curl --request POST \
  --url https://preview.api.climatiq.io/management/v1-preview1/project/1234/api-key \
  --header "Authorization: Bearer $CLIMATIQ_MANAGEMENT_API_KEY" \
  --data '{
		"key_name": "My new key"
}'

Response

Returns the newly created API key

{
    "id": "8888",
    "key_name": "My new key",
    "key": "YOUR_API_KEY_HERE",
    "project": {
        "id": "1234"
    }
}

Update

PATCH Updates a specific API Key.

https://preview.api.climatiq.io/management/v1-preview1/api-key/:api_key_id

The API key is selected by replacing :api_key_id in the URL above with the ID of the specific API key.

Request

Request parametersShould be sent as a JSON object in the body

key_namerequired string
The name of the API key

curl --request PATCH \
  --url https://preview.api.climatiq.io/management/v1-preview1/api-key/8888 \
  --header "Authorization: Bearer $CLIMATIQ_MANAGEMENT_API_KEY" \
  --data '{
		"key_name": "My new name"
}'

Response

Returns the newly updated API key.

{
    "id": "8888",
    "key_name": "My new name",
    "key": "YOUR_API_KEY",
    "project": {
        "id": "1234"
    }
}

Delete

DELETE Deletes a specific project.

https://preview.api.climatiq.io/management/v1-preview1/api-key/:api_key_id

The API key is selected by replacing :api_key_id in the URL above with the ID of the specific API key.

Request

curl --request DELETE \
  --url https://preview.api.climatiq.io/management/v1-preview1/api-key/8888 \
  --header "Authorization: Bearer $CLIMATIQ_MANAGEMENT_API_KEY"

Response

Response parameters

messagestring
A message concerning the deletion status of the API key

{
    "message": "API key deleted"
}

Models

Project

Most of the project-related endpoints return this model.

Response parameters

idstring
The ID of the project.
project_namestring
The name of the project.
ownerobject
The user that owns the project
owner.idstring
The ID of the user that owns the project.

API Key

Most of the API key-related endpoints return this model.

Response parameters

idstring
The ID of the API key.
key_namestring
The name of the API key. This name is displayed in the Climatiq dashboard
key
The actual API key. This is the value that goes in the Authorization header for requests.
projectobject
The project that this API key belongs to
project.id
The ID of the project this API key belongs to

Data Versions Freight v2