Getting Started with the Cooledge API

The Cooledge API lets you read and manage your Cooledge data from your own systems. You can work with customers, jobs, quotes, invoices, bookings and leads programmatically, so the records you already keep in Cooledge can drive automations, dashboards and integrations you build yourself.

It is a REST API. Requests and responses are JSON, list endpoints use cursor pagination, errors follow the RFC 7807 problem-details format and webhooks are signed so you can verify they came from Cooledge.

The base URL is:

https://app.cooledge.com.au/api

Every path in the docs is relative to that base. So /v1/me is the full URL https://app.cooledge.com.au/api/v1/me.

Available on the Growth and Scale plans, and that includes your 14-day free trial. New signups start on Growth, so the free trial has full API access with no card required. The underlying switch is the api_access feature on your subscription. If you signed up and you are still in your trial, you already have what you need to start.

Getting a key

API access is available on the Growth and Scale plans. You create and manage your own API keys from the Developers page in Settings. Open Settings, go to Developers, create a key, choose its scopes and copy the secret. The secret is shown once, so store it somewhere safe.

When you create a key it looks like this:

ck_live_AB12CD_xxxxxxxxxxxxxxxxxxxxxxxx

A key has two visible parts joined by underscores. The ck_live_AB12CD portion is the key identifier, also called the prefix. It is stored and displayable, so you will see it again to recognise which key is which. The part after it is the secret.

The full secret is shown once at creation and cannot be retrieved again. Copy it into a secrets manager or environment variable the moment you receive it. If you lose it you will need a new key issued.

Authenticate every request

Authenticate by sending your full key in the X-Api-Key request header on every call:

X-Api-Key: ck_live_AB12CD_your_secret_here

There is no separate login step and no session to manage. The header carries the credential on each request. See the authentication guide for the key lifecycle and the full list of scopes.

OAuth for partners and MCP is planned, not yet available. For now the X-Api-Key header is the way to authenticate.

Your first call

GET /v1/me is the quickest way to confirm your key works. It returns the business the key belongs to and the scopes the caller is allowed to use, so it is a good health check.

curl https://app.cooledge.com.au/api/v1/me \
  -H "X-Api-Key: ck_live_AB12CD_your_secret_here"

A successful call returns the business profile and the caller's scopes:

{
  "business": {
    "id": "biz_8f2a1c9e",
    "name": "Brightline Heating & Cooling",
    "slug": "brightline-heating-cooling",
    "business_email": "office@brightlinehvac.com.au",
    "business_phone": "+61731234567",
    "website": "https://brightlinehvac.com.au",
    "abn": "53004085616"
  },
  "caller": {
    "kind": "api_key",
    "scopes": [
      "customers:read",
      "jobs:read",
      "quotes:read",
      "invoices:read"
    ]
  }
}

Most business fields can be null if you have not filled them in. Only id and name are always present. A business with no website or ABN on file returns them as null:

{
  "business": {
    "id": "biz_8f2a1c9e",
    "name": "Brightline Heating & Cooling",
    "slug": "brightline-heating-cooling",
    "business_email": "office@brightlinehvac.com.au",
    "business_phone": "+61731234567",
    "website": null,
    "abn": null
  },
  "caller": {
    "kind": "api_key",
    "scopes": ["customers:read", "jobs:read"]
  }
}

If the call fails, check the authentication guide for what a 401 or 403 means.

Where to go next

• Authentication covers the key format, the key lifecycle, the full scope list and how to read auth errors.
• Pagination and errors covers cursor pagination on list endpoints and the RFC 7807 error shape.
• Webhooks covers subscribing to events and verifying signed deliveries.
• The API reference is the live, endpoint-by-endpoint specification you can read and try against your own data.