openapi.yaml

---
openapi: 3.0.2
info:
  version: 0.0.1
  title: Hakuna-open-api
  description: Unoffical hakuna api spec
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
servers:
- url: https://{company}.hakuna.ch/api/{basePath}
  description: The production API server
  variables:
    company:
      default: example
    basePath:
      default: v1
security:
  - ApiToken: []
paths:
  /ping:
    get:
      tags:
        - Test
      description: Test endpoint
      operationId: ping
      responses:
        '200':
          description: Pong
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pong'
        '429':
          $ref: '#/components/responses/RateLimit'
  /overview:
    get:
      tags:
        - Personal
      description: Retrieves key numbers about your user, e.g. your current overtime.
      operationId: overview
      parameters:
        - $ref: '#/components/parameters/user_id'
      responses:
        '200':
          description: key metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyMetrics'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
  /timer:
    get:
      tags:
        - Personal
      description: Retrieves the timer.
      operationId: getTimer
      parameters:
        - $ref: '#/components/parameters/user_id'
      responses:
        '200':
          description: Time Entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timer'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
    post:
      tags:
        - Personal
      description: Start Timer
      operationId: startTime
      parameters:
        - $ref: '#/components/parameters/user_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTimer'
      responses:
        '200':
          description: ok
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
    put:
      tags:
        - Personal
      description: End Timer
      operationId: endTimer
      parameters:
        - $ref: '#/components/parameters/user_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndTimer'
      responses:
        '200':
          description: ok
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
    delete:
      tags:
        - Personal
      description: Deletes the timer
      operationId: deleteTimer
      parameters:
        - $ref: '#/components/parameters/user_id'
      responses:
        '200':
          description: ok
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
  /time_entries:
    get:
      tags:
        - Personal
      parameters:
        - $ref: '#/components/parameters/user_id'
        - name: date
          in: query
          description: Date of time entry
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: List of time entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfTimeEntries'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
    post:
      tags:
        - Personal
      parameters:
        - $ref: '#/components/parameters/user_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTimeEntry'
      responses:
        '200':
          description: ok
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
  /time_entries/{id}:
    get:
      tags:
        - Personal
      parameters:
        - $ref: '#/components/parameters/user_id'
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Time entry id
      responses:
        '200':
          description: Time Entry with the given id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntries'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
    patch:
      tags:
        - Personal
      parameters:
        - $ref: '#/components/parameters/user_id'
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Time entry id
      requestBody:
        content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTimeEntry'
      responses:
        '200':
          description: ok
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
    delete:
      tags:
        - Personal
      parameters:
        - $ref: '#/components/parameters/user_id'
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Time entry id
      responses:
        '200':
          description: ok
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
  /absences:
    get:
      tags:
        - Personal
      description: |
        Retrieves your absences in the supplied year
      parameters:
        - name: year
          in: query
          description: Year
          required: true
          schema:
            type: string
            format: year
      operationId: listAbsences
      responses:
        '200':
          description: List of absences for the given year of the current user
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Absence'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
  /absence_types:
    get:
      tags:
        - Global
      description: |
        Retrieves all absence types
      operationId: listAbsenceTypes
      responses:
        '200':
          description: List of all absences types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AbsenceType'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
  /users:
    get:
      tags:
        - User
      description: |
        Retrieves all user you can manage (as admin or team leader). See here how to make requests for these users.
      operationId: listUsers
      responses:
        '200':
          description: List users you can manage
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
  /users/me:
    get:
      tags:
        - User
      description: |
        Retrives the currently authenticated user.
      operationId: getCurrentUser
      responses:
        '200':
          description: Authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '429':
          $ref: '#/components/responses/RateLimit'
  /tasks:
    get:
      tags:
        - Global
      description: Retrieves all tasks
      operationId: listTasks
      responses:
        '200':
          description: Task
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimit'
  /projects:
    get:
      tags:
        - Global
      description: |
        Retrieves a list of all active and archived projects.
      operationId: listProjects
      responses:
        '200':
          description: List of all active and archived projects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '429':
          $ref: '#/components/responses/RateLimit'
  /company:
    get:
      tags:
        - Global
      description: |
        Fetches account-wide company info.
      operationId: fetchCompany
      responses:
        '200':
          description: Account-wide company info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '429':
          $ref: '#/components/responses/RateLimit'
  /organization/status:
    get:
      tags:
        - Organization
      operationId: fetchOrganizationStatus
      description: |
        **ATTENTION:** You need to use the **organization API token** to access this endpoint! This endpoint is for example useful if you want to show the presence/absence status of your users on a dashboard.

        Retrieves today's presence/absence information about all users in your organization.
      responses:
        '200':
          description: Today's presence/absence information about all users in your organization.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationStatus'
        '429':
          $ref: '#/components/responses/RateLimit'
