Quick Start Guide

Make your first Coolset API call in a few minutes. You create your own API key in the Coolset app, then use it to call the endpoints integrators use most.

What you need

• A Coolset account
• A terminal with curl, or any HTTP client

1. Create an API key

You create and manage API keys yourself, in the Coolset app. It takes under a minute.

Sign in to the Coolset app, open My account and scroll to API keys. Any user can create keys for themselves.

Coolset/My account

My account

API keys

Create keys to access the Coolset API programmatically. Each key acts as you, and is scoped either to follow your active workspace or to stay pinned to a single workspace. API authentication docs

Create API key

No API keysYou haven't created any API keys yet.

My account

API keys

Create keys to access the Coolset API programmatically. Each key acts as you, and is scoped either to follow your active workspace or to stay pinned to a single workspace. API authentication docs

Create API key

No API keysYou haven't created any API keys yet.

Create API key

The key authenticates as you. Keep it secret and never share it.

Name *ERP sync

ScopeYou, follows your active workspaceThis workspace only (Example Foods B.V.)

Expiration6 weeks

CancelCreate key

My account

API keys

Create keys to access the Coolset API programmatically. Each key acts as you, and is scoped either to follow your active workspace or to stay pinned to a single workspace. API authentication docs

Create API key

NameKeyScopeCreatedLast usedExpires

Workspace keys (1)

ERP syncgc_7Qm2x…Example Foods B.V.Oct 8, 2026NeverNov 19, 2026

Create API key

Copy your API key now. You won't be able to see it again.

Your API keygc_7Qm2xV9pLr4TnY8sKd3WbH6cJf1Z

Done

$ export COOLSET_API_KEY=gc_7Qm2xV9pLr4TnY8sKd3WbH6cJf1Z

$ curl https://developers.coolset.com/api/accounts/users/me/ \

-H "Authorization: ApiKey $COOLSET_API_KEY"

HTTP/1.1 200 OK

{ "email": "[email protected]", "company": { "name": "Example Foods B.V." } }

API keys

Create keys to access the Coolset API programmatically. Each key acts as you, and is scoped either to follow your active workspace or to stay pinned to a single workspace. API authentication docs

Create API key

NameKeyScopeCreatedLast usedExpires

Workspace keys (1)

ERP syncgc_7Qm2x…Example Foods B.V.Oct 8, 2026Just nowNov 19, 2026

Step 1 of 4

Your key starts with gc_. Treat it like a password: anyone who has it can use the API as you.

Choose a scope

Every key acts as you, with the same permissions you have in the app. The scope decides which workspace its requests go to. Switch the workspace below to see the difference.

Workspace open in the app

User key

Scope option: You, follows your active workspace

Requests go toExample Foods B.V.

Acts as you in whichever workspace you have open. Switch workspace in the app and the key follows.

Good for scripts you run yourself, notebooks and AI assistants.

Workspace key

Scope option: This workspace only

Requests go toExample Foods B.V.

Pinned to the workspace that was open when you created it. Switching in the app has no effect.

Good for integrations, ERP syncs and anything that runs on a server.

Not sure? Use a workspace key for anything that runs unattended. It can never write to the wrong workspace because someone switched in the app.

Choose an expiration

New keys expire after 6 weeks by default. You can choose 30 days, 6 weeks, 90 days, 1 year or no expiration. When a key expires, requests with it return 401. Create a new key and swap it in before then. The Expires column on My account shows when each key stops working.

See Authentication for revoking keys, rotation and security practices.

2. Use the right base URL

Each part of the API is served by its own host. Use the base URL listed for the endpoint you call.

API	What it covers	Base URL
Accounts	Current user, workspaces, team members, invitations	https://developers.coolset.com/api
Carbon	Emissions, emission factors	https://developers.coolset.com/api
Supply Chain	Orders, products, origins, value chains, due diligence statements, traces	https://developers-scranton.coolset.com/api
Compliance	Risk assessments and evidence	https://developers-pulse.coolset.com/api
AI	Skills	https://developers-pulse.coolset.com/api
Data: documents, imports, knowledge base	/documents/, /imports/, /rag/queries/	https://developers-pulse.coolset.com/api
Data: transactions	/expenses/transactions/	https://developers.coolset.com/api
Data: surveys	/consumer-app/...	https://developers-data-room.coolset.com/api

