API Overview

The CallCov API is organized around REST principles. It uses predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Base URL

https://api.callcov.com/api/v1

Authentication

The CallCov API uses API keys or JWT tokens to authenticate requests. Include your key in the Authorization header:

Authorization: Bearer sk_live_abc123...

Learn more in the Authentication Guide.

Request Format

All POST, PUT, and PATCH requests must include a Content-Type header:

Content-Type: application/json

For file uploads, use:

Content-Type: multipart/form-data

Response Format

All responses are returned in JSON format with a consistent structure:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1642248000,
  ...
}

HTTP Status Codes

CallCov uses conventional HTTP response codes:

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error (contact support)

Error Handling

Errors include detailed information:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "audio_url"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Learn more in the Error Handling Guide.

Versioning

The API version is included in the URL path:

/api/v1/analysis/

We'll maintain backward compatibility within major versions. Breaking changes will result in a new version (e.g., /api/v2/).

Rate Limiting

Rate limits protect our infrastructure and ensure fair usage:

• Default: 100 requests per minute
• Analysis submissions: 20 per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248060

Pagination

List endpoints support pagination:

GET /api/v1/analysis/?skip=0&limit=20

Parameters:

• skip: Number of records to skip (default: 0)
• limit: Maximum number of records to return (default: 20, max: 100)

Response:

{
  "items": [...],
  "total": 150,
  "skip": 0,
  "limit": 20
}

Timestamps

All timestamps are Unix timestamps (seconds since epoch):

{
  "created": 1642248000  // January 15, 2022 10:00:00 UTC
}

Convert in your language of choice:

# Python
from datetime import datetime
dt = datetime.fromtimestamp(1642248000)

// JavaScript
const date = new Date(1642248000 * 1000);

Idempotency

To safely retry requests without performing the same operation twice, include an Idempotency-Key header:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Idempotency keys are valid for 24 hours.

Metadata

Many resources accept custom metadata:

{
  "audio_url": "https://example.com/call.wav",
  "metadata": {
    "campaign_id": "summer_2024",
    "department": "sales"
  }
}

Metadata is returned unchanged and can be used for your own tracking purposes.

Webhooks

For long-running operations like analysis, use webhooks instead of polling:

{
  "audio_url": "https://example.com/call.wav",
  "webhook_url": "https://your-app.com/webhooks/analysis"
}

Learn more in the Webhooks Guide.

Test Mode vs Live Mode

Use test mode to experiment without affecting production data:

• Test API Keys: sk_test_...
• Live API Keys: sk_live_...

Test mode uses the same base URL but doesn't process real charges or send actual notifications.

API Endpoints

Authentication

• POST /auth/register - Create account
• POST /auth/login - Get access token
• POST /auth/refresh - Refresh access token
• POST /auth/verify-email - Verify email address
• POST /auth/password-reset - Request password reset
• POST /auth/password-reset/confirm - Confirm password reset

User Management

• GET /users/me - Get current user
• PUT /users/me - Update current user
• DELETE /users/me - Delete account

API Keys

• POST /api-keys/ - Create API key
• GET /api-keys/ - List API keys
• DELETE /api-keys/{id} - Revoke API key

Analysis (Core)

• POST /analysis/ - Submit analysis
• GET /analysis/{id} - Retrieve analysis
• GET /analysis/ - List analyses
• POST /analysis/{id}/webhook - Register webhook

Billing

• GET /billing/subscription - Get subscription
• POST /billing/subscription - Create subscription
• POST /billing/subscription/update - Update plan
• POST /billing/subscription/cancel - Cancel subscription
• GET /billing/usage - Get usage summary
• GET /billing/history - Get usage history
• GET /billing/customer-portal - Stripe customer portal

SDKs

Official SDKs are coming soon for:

• Python
• Node.js
• Ruby
• PHP

Until then, the API works great with standard HTTP libraries like requests (Python) or axios (Node.js).

Support

• Documentation: https://docs.callcov.com
• Email: support@callcov.com
• Status: status.callcov.com