components:
  parameters:
    user_id:
      in: query
      name: user_id
      required: false
      schema:
        type: integer
      example: 4
      description: |
        For these personal API endpoints you can supply an optional user_id parameter. This allows you to make requests in the context of a user you can manage. For example if you are an admin/team leader and would like to retrieve the time entries of another user, use e.g. GET /api/v1/time_entries?date=2016-11-08&user_id=4. To retrieve the list of users you can manage, see Users.

  responses:
    RateLimit:
      description: |
        Our API rate limits are setup per IP and tenant. We allow 4000 requests per hour.

        If the rate limit is being triggered, the response will have HTTP status 429 contain a corresponding JSON structure.
      headers:
        Retry-After:
          description: The Retry-After header will indicate how long the client should wait before trying again.
          schema:
            type: integer
      content:
        application/json:
          example:
            error: 'You sent too many requests, please try again later.'
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The Request is unauthorized, please check your API-Key
      content:
        application/json:
          example:
            error: '401 Unauthorized (300)'
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The Request is authorized, but you don't have access to the Resource
      content:
        application/json:
          example:
            error: '403'
          schema:
            $ref: '#/components/schemas/HttpStatus'
  schemas:
    Pong:
      type: object
      properties:
        pong:
          type: string
          format: date-time
    KeyMetrics:
      type: object
      properties:
        overtime:
          type: string
        overtime_in_secondes:
          type: integer
        vacation:
          type: object
          properties:
            redeemed_days:
              type: number
              format: float
            remaining_days:
              type: number
              format: float
    Timer:
      type: object
      properties:
        date:
          type: string
          format: date
          description: Date when timer was started in yyyy-mm-dd format
        start_time:
          type: string
          description: Start time in hh:mm format
        duration:
          type: string
          format: time
          description: Duration in `hh:mm` format (as displayed in hakuna)
        duration_in_seconds:
          type: integer
          description: Duration in seconds
        note:
          type: string
        user:
          $ref: '#/components/schemas/User'
        task:
          $ref: '#/components/schemas/Task'
        project:
          $ref: '#/components/schemas/Project'
      example:
        date: "2016-11-08"
        start_time: "19:00"
        duration: "02:16"
        duration_in_seconds: 8138
        note: "Did a lot of work."
    NewTimer:
      type: object
      required:
        - task_id
      properties:
        task_id:
          type: integer
        star_time:
          type: string
        duration:
          type: string
        project_id:
          type: integer
        note:
          type: string
    EndTimer:
      type: object
      properties:
        end_time:
          type: string
        duration:
          type: string
    Absence:
      type: object
      properties:
        id:
          type: integer
        start_date:
          type: string
          format: date
          description: Start date in ISO 8601 format
        end_date:
          type: string
          format: date
          description: End date in ISO 8601 format
        first_half_day:
          type: boolean
          description: |
            `true` if this absence covers the the first half day (or the whole day),
            `false` otherwise
        second_half_day:
          type: boolean
          description: |
            `true` if this absence covers the the second half day (or the whole day),
            `false` otherwise
        is_recurring:
          type: boolean
          description: Whether or not this absence is recurring
        weekly_repeat_interval:
          type: integer
          description: The weekly repeat interval (`is_recurring` must be `true`)
          nullable: true
        user:
          $ref: '#/components/schemas/User'
        absence_type:
          $ref: '#/components/schemas/AbsenceType'
      example:
        id: 148
        start_date: "2016-01-06"
        end_date: "2016-01-06"
        first_half_day: true
        second_half_day: false
        is_recurring: false
        weekly_repeat_interval: null
    AbsenceType:
      type: object
      properties:
        id:
          type: integer
          description: The ID to reference this absence type
        name:
          type: string
          description: The name of the absence type
        grants_work_time:
          type: boolean
          description: if `true`, the absence type yields a time credit equaling the planned working time in the absent time frame.
        is_vacation:
          type: boolean
          description: if `true`, the absence will affect the vacation balance.
        archived:
          type: boolean
          description: "`true` if the absence type has been archived"
      example:
        id: 1
        name: "Paid Leave"
        archived: false
        grants_work_time: true
        is_vacation: false
    User:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        team:
          type: array
          items:
            type: string
    Task:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        archived:
          type: boolean
        default:
          type: boolean
      example:
        id: 1,
        name: "Development"
        archived: false,
        default: true
    Project:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        client:
          type: string
        archived:
          type: boolean
        teams:
          type: array
          items:
            type: string
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        buget:
          type: string
        buget_in_seconds:
          type: integer
        buget_is_monthly:
          type: boolean
    TimeEntries:
      allOf:
        - $ref: '#/components/schemas/Timer'
      properties:
        id:
          type: integer
        end_time:
          type: string
    ListOfTimeEntries:
      type: array
      items:
        $ref: '#/components/schemas/TimeEntries'
    NewTimeEntry:
      allOf:
        - $ref: '#/components/schemas/Timer'
      required:
        - date
      properties:
        date:
          type: string
          format: date
        end_time:
          type: string
    UpdateTimeEntry:
      required:
        - end_time
      properties:
        end_time:
          type: string
    Error:
      properties:
        error:
          type: string
      example:
        error: 'You sent too many requests, please try again later.'
    HttpStatus:
      description: Represents a HTTP Status
      properties:
        status:
          type: integer
          example:
            status: 403
    Company:
      properties:
        company_name:
          description: The configured name of the company
          type: string
        duration_format:
          description: The configured display of durations, either `hhmm` or `decimal`
          type: string
          enum: [hhmm, decimal]
        absence_requests_enabled:
          description: Whether or not absence requests module is enabled
          type: boolean
        projects_enabled:
          description: Whether or not the projects module is enabled. This setting changes how the [Time Entry] and [Timer] endpoints have to be used
          type: boolean
        teams_enabled:
          description: Whether or not the teams module is enabled
          type: boolean
    OrganizationStatus:
      properties:
        user:
          $ref: '#/components/schemas/User'
        absent_first_half_day:
          description: |
            `true` if the user is absent in the first half day or the whole day (e.g. on vacation or due to part-time workplan).
          type: boolean
        absent_second_half_day:
          description: |
            `true` if the user is absent in the second half day or the whole day (e.g. on vacation or due to part-time workplan).
          type: boolean
        has_timer_running:
          description: |
            `true` if the user has a timer running
          type: boolean

  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: X-Auth-Token