{ "openapi": "3.1.0", "info": { "title": "AI Call Review API", "version": "v1", "summary": "Submit sales call recordings and retrieve structured, scored analysis reports.", "description": "Turn raw sales call recordings into a structured, machine-readable intelligence report. Submit a call by recording URL or audio upload, poll for completion, and fetch the report. Authenticate every request with an API key (Bearer or X-Api-Key).", "contact": { "url": "https://docs.callanalyticsapi.com" } }, "servers": [ { "url": "https://api.callanalyticsapi.com/v1", "description": "Production (v1)" } ], "externalDocs": { "description": "Full documentation", "url": "https://docs.callanalyticsapi.com" }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "tags": [ { "name": "Calls", "description": "Create, list, and read calls." }, { "name": "Reports", "description": "Structured analysis reports." }, { "name": "Uploads", "description": "Multipart audio upload." }, { "name": "Webhooks", "description": "Outbound webhook deliveries." } ], "paths": { "/calls": { "post": { "tags": [ "Calls" ], "summary": "Create a call", "description": "Submit a call for transcription and analysis. Idempotent on external_call_id: resubmitting a known external_call_id returns the existing call with status \"duplicate\" and HTTP 200.", "operationId": "createCall", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallSubmission" } } } }, "responses": { "201": { "description": "Call created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallAccepted" }, "example": { "call_id": 4127, "status": "received", "processing_status_url": "/api/v1/calls/4127", "report_url": null } } } }, "200": { "description": "Duplicate \u2014 existing call returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallAccepted" }, "example": { "call_id": 4127, "status": "duplicate", "processing_status_url": "/api/v1/calls/4127", "report_url": null } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Calls" ], "summary": "List calls", "operationId": "listCalls", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max results, 1\u2013100 (default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "A page of calls.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Call" } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{id}": { "get": { "tags": [ "Calls" ], "summary": "Retrieve a call", "operationId": "getCall", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call_id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Call" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{id}/report": { "get": { "tags": [ "Reports" ], "summary": "Get the report for a call", "operationId": "getCallReport", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call_id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The structured report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call_id": { "type": "integer" }, "report": { "$ref": "#/components/schemas/Report" } } } } } }, "409": { "description": "Report not ready yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "report_not_ready" }, "status": { "type": "string", "example": "analyzing" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{id}/reprocess": { "post": { "tags": [ "Calls" ], "summary": "Reprocess a call", "operationId": "reprocessCall", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The call_id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reprocessing queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call_id": { "type": "integer" }, "status": { "type": "string", "example": "reprocessing" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/uploads": { "post": { "tags": [ "Uploads" ], "summary": "Upload audio to create a call", "description": "Multipart upload. The audio file must be sent in the \"file\" part.", "operationId": "uploadCall", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file." }, "rep_name": { "type": "string" }, "customer_name": { "type": "string" }, "duration_seconds": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Upload accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallAccepted" }, "example": { "call_id": 4128, "status": "received", "processing_status_url": "/api/v1/calls/4128" } } } }, "422": { "description": "Missing or invalid file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "List recent outbound webhook deliveries", "operationId": "listWebhookEvents", "responses": { "200": { "description": "Recent deliveries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key as a Bearer token: Authorization: Bearer ." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key in the X-Api-Key header." } }, "schemas": { "CallSubmission": { "type": "object", "description": "Body for POST /calls.", "properties": { "external_call_id": { "type": "string", "description": "Your id for the call. Dedupe key." }, "rep_name": { "type": "string" }, "rep_email": { "type": "string", "format": "email" }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "call_started_at": { "type": "string", "format": "date-time" }, "call_ended_at": { "type": "string", "format": "date-time" }, "duration_seconds": { "type": "integer" }, "recording_url": { "type": "string", "format": "uri" }, "source_system": { "type": "string", "default": "generic" }, "crm_contact_id": { "type": "string" }, "crm_deal_id": { "type": "string" }, "metadata": { "type": "object", "properties": { "high_value_opportunity": { "type": "boolean" } }, "additionalProperties": true } }, "example": { "external_call_id": "crm-8821", "rep_name": "Jordan Lee", "customer_name": "Acme Corp", "recording_url": "https://example.com/recordings/8821.mp3", "source_system": "my_app", "metadata": { "high_value_opportunity": true } } }, "CallAccepted": { "type": "object", "properties": { "call_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "received", "duplicate" ] }, "processing_status_url": { "type": "string" }, "report_url": { "type": [ "string", "null" ] } }, "required": [ "call_id", "status" ] }, "Call": { "type": "object", "properties": { "call_id": { "type": "integer" }, "external_call_id": { "type": [ "string", "null" ] }, "customer_name": { "type": [ "string", "null" ] }, "processing_status": { "type": "string", "description": "queued | transcribing | analyzing | complete | failed" }, "report_status": { "type": "string", "description": "pending | ready" }, "overall_score": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "outcome": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "report_url": { "type": [ "string", "null" ], "description": "Set when report_status is \"ready\"." } }, "required": [ "call_id", "processing_status", "report_status", "created_at" ], "example": { "call_id": 4127, "external_call_id": "crm-8821", "customer_name": "Acme Corp", "processing_status": "complete", "report_status": "ready", "overall_score": 78, "outcome": "follow_up_scheduled", "created_at": "2026-06-22T15:21:40Z", "report_url": "/api/v1/calls/4127/report" } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer" }, "event_type": { "type": "string" }, "status": { "type": "string" }, "response_status": { "type": [ "integer", "null" ] }, "attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "Report": { "type": "object", "description": "Structured analysis report for a call.", "additionalProperties": false, "required": [ "overall_score", "score_breakdown", "summary", "call_outcome", "close_likelihood", "objections", "buying_signals", "missed_opportunities", "coaching_notes", "rep_strengths", "rep_weaknesses", "suggested_follow_up", "crm_note", "compliance_alerts", "timeline", "confidence_level" ], "properties": { "overall_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "score_breakdown": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 10 }, "description": "Per-category scores 0\u201310 across ~12 evaluation categories." }, "summary": { "type": "string" }, "call_outcome": { "type": "string" }, "close_likelihood": { "type": "integer", "minimum": 0, "maximum": 100 }, "manager_review_required": { "type": "boolean" }, "customer_needs": { "type": "array", "items": { "type": "string" } }, "pain_points": { "type": "array", "items": { "type": "string" } }, "objections": { "type": "array", "items": { "type": "object" } }, "buying_signals": { "type": "array", "items": { "type": "object" } }, "missed_opportunities": { "type": "array", "items": { "type": "string" } }, "coaching_notes": { "type": "object" }, "rep_strengths": { "type": "array", "items": { "type": "string" } }, "rep_weaknesses": { "type": "array", "items": { "type": "string" } }, "recommended_training": { "type": "array", "items": { "type": "string" } }, "suggested_follow_up": { "type": "string" }, "crm_note": { "type": "string" }, "compliance_alerts": { "type": "array", "items": { "type": "object" } }, "transcript_highlights": { "type": "array", "items": { "type": "object" } }, "timeline": { "type": "array", "items": { "type": "object" } }, "confidence_level": { "type": "string", "enum": [ "low", "medium", "high" ] } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string" } }, "required": [ "error" ], "example": { "error": "unauthorized", "message": "Invalid, expired, or revoked API key." } }, "ValidationError": { "type": "object", "properties": { "error": { "type": "string", "example": "validation_failed" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error" ] } } } }