Agentbookable Discovery API

openapi: 3.2.0
info:
  title: AgentBookable — Booking API for AI agents Discovery 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: Discovery
  description: Find businesses and read their capabilities
paths:
  /businesses:
    get:
      tags:
      - Discovery
      summary: Search published businesses
      description: Search the AgentBookable registry. Falls back to legacy seeded businesses when the registry has no matches. Returns capability flags for each business.
      operationId: searchBusinesses
      parameters:
      - name: query
        in: query
        schema:
          type: string
        description: Free-text match on name/category/description/services
        example: hairdresser
      - name: category
        in: query
        schema:
          type: string
        description: Exact category match
        example: hairdresser
      - name: city
        in: query
        schema:
          type: string
        example: London
      - name: country
        in: query
        schema:
          type: string
      - name: service
        in: query
        schema:
          type: string
        description: Match service names
        example: Haircut
      - name: latitude
        in: query
        schema:
          type: number
      - name: longitude
        in: query
        schema:
          type: number
      - name: radiusKm
        in: query
        schema:
          type: number
          default: 25
      responses:
        '200':
          description: Matching published businesses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Business'
              example:
              - id: ab_bus_c24850fce8cfb9db
                name: AgentBookable Demo
                slug: agentbookable-demo
                category: hairdresser
                location:
                  city: London
                  country: FR
                timezone: Europe/Paris
                provider:
                  type: registry
                capabilities:
                  services: true
                  availability: true
                  booking: true
                  reschedule: false
                  cancellation: false
                  payment: false
                  instantConfirmation: true
        '429':
          $ref: '#/components/responses/RateLimited'
  /businesses/{businessId}:
    get:
      tags:
      - Discovery
      summary: Get a business record
      description: Normalized details + capability flags. Accepts an `ab_bus_*` id or a public slug (e.g. `agentbookable-demo`). Always read `capabilities` before attempting actions.
      operationId: getBusiness
      parameters:
      - name: businessId
        in: path
        required: true
        schema:
          type: string
        example: agentbookable-demo
      responses:
        '200':
          description: The business record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Business'
        '404':
          description: Business not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: BUSINESS_NOT_FOUND
                message: Business 'x' not found in the registry.
        '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
    Business:
      type: object
      properties:
        id:
          type: string
          example: ab_bus_c24850fce8cfb9db
        name:
          type: string
          example: AgentBookable Demo
        slug:
          type:
          - string
          - 'null'
          example: agentbookable-demo
        category:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        location:
          type: object
          properties:
            city:
              type: string
            postcode:
              type: string
            country:
              type: string
        timezone:
          type: string
          example: Europe/Paris
        provider:
          type: object
          properties:
            type:
              type: string
              description: Internal provider family. Providers are never exposed by name to agents.
              enum:
              - registry
              - calcom
              - zoho
              - simplybook
        capabilities:
          $ref: '#/components/schemas/Capabilities'
    Capabilities:
      type: object
      description: 'What is possible for this business. Agents MUST respect these: do not promise actions whose flag is false.'
      properties:
        services:
          type: boolean
          description: Service listing supported.
        availability:
          type: boolean
          description: Live availability lookup supported. When true you may call POST /businesses/{id}/availability.
        booking:
          type: boolean
          description: Booking creation supported. When true you may call POST /bookings (with a mandate).
        reschedule:
          type: boolean
          description: Rescheduling supported. When false, never offer to move an appointment.
        cancellation:
          type: boolean
          description: Cancellation supported. When false, never offer to cancel.
        payment:
          type: boolean
          description: Payment through AgentBookable. When false, payment (if any) is handled at the venue.
        instantConfirmation:
          type: boolean
          description: True when bookings are confirmed immediately; false means the provider may hold requests for manual confirmation.
    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
  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.