Ayra AI
|Docs

Getting Started with Ayra API

Welcome to Ayra API

The Ayra API provides programmatic access to all platform capabilities, enabling you to build powerful integrations, automate workflows, and create custom applications on top of Ayra's voice AI infrastructure. Whether you're building internal tools, integrating with existing systems, or creating custom client experiences, the API gives you complete control over your Ayra implementation.

Who Should Use the API

Developers

Building custom integrations, automating agent deployment and configuration, or creating custom dashboards and reporting tools will find the API essential for extending Ayra beyond the web interface.

Agencies

Managing multiple client accounts can use the API to provision agents at scale, automate configuration across clients, and build white-labeled experiences on top of Ayra infrastructure.

Enterprise Teams

With complex workflows can integrate Ayra into existing business systems, synchronize data between platforms, and build custom internal tools tailored to their specific processes.

Partners

Building applications on Ayra can leverage the API to create value-added services, integrate Ayra capabilities into their own products, or build marketplace offerings.

API Capabilities Overview

The Ayra API enables comprehensive platform interaction across several capability domains:

Voice Agent Management

  • • Create, configure, update, and delete AI voice agents
  • • List and filter agents across your account
  • • Retrieve detailed agent configurations and settings
  • • Enable, disable, or archive agents as needed

Conversation Access

  • • Retrieve conversation history and details
  • • Access real-time conversation data
  • • Download call recordings and transcripts
  • • Query conversation analytics and metrics

Contact Management

  • • Create and update contact records
  • • Search and filter contacts by various criteria
  • • Manage contact tags and custom fields
  • • Track contact interaction history

Calendar and Scheduling

  • • Manage appointment bookings programmatically
  • • Check availability across calendars
  • • Create, update, and cancel appointments
  • • Handle recurring appointment series

Workflow Automation

  • • Trigger workflows via API
  • • Pass data into workflow executions
  • • Retrieve workflow results and status
  • • Create and configure automated workflows

Analytics and Reporting

  • • Access aggregate analytics data
  • • Generate custom reports programmatically
  • • Export data for external analysis
  • • Query real-time metrics and KPIs

API Basics

This API follows RESTful principles using standard HTTP methods, accepts and returns JSON payloads, uses conventional HTTP response codes, and supports cross-origin resource sharing (CORS) for browser-based applications.

Base URL: https://api.ayra.ai/v1

API Versioning

The Ayra API uses versioning to ensure backward compatibility as the platform evolves. The current API version is v1, indicated in the base URL: https://api.ayra.ai/v1.

When breaking changes are introduced, a new API version will be released (v2, v3, etc.) while maintaining support for older versions during a deprecation period. You'll receive advance notice before any API version is deprecated, providing ample time to migrate.

Note: Non-breaking changes - adding new endpoints, adding optional parameters, adding new fields to responses - may be introduced without version changes. Your integrations should gracefully handle unexpected response fields to remain compatible with these additions.

Development and Production Environments

Ayra provides separate environments for development and production use:

Production Environment

https://api.ayra.ai/v1

This is the live environment affecting real agents, customers, and data. Use production API keys and exercise caution with operations that modify data.

Sandbox Environment

https://sandbox-api.ayra.ai/v1

This is a separate test environment for safe development and testing. Sandbox uses separate API keys and contains no production data. All operations in sandbox affect only test data.

Important: Always develop and test integrations in the sandbox environment before deploying to production. This prevents accidental data corruption or service disruption while you're learning the API or testing new functionality.

API Response Format

All API responses use JSON format with consistent structure. Successful responses (2xx status codes) return data in this format:

{
  "data": {
    // Response data here
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

For list endpoints returning multiple items, responses include pagination metadata:

{
  "data": [
    // Array of items
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 25,
    "total_pages": 6,
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  },
  "links": {
    "first": "https://api.ayra.ai/v1/agents?page=1",
    "prev": null,
    "next": "https://api.ayra.ai/v1/agents?page=2",
    "last": "https://api.ayra.ai/v1/agents?page=6"
  }
}

Error responses (4xx and 5xx status codes) return error details:

{
  "error": {
    "type": "invalid_request",
    "message": "The 'phone_number' field is required",
    "code": "missing_required_field",
    "field": "phone_number",
    "request_id": "req_abc123"
  }
}

The request_id in all responses helps track specific requests for debugging and support purposes. Include request_id when contacting support about API issues.

Common HTTP Status Codes

Understanding HTTP status codes helps diagnose API issues:

2xx Success

  • • 200 OK - Request succeeded, response contains requested data
  • • 201 Created - Resource was successfully created
  • • 204 No Content - Request succeeded but no content to return (typically for DELETE operations)

4xx Client Errors

  • • 400 Bad Request - Request is malformed or contains invalid parameters
  • • 401 Unauthorized - Authentication credentials are missing or invalid
  • • 403 Forbidden - Authentication succeeded but you lack permission for this operation
  • • 404 Not Found - Requested resource doesn't exist
  • • 422 Unprocessable Entity - Request is well-formed but contains semantic errors
  • • 429 Too Many Requests - Rate limit exceeded, slow down requests

5xx Server Errors

  • • 500 Internal Server Error - Unexpected server error occurred
  • • 503 Service Unavailable - Service is temporarily unavailable, retry later

When receiving errors, examine the error response body for specific details about what went wrong and how to correct it.

API Best Practices

Error Handling

Always implement robust error handling. Catch and appropriately respond to different error types. Retry transient errors (5xx, network issues) with exponential backoff. Fix permanent errors (4xx) by correcting your request. Log errors for debugging without exposing sensitive data to end users.

Idempotency

For operations that create or modify resources, use idempotency keys to safely retry requests. Network issues can cause duplicate requests. Idempotency keys ensure requests are processed exactly once even if submitted multiple times.

Caching

Cache data that doesn't change frequently to reduce API calls. Agent configurations typically change infrequently and can be cached. Reference data like available voices or time zones rarely changes. Implement cache invalidation when data is updated through the API.

Pagination

Always handle pagination for list endpoints. Don't assume all results fit in a single page. Implement pagination logic iterating through all pages when you need complete datasets.

Security

Protect API keys like passwords. Use HTTPS exclusively, never HTTP. Validate data received from API before using it. Implement proper authentication and authorization in your application.

Next Steps

Now that you understand the basics, let's dive into authentication and API key management:

Authentication

Ready to transform your agency?

Start building with Ayra today. No credit card required.