Cradle API and CLI

Getting started with the Cradle API (private beta)

Read your organisation's calls, transcripts, summaries, recordings and reports from your own systems with an organisation API key. Private beta: your organisation must be added by Cradle first.

Private beta. The Cradle API is available only to organisations that Cradle has added to the private beta. If your organisation hasn't been added, requests are refused with API_BETA_NOT_ENABLED. To join, ask your Cradle contact or email help@cradle.io. The API may change before general release.

What the Cradle API does

The Cradle API gives your own systems read-only access to your organisation's calls: a reporting warehouse, a practice management integration, a CRM sync or an internal dashboard. With an organisation API key it can:

  • List calls for a date range, or every call that changed since you last asked, with who was on them, how they went, matched contacts and which CRMs they were logged to.
  • Read a call's transcript and AI summary.
  • List a call's recordings and download their audio.
  • Run call reports, with the same numbers as the Cradle web app, plus reports on why calls are missed and how calls are routed.

It can't change, delete or send anything in Cradle. Each key reads only what an admin allowed when creating it (its scopes).

The Cradle API is the same service the Cradle Calls CLI uses. If you want an AI assistant or a person to read calls from a command line, see Connecting your AI assistant with the Cradle Calls CLI (/knowledge/cradle-calls-cli-private-beta).

API reference

The guides in this collection explain how to use them well.

Before you start

  1. Your organisation is in the private beta.
  2. An admin creates an API key on the access page, with the scopes your system needs and the IP addresses it will call from. See Creating and managing Cradle API keys (/knowledge/cradle-api-keys).
  3. Keep the key in your secrets manager. It's shown once.

Making requests

  • Base address: https://reporting-api.cradle.io

  • Authentication: send the key in the Authorization header on every request:

    Authorization: Bearer cr_org_...
    

    Keys sent any other way, such as in the address, are refused.

  • Format: JSON responses, UTF-8. Dates and times are ISO 8601.

  • Time zone: date parameters such as since=today use the tz parameter, an IANA time zone such as Australia/Sydney. It defaults to Pacific/Auckland.

Your first requests

Check the key works and see what it can read:

curl -H "Authorization: Bearer $CRADLE_API_KEY" https://reporting-api.cradle.io/api/v1/me

The response shows credential: "org_key", and under api_key the key's name, scopes, expiry and IP addresses. client_ip is the address Cradle sees your request coming from, which is the one to put on the key's IP list.

List the last seven days of calls:

curl -H "Authorization: Bearer $CRADLE_API_KEY" \
  "https://reporting-api.cradle.io/api/v1/calls?since=7d&limit=50"

since and until accept today, yesterday, a number of days or weeks such as 7d or 2w, a date such as 2026-10-01, or a full ISO 8601 time. One request covers up to 93 days. Follow next_cursor (send it as cursor) for the next page.

Narrow the list with user (a person's email), direction (inbound, outbound or internal), number, contact, crm with crm_id, crm_logged, min_duration and max_duration. The reference describes each one.

Read one call, with its transcript:

curl -H "Authorization: Bearer $CRADLE_API_KEY" \
  "https://reporting-api.cradle.io/api/v1/calls/<call id>?transcript=true"

Reports

With the reports:read scope, GET /api/v1/cli/reports lists the available reports, and GET /api/v1/cli/reports/<report> runs one, for example overview?since=7d. Reports can be run for the organisation, a team (team), a person (user) or one of your Cradle numbers (number).

Three reports help explain missed calls. Each runs for the organisation or a team:

Report What it shows
diagnose Each person rung: how many calls rang them, how many they answered and missed, and how many of those misses nobody answered. Inbound calls by hour and by weekday, each with one outcome (including calls someone answered that still ended as missed). How long callers waited before hanging up or being answered. How much of each team actually rang: ringing-coverage for every team, or role-ringing-coverage for one, with the share of the team and of its first step rung per call (fractions from 0 to 1), how often the first step rang everyone, and calls that rang nobody. Team level only, measured against each team's current members and steps.
presence Each person's Cradle presence (available, away, offline and so on) when calls rang them. A week at most from the last 28 days, for example presence?since=6d. Needs the presence:read scope as well as reports:read.
routing Each group's current setup (ring order, ring time and attempts) and each number's routes. It shows today's setup only.

Guides

  • Creating and managing Cradle API keys (/knowledge/cradle-api-keys): scopes, IP restrictions, expiry and revoking.
  • Keeping your systems in sync with the Cradle API (/knowledge/cradle-api-change-feed): fetch only what changed instead of re-reading every call.
  • Transcripts, summaries and recording audio (/knowledge/cradle-api-audio-and-content): reading call content and downloading audio.
  • Cradle API errors and limits (/knowledge/cradle-api-errors-and-limits): what each error means and how to handle rate limits.
  • Moving from the older Cradle integration API (/knowledge/cradle-api-migrating-from-legacy-api): for systems built on the previous API.

Terms

Use of the API during the beta is subject to the Cradle Private Beta Terms (https://reporting-api.cradle.io/cli/terms), which add to Cradle's Terms of Use, Data Processing Agreement and Privacy Policy. The admin who creates a key accepts them for your organisation.

Questions? Email help@cradle.io, Monday to Friday, 8:30 am to 5:00 pm New Zealand time.

Was this helpful?

Still stuck?

Ask Cradle AI or open a ticket.

Open a ticket