---
title: "API Overview"
url: https://docs.aila.fyi/api-reference
source: https://docs.aila.fyi/llms.txt
---

# API Overview

The Aila REST API gives you programmatic access to calls, transcripts, contacts, compliance results, metrics, and MISMO 3.4 loan files. Use it with [outbound webhooks](https://docs.aila.fyi/api-reference/webhooks) to react to events as they happen.

---

## Full reference (OpenAPI)

The complete, always-current endpoint reference is generated from the app:

- **Interactive reference:** [app.aila.fyi/api-docs](https://app.aila.fyi/api-docs)
- **OpenAPI spec (JSON):** [app.aila.fyi/api/openapi](https://app.aila.fyi/api/openapi)

The tables below cover the most-used endpoints.

---

## Base URL and authentication
```
https://app.aila.fyi/api/v1
```
Send an API key as a Bearer token:
```http
Authorization: Bearer ak_<64 hex characters>
```
Each key carries explicit permissions. Grant each integration only the permissions listed for the endpoints it uses. See [Authentication](https://docs.aila.fyi/api-reference/authentication).

Most list endpoints are scoped to your organization: `/organizations/{organizationId}/...`. Call `GET /auth/verify` or `GET /users/me` to confirm your key and look up your organization ID.

---

## Common endpoints

### Calls

| Method & path | Description | Permission to grant |
| :--- | :--- | :--- |
| `GET /organizations/{organizationId}/calls` | List calls with filters and pagination. | `calls:read` |
| `GET /calls/{callId}` | Call details, stats, and AI summary. | `calls:read` |
| `GET /calls/{callId}/transcript` | Speaker-labeled transcript. | `calls:read` |
| `PATCH /calls/{callId}` · `DELETE /calls/{callId}` | Update or delete a call. | `calls:write` |
| `GET /organizations/{organizationId}/calls/{callId}/analysis` | AI analysis of the call. | `calls:read` |
| `GET /organizations/{organizationId}/calls/{callId}/compliance` | Scorecard (Call Compliance Agent) results. | `calls:read` |
| `POST /calls/upload/batch` | Upload 1–100 recordings by URL. See [Batch Call Upload](https://docs.aila.fyi/api-reference/batch-upload). | `calls:write` |
| `GET /batches/{batchId}` | Batch upload status. | `calls:write` |

### Contacts and loan files

| Method & path | Description | Permission to grant |
| :--- | :--- | :--- |
| `GET /organizations/{organizationId}/contacts` | List contacts. | `contacts:read` |
| `POST /organizations/{organizationId}/contacts` | Create a contact. | `contacts:write` |
| `GET /contacts/{contactId}` | Contact details (add `includeCalls` for their calls). | `contacts:read` |
| `GET /organizations/{organizationId}/contacts/{contactId}/mortgage-application/export/fnma` | Export the borrower's loan file as MISMO 3.4 XML. | `loan-files:read` |

### Metrics, insights, and webhooks

| Method & path | Description | Permission to grant |
| :--- | :--- | :--- |
| `GET /organizations/{organizationId}/metrics/summary` | Team call volume, duration, and speed-to-lead summary. | `metrics:read` |
| `GET /organizations/{organizationId}/insights` | Questions and objections across calls. | `insights:read` |
| `GET` · `POST /organizations/{organizationId}/webhooks` | List or create webhook endpoints. See [Webhooks](https://docs.aila.fyi/api-reference/webhooks). | Any key |

Check the [OpenAPI spec](https://app.aila.fyi/api/openapi) for request parameters and response schemas.

---

## Responses and errors

Successful responses use `{ "success": true, "data": ... }`. Every response includes an `x-request-id` header; include it when you contact support.

| Status | `code` | Meaning |
| :--- | :--- | :--- |
| `400` | `VALIDATION_ERROR` | The request body or query failed validation. |
| `401` | `UNAUTHORIZED` / `INVALID_API_KEY` | Missing, invalid, deleted, or expired key. |
| `403` | `INSUFFICIENT_PERMISSIONS` / `FORBIDDEN` | The key lacks the scope, or the resource belongs to another organization. |
| `404` | `NOT_FOUND` | The resource doesn't exist. |
| `429` | `RATE_LIMITED` | Too many requests. Back off and retry. |
| `500` | `INTERNAL_ERROR` | Something failed on our side. Retry, then contact support with the request ID. |

---

## Rate limits

Each key can make about **500 requests per minute**. Over the limit, the API returns `429 RATE_LIMITED`. There are no rate-limit headers, so retry with exponential backoff. Need more? Email [support@aila.fyi](mailto:support@aila.fyi).

---

## Related

- [Authentication](https://docs.aila.fyi/api-reference/authentication): Create keys and choose scopes.
- [Batch Call Upload](https://docs.aila.fyi/api-reference/batch-upload): Send recordings from any system.
- [Webhooks](https://docs.aila.fyi/api-reference/webhooks): Real-time events.
- [Aila MCP server](https://docs.aila.fyi/integrations/aila-mcp): Use Aila from ChatGPT, Claude, and other AI clients.