# AI Call Review API

> Turn raw sales call recordings into a structured, scored intelligence report over a simple REST API. Submit a call (by recording URL or audio upload), we transcribe and analyze it, and you fetch back a machine-readable report with scores, objections, buying signals, compliance alerts, and coaching notes. Built to be driven by autonomous agents.

Base URL: https://api.callanalyticsapi.com/v1
(also served at https://api.callanalyticsapi.com/api/v1)

## Authentication
- API key per company. Send it as `Authorization: Bearer <key>` or `X-Api-Key: <key>` on every request.
- Keys are created in the app under Company -> API keys and shown once. Format: `cc_<id>_<secret>` (e.g. `cc_3a91f8e2_...`). Mock vs live analysis is a server-side setting, not a key property.
- Scopes: `calls:write`, `calls:read`, `reports:read`.
- The same key authenticates the inbound webhook via `X-Api-Key`.

## Core endpoints
- POST /calls — submit a call (recording_url + metadata). Returns `call_id` and `status` (`received` or `duplicate`). Idempotent on `external_call_id`. 201, or 200 on duplicate.
- GET /calls — list recent calls (`?limit=` 1-100, default 25).
- GET /calls/{id} — call status. When `report_status` is `ready`, `report_url` is set.
- GET /calls/{id}/report — the structured report. 409 `report_not_ready` while still processing.
- POST /calls/{id}/reprocess — re-run the pipeline.
- POST /uploads — multipart audio upload (field `file`).
- GET /webhooks/events — recent outbound webhook deliveries.

## Inbound webhook
- POST https://api.callanalyticsapi.com/webhooks/inbound/generic with `X-Api-Key`.
- Flexible field mapping (e.g. id/call_id/external_call_id, contact_name/customer_name, phone/from, recording/recording_url/audio_url, duration/duration_seconds). Deduped by external id.

## Outbound webhooks
- Subscribe endpoints to events: call.received, call.processing_started, call.transcription_completed, call.analysis_completed, call.report_completed, call.failed, call.low_score_detected, call.buying_signal_detected, call.compliance_alert_detected.
- Signed with `X-Cadence-Signature: t=<ts>,v1=<hmac-sha256(ts.body)>`.

## Errors & limits
- Error envelope: `{"error":"code","message":"..."}`. Codes: 200, 201, 400, 401, 403, 404, 409, 422, 429, 500.
- Rate limit: 120 requests / 60s fixed window per API key. Headers `X-RateLimit-Limit` / `X-RateLimit-Remaining`; 429 returns `Retry-After`.

## Documentation
- [Overview](https://docs.callanalyticsapi.com/)
- [Authentication](https://docs.callanalyticsapi.com/authentication)
- [Calls](https://docs.callanalyticsapi.com/calls)
- [Reports](https://docs.callanalyticsapi.com/reports)
- [Webhooks](https://docs.callanalyticsapi.com/webhooks)
- [Errors](https://docs.callanalyticsapi.com/errors)
- [Rate limits](https://docs.callanalyticsapi.com/rate-limits)
- [AI agents](https://docs.callanalyticsapi.com/agents)
- [GoHighLevel integration](https://docs.callanalyticsapi.com/integrations/gohighlevel)
- [Zapier integration](https://docs.callanalyticsapi.com/integrations/zapier)
- [Generic webhook integration](https://docs.callanalyticsapi.com/integrations/generic-webhook)

## Machine-readable
- [OpenAPI 3.1 spec](https://docs.callanalyticsapi.com/openapi.json)
- [llms.txt](https://docs.callanalyticsapi.com/llms.txt)