The Data API groups endpoints from three services. Check the table, or the server shown on each endpoint in the API reference, before you call one.

All paths end with a trailing slash, for example /accounts/users/me/.

3. Make your first call

Keep the key out of your code. Put it in an environment variable:

export COOLSET_API_KEY="gc_..."

Then check that it works by reading your own user. Send the key in the Authorization header with the ApiKey scheme:

cURL

curl https://developers.coolset.com/api/accounts/users/me/ \
  -H "Authorization: ApiKey $COOLSET_API_KEY"

Python

import os
import requests

response = requests.get(
    "https://developers.coolset.com/api/accounts/users/me/",
    headers={"Authorization": f"ApiKey {os.environ['COOLSET_API_KEY']}"},
)
response.raise_for_status()
print(response.json()["company"]["name"])

JavaScript

const response = await fetch('https://developers.coolset.com/api/accounts/users/me/', {
  headers: { Authorization: `ApiKey ${process.env.COOLSET_API_KEY}` },
});

if (!response.ok) throw new Error(`Coolset API returned ${response.status}`);
const me = await response.json();
console.log(me.company.name);

Response (trimmed):

{
  "id": 1042,
  "first_name": "Sam",
  "last_name": "Jansen",
  "email": "[email protected]",
  "active_user_company_id": 2210,
  "company": {
    "id": 671,
    "name": "Example Foods B.V.",
    "country": "NL",
    "default_currency": "EUR"
  },
  "auth_group": {
    "id": 4,
    "name": "Owner"
  }
}

For a user key, company is the workspace your requests run in. Bearer does not work for API keys and returns 401. For other 401 responses, see Error Handling.

4. Common calls

List your purchase orders

curl "https://developers-scranton.coolset.com/api/orders/?order_action=buying&limit=20" \
  -H "Authorization: ApiKey $COOLSET_API_KEY"

order_action is required on order lists:

• buying: orders where your company is the buyer (purchase orders).
• selling: orders where your company is the seller (sale orders).

Without it you get 400 with {"order_action": ["This field is required."]}.

Response (trimmed):

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 193,
      "external_id": "PO-2025-0042",
      "type": "order",
      "order_created_at": "2025-07-01",
      "buyer_company_status": "ready_for_review",
      "seller_company_status": "pending",
      "assessment_status": "pending",
      "items": [
        {
          "id": 322,
          "buyer_product": 88430,
          "volume": 12000.0,
          "unit": "kg"
        }
      ],
      "pulse_params": {
        "identifier": "scranton$Order$193",
        "model_identifier": "scranton$Order"
      }
    }
  ]
}

Keep pulse_params.identifier. You use it to look up the order's risk assessment below.

Find products

Filter by commodity, type or your own ID:

curl "https://developers-scranton.coolset.com/api/products/?commodity=cocoa&limit=20" \
  -H "Authorization: ApiKey $COOLSET_API_KEY"

Response (trimmed):

{
  "count": 13,
  "next": "https://developers-scranton.coolset.com/api/products/?commodity=cocoa&limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 88430,
      "sku": "COCOA-NIBS-01",
      "name": "Cocoa nibs",
      "type": "purchased",
      "commodity": "cocoa",
      "composition": "simple",
      "external_id": "ERP-55120",
      "assessment_status": "pending",
      "tags": []
    }
  ]
}

Other useful filters: external_id, type (purchased, produced, manufactured), search.

Get the latest EUDR risk assessment for an order

Coolset runs risk assessments for you. You read them, you do not create them. There is no endpoint to fetch an assessment by ID, so filter the list by the order's identifier:

