API Documentation

Integrate Voicory's call logs, customer data, and WhatsApp messages into your CRM, analytics platform, or custom application.

Call Logs

Access call history, transcripts, recordings, and cost data

Customers

Pull customer profiles with interaction history

Messages

Retrieve WhatsApp conversations and message status

Base URL: https://voicory-backend-783942490798.asia-south1.run.app/api/v1

Authentication

All API requests require an API key passed in the x-api-key header.

You can generate API keys from the Voicory Dashboard → Settings → API Keys.

PUBLICpk_...

Read-only access. Safe for client-side widgets and integrations.

PRIVATEsk_...

Full access. Keep server-side only — never expose in frontend code.

bash

curl -s "https://voicory-backend-783942490798.asia-south1.run.app/api/v1/calls" \
  -H "x-api-key: YOUR_API_KEY"

Rate Limits

API requests are rate-limited per API key to ensure fair usage and platform stability.

Limit	Window	Description
60 requests	1 minute	Sliding window per API key
10 requests	5 seconds	Burst protection

Response Headers

X-RateLimit-Limit

Max requests per window

X-RateLimit-Remaining

Requests left in window

X-RateLimit-Reset

Unix timestamp when window resets

http

HTTP/1.1 429 Too Many Requests
Retry-After: 45
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Maximum 60 requests per minute.",
    "retry_after": 45
  }
}

Pagination

All list endpoints return paginated results. Use page and limit query parameters.

Parameter	Default	Range
page	1	1 – ∞
limit	25	1 – 100

json

// meta object in every list response
{
  "page": 2,
  "limit": 25,
  "total": 142,
  "total_pages": 6,
  "has_more": true
}

Error Handling

All errors return a consistent JSON structure with an error object.

Status	Code	Meaning
400	INVALID_ID / INVALID_FILTER	Bad request — invalid UUID or filter format
401	MISSING_API_KEY	No x-api-key header provided
401	INVALID_API_KEY	API key not found or wrong
401	REVOKED_API_KEY	API key has been revoked
404	NOT_FOUND	Resource not found
429	RATE_LIMIT_EXCEEDED	Too many requests
500	INTERNAL_ERROR	Server error — contact support

json

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Call Logs

Access your voice call history including transcripts, summaries, recordings, and cost breakdowns.

Customers

Pull customer profiles from Voicory's built-in CRM. Each customer detail includes recent calls and WhatsApp messages.

WhatsApp Messages

Retrieve WhatsApp messages sent and received through your Voicory-connected WhatsApp Business numbers.

Security

Tenant Isolation

All data is scoped to your API key. You can never access another account's data.

Input Sanitization

All query parameters are sanitized and validated before reaching the database.

Redis Rate Limiting

Per-key sliding window rate limits backed by Redis — no in-memory cheating.

UUID Validation

All ID parameters are validated as proper UUIDs — no SQL injection vectors.

Request Logging

Every API request is logged with key, path, status, duration, and IP.

Security Headers

X-Content-Type-Options, X-Frame-Options, Cache-Control on all responses.

No Internal Fields

Internal fields like user_id, config_id, secrets are never exposed in responses.

Key Revocation

Revoked keys are immediately rejected — no grace period.

Ready to integrate?

Generate your API key from the Voicory dashboard and start pulling data in minutes.

Go to Dashboard