openapi: 3.0.1
info:
  title: Swarmia Additional AI integrations Time off API
  description: The Swarmia API provides programmatic access to engineering-effectiveness analytics. It exposes machine-readable built-in reports (code metrics, DORA metrics, AI adoption), custom reports, deployment and AI-usage ingestion, team and membership management, and time-off records. All endpoints are authenticated with a Bearer API token provisioned in the Swarmia application under Settings / API tokens.
  termsOfService: https://www.swarmia.com/terms-of-service/
  contact:
    name: Swarmia Support
    email: hello@swarmia.com
    url: https://help.swarmia.com
  version: v1
servers:
- url: https://app.swarmia.com/api/v1
  description: Built-in and custom reports plus ingestion (v1)
- url: https://app.swarmia.com/api/v0
  description: Legacy Export API and management endpoints (v0)
- url: https://hook.swarmia.com
  description: Deployment events ingestion hook
security:
- bearerToken: []
tags:
- name: Time off
  description: Create, read, update, and delete employee time-off periods.
paths:
  /time-offs:
    servers:
    - url: https://app.swarmia.com/api/v0
    post:
      operationId: createTimeOff
      tags:
      - Time off
      summary: Create a time-off period
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOff'
      responses:
        '200':
          description: Time-off period created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOff'
  /time-offs/{id}:
    servers:
    - url: https://app.swarmia.com/api/v0
    parameters:
    - name: id
      in: path
      required: true
      description: Swarmia UUID or the caller-supplied externalId.
      schema:
        type: string
    get:
      operationId: getTimeOff
      tags:
      - Time off
      summary: Get a time-off period
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOff'
    put:
      operationId: updateTimeOff
      tags:
      - Time off
      summary: Update a time-off period
      description: Updates email and dates. externalId is immutable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOff'
      responses:
        '200':
          description: Time-off period updated.
    delete:
      operationId: deleteTimeOff
      tags:
      - Time off
      summary: Delete a time-off period
      responses:
        '200':
          description: Time-off period deleted.
components:
  schemas:
    TimeOff:
      type: object
      required:
      - email
      - startDate
      - endDate
      properties:
        email:
          type: string
          format: email
          description: Must match an existing team member.
        startDate:
          type: string
          format: date
          description: yyyy-MM-dd.
        endDate:
          type: string
          format: date
          description: yyyy-MM-dd; must be greater than or equal to startDate.
        externalId:
          type: string
          maxLength: 128
          description: Optional caller identifier. Max 128 chars, no whitespace, slashes, or quotes, and unique. Immutable after creation.
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      description: Bearer API token provisioned at https://app.swarmia.com/settings/api-tokens. Built-in/custom reports require the entityQuery scope; AI usage ingestion requires the aiUsage scope. GET endpoints also accept the token via a ?token= query parameter.