API Reference

Aura exposes two HTTP surfaces over the same data:

Both surfaces share authentication, scopes, rate limits, and underlying business logic — pick whichever fits your integration.

Endpoint reference

This site documents concepts: auth, scopes, attribution, webhooks. For the live, type-safe endpoint reference, use the OpenAPI-driven sites:

• docs.api.aura-app.ai — every REST endpoint with request/response schemas, generated from the same Zod schemas that validate live traffic.
• api.aura-app.ai/docs — the OpenAPI playground rendered straight from /openapi.json.
• api.aura-app.ai/graphql — GraphQL Playground (requires a valid API key in the Authorization header). Schema introspection is disabled in production by design; use the docs site above for schema discovery.

If a field appears in the endpoint reference but not in this docs site, the endpoint reference is canonical.

Quick start

1. Create an API key

Settings → API Keys → Create API Key. Pick the minimum scopes your integration needs (see Authentication).

API keys have the format:

aura_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

The full key is shown once at creation — store it immediately.

2. Make a request

curl https://api.aura-app.ai/v1/leads \
  -H "Authorization: Bearer aura_pk_live_XXXXX"

curl https://api.aura-app.ai/graphql \
  -H "Authorization: Bearer aura_pk_live_XXXXX" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ leads(first: 5) { edges { node { id name email } } } }"}'

3. Handle webhooks (optional)

Pull is rarely enough on its own. Subscribe to webhooks for lead, call, and payment lifecycle events.

Response envelopes

REST endpoints return one of three shapes:

// Single resource
{ "success": true, "data": { ... } }

// Paginated list
{ "data": [ ... ], "pagination": { "next_cursor": "...", "has_more": true } }

// Error
{ "success": false, "error": "message", "code": "ERROR_CODE", "requestId": "req_..." }

List endpoints intentionally omit success — check the HTTP status code (200 for success) and the presence of data.

GraphQL follows the standard { data, errors } envelope. Mutations also return a typed userErrors: [{ field, message }] array for validation failures — these arrive in data, not errors, because they're business-rule violations, not transport-level errors.

Rate limits

Limits are applied per API key and per organization. When you hit a limit you'll receive a 429 Too Many Requests with these headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715520600
Retry-After: 12

Back off using Retry-After. Repeatedly retrying inside the window will not succeed.

Pagination

REST list endpoints use cursor-based pagination:

curl "https://api.aura-app.ai/v1/leads?limit=50&cursor=eyJpZCI6...&direction=next" \
  -H "Authorization: Bearer aura_pk_live_XXXXX"

The response's pagination.next_cursor is what you pass on the next request. When has_more is false, you've reached the end.

GraphQL uses Relay-style cursor connections (first, after, pageInfo, edges[].cursor). See the endpoint reference at docs.api.aura-app.ai for per-resource examples.

Versioning

REST is versioned in the URL path (/v1/). Additive changes — new fields, new endpoints, new optional inputs — ship without a version bump and may appear at any time. Removing or renaming a field is a breaking change, gated by an internal schema-diff CI check before merge.

GraphQL is unversioned. Deprecated fields are marked with @deprecated and remain queryable for at least 6 months after deprecation.

Attribution

Every lead and call carries UTM attribution plus booking_link_id. See apps/api/AGENTS.md in the source repo for the data-model conventions, or query the source object on Lead / the flat utm_* columns on Call. Webhook payloads carry the same attribution — see Webhooks → Payload Reference.

Support

• API status: status.aura-app.ai
• Endpoint reference: docs.api.aura-app.ai
• Webhooks: /webhooks
• Authentication & scopes: /api/authentication