Agentbookable Services API

openapi: 3.2.0
info:
  title: AgentBookable — Booking API for AI agents Services 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: Services
  description: List bookable services and their requirements
paths:
  /businesses/{businessId}/services:
    get:
      tags:
      - Services
      summary: List bookable services
      description: Services the business has opened to AI booking. Each service carries `bookingRequirements` — check them before booking (e.g. a required customer phone) so you can collect the details from the user up front.
      operationId: listServices
      parameters:
      - name: businessId
        in: path
        required: true
        schema:
          type: string
        example: agentbookable-demo
      responses:
        '200':
          description: Bookable services
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '404':
          description: Business not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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
    BookingRequirements:
      type: object
      description: What the agent must collect from the user BEFORE booking. Contact requirements are provider-derived; AgentBookable never reveals which provider.
      properties:
        name:
          type: string
          enum:
          - required
          - optional
          description: Customer name.
        email:
          type: string
          enum:
          - required
          - optional
          description: Customer email.
        phone:
          type: string
          enum:
          - required
          - optional
          description: Customer phone. 'required' means the booking is rejected without one — collect it first.
        payment:
          type: boolean
          description: True when payment is required to confirm.
    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
    Service:
      type: object
      properties:
        id:
          type: string
          example: bb_srv_e64d99e1e1243d68
        businessId:
          type: string
        name:
          type: string
          example: Haircut
        description:
          type:
          - string
          - 'null'
        durationMinutes:
          type: integer
          example: 30
        price:
          type:
          - object
          - 'null'
          properties:
            amount:
              type: number
            currency:
              type: string
        staff:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
        bookingRequirements:
          $ref: '#/components/schemas/BookingRequirements'
  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.