API Overview

Programmatic Access to Ayra

Ayra's comprehensive RESTful API enables programmatic access to all platform capabilities—build custom dashboards, automate workflows, and integrate with any system.

What the API Enables

Agent Management

Create, configure, enable/disable, and delete voice agents programmatically

Conversation Data

Retrieve conversations, transcripts, recordings, and analytics

Contact Sync

Manage customer records, sync with external systems

Workflow Automation

Trigger workflows, pass data, retrieve execution status

API Authentication

API Keys

Ayra uses API keys for authentication. Generate keys in Settings → API. Create separate keys for different integrations for granular tracking and easy revocation.

Security: Protect API keys like passwords. Never commit to repositories. Store in environment variables. Rotate periodically. Revoke unused keys.

Request Headers

Include API key in request headers for authentication:

GET https://api.ayra.ai/v1/conversations
Authorization: Bearer your_api_key_here

Rate Limiting

APIs enforce rate limits (typically several hundred requests/minute). Implement exponential backoff for 429 responses. Cache data rather than repeatedly requesting. Batch operations when possible.

API Endpoints

Conversations

List conversationsGet conversation detailsAccess transcriptsDownload recordings

Agents

Create agentsUpdate configurationEnable/disableList all agents

Contacts

Create contactsUpdate recordsSearch contactsTag management

Workflows

Trigger executionPass dataGet statusRetrieve results

Analytics

Volume metricsSentiment analysisPerformance statsCustom reports

Request & Response Format

Request Format (JSON)

POST https://api.ayra.ai/v1/contacts
Content-Type: application/json
Authorization: Bearer your_api_key

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15555551234",
  "company": "Acme Corp",
  "tags": ["prospect", "enterprise"]
}

Response Format

Success (200-299)

{
  "id": "contact_abc123",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "created_at": "2025-01-15..."
}

Error (400-599)

{
  "error": {
    "code": "invalid_request",
    "message": "Phone format invalid",
    "details": "Include country code"
  }
}

Pagination

List endpoints use pagination. Include limit (1-100) and offset or cursor parameters.

GET /v1/conversations?limit=50&offset=100

API Best Practices

Handle Errors Gracefully

Catch different error types. Retry transient errors (500s) with backoff. Fix permanent errors (400s) by correcting requests.

Implement Idempotency

Include idempotency keys for creation requests. Prevents duplicate records from network retries.

Cache Appropriately

Don't request unchanged data repeatedly. Cache stable information locally. Refresh periodically.

Use Webhooks for Real-Time

Rather than polling, use webhooks for push notifications when events occur.

Secure Credentials

Never hardcode keys. Use environment variables or secure credential management.

Explore More

Learn about event-driven integration with Webhooks and connecting external systems with Third-Party APIs.

Webhooks Third-Party APIs

Ready to transform your agency?

Start building with Ayra today. No credit card required.