curl -G "https://developers-pulse.coolset.com/api/compliance/risk-assessments/" \
  -H "Authorization: ApiKey $COOLSET_API_KEY" \
  --data-urlencode "identifier=scranton\$Order\$193" \
  --data-urlencode "assessment_type=eudr_order_assessment" \
  --data-urlencode "latest_per_identifier=true"

Response (trimmed):

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 31270,
      "identifier": "scranton$Order$193",
      "display_name": "Order Assessment - PO-2025-0042",
      "assessment_type": "eudr_order_assessment",
      "assessment_run_id": "25637e10-26c5-4d97-999b-7c482567a078",
      "assessment_date": "2026-10-06T15:17:07Z",
      "assessment_summary": {
        "status": "failing",
        "status_breakdown": {
          "counts": { "failing": 4, "passing": 4 },
          "total": 8
        }
      }
    }
  ]
}

Read assessment_summary.status:

Status	Meaning
pending	Not assessed yet
in_progress	Coolset is assessing it now. Check again later.
failing	Risks found. Fix them before filing a due diligence statement.
mitigated	Risks found and mitigated
passing	No blocking risks

Only passing and mitigated assessments can back a due diligence statement. See the EUDR guide for the full flow.

Upload a document

Uploading takes three calls: create the document, upload the file, then confirm.

Step 1. Create the document and get an upload URL. content_type is the file's MIME type.

curl -X POST https://developers-pulse.coolset.com/api/documents/ \
  -H "Authorization: ApiKey $COOLSET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Certificate of origin.pdf",
    "content_type": "application/pdf",
    "identifiers": ["scranton$Order$193"]
  }'

identifiers is optional. It links the document to Coolset objects, here the order from the earlier example.

Response:

{
  "document_id": 5521,
  "upload_url": "https://storage.googleapis.com/...",
  "blob_name": "documents/671/....pdf",
  "expires_at": "2026-10-07T14:15:00+00:00"
}

Step 2. Upload the file to upload_url within 15 minutes. Send the same Content-Type you used in step 1. Files can be up to 100 MB.

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  -H "x-goog-content-length-range: 0,104857600" \
  --upload-file "Certificate of origin.pdf"

Step 3. Confirm the upload. No request body is needed.

curl -X POST https://developers-pulse.coolset.com/api/documents/5521/confirm_upload/ \
  -H "Authorization: ApiKey $COOLSET_API_KEY"

200 returns the document with upload_status set to completed. 202 means the file is not visible yet. Wait a few seconds and confirm again.

List emissions for a date range

curl "https://developers.coolset.com/api/emission_calculations/emissions/?accounting_date__gte=2025-01-01&accounting_date__lte=2025-12-31&limit=50" \
  -H "Authorization: ApiKey $COOLSET_API_KEY"

Response (trimmed):

{
  "count": 56713,
  "next": "https://developers.coolset.com/api/emission_calculations/emissions/?accounting_date__gte=2025-01-01&accounting_date__lte=2025-12-31&limit=50&offset=50",
  "previous": null,
  "results": [
    {
      "id": 946531,
      "title": "452000 - Consultancy",
      "vendor_name": null,
      "accounting_date": "2025-12-31T00:00:00Z",
      "scope": "3",
      "ghg_category_name": "Capital goods",
      "category_name": "Equipment",
      "co2_kg": 1572.68
    }
  ]
}

For totals and trends, use /emission_calculations/charts/ instead. For example, ?group_by=scope returns totals per scope. See the Carbon accounting guide.

5. Pagination

List endpoints return pages:

{
  "count": 250,
  "next": "https://...?limit=100&offset=100",
  "previous": null,
  "results": [ ... ]
}

• limit sets the page size. The default is 100.
• offset sets where the page starts.
• Follow next until it is null to read everything.

More in Making Requests.

6. Errors

Errors return JSON with a detail message, or a field-by-field object for validation errors:

{ "order_action": ["This field is required."] }

See Error Handling for each status code.

Next steps

• Authentication
• Making Requests
• Error Handling
• EUDR compliance guide
• Supply chain guide

Need help?

• Email: [email protected]
• API reference: browse the API sections in the sidebar