openapi: 3.0.3
info:
  title: Vagaro Enterprise Business API (Partial, Community-Modeled) Appointments Employees API
  description: 'Vagaro publishes a "PUBLIC - Enterprise Business API V2" reference at docs.vagaro.com (readme.io). The Access Token endpoint below is transcribed directly from that public reference page: method, full path pattern, request body fields, and documented response codes. The Appointments, Customers, Employees, Employee Management, and Locations paths are honestly modeled from Vagaro''s own capability-level descriptions of those five areas ("retrieve details about appointments including status, start time, and service provider", "obtain customer contact information and tags", "view service provider details, contact information, and reporting relationships", "assign and unassign employees across locations with access levels, provision/deprovision calendars", "retrieve single or multi-location business details") and from the confirmed field names in Vagaro''s Webhook event payloads (Appointment, Customer, Employee, Business Location events). Exact parameter names, pagination style, and full response schemas for those five areas are not publicly visible without an approved Vagaro partner account and are marked x-endpointsModeled: true. Do not treat the modeled paths as verified against a live response.'
  version: v2
  contact:
    name: Vagaro
    url: https://www.vagaro.com/pro
  license:
    name: Proprietary
    url: https://docs.vagaro.com/
servers:
- url: https://api.vagaro.com/{region}/api/v2
  description: Vagaro Enterprise Business API (region-scoped)
  variables:
    region:
      default: us
      description: Business region assigned to the Vagaro account, as documented in the API basics guide.
security:
- bearerAuth: []
tags:
- name: Employees
  description: Service provider contact information and reporting relationships. Endpoints modeled.
paths:
  /employees:
    get:
      operationId: listEmployees
      tags:
      - Employees
      summary: List employees / service providers (modeled)
      description: Modeled from Vagaro's documented capability summary and the confirmed Employee webhook payload fields.
      x-endpointsModeled: true
      parameters:
      - name: businessId
        in: query
        schema:
          type: string
        description: Modeled - filter to a single business location.
      responses:
        '200':
          description: A list of employees (modeled response shape).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /employees/{employeeId}:
    get:
      operationId: getEmployee
      tags:
      - Employees
      summary: Get an employee (modeled)
      x-endpointsModeled: true
      parameters:
      - name: employeeId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: An employee (modeled response shape).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Employee not found.
components:
  schemas:
    Employee:
      type: object
      description: Modeled from the documented capability ("contact information and reporting structure") and Employee webhook events.
      properties:
        employeeId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        title:
          type: string
        reportsToEmployeeId:
          type: string
        businessId:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid access token, or token lacks the required scope.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token issued by /merchants/generate-access-token