Daycal Public API

openapi: 3.2.0
info:
  title: Daycal Public API
  version: 1.0.0
  description: 'Daycal gives a person a page where other people can book time with them, matching their real situation (trips in other time zones, holidays, Friday cutoffs, focus blocks, daily limits, several calendars) because they just tell their AI assistant. This API serves both kinds of assistant. The public booking API (tag public, no auth) is for an invitee''s assistant booking a time on someone''s page. The owner API (tag owner; Bearer: an MCP OAuth access token or a Daycal API token from /token) is for the owner''s assistant: under the hood, availability is a short rules.js written against the daycal standard library, which the assistant writes and maintains, always previewing and getting the owner''s go-ahead before making it live. Every MCP tool (connecting calendars, importing from Calendly or Cal.com, the handle, account deletion and the rest) is also a REST call: GET /api/me/tools lists them with their input schemas, plus the instructions every MCP client gets (read and follow them first) and the prompts as text (setup: first-time setup step by step); POST /api/me/tools/{name} runs one. Times are ISO 8601 in UTC.'
servers:
- url: https://daycal.io
tags:
- name: Public
paths:
  /api/pages/{handle}:
    get:
      tags:
      - Public
      summary: Booking page and its event types
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '429':
          description: Rate limited. Retry-After is set when a rate-limit window is spent (not on a booking's own budget)
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiPagesByHandle
      x-operation-id-source: derived
  /api/pages/{handle}/slots:
    get:
      tags:
      - Public
      summary: Open slots for one event type (to - from <= 35 days)
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
      - name: type
        in: query
        required: true
        schema:
          type: string
        description: Event type slug
      - name: from
        in: query
        required: true
        schema:
          type: string
        description: ISO instant
      - name: to
        in: query
        required: true
        schema:
          type: string
        description: ISO instant
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  slots:
                    type: array
                    items:
                      $ref: '#/components/schemas/Slot'
                  timezone:
                    type: string
                  configVersion:
                    type: integer
                  eventsVersion:
                    type: integer
                  stale:
                    type: boolean
                required:
                - slots
                - timezone
                - configVersion
                - eventsVersion
                - stale
        '429':
          description: Rate limited. Retry-After is set when a rate-limit window is spent (not on a booking's own budget)
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiPagesByHandleSlots
      x-operation-id-source: derived
  /api/pages/{handle}/bookings:
    post:
      tags:
      - Public
      summary: Book a slot, one of four ways, each checked the same way.
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                eventType:
                  type: string
                start:
                  type: string
                  format: date-time
                name:
                  type: string
                email:
                  type: string
                note:
                  type: string
                tz:
                  type: string
                pageId:
                  type: string
                  description: 'The pageId GET /api/pages/{handle} gave: read the page first and send it on every booking, so a handle that names another account now is refused (409 page_changed) rather than booked with them. Required (400 invalid_request without it), except with invite: a booking link''s token names its owner'
                invite:
                  type: string
                  description: 'A booking link''s token: books once, no bot check, no code'
                turnstileToken:
                  type: string
                  description: Solved by the booking page's form only
              required:
              - eventType
              - start
              - name
              - email
              - tz
              anyOf:
              - required:
                - pageId
              - required:
                - invite
            example:
              eventType: 30min
              start: '2026-10-20T16:00:00Z'
              name: Dana Park
              email: dana@example.com
              tz: America/New_York
              pageId: <pageId from GET /api/pages/{handle}>
      responses:
        '201':
          description: Booked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booked'
        '202':
          description: Code emailed to the invitee (10 minutes, 5 tries); nothing is booked or held yet
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - confirm_email
                  confirmation:
                    type: string
                    description: Pass to /bookings/confirm with the emailed code
                  expiresAt:
                    type: string
                    format: date-time
                required:
                - status
                - confirmation
                - expiresAt
        '429':
          description: Rate limited. Retry-After is set when a rate-limit window is spent (not on a booking's own budget)
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiPagesByHandleBookings
      x-operation-id-source: derived
  /api/pages/{handle}/bookings/confirm:
    post:
      tags:
      - Public
      summary: 'Book the request a 202 named, with the code emailed to the invitee: checked…'
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                confirmation:
                  type: string
                code:
                  type: string
              required:
              - confirmation
              - code
      responses:
        '201':
          description: Booked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booked'
        '429':
          description: Rate limited. Retry-After is set when a rate-limit window is spent (not on a booking's own budget)
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiPagesByHandleBookingsConfirm
      x-operation-id-source: derived
  /api/b/{token}:
    get:
      tags:
      - Public
      summary: A booking by its manage token
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  booking:
                    $ref: '#/components/schemas/ManagedBooking'
                  page:
                    $ref: '#/components/schemas/ManagedPage'
                required:
                - booking
                - page
        '429':
          description: Rate limited. Retry-After is set when a rate-limit window is spent (not on a booking's own budget)
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiBByToken
      x-operation-id-source: derived
  /api/b/{token}/reschedule:
    post:
      tags:
      - Public
      summary: Move a booking
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start:
                  type: string
                  format: date-time
                tz:
                  type: string
              required:
              - start
              - tz
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  booking:
                    $ref: '#/components/schemas/Booking'
                required:
                - booking
        '429':
          description: Rate limited. Retry-After is set when a rate-limit window is spent (not on a booking's own budget)
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiBByTokenReschedule
      x-operation-id-source: derived
  /api/b/{token}/cancel:
    post:
      tags:
      - Public
      summary: Cancel a booking
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              required: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  booking:
                    $ref: '#/components/schemas/Booking'
                required:
                - booking
        '429':
          description: Rate limited. Retry-After is set when a rate-limit window is spent (not on a booking's own budget)
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiBByTokenCancel
      x-operation-id-source: derived
components:
  schemas:
    Page:
      type: object
      properties:
        handle:
          type: string
        ownerName:
          type: string
        timezone:
          type: string
        eventTypes:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
              title:
                type: string
              description:
                type: string
              duration:
                type: integer
                description: Minutes
              location:
                type:
                - string
                - 'null'
              conferencing:
                type: string
                enum:
                - google-meet
                - link
                - none
            required:
            - slug
            - title
            - description
            - duration
            - location
            - conferencing
        booking:
          type: object
          properties:
            note:
              type: boolean
            confirmation:
              type: string
          required:
          - note
          - confirmation
        footer:
          type: boolean
        turnstileSiteKey:
          type:
          - string
          - 'null'
        pageId:
          type: string
          description: Opaque; send it back as the booking's pageId
      required:
      - handle
      - ownerName
      - timezone
      - eventTypes
      - booking
      - footer
      - turnstileSiteKey
      - pageId
    Slot:
      type: object
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
      required:
      - start
      - end
    ManagedPage:
      type: object
      properties:
        handle:
          type:
          - string
          - 'null'
          description: 'null while the account holds no handle: no page to book again on'
        ownerName:
          type: string
        timezone:
          type: string
        eventTypes:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
              title:
                type: string
              description:
                type: string
              duration:
                type: integer
                description: Minutes
              location:
                type:
                - string
                - 'null'
              conferencing:
                type: string
                enum:
                - google-meet
                - link
                - none
            required:
            - slug
            - title
            - description
            - duration
            - location
            - conferencing
        booking:
          type: object
          properties:
            note:
              type: boolean
            confirmation:
              type: string
          required:
          - note
          - confirmation
        footer:
          type: boolean
        turnstileSiteKey:
          type:
          - string
          - 'null'
      required:
      - handle
      - ownerName
      - timezone
      - eventTypes
      - booking
      - footer
      - turnstileSiteKey
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            alternatives:
              type: array
              items:
                $ref: '#/components/schemas/Slot'
              description: 'slot_taken (public API): the nearest open slots'
            triesLeft:
              type: integer
              description: 'wrong_code (public API): wrong codes the request still takes'
            details:
              description: Machine-readable detail, e.g. invalid_rules' RuleError (owner API)
          required:
          - code
          - message
      required:
      - error
    ManagedBooking:
      type: object
      properties:
        id:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        eventType:
          type: string
        title:
          type: string
        manageUrl:
          type: string
        conferenceUrl:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - confirmed
          - cancelled
          - rescheduled
        inviteeName:
          type: string
        inviteeEmail:
          type: string
        note:
          type:
          - string
          - 'null'
      required:
      - id
      - start
      - end
      - eventType
      - title
      - manageUrl
      - conferenceUrl
      - status
      - inviteeName
      - inviteeEmail
      - note
    Booking:
      type: object
      properties:
        id:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        eventType:
          type: string
        title:
          type: string
        manageUrl:
          type: string
        conferenceUrl:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - confirmed
          - cancelled
          - rescheduled
      required:
      - id
      - start
      - end
      - eventType
      - title
      - manageUrl
      - conferenceUrl
      - status
    Booked:
      type: object
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
        confirmation:
          type: string
      required:
      - booking
      - confirmation
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'OAuth access token or Daycal API token (daycal_...). Its owner scopes decide which tools and routes it reaches: read, write (includes read), billing, secrets; GET /api/me/tools lists the tools it may call.'