BambooHR API (minimal) — OpenAPI spec for Redpanda AI Gateway OpenAPI MCP, token-vault smoke test

bamboohr-api.yaml

openapi: 3.0.3
info:
  title: BambooHR API (minimal)
  version: "1.0"
  description: |
    Minimal OpenAPI spec for the BambooHR REST API, covering just enough
    endpoints to validate the OAuth token vault end-to-end. Official docs:
    https://documentation.bamboohr.com/reference
servers:
  - url: https://redpanda.bamboohr.com
    description: Override at MCP registration time via base_url.
paths:
  /api/v1/employees/directory:
    get:
      operationId: getEmployeeDirectory
      summary: Get the employee directory
      description: |
        Returns a list of employees visible to the authenticated user. Useful
        as a smoke test: any valid bearer token returns a non-empty result.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeDirectory'
  /api/v1/employees/{employeeId}:
    get:
      operationId: getEmployee
      summary: Get a single employee by ID
      description: |
        Returns the requested fields for a single employee. Pass `0` or the
        authenticated user's own id to retrieve self.
      parameters:
        - name: employeeId
          in: path
          required: true
          description: Numeric employee id, or `0` for the authenticated user.
          schema:
            type: string
        - name: fields
          in: query
          required: true
          description: |
            Comma-separated list of fields to return, e.g.
            `firstName,lastName,jobTitle,department,workEmail`.
          schema:
            type: string
            default: firstName,lastName,jobTitle,department,workEmail
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
  /api/v1/meta/users:
    get:
      operationId: getUsers
      summary: List BambooHR user accounts
      description: |
        Returns the map of BambooHR user accounts. Small, cheap endpoint —
        handy for verifying the bearer token is accepted.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    EmployeeDirectory:
      type: object
      properties:
        fieldCount:
          type: integer
        fields:
          type: array
          items:
            type: object
            additionalProperties: true
        employees:
          type: array
          items:
            $ref: '#/components/schemas/Employee'
    Employee:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
        displayName:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        jobTitle:
          type: string
        department:
          type: string
        workEmail:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []