API Reference

Complete documentation for the CallQA REST API. Build powerful integrations with our audio analysis platform.

Authentication

API Key Authentication

All API requests must include your API key in the Authorization header using the Bearer token scheme.

Authorization: Bearer your_api_key

Getting Your API Key

1. Log in to your CallQA dashboard
2. Navigate to Settings → API Keys
3. Click "Generate New Key"
4. Copy and securely store your key

Security Best Practices

• Keep your API key secret
• Use environment variables
• Rotate keys regularly
• Monitor usage in dashboard

Rate Limits

API Rate Limits

Free

100 requests/hour

Pro

1,000 requests/hour

Enterprise

Custom limits

Response Headers

X-RateLimit-Limit: 1000 - Your rate limit

X-RateLimit-Remaining: 950 - Remaining requests

X-RateLimit-Reset: 1640995200 - Reset timestamp

Retry-After: 60 - Seconds to wait (429 response)

API Endpoints

POST/v1/transcribe

Upload and transcribe audio file

Required

10/minute

Parameters

Name	Type	Required	Description
file	file	Required	Audio file to transcribe
language	string	Optional	Language code (e.g., 'en', 'es', 'fr')
analysis_template	string	Optional	Custom analysis template ID
webhook_url	string	Optional	URL to receive webhook notifications

Response

{
  "id": "transcription_123456",
  "status": "processing",
  "file_name": "customer_call.mp3",
  "duration": 245,
  "language": "en",
  "created_at": "2025-03-15T10:30:00Z",
  "webhook_url": "https://your-app.com/webhook"
}

Example

curl -X POST "https://api.callqa.com/v1/transcribe" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@customer_call.mp3" \
  -F "language=en" \
  -F "analysis_template=customer_service"

GET/v1/transcriptions/{id}

Get transcription status and results

Required

60/minute

Parameters

Name	Type	Required	Description
id	path	Required	Transcription ID
include_analysis	boolean	Optional	Include analysis results

Response

{
  "id": "transcription_123456",
  "status": "completed",
  "file_name": "customer_call.mp3",
  "duration": 245,
  "text": "Hello, thank you for calling...",
  "segments": [
    {
      "start": 0.0,
      "end": 3.5,
      "text": "Hello, thank you for calling",
      "speaker": "agent",
      "confidence": 0.98
    }
  ],
  "analysis": {
    "sentiment": "positive",
    "keywords": ["thank you", "help", "satisfied"],
    "quality_score": 8.5
  },
  "created_at": "2025-03-15T10:30:00Z",
  "completed_at": "2025-03-15T10:35:00Z"
}

Example

curl -X GET "https://api.callqa.com/v1/transcriptions/transcription_123456" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

Webhooks

Webhook Events

Configure webhooks to receive real-time notifications about transcription and analysis events.

transcription.completedFired when transcription is completed

{
  "event": "transcription.completed",
  "data": {
    "id": "transcription_123456",
    "status": "completed",
    "text": "Transcribed text...",
    "duration": 245,
    "language": "en",
    "created_at": "2025-03-15T10:30:00Z",
    "completed_at": "2025-03-15T10:35:00Z"
  }
}

transcription.failedFired when transcription fails

{
  "event": "transcription.failed",
  "data": {
    "id": "transcription_123456",
    "status": "failed",
    "error": "Audio format not supported",
    "created_at": "2025-03-15T10:30:00Z"
  }
}

analysis.completedFired when analysis is completed

{
  "event": "analysis.completed",
  "data": {
    "analysis_id": "analysis_789012",
    "transcription_id": "transcription_123456",
    "analysis_type": "sentiment",
    "results": {...},
    "created_at": "2025-03-15T10:40:00Z"
  }
}

Error Handling

HTTP Status Codes

Client Errors (4xx)

400 Bad RequestInvalid request format

401 UnauthorizedInvalid API key

403 ForbiddenInsufficient permissions

404 Not FoundResource not found

422 Unprocessable EntityValidation error

429 Too Many RequestsRate limit exceeded

Server Errors (5xx)

500 Internal Server ErrorServer error

502 Bad GatewayGateway error

503 Service UnavailableService temporarily down

504 Gateway TimeoutGateway timeout

Error Response Format

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or expired",
    "details": {
      "request_id": "req_123456"
    }
  }
}

SDKs & Libraries

Python SDK

Official Python library for CallQA API integration.

pip install callqa-python

JavaScript SDK

Modern JavaScript/TypeScript library for browser and Node.js.

npm install callqa-js

Java SDK

Java library for enterprise application integration.

implementation 'com.callqa:callqa-java:1.0.0'

C# SDK

.NET library for Windows and cross-platform applications.

Install-Package CallQA.NET