Calendly Shares API

openapi: 3.1.0
info:
  title: Calendly Scheduling Activity Log Shares API
  description: The Calendly Scheduling API (v2) is a RESTful API that allows developers to programmatically manage scheduling workflows. It provides endpoints for managing users, organizations, event types, scheduled events, invitees, routing forms, availability schedules, and webhook subscriptions. The API uses JSON for request and response bodies, standard HTTP methods, and supports authentication via personal access tokens and OAuth 2.1. Developers can use it to create events on behalf of invitees, retrieve scheduling data, and integrate Calendly functionality directly into their applications.
  version: 2.0.0
  contact:
    name: Calendly Developer Support
    url: https://developer.calendly.com/
  termsOfService: https://calendly.com/pages/terms
servers:
- url: https://api.calendly.com
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Shares
  description: Endpoints for creating and managing shareable scheduling links.
paths:
  /shares:
    post:
      operationId: createShare
      summary: Create share
      description: Creates a shareable scheduling link that can be distributed to potential invitees. Shares can include multiple event types and custom availability settings.
      tags:
      - Shares
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_type
              properties:
                event_type:
                  type: string
                  format: uri
                  description: The URI of the event type to create a share for.
                max_spots:
                  type: integer
                  description: The maximum number of spots available for booking through this share.
                  minimum: 1
      responses:
        '201':
          description: Successfully created the share
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    $ref: '#/components/schemas/Share'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: The request was invalid or malformed. Check the request body and parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed. Verify that a valid access token is provided in the Authorization header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Share:
      type: object
      description: A shareable scheduling link that can be distributed to potential invitees.
      properties:
        uri:
          type: string
          format: uri
          description: The canonical URI of the share resource.
        scheduling_url:
          type: string
          format: uri
          description: The shareable scheduling URL.
        booking_url:
          type: string
          format: uri
          description: The direct booking URL.
        event_type:
          type: string
          format: uri
          description: The URI of the associated event type.
    Error:
      type: object
      description: An error response from the Calendly API.
      properties:
        title:
          type: string
          description: A short summary of the error.
        message:
          type: string
          description: A detailed description of the error.
        details:
          type: array
          items:
            type: object
            properties:
              parameter:
                type: string
                description: The parameter that caused the error.
              message:
                type: string
                description: A description of what was wrong with the parameter.
          description: Specific details about validation errors.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal access token or OAuth 2.1 access token. Include in the Authorization header as Bearer {token}.
externalDocs:
  description: Calendly API Documentation
  url: https://developer.calendly.com/api-docs