Gaplessly Agent (MCP) API

openapi: 3.2.0
info:
  title: Gaplessly booking Agent (MCP) API
  version: 1.0.0
  summary: Two booking engines sharing plumbing, never booking logic.
  description: 'Gaplessly runs **two booking engines**: appointments (a client books one service with one staff member for a set duration) and table reservations (a guest books a table for a party inside a service period). They are two products, not one product with a flag. Each organization runs exactly one, chosen when it signs up, and `businessType` on `GET /api/v1/organization` says which.


    This document covers the surfaces built for other software:


    - **`/api/v1/*`**: an organization''s own data with an API key, sent as `Authorization: Bearer sk_live_…`: read it, find free times, and book, change or cancel on a guest''s behalf. Scoped and rate limited.

    - **`/api/book/{slug}/*`**: the public booking endpoints a business''s booking page calls. No authentication.

    - **`/api/book/{slug}/manage/{token}`**: guest self-service. The token in the guest''s booking link is the whole credential.

    - **`/api/mcp`**: a Model Context Protocol endpoint for AI assistants helping a guest find a time. No authentication.


    Guides, a quickstart and the versioning and deprecation policy: /docs.'
  contact:
    name: Gaplessly
    url: mailto:support@gaplessly.com
servers:
- url: https://gaplessly.com
  description: 'Production. There is deliberately no CORS policy: an API key is a secret, so call `/api/v1` from a server, never from browser JavaScript.'
tags:
- name: Agent (MCP)
  description: One JSON-RPC endpoint (Model Context Protocol) an AI assistant uses to find free times at any Gaplessly business on a guest's behalf. No authentication. See the MCP connector page.
paths:
  /api/mcp:
    post:
      summary: MCP endpoint
      description: 'The Model Context Protocol endpoint an AI assistant connects to in order to read the public booking surface on a guest''s behalf. One endpoint for the whole platform, with the venue as a tool argument.


        **Not a REST operation.** The body is JSON-RPC 2.0 and the method vocabulary is the MCP specification''s (`initialize`, `tools/list`, `tools/call`, ...). Read the MCP specification for the envelope, and call `tools/list` against this endpoint for the tools: that is the authoritative, self-describing answer.


        **Six tools, none of which books anything.** `find_venues` searches the businesses that chose to be found by name, suburb or postcode; `get_venue`, `find_appointment_times` and `find_table_times` read; `start_appointment_booking` and `start_table_booking` turn a slot token into a short-lived link on the venue''s own booking page, where the guest enters their own details and confirms. No tool accepts a guest''s name, email or phone, and none moves money. Opening a `start_table_booking` link holds that table for about ten minutes on the booking page; the tool call itself holds nothing. Everything returned is already shown to any visitor of the venue''s booking page.


        **Findable on every plan, bookable from Growth and Pro (Venue Growth and Venue Pro).** `get_venue` answers for any venue with its `bookingPage` link. The two time searches and the two booking tools need the venue''s plan to include AI booking; below it they answer with `bookingPage` and `liveTimes: false`.


        **No timezone and no machine-readable instant is ever returned.** Times come back as display text plus an opaque signed slot token, because a model handed a timezone next to a time converts it and books hours wrong.


        **No CORS.** An MCP client is a server-to-server HTTP client; the browser-based MCP Inspector cannot reach this, so use the Inspector CLI.


        **No authentication**, by design: nothing this endpoint reads is private.'
      tags:
      - Agent (MCP)
      operationId: callBookingMcp
      security: []
      responses:
        '200':
          description: 'A JSON-RPC 2.0 response, or a `text/event-stream` when the client negotiates streaming. Application-level failures (unknown tool, invalid arguments, unknown venue) are reported in the `error` member or as a tool result with `isError: true`, not as an HTTP status.'
          content:
            application/json:
              schema:
                type: object
                description: A JSON-RPC 2.0 response envelope. Shape is defined by the MCP specification, not by this document.
                properties:
                  jsonrpc:
                    const: '2.0'
                  id:
                    type:
                    - string
                    - number
                    - 'null'
                  result:
                    type: object
                    description: Present on success. Contents depend on the method called.
                  error:
                    type: object
                    description: Present on a protocol-level failure.
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
components:
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: sk_live_<16 hex key id>_<43 char base64url secret> (sk_test_ for a test key)
      description: 'An organization admin creates keys in the dashboard under **Developer**; API access is included on Pro (Venue Pro for venues). The raw key is shown once, when it is created. Send it as `Authorization: Bearer sk_live_…` and nowhere else: no query parameter, custom header or cookie, because a credential in a URL ends up in logs and browser history.


        - **Scopes are the whole permission model.** A key carries `resource:action` scopes, never a role, and `write` does not imply `read`.

        - **Engine endpoints check the engine.** A key from a table-reservations organization gets `403 wrong_vertical` from an appointments endpoint, and the other way round, even when it holds the scope.

        - **Keys cannot manage keys.** Keys are created and revoked only in the dashboard, so a leaked key cannot mint another.

        - **Errors carry a stable `code`** beside the `error` sentence: `missing_authorization`, `invalid_key`, `key_revoked`, `key_expired`, `organization_inactive` (401); `insufficient_scope`, `wrong_vertical`, `plan_required` (403); `rate_limited` (429). Match on `code`, never on the sentence.

        - **Rate limits are per key**: a fixed 60-second window, 120 requests a minute by default. Every response states the policy in `RateLimit-Policy`, a response to a known key adds what is left in `RateLimit`, and a 429 adds `Retry-After`.

        - **Every list is `{ data, nextCursor }`**, keyset paged and camelCase. `nextCursor` is null exactly when there are no more rows.

        - **`/api/v1/` is a real version.** A breaking change ships as `/api/v2/`, and `v1` keeps answering unchanged for at least 6 months with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers on every response. Only a security fix can shorten that window, and the notice says why.'
externalDocs:
  description: Versioning and deprecation policy
  url: /docs/conventions#versioning