Making API Requests

How to call the Coolset APIs: hosts, headers, pagination, filtering and limits.

Base URLs

Each API is served by its own host. Every path is relative to /api:

API	Base URL
Accounts, Carbon	`https://developers.coolset.com/api`
Supply Chain	`https://developers-scranton.coolset.com/api`
Compliance, AI	`https://developers-pulse.coolset.com/api`
Data: documents, imports, knowledge base	`https://developers-pulse.coolset.com/api`
Data: transactions	`https://developers.coolset.com/api`
Data: surveys	`https://developers-data-room.coolset.com/api`

Each endpoint in the API reference also shows its server. Paths end with a trailing slash, for example /orders/.

Request Format

Headers

Authorization: ApiKey YOUR_API_TOKEN
Content-Type: application/json

Content-Type is only needed on requests with a body.

Request Body

Send POST, PUT and PATCH bodies as JSON. Each endpoint's request schema is listed in the API reference.

HTTP Methods

Method	Usage
`GET`	Retrieve resources
`POST`	Create resources, or run an action such as `confirm_upload`
`PATCH`	Update part of a resource
`PUT`	Replace a resource (only where documented)
`DELETE`	Remove a resource

Response Format

Successful responses return JSON, except file downloads such as CSV exports and evidence packages.

Code	Meaning
`200`	OK
`201`	Created
`202`	Accepted: the work continues in the background, or try again shortly
`204`	No Content: success with no response body

Pagination

List endpoints use limit/offset pagination:

GET /api/products/?limit=50&offset=0

Parameter	Description	Default
`limit`	Results per page	100
`offset`	Index of the first result	0

{
  "count": 250,
  "next": "https://developers-scranton.coolset.com/api/products/?limit=50&offset=50",
  "previous": null,
  "results": [...]
}

Follow next until it is null. Statistics and chart endpoints that say "not paginated" return a plain array.

Filtering

Filters are query parameters. Each endpoint lists its filters in the API reference. Common patterns:

Pattern	Example	Meaning
exact	`commodity=cocoa`	Equal to
`__in`	`commodity__in=cocoa,coffee`	Any of
`__gte` / `__lte`	`created_at__gte=2025-01-01`	On or after / on or before
`__icontains`	`name__icontains=coffee`	Contains, case-insensitive
`search`	`search=PO-2025`	Free-text search

Some endpoints have required filters. Order lists and order statistics need order_action=buying or order_action=selling:

GET /api/orders/?order_action=buying&assessment_status=failing

Sorting

Use ordering with a field name. Prefix with - for descending:

GET /api/products/?ordering=-created_at

The fields you can sort by are listed for each endpoint in the API reference.

Rate Limiting

You can make 600 requests per minute to each API host. The limit applies per user, so all keys belonging to the same user share it. Above that you receive 429 Too Many Requests with a Retry-After header giving the seconds to wait.

Request Examples

GET: retrieve a resource

curl "https://developers-scranton.coolset.com/api/orders/193/?order_action=buying" \
  -H "Authorization: ApiKey YOUR_API_TOKEN"

POST: create a resource

curl -X POST https://developers-scranton.coolset.com/api/orders/purchase/ \
  -H "Authorization: ApiKey YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order",
    "external_id": "PO-2025-0042",
    "order_created_at": "2025-07-01",
    "items": [
      { "buyer_product": 88430, "volume": 12000, "unit": "kg" }
    ]
  }'

PATCH: update a resource

curl -X PATCH https://developers-scranton.coolset.com/api/orders/purchase/193/ \
  -H "Authorization: ApiKey YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_arrival_at": "2025-08-15"
  }'

DELETE: remove a resource

curl -X DELETE https://developers-scranton.coolset.com/api/orders/193/ \
  -H "Authorization: ApiKey YOUR_API_TOKEN"

Best Practices

1. Read every page

async function getAllPurchaseOrders(headers) {
  let results = [];
  let url = 'https://developers-scranton.coolset.com/api/orders/?order_action=buying&limit=100';

  while (url) {
    const response = await fetch(url, { headers });
    const data = await response.json();
    results = results.concat(data.results);
    url = data.next;
  }

  return results;
}

2. Respect `Retry-After`

import time
import requests


def get_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
    return response

3. Filter on the server

# Good: let the API filter
GET /api/orders/?order_action=buying&assessment_status=failing

# Avoid: fetching everything and filtering locally

4. Cache what rarely changes

Emission factors, categories and your product catalogue change rarely. Cache them instead of fetching them on every request.

Base URLs​

Request Format​

Headers​

Request Body​

HTTP Methods​

Response Format​

Pagination​

Filtering​

Sorting​

Rate Limiting​

Request Examples​

GET: retrieve a resource​

POST: create a resource​

PATCH: update a resource​

DELETE: remove a resource​

Best Practices​

1. Read every page​

2. Respect Retry-After​

3. Filter on the server​

4. Cache what rarely changes​

Next Steps​