Cargo Prices, Freight Market Intelligence & Analytics

All API requests require authentication using an API key passed in the Authorization header.

API Keys

Header Format

Include your API key in every request:

Authorization: Bearer cb_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key Types

Prefix	Type	Description
`cb_live_`	Production	Billed requests, real market data
`cb_test_`	Test	Free requests, mock data for development

Creating a Key

Go to the Developer Console
Click Create Key
Name your key (e.g., "Production", "Staging", "Local Dev")
Select the permissions your key needs
Click Create
Copy the key immediately — it won't be shown again

Key Security

Never expose API keys in client-side code or public repositories
Always call the API from your server, not from browsers
Use environment variables to store keys
Rotate keys regularly and revoke unused ones

Permissions

Each API key has specific permissions that determine which endpoints it can access.

Permission	Required For
`benchmark:basic`	`POST /benchmark/basic`
`benchmark:detailed`	`POST /benchmark/detailed`
`market:read`	`GET /market`

If you call an endpoint without the required permission, you'll receive:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key lacks required permission: benchmark:detailed"
  }
}

Updating Permissions

To add or remove permissions:

Go to the Developer Console
Find your key in the list
Click the ... menu and select Edit permissions
Toggle the permissions you need
Click Save

Changes take effect immediately.

Test Mode

Keys starting with cb_test_ operate in test mode:

No credits consumed — Free unlimited requests
Mock data returned — Realistic but not real market data
Perfect for development — Test your integration without cost

Test Mode Response

Responses include a test_mode flag:

{
  "success": true,
  "data": {
    "median_rate_per_km": 1.35,
    "avg_rate_per_km": 1.38,
    "offer_count": 100,
    "confidence": "high",
    "search_method": "route_stats"
  },
  "test_mode": true,
  "request_id": "test-550e8400-e29b-41d4-a716-446655440000"
}

When to Use Test Keys

Use test keys during:

Local development
CI/CD pipeline testing
Integration testing
Demo environments

Switch to production keys (cb_live_) when you need real market data.

Key Management

Viewing Keys

In the Developer Console, you can see:

Key name and prefix (first 12 characters)
Created date
Last used date
Enabled/disabled status
Assigned permissions

For security, the full key is never shown after creation. If you lose a key, revoke it and create a new one.

Disabling Keys

You can temporarily disable a key without revoking it:

Find the key in the Developer Console
Toggle the Enabled switch off

Disabled keys return a 401 INVALID_API_KEY error. Re-enable anytime by toggling the switch back on.

Revoking Keys

To permanently delete a key:

Find the key in the Developer Console
Click ... → Revoke key
Confirm the action

Irreversible

Revoked keys cannot be recovered. Any applications using the key will immediately stop working.

Example Integration

// Store your key in an environment variable
const CARGOBLOOM_API_KEY = process.env.CARGOBLOOM_API_KEY;

async function getBenchmark(origin, destination) {
  const response = await fetch('https://cargobloom.io/api/v1/benchmark/basic', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${CARGOBLOOM_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      origin_country: origin,
      dest_country: destination,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || 'API request failed');
  }

  return response.json();
}

import os
import requests

CARGOBLOOM_API_KEY = os.environ['CARGOBLOOM_API_KEY']

def get_benchmark(origin: str, destination: str) -> dict:
    response = requests.post(
        'https://cargobloom.io/api/v1/benchmark/basic',
        headers={
            'Authorization': f'Bearer {CARGOBLOOM_API_KEY}',
            'Content-Type': 'application/json',
        },
        json={
            'origin_country': origin,
            'dest_country': destination,
        }
    )

    response.raise_for_status()
    return response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func getBenchmark(origin, destination string) (map[string]interface{}, error) {
    apiKey := os.Getenv("CARGOBLOOM_API_KEY")

    payload, _ := json.Marshal(map[string]string{
        "origin_country": origin,
        "dest_country":   destination,
    })

    req, _ := http.NewRequest("POST",
        "https://cargobloom.io/api/v1/benchmark/basic",
        bytes.NewBuffer(payload))

    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

Authentication Errors

Status	Code	Cause
401	`MISSING_API_KEY`	No `Authorization` header provided
401	`INVALID_API_KEY`	Key not found, wrong format, or revoked
403	`INSUFFICIENT_PERMISSIONS`	Key lacks required permission for endpoint

See Error Handling for complete error documentation.

Last updated: February 1, 2026

All API requests require authentication using an API key passed in the Authorization header.

API Keys

Header Format

Include your API key in every request:

Authorization: Bearer cb_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key Types

Prefix	Type	Description
`cb_live_`	Production	Billed requests, real market data
`cb_test_`	Test	Free requests, mock data for development

Creating a Key

Go to the Developer Console
Click Create Key
Name your key (e.g., "Production", "Staging", "Local Dev")
Select the permissions your key needs
Click Create
Copy the key immediately — it won't be shown again

Key Security

Never expose API keys in client-side code or public repositories
Always call the API from your server, not from browsers
Use environment variables to store keys
Rotate keys regularly and revoke unused ones

Permissions

Each API key has specific permissions that determine which endpoints it can access.

Permission	Required For
`benchmark:basic`	`POST /benchmark/basic`
`benchmark:detailed`	`POST /benchmark/detailed`
`market:read`	`GET /market`

If you call an endpoint without the required permission, you'll receive:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key lacks required permission: benchmark:detailed"
  }
}

