Agentbookable Availability API

openapi: 3.2.0
info:
  title: AgentBookable — Booking API for AI agents Availability API
  version: 3.0.0
  description: 'One booking interface for AI agents. Businesses keep their existing booking system and connect through AgentBookable (Composio-backed connectors such as Cal.com). Provider-specific identifiers are never exposed.


    ## Workflow


    1. Discover businesses: `GET /businesses`.

    2. Read capabilities on the business record.

    3. List services: `GET /businesses/{businessId}/services`.

    4. Check live availability: `POST /businesses/{businessId}/availability`.

    5. Prepare a draft: `POST /booking-drafts`.

    6. Obtain explicit user consent to that draft.

    7. Authorize: `POST /mandates/for-draft`.

    8. Book: `POST /bookings` with mandateRef + draftId.


    Example published business: `agentbookable-demo`.'
  contact:
    name: AgentBookable
    url: https://agentbookable.com
servers:
- url: https://agentbookable.com
tags:
- name: Availability
  description: Live slot lookup
paths:
  /businesses/{businessId}/availability:
    post:
      tags:
      - Availability
      summary: Find live availability
      description: Live slots for a service. Slots are TEMPORARY (~60 seconds, see `expiresAt`) and revalidated at booking time. Always call this immediately before `POST /bookings`. If the chosen slot is taken you receive `409 SLOT_NO_LONGER_AVAILABLE` with alternatives.
      operationId: findAvailability
      parameters:
      - name: businessId
        in: path
        required: true
        schema:
          type: string
        example: ab_bus_c24850fce8cfb9db
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - serviceId
              - from
              - to
              properties:
                serviceId:
                  type: string
                  example: bb_srv_e64d99e1e1243d68
                from:
                  type: string
                  description: ISO-8601 window start
                  example: '2026-09-01T00:00:00Z'
                to:
                  type: string
                  description: ISO-8601 window end
                  example: '2026-09-01T23:59:59Z'
      responses:
        '200':
          description: Live slots in the window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityResult'
              example:
                businessId: ab_bus_c24850fce8cfb9db
                serviceId: bb_srv_e64d99e1e1243d68
                slots:
                - id: bb_slot_8d05aa3a
                  serviceId: bb_srv_e64d99e1e1243d68
                  start: '2026-09-01T09:00:00+02:00'
                  end: '2026-09-01T09:30:00+02:00'
                  staffId: sb-unit-2
                  fetchedAt: '2026-08-29T14:30:39Z'
                  expiresAt: '2026-08-29T14:31:39Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Business or service unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: Fixed error-code vocabulary
          enum:
          - INVALID_REQUEST
          - AUTHENTICATION_FAILED
          - BUSINESS_NOT_FOUND
          - SERVICE_NOT_FOUND
          - SLOT_NO_LONGER_AVAILABLE
          - MANDATE_REQUIRED
          - MANDATE_INVALID
          - MANDATE_EXPIRED
          - MANDATE_ALREADY_USED
          - MANDATE_ACTION_MISMATCH
          - MANDATE_BUSINESS_MISMATCH
          - RATE_LIMITED
          - PROVIDER_ERROR
          - PROVIDER_UNAVAILABLE
        message:
          type: string
        requiredFields:
          type: array
          items:
            $ref: '#/components/schemas/Requirement'
          description: Present on 400 when customer details are missing
        alternatives:
          type: array
          items:
            type: object
          description: Present on 409 SLOT_NO_LONGER_AVAILABLE
    AvailabilityResult:
      type: object
      properties:
        businessId:
          type: string
        serviceId:
          type: string
        slots:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Pass as slotId to POST /bookings
              serviceId:
                type: string
              start:
                type: string
                description: ISO-8601 with business-timezone offset
              end:
                type: string
              staffId:
                type:
                - string
                - 'null'
              fetchedAt:
                type: string
              expiresAt:
                type: string
                description: Slots are temporary; book before this time or re-fetch
    Requirement:
      type: object
      properties:
        id:
          type: string
          example: phone
        type:
          type: string
          enum:
          - text
          - email
          - phone
          - number
          - boolean
          - select
        label:
          type: string
        required:
          type: boolean
  responses:
    RateLimited:
      description: Too many requests — slow down
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: RATE_LIMITED
            message: Too many requests. Retry later.