Agentbookable Bookings API

openapi: 3.2.0
info:
  title: AgentBookable — Booking API for AI agents Bookings 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: Bookings
  description: Create and inspect bookings
paths:
  /bookings:
    post:
      tags:
      - Bookings
      summary: Create a booking
      description: Creates a real appointment at the provider. Requires a mandate (`mandateRef`) created from the user's instruction. The slot is revalidated at booking time. Check the service's `bookingRequirements` first (e.g. phone required) — missing details return `400` with the missing fields. Include a stable `idempotencyKey` so retries never double-book.
      operationId: createBooking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingCreate'
      responses:
        '200':
          description: Confirmed booking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          description: Invalid request or missing customer information (see requiredFields)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: INVALID_REQUEST
                message: Additional customer information is required.
                requiredFields:
                - id: phone
                  type: phone
                  label: Phone number
                  required: true
        '409':
          description: Slot taken — alternatives provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: SLOT_NO_LONGER_AVAILABLE
                message: That slot is no longer available.
                alternatives: []
        '429':
          $ref: '#/components/responses/RateLimited'
  /bookings/{bookingId}:
    get:
      tags:
      - Bookings
      summary: Retrieve a booking
      description: Live status of a booking by its AgentBookable id (`bb_bkg_*`). Customer personal data is partially masked.
      operationId: getBooking
      parameters:
      - name: bookingId
        in: path
        required: true
        schema:
          type: string
        example: bb_bkg_3e74e9ebd024c32b
      responses:
        '200':
          description: The booking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '404':
          description: Booking not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
  /bookings/{bookingId}/reschedule:
    post:
      tags:
      - Bookings
      summary: Reschedule a booking (only when supported)
      description: Requires a mandate with action `reschedule_booking`. **Only available when the business `capabilities.reschedule` is true** — otherwise you get `RESCHEDULE_NOT_SUPPORTED`. Do not offer rescheduling to users for businesses where it is unsupported.
      operationId: rescheduleBooking
      parameters:
      - name: bookingId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RescheduleCreate'
      responses:
        '200':
          description: Rescheduled booking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Reschedule not supported for this business
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
  /bookings/{bookingId}/cancel:
    post:
      tags:
      - Bookings
      summary: Cancel a booking (only when supported)
      description: Requires a mandate with action `cancel_booking`. **Only available when the business `capabilities.cancellation` is true** — otherwise you get `CANCELLATION_NOT_ALLOWED`. Do not offer cancellation to users for businesses where it is unsupported.
      operationId: cancelBooking
      parameters:
      - name: bookingId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelCreate'
      responses:
        '200':
          description: Cancelled booking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Cancellation not allowed for this business
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: CANCELLATION_NOT_ALLOWED
                message: This business does not allow cancellation.
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    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
    Booking:
      type: object
      properties:
        id:
          type: string
          example: bb_bkg_3e74e9ebd024c32b
        businessId:
          type: string
        serviceId:
          type: string
        staffId:
          type:
          - string
          - 'null'
        start:
          type: string
        end:
          type: string
        status:
          type: string
          enum:
          - confirmed
          - pending
          - cancelled
          - completed
        customer:
          type: object
          description: Personal data partially masked
          properties:
            name:
              type: string
            email:
              type:
              - string
              - 'null'
            phone:
              type:
              - string
              - 'null'
        createdVia:
          type: string
          enum:
          - agent
        mandateRef:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
    RescheduleCreate:
      type: object
      required:
      - businessId
      - newStart
      - mandateRef
      properties:
        businessId:
          type: string
        newStart:
          type: string
          description: New start, ISO-8601 in the business timezone
        mandateRef:
          type: string
        idempotencyKey:
          type: string
    CancelCreate:
      type: object
      required:
      - businessId
      - mandateRef
      properties:
        businessId:
          type: string
        mandateRef:
          type: string
        reason:
          type: string
        idempotencyKey:
          type: string
    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
    BookingCreate:
      type: object
      required:
      - businessId
      - serviceId
      - customer
      - mandateRef
      properties:
        businessId:
          type: string
        serviceId:
          type: string
        slotId:
          type: string
          description: Slot id from the availability call (preferred)
        slot:
          type: object
          description: Explicit slot when you do not have a slotId
          properties:
            start:
              type: string
            end:
              type: string
            staffId:
              type: string
        customer:
          type: object
          required:
          - name
          properties:
            name:
              type: string
            email:
              type: string
              format: email
            phone:
              type: string
              description: Required when the service's bookingRequirements.phone is 'required'
            locale:
              type: string
            timezone:
              type: string
        mandateRef:
          type: string
          description: From POST /mandates — single-use, expires in 15 minutes
        idempotencyKey:
          type: string
          description: Stable key for safe retries
        draftId:
          type: string
          description: The consented draft (from POST /booking-drafts + POST /mandates/for-draft). Request must match the draft exactly.
  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.