Updating Permissions

To add or remove permissions:

Go to the Developer Console
Find your key in the list
Click the ... menu and select Edit permissions
Toggle the permissions you need
Click Save

Changes take effect immediately.

Test Mode

Keys starting with cb_test_ operate in test mode:

No credits consumed — Free unlimited requests
Mock data returned — Realistic but not real market data
Perfect for development — Test your integration without cost

Test Mode Response

Responses include a test_mode flag:

{
  "success": true,
  "data": {
    "median_rate_per_km": 1.35,
    "avg_rate_per_km": 1.38,
    "offer_count": 100,
    "confidence": "high",
    "search_method": "route_stats"
  },
  "test_mode": true,
  "request_id": "test-550e8400-e29b-41d4-a716-446655440000"
}

When to Use Test Keys

Use test keys during:

Local development
CI/CD pipeline testing
Integration testing
Demo environments

Switch to production keys (cb_live_) when you need real market data.

Key Management

Viewing Keys

In the Developer Console, you can see:

Key name and prefix (first 12 characters)
Created date
Last used date
Enabled/disabled status
Assigned permissions

For security, the full key is never shown after creation. If you lose a key, revoke it and create a new one.

Disabling Keys

You can temporarily disable a key without revoking it:

Find the key in the Developer Console
Toggle the Enabled switch off

Disabled keys return a 401 INVALID_API_KEY error. Re-enable anytime by toggling the switch back on.

Revoking Keys

To permanently delete a key:

Find the key in the Developer Console
Click ... → Revoke key
Confirm the action

Irreversible

Revoked keys cannot be recovered. Any applications using the key will immediately stop working.

Example Integration

// Store your key in an environment variable
const CARGOBLOOM_API_KEY = process.env.CARGOBLOOM_API_KEY;

async function getBenchmark(origin, destination) {
  const response = await fetch('https://cargobloom.io/api/v1/benchmark/basic', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${CARGOBLOOM_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      origin_country: origin,
      dest_country: destination,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || 'API request failed');
  }

  return response.json();
}

import os
import requests

CARGOBLOOM_API_KEY = os.environ['CARGOBLOOM_API_KEY']

def get_benchmark(origin: str, destination: str) -> dict:
    response = requests.post(
        'https://cargobloom.io/api/v1/benchmark/basic',
        headers={
            'Authorization': f'Bearer {CARGOBLOOM_API_KEY}',
            'Content-Type': 'application/json',
        },
        json={
            'origin_country': origin,
            'dest_country': destination,
        }
    )

    response.raise_for_status()
    return response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func getBenchmark(origin, destination string) (map[string]interface{}, error) {
    apiKey := os.Getenv("CARGOBLOOM_API_KEY")

    payload, _ := json.Marshal(map[string]string{
        "origin_country": origin,
        "dest_country":   destination,
    })

    req, _ := http.NewRequest("POST",
        "https://cargobloom.io/api/v1/benchmark/basic",
        bytes.NewBuffer(payload))

    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

Authentication Errors

Status	Code	Cause
401	`MISSING_API_KEY`	No `Authorization` header provided
401	`INVALID_API_KEY`	Key not found, wrong format, or revoked
403	`INSUFFICIENT_PERMISSIONS`	Key lacks required permission for endpoint

See Error Handling for complete error documentation.

Last updated: February 1, 2026

Authentication

API Keys

Header Format

Key Types

Creating a Key

Permissions

Updating Permissions

Test Mode

Test Mode Response

Key Management

Viewing Keys

Disabling Keys

Revoking Keys

Example Integration

Authentication Errors

On this page

Authentication

API Keys

Header Format

Key Types

Creating a Key

Permissions

Updating Permissions

Test Mode

Test Mode Response

Key Management

Viewing Keys

Disabling Keys

Revoking Keys

Example Integration

Authentication Errors

On this page