openapi: 3.0.3
info:
  title: Everhour Clients Timers 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: Timers
  description: Start, inspect, and stop running timers.
paths:
  /timers:
    post:
      operationId: startTimer
      tags:
      - Timers
      summary: Start timer
      description: Starts a timer on a task for the current user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimerRequest'
      responses:
        '201':
          description: The started timer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /timers/current:
    get:
      operationId: getRunningTimer
      tags:
      - Timers
      summary: Get running timer
      description: Returns the currently running timer for the current user.
      responses:
        '200':
          description: The running timer (status stopped if none is running).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: stopTimer
      tags:
      - Timers
      summary: Stop timer
      description: Stops the currently running timer and records the tracked time.
      responses:
        '200':
          description: The stopped timer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /team/timers:
    get:
      operationId: getAllTeamTimers
      tags:
      - Timers
      summary: Get all team timers
      description: Returns all currently running timers across the team.
      responses:
        '200':
          description: A list of running timers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Timer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    TaskTime:
      type: object
      properties:
        total:
          type: integer
          description: Total task time in seconds.
        users:
          type: object
          description: Task time in seconds keyed by user ID.
          additionalProperties:
            type: integer
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    TaskEstimate:
      type: object
      properties:
        total:
          type: integer
          description: Total task estimate in seconds.
        type:
          type: string
          enum:
          - overall
          - users
        users:
          type: object
          description: Task estimate in seconds keyed by user ID.
          additionalProperties:
            type: integer
    Task:
      type: object
      properties:
        id:
          type: string
          description: Task ID (for example ev:9876543210).
        name:
          type: string
        projects:
          type: array
          description: Project IDs.
          items:
            type: string
        section:
          type: integer
          description: Section ID.
        labels:
          type: array
          items:
            type: string
        position:
          type: integer
        description:
          type: string
        dueAt:
          type: string
        status:
          type: string
          enum:
          - open
          - closed
        time:
          $ref: '#/components/schemas/TaskTime'
        estimate:
          $ref: '#/components/schemas/TaskEstimate'
        unbillable:
          type: boolean
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        headline:
          type: string
        avatarUrl:
          type: string
        role:
          type: string
          enum:
          - admin
          - supervisor
          - member
        status:
          type: string
          enum:
          - active
          - invited
          - pending
          - removed
    TimerRequest:
      type: object
      required:
      - task
      properties:
        task:
          type: string
          description: Task ID to track time against.
        userDate:
          type: string
          format: date
        comment:
          type: string
    Timer:
      type: object
      properties:
        status:
          type: string
          enum:
          - active
          - stopped
        duration:
          type: integer
          description: Timer duration in seconds.
        today:
          type: integer
          description: Time tracked today by the user on the timer task, in seconds.
        startedAt:
          type: string
        userDate:
          type: string
          format: date
        comment:
          type: string
        task:
          $ref: '#/components/schemas/Task'
        user:
          $ref: '#/components/schemas/User'
  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.