openapi: 3.0.3
info:
  title: Everhour Clients Time Off API
  description: The Everhour API is a RESTful interface providing programmatic access to time tracking, timesheets, timers, projects, tasks, clients, invoices, expenses, resource scheduling, time off, and reporting data in Everhour. The API accepts and returns JSON (UTF-8 only). All requests are authenticated with an X-Api-Key header carrying an API key found at the bottom of your Everhour profile page. An optional X-Accept-Version header pins a specific API version (the most recent, 1.2, is used by default). The API is labeled BETA by Everhour, meaning some calls can be slightly adjusted; breaking changes are pushed in separate API versions. Time values are in seconds and money amounts are in cents throughout.
  version: '1.2'
  contact:
    name: Everhour
    url: https://everhour.com
    email: ask@everhour.com
servers:
- url: https://api.everhour.com
  description: Everhour production API
security:
- apiKey: []
tags:
- name: Time Off
  description: Time off types and allocations.
paths:
  /resource-planner/time-off-types:
    get:
      operationId: getTimeOffTypes
      tags:
      - Time Off
      summary: Get time off types
      description: Returns the team's time off types (vacation, sick leave, and so on).
      responses:
        '200':
          description: A list of time off types.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeOffType'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createTimeOffType
      tags:
      - Time Off
      summary: Create time off type
      description: Creates a time off type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffTypeRequest'
      responses:
        '201':
          description: The created time off type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffType'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /resource-planner/time-off-types/{typeId}:
    parameters:
    - name: typeId
      in: path
      required: true
      description: Time off type ID.
      schema:
        type: integer
    put:
      operationId: updateTimeOffType
      tags:
      - Time Off
      summary: Update time off type
      description: Updates a time off type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffTypeRequest'
      responses:
        '200':
          description: The updated time off type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffType'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteTimeOffType
      tags:
      - Time Off
      summary: Delete time off type
      description: Deletes a time off type.
      responses:
        '204':
          description: Time off type deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /allocations:
    get:
      operationId: getAllAllocations
      tags:
      - Time Off
      summary: Get all allocations
      description: Returns time off allocations (accrual balances) for team members.
      responses:
        '200':
          description: A list of time off allocations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeOffAllocation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createAllocation
      tags:
      - Time Off
      summary: Create allocation
      description: Creates a time off allocation for one or more users.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffAllocationRequest'
      responses:
        '201':
          description: The created allocation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffAllocation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /allocations/{allocationId}:
    parameters:
    - name: allocationId
      in: path
      required: true
      description: Allocation ID.
      schema:
        type: integer
    put:
      operationId: updateAllocation
      tags:
      - Time Off
      summary: Update allocation
      description: Updates a time off allocation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffAllocationRequest'
      responses:
        '200':
          description: The updated allocation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffAllocation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteAllocation
      tags:
      - Time Off
      summary: Delete allocation
      description: Deletes a time off allocation.
      responses:
        '204':
          description: Allocation deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    TimeOffTypeRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        color:
          type: string
        paid:
          type: boolean
        description:
          type: string
    TimeOffAllocationRequest:
      type: object
      properties:
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        contractStartDate:
          type: string
          format: date
        users:
          type: array
          items:
            type: integer
        timeOffType:
          type: integer
        days:
          type: number
        daysCarried:
          type: number
        accrualFrequency:
          type: string
          enum:
          - daily
          - immediately
        restrictOverAllocation:
          type: boolean
        completed:
          type: boolean
        notes:
          type: string
    TimeOffAllocation:
      type: object
      properties:
        id:
          type: integer
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        contractStartDate:
          type: string
          format: date
        user:
          type: integer
        timeOffType:
          type: integer
        days:
          type: number
        daysCarried:
          type: number
        daysAllocated:
          type: number
        daysUsed:
          type: number
        accrualFrequency:
          type: string
          enum:
          - daily
          - immediately
        restrictOverAllocation:
          type: boolean
        completed:
          type: boolean
        notes:
          type: string
        createdBy:
          type: integer
        createdAt:
          type: string
    TimeOffType:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        color:
          type: string
        paid:
          type: boolean
        description:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid X-Api-Key header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded (around 20 requests per 10 seconds per API key). The Retry-After response header specifies the number of seconds to wait before making another request.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key from the bottom of your Everhour profile page.