> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.aura-app.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Enterprise REST API for external partner integrations

# Aura Partner Integrations API

Enterprise REST API for external partner integrations including commission platforms, external mobile apps, and client booking widgets.

## Getting Started

### 1. Get Your API Key

1. Log in to your [Aura dashboard](https://app.aura-app.ai)
2. Navigate to **Settings → API Keys**
3. Click **Create API Key**, give it a descriptive name (e.g. "Postman Testing"), and choose a scope (`read`, `write`, or `admin`)
4. Copy the key immediately — it is only shown once

Your key will look like: `aura_pk_live_xxxxxxxxxxxxxxxxxxxxxxxx`

### 2. Make Your First Request

Test your API key with a simple health check and then an authenticated request:

```bash theme={null}
# No auth required
curl https://api.aura-app.ai/health

# Authenticated request — replace with your key
curl -H "Authorization: Bearer aura_pk_live_xxxxx" \
  https://api.aura-app.ai/v1/leads
```

### Environments

| Environment | Base URL | Use |
| - | - | - |
| Production | `https://api.aura-app.ai` | Live data |
| Staging | `https://staging-api.aura-app.ai` | Pre-production testing |
| Local | `http://localhost:3001` | Local development |

> **Test keys are read-only.** Keys are prefixed `aura_pk_live_…` or `aura_pk_test_…`. A `test`-prefixed key can **read** your production data but cannot create, update, or delete — write/admin calls return `403`. A fully isolated sandbox dataset is planned; until then, use a `test` key to safely explore the read endpoints.

### 3. Explore the API

* Browse the endpoint reference in the sidebar
* Download the [OpenAPI spec](https://docs.api.aura-app.ai/openapi.json) for Postman or other tools
* Read the [GraphQL guide](https://docs.api.aura-app.ai/graphql.md) and download the [GraphQL schema](https://docs.api.aura-app.ai/schema.graphql)
* Use the [TypeScript client guide](https://docs.api.aura-app.ai/sdk.md) for the generated REST client

## Authentication

REST partner endpoints under `/v1` require a partner API key. The
[GraphQL endpoint](https://docs.api.aura-app.ai/graphql.md) accepts partner API keys and Clerk organization JWTs:

**1. API Key (for partners and integrations):**

```
Authorization: Bearer aura_pk_live_xxxxxxxxxxxxxxxx
```

Get your API key from the Aura dashboard at **Settings → API Keys**.

**2. Clerk organization JWT (GraphQL, for mobile and web apps):**

```
Authorization: Bearer <clerk_jwt_token>
```

Use Clerk's authentication SDK to obtain a JWT token with user and organization
claims. Permissions follow the organization role. See [Making requests](https://docs.api.aura-app.ai/requests.md)
for scopes, pagination and error handling.

## Rate Limiting

* **Per source IP:** 200 requests/minute
* **Per API Key:** 100 requests/minute
* **Per Organization:** 1000 requests/minute

Rate limit headers are included on responses:

* `X-RateLimit-Limit`: Maximum requests allowed
* `X-RateLimit-Remaining`: Remaining requests in current window
* `X-RateLimit-Reset`: Unix timestamp when limit resets
* `Retry-After`: Seconds to wait before retrying (sent on `429` responses)

On a `429`, back off using `Retry-After` rather than retrying immediately. Limits are enforced per region and are approximate under high concurrency.

## Idempotency

Safely retry unsafe writes by sending an `Idempotency-Key` header (any unique string, e.g. a UUID) on `POST /v1/payments`:

```bash theme={null}
curl -X POST https://api.aura-app.ai/v1/payments \
  -H "Authorization: Bearer aura_pk_live_xxxxx" \
  -H "Idempotency-Key: 8f3a1c2e-3b9d-4f5a-9c7e-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{ "lead_id": "...", "amount": 5000.00, "currency": "USD", "payment_date": "2026-06-12T00:00:00Z", "status": "succeeded", "source": "stripe" }'
```

If a request with the same key has already succeeded, Aura returns the existing payment and creates no duplicate payment. A request still being processed returns `409`. Retry shortly. Keys are scoped to your organization. Send the same body when you retry.

Retries return the saved payment's current values. Use a new key for a different payment. Creation webhooks keep the same `idempotency_key` on retries. Follow the [webhook deduplication guide](https://docs.api.aura-app.ai/webhooks.md#quick-start) when processing deliveries.

Payment amounts are dollars for both create and update. For example, `12.34` means twelve dollars and thirty-four cents. The database rounds additional decimal places and stores two decimal places.

## API Endpoints

### Leads

* [List leads](https://docs.api.aura-app.ai/openapi/v1/leads/get.md) - Retrieve paginated list of leads
* [Get lead](https://docs.api.aura-app.ai/openapi/v1/leads/id/get.md) - Get a specific lead by ID

### Calls

* [List calls](https://docs.api.aura-app.ai/openapi/v1/calls/get.md) - Retrieve paginated list of calls
* [Get call](https://docs.api.aura-app.ai/openapi/v1/calls/id/get.md) - Get a specific call by ID

### Team

* [List team members](https://docs.api.aura-app.ai/openapi/v1/team/get.md) - Retrieve team members with roles and commission rates
* [Get team member](https://docs.api.aura-app.ai/openapi/v1/team/id/get.md) - Get a specific team member by ID

### Schedulers

* [List schedulers](https://docs.api.aura-app.ai/openapi/v1/booking-links/get.md) - Retrieve schedulers
* [Get scheduler](https://docs.api.aura-app.ai/openapi/v1/booking-links/id/get.md) - Get a specific scheduler

### Products

* [List products](https://docs.api.aura-app.ai/openapi/v1/products/get.md) - Retrieve product catalog
* [Get product](https://docs.api.aura-app.ai/openapi/v1/products/id/get.md) - Get a specific product

### Payments

* [List payments](https://docs.api.aura-app.ai/openapi/v1/payments/get.md) - Retrieve payment records
* [Get payment](https://docs.api.aura-app.ai/openapi/v1/payments/id/get.md) - Get a specific payment

### Webhooks

New to webhooks? Start with the **[Webhooks guide](https://docs.api.aura-app.ai/webhooks.md)** — it covers
the full flow end-to-end including HMAC signature verification, the retry
policy, the event catalog, and drop-in Node/Python verification code.

REST endpoints for managing subscriptions:

* [List webhooks](https://docs.api.aura-app.ai/openapi/v1/webhooks/get.md) - List webhook subscriptions
* [Create webhook](https://docs.api.aura-app.ai/openapi/v1/webhooks/post.md) - Subscribe to events
* [Get webhook](https://docs.api.aura-app.ai/openapi/v1/webhooks/id/get.md) - Get a specific webhook subscription
* [Update webhook](https://docs.api.aura-app.ai/openapi/v1/webhooks/id/patch.md) - Update a webhook subscription
* [Delete webhook](https://docs.api.aura-app.ai/openapi/v1/webhooks/id/delete.md) - Remove a webhook subscription
* [Test webhook](https://docs.api.aura-app.ai/openapi/v1/webhooks/test/post.md) - Send a test event to a webhook

## Error Handling

All errors follow a standard format:

```json theme={null}
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "requestId": "req_abc123"
}
```

Common HTTP status codes:

* **400** Bad Request - Invalid input
* **401** Unauthorized - Missing or invalid API key
* **403** Forbidden - Insufficient permissions
* **404** Not Found - Resource not found
* **429** Too Many Requests - Rate limit exceeded
* **500** Internal Server Error - Server error

## Leads without a booked meeting

Use [Calls: intent calls and form answers](https://docs.api.aura-app.ai/openapi/v1/calls/get.md#intent-calls-and-form-answers)
to find a lead's booking intent and retrieve submitted answers. A lead ID
identifies the person; an intent call ID identifies their booking attempt.
See the [Webhooks guide](https://docs.api.aura-app.ai/webhooks.md#lead-lifecycle-events-in-settings-and-zapier)
for the lifecycle events available in Settings and Zapier.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.