> ## 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. # Get bookable time slots for a scheduler > Compute the bookable time slots for a scheduler over a date range — exactly what a guest sees on the public booking page, through the same shared engine: live roster resolution, calendar free/busy + working hours, the min-booking-notice floor, and the existing-bookings buffer/overbooking screen against Aura's own calls table. **Semantics:** - `start_date`/`end_date` are inclusive UTC calendar days; the range spans at most 31 days and must start today or later. - `start` and `end` accept instants with offsets instead of the date fields. Send exactly one input per edge. Start is inclusive and end is exclusive for slot start times. An instant start must be now or later. - The window is additionally clamped to the link's booking horizon (`available_days_in_future`). - Slot times are unix seconds (UTC); `timezone` is echoed back for client-side formatting only. - An empty roster or a fully-booked range returns `slots: []` (200). **Expected failures are typed, never a bare 500:** - 400 — invalid date range - 422 — the link's configuration was rejected by the availability provider (e.g. a misconfigured grant or calendar) - 502 — the availability provider is degraded (5xx / timeout) Compute the bookable time slots for a scheduler over a date range — exactly what a guest sees on the public booking page, through the same shared engine: live roster resolution, calendar free/busy + working hours, the min-booking-notice floor, and the existing-bookings buffer/overbooking screen against Aura's own calls table. **Semantics:** * `start_date`/`end_date` are inclusive UTC calendar days; the range spans at most 31 days and must start today or later. * `start` and `end` accept instants with offsets instead of the date fields. Send exactly one input per edge. Start is inclusive and end is exclusive for slot start times. An instant start must be now or later. * The window is additionally clamped to the link's booking horizon (`available_days_in_future`). * Slot times are unix seconds (UTC); `timezone` is echoed back for client-side formatting only. * An empty roster or a fully-booked range returns `slots: []` (200). **Expected failures are typed, never a bare 500:** * 400 — invalid date range * 422 — the link's configuration was rejected by the availability provider (e.g. a misconfigured grant or calendar) * 502 — the availability provider is degraded (5xx / timeout) ## OpenAPI ````yaml openapi.json GET /v1/booking-links/{id}/availability openapi: 3.1.0 info: contact: email: support@aura-app.ai name: Aura Support description: >- # Aura Partner Integrations API > **Alpha Release** - This API is under active development. Endpoints, request/response schemas, and behaviors may change without prior notice. We recommend pinning to specific response fields you need and handling unknown fields gracefully. Enterprise REST API for external partner integrations including commission platforms, external mobile apps, and client booking widgets. ## MCP Connector Aura also exposes a **Model Context Protocol** server at `/mcp` so AI assistants (Claude, ChatGPT) can answer questions about a user's own sales data. If you are building an assistant integration rather than a server-to-server one, that is almost certainly the surface you want — it is task-shaped ("prep me for my next call") rather than resource-shaped, and it handles auth per-user. Read-only. OAuth 2.1 + PKCE, with Clerk as the authorization server; discover it from `/.well-known/oauth-protected-resource`. Setup guide: https://docs.api.aura-app.ai/mcp-connector ## Authentication Authenticated endpoints support two authentication methods: **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 JWT (for mobile and web apps):** ``` Authorization: Bearer ``` Use Clerk's authentication SDK to obtain a JWT token with org claims. ## Rate Limiting - **Per API Key:** 100 requests/minute - **Per Organization:** 1000 requests/minute Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests allowed - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp when limit resets These counters are held per serving instance, so under concurrency the effective ceiling is higher than the number above and the headers describe one instance's view rather than a global total. Treat a 429 as backpressure to obey and pace your client to the documented rate — but do not rely on us to reject your 101st request, and do not derive a global remaining-quota figure from the headers. The limit may become globally enforced without notice, so a client that stays within it will not be affected when that happens. ## Pagination List endpoints support cursor-based pagination: - `limit`: Number of results per page (default: 50, max: 100) - `cursor`: Opaque cursor for next page ## Error Handling All errors follow a standard format: ```json { "success": false, "error": "Error message", "code": "ERROR_CODE" } ``` Common HTTP status codes: - **400** Bad Request - Invalid input (`VALIDATION_ERROR`) - **401** Unauthorized - Missing or invalid API key (`AUTHENTICATION_ERROR`) - **402** Payment Required - The key is valid, but the organization's subscription is not active (`PAYMENT_REQUIRED`). Every authenticated endpoint can return this. Retrying will not help until the account's payment method is updated in Aura; surface it to the account owner rather than treating it as an auth failure. - **403** Forbidden - Insufficient permissions (`AUTHORIZATION_ERROR`) - **404** Not Found - Resource not found (`NOT_FOUND`) - **409** Conflict - Resource state prevents the operation (`CONFLICT`) - **413** Payload Too Large - Request body exceeds 256KB (`PAYLOAD_TOO_LARGE`) - **429** Too Many Requests - Rate limit exceeded (`RATE_LIMIT_EXCEEDED`) - **500** Internal Server Error - Server error (`INTERNAL_ERROR`) ## Webhooks Subscribe to real-time events using the Webhooks API. All webhook payloads are signed with HMAC-SHA256 for security verification. Delivery is at-least-once. Every payload carries an `idempotency_key` that is stable across retries of the same event, so you can enforce exactly-once with a `(subscription_id, idempotency_key)` unique constraint on your side. For full documentation, visit [docs.aura-app.ai/api](https://docs.aura-app.ai/api) license: name: Proprietary title: Aura Partner Integrations API version: 1.0.0-alpha servers: - description: Production url: https://api.aura-app.ai - description: Staging url: https://staging-api.aura-app.ai - description: Local Development url: http://localhost:3001 security: - bearerAuth: [] tags: - description: Lead management operations name: Leads - description: Call booking and management name: Calls - description: Booking link configuration (read-only) name: Booking Links - description: Product catalog (read-only) name: Products - description: Payment tracking (read-only) name: Payments - description: Public booking creation name: Bookings - description: Real-time event subscriptions and webhook management name: Webhooks - description: >- Team member information for commission attribution. **Alpha** - schema may change without notice. name: Team (Alpha) - description: >- Dashboard analytics, lead source attribution, and objection analysis. **Alpha** - schema may change without notice. name: Analytics (Alpha) - description: System endpoints (health checks) name: System paths: /v1/booking-links/{id}/availability: get: tags: - Booking Links summary: Get bookable time slots for a scheduler description: "\nCompute the bookable time slots for a scheduler over a date range —\nexactly what a guest sees on the public booking page, through the same\nshared engine: live roster resolution, calendar free/busy + working hours,\nthe min-booking-notice floor, and the existing-bookings buffer/overbooking\nscreen against Aura's own calls table.\n\n**Semantics:**\n- `start_date`/`end_date` are inclusive UTC calendar days; the range\n spans at most 31 days and must start today or later.\n- `start` and `end` accept instants with offsets instead of the date fields.\n Send exactly one input per edge. Start is inclusive and end is exclusive\n for slot start times. An instant start must be now or later.\n- The window is additionally clamped to the link's booking horizon\n (`available_days_in_future`).\n- Slot times are unix seconds (UTC); `timezone` is echoed back for\n client-side formatting only.\n- An empty roster or a fully-booked range returns `slots: []` (200).\n\n**Expected failures are typed, never a bare 500:**\n- 400 — invalid date range\n- 422 — the link's configuration was rejected by the availability provider\n (e.g. a misconfigured grant or calendar)\n- 502 — the availability provider is degraded (5xx / timeout)\n\t" parameters: - description: Scheduler ID (UUID) in: path name: id required: true schema: description: Scheduler ID (UUID) example: 550e8400-e29b-41d4-a716-446655440000 type: string - description: >- Inclusive start UTC day, today or later. Send start_date or start, not both. in: query name: start_date required: false schema: description: >- Inclusive start UTC day, today or later. Send start_date or start, not both. example: '2026-07-10' pattern: ^\d{4}-\d{2}-\d{2}$ type: string - description: >- Inclusive end UTC day. Send end_date or end, not both. The window spans at most 31 days. in: query name: end_date required: false schema: description: >- Inclusive end UTC day. Send end_date or end, not both. The window spans at most 31 days. example: '2026-07-17' pattern: ^\d{4}-\d{2}-\d{2}$ type: string - description: >- Inclusive start instant with an offset, now or later. Alternative to start_date. in: query name: start required: false schema: description: >- Inclusive start instant with an offset, now or later. Alternative to start_date. example: '2026-07-10T20:00:00-04:00' format: date-time type: string - description: >- Exclusive end instant with an offset. Alternative to end_date. Slot start times fall before this instant. in: query name: end required: false schema: description: >- Exclusive end instant with an offset. Alternative to end_date. Slot start times fall before this instant. example: '2026-07-17T20:00:00-04:00' format: date-time type: string - description: >- IANA timezone echoed back for formatting. Defaults to the scheduler's timezone. in: query name: timezone required: false schema: description: >- IANA timezone echoed back for formatting. Defaults to the scheduler's timezone. example: Europe/Berlin type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BookingLinkAvailabilityResponse' description: Successfully computed availability '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid date range '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid or missing API key '402': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The organization's subscription is not active headers: X-Request-Id: description: Request identifier for support schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The API key does not have the required scope headers: X-Request-Id: description: Request identifier for support schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Booking link not found '408': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- The request exceeded its processing time limit. Check the outcome before retrying a write headers: X-Request-Id: description: Request identifier for support schema: type: string '413': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The request body exceeds 256KB headers: X-Request-Id: description: Request identifier for support schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Scheduler configuration rejected by the availability provider '429': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: Rate limit exceeded. Wait before retrying headers: Retry-After: description: Seconds to wait before retrying schema: type: string X-RateLimit-Limit: description: Requests allowed in the current window schema: type: string X-RateLimit-Remaining: description: Requests remaining in the current window schema: type: string X-RateLimit-Reset: description: Window reset as a Unix timestamp schema: type: string X-Request-Id: description: Request identifier for support schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- Unexpected server failure. Include the request identifier when contacting support headers: X-Request-Id: description: Request identifier for support schema: type: string '502': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Availability provider temporarily unavailable security: - bearerAuth: [] components: schemas: BookingLinkAvailabilityResponse: properties: data: properties: slots: description: >- Bookable slots after the same filters the public booking page applies (min-notice floor, existing-bookings buffer screen, overbooking rules). items: $ref: '#/components/schemas/BookingLinkAvailabilitySlot' type: array timezone: description: Timezone for formatting (the requested timezone, or the link's). example: Europe/Berlin type: string required: - slots - timezone type: object success: enum: - true type: boolean required: - success - data type: object ErrorResponse: properties: code: description: Error code for programmatic handling example: NOT_FOUND type: string error: description: Human-readable error message example: Lead not found type: string requestId: description: Request ID for support debugging example: req_abc123 type: string success: enum: - false type: boolean required: - success - error - code type: object MiddlewareErrorResponse: properties: code: type: string error: type: string requestId: type: string success: enum: - false type: boolean required: - success - error - code type: object BookingLinkAvailabilitySlot: properties: emails: description: Host emails free at this slot (round-robin candidate pool) items: type: string type: array end_time: description: Slot end (unix seconds, UTC) example: 1783509300 type: integer start_time: description: Slot start (unix seconds, UTC) example: 1783507500 type: integer required: - start_time - end_time type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.