NAV
HTTP Shell

Introduction

Welcome to the hakuna API. You can use our API to:

Making Requests

GET /api/v1/ping HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

curl 'https://{example}.hakuna.ch/api/v1/ping' \
  -H 'X-Auth-Token: your-token'

All API responses are delivered in the json format:

{
  "pong": "2016-11-08T13:38:11.086+00:00"
}

Requirements for making requests:

Authentication

To authenticate against hakuna, you need to use an API authentication token and supply it in every request as X-Auth-Token HTTP header.

You can retrieve your personal token by clicking your name on the top right in your hakuna and select “API”.

Personal

Overview

Retrieve key metrics

GET /api/v1/overview HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch
curl -X "GET" "https://{example}.hakuna.ch/api/v1/overview" \
     -H "Accept-Version: v1" \
     -H "X-Auth-Token: your-token"

Response:

{
  "overtime": "470:30",
  "overtime_in_seconds": 1693800,
  "vacation": {
    "redeemed_days": 21.5,
    "remaining_days": 3.5
  }
}

GET /api/v1/overview

Retrieves key numbers about your user, e.g. your current overtime.

Attribute Description
overtime string Overtime in hh:mm format (as displayed in hakuna)
overtime_in_seconds integer Overtime in seconds
vacation hash Vacation information (redeemed and remaining days for the current year)

Timer

{
  "date": "2016-11-08",
  "start_time": "19:00",
  "duration": "02:16",
  "duration_in_seconds": 8138,
  "note": "Did a lot of work.",
  "user": {
    "id": 1,
    "name": "Ursula Schneider",
    "teams": [
      "Administration"
    ]
  },
  "time_type": {
    "id": 1,
    "name": "Arbeit",
    "type": "work",
    "excluded_from_calculations": false
  },
  "project": {
    "id": 3,
    "name": "HR",
    "archived": false
  }
}
Attribute Description
start_time string Start time in hh:mm format
date string Date when timer was started in yyyy-mm-dd format
duration string Duration in hh:mm format (as displayed in hakuna)
duration_in_seconds integer Duration in seconds
note string
user object User object
time_type object Time Type object, must be of type “work”
project object Optional Project object

Get Timer

curl -X "GET" "https://{example}.hakuna.ch/api/v1/timer" \
     -H "Accept-Version: v1" \
     -H "X-Auth-Token: your-token"
GET /api/v1/timer HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

GET /api/v1/timer

Retrieves the timer.

Start Timer

curl -X "POST" "https://{example}.hakuna.ch/api/v1/timer" \
     -H "Accept-Version: v1" \
     -H "X-Auth-Token: your-token" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "note": "Did a lot of work.",
          "project_id": "3",
          "time_type_id": "1"
        }'
POST /api/v1/timer HTTP/1.1
X-Auth-Token: your-token
Content-Type: application/json; charset=utf-8
Host: {example}.hakuna.ch
Content-Length: 65

{
  "note": "Did a lot of work.",
  "project_id": "3",
  "time_type_id": "1"
}

POST /api/v1/timer

Parameter Description
time_type_id required Time type id (see Time Types, must be of type work)
start_time optional Start time in hh:mm format
project_id optional Project id (see Projects)
note optional Note as string

Starts the timer.

Stop Timer

curl -X "PUT" "https://{example}.hakuna.ch/api/v1/timer" \
     -H "X-Auth-Token: your-token"
PUT /api/v1/timer HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

PUT /api/v1/timer

Parameter Description
end_time optional End time in hh:mm format

Stops the timer and creates a corresponding Time Entry.

Cancel Timer

curl -X "DELETE" "https://{example}.hakuna.ch/api/v1/timer" \
     -H "X-Auth-Token: your-token"
DELETE /api/v1/timer HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

DELETE /api/v1/timer

Deletes the timer.

Time Entries

{
  "id": 7043,
  "starts": "2016-10-11T12:00:00+02:00",
  "ends": "2016-10-11T14:00:00+02:00",
  "date": "2016-10-11",
  "start_time": "12:00",
  "end_time": "14:00",
  "duration": "02:00",
  "duration_in_seconds": 7200,
  "note": "This is a long text explaining what I did.",
  "user": {
    "id": 1,
    "name": "Ursula Schneider",
    "teams": [
      "Administration"
    ]
  },
  "time_type": {
    "id": 1,
    "name": "Arbeit",
    "type": "work",
    "excluded_from_calculations": false
  },
  "project": {
    "id": 3,
    "name": "HR",
    "archived": false
  }
}

Time entries are your “work blocks” and can be created either directly or via timer.

Attribute Description
id integer
starts string Start date and time in ISO 8601 format
ends string End date and time in ISO 8601 format
date string Date in ISO 8601 format
start_time string Start time in hh:mm format
end_time string End time in hh:mm format
duration string Duration in hh:mm format (as displayed in hakuna)
duration_in_seconds integer Duration in seconds
note string
user object User object
time_type object Time Type object, must be of type work
project object Optional Project object

List time entries

curl -X "GET" "https://{example}.hakuna.ch/api/v1/time_entries?date=2016-01-05" \
     -H "X-Auth-Token: your-token"
GET /api/v1/time_entries?date=2016-01-05 HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

GET /api/v1/time_entries?date={date}

Parameter Description
date required Date of the time entries (ISO 8601, i.e. yyyy-mm-dd).

Retrieves all time entries on the specific date.

Get a time entry

curl -X "GET" "https://{example}.hakuna.ch/api/v1/time_entries/1838" \
     -H "X-Auth-Token: your-token"
GET /api/v1/time_entries/1838 HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

GET /api/v1/time_entries/{id}

Retrieves the time entry specified by id.

Create a time entry

curl -X "POST" "https://{example}.hakuna.ch/api/v1/time_entries" \
     -H "X-Auth-Token: your-token" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "date": "2016-10-10",
          "start_time": "22:00",
          "end_time": "23:00",
          "note": "This is a long text explaining what I did.",
          "project_id": 1,
          "time_type_id": 1
        }'
POST /api/v1/time_entries HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: {example}.hakuna.ch

{
  "starts": "2016-10-10T22:00:00",
  "ends": "2016-10-10T23:00:00",
  "date": "2016-10-10",
  "start_time": "22:00",
  "end_time": "23:00",
  "note": "This is a long text explaining what I did.",
  "project_id": 1,
  "time_type_id": 1
}

POST /api/v1/time_entries

Parameter Description
date required Date in ISO 8601 format
start_time required Start time in hh:mm format
end_time required End time in hh:mm format
time_type_id required Time type id (see Time Types, must be of type work)
project_id optional Project id (see Projects)
note optional Note as string

Creates a new time entry.

Update a time entry

curl -X "PATCH" "https://{example}.hakuna.ch/api/v1/time_entries/128" \
     -H "X-Auth-Token: your-token" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "end_time": "23:30:00"
        }'
PATCH /api/v1/time_entries/128 HTTP/1.1
X-Auth-Token: your-token
Content-Type: application/json; charset=utf-8
Host: {example}.hakuna.ch

{
  "starts": "2016-10-10T22:00:00",
  "ends": "2016-10-10T23:30:00",
  "date": "2016-10-10",
  "start_time": "22:00",
  "end_time": "23:30",
  "note": "This is a long text explaining what I did.",
  "project_id": 1,
  "time_type_id": 1
}

PATCH /api/v1/time_entries/{id}

Updates the time entry specified by id.

Delete a time entry

curl -X "DELETE" "https://{example}.hakuna.ch/api/v1/time_entries/128" \
     -H "X-Auth-Token: your-token"
DELETE /api/v1/time_entries/128 HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

DELETE /api/v1/time_entries/{id}

Deletes the time entry specified by id.

Absences

{
  "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,
  "user": {
    "id": 1,
    "name": "Ursula Schneider",
    "teams": [
      "Administration"
    ]
  },
  "time_type": {
    "id": 10,
    "name": "Kompensation",
    "type": "absence",
    "excluded_from_calculations": true
  }
}
Attribute Description
id integer
start_date date Start date in ISO 8601 format
end_date date End date in ISO 8601 format
first_half_day boolean true if this absence covers the the first half day (or the whole day), false otherwise
second_half_day boolean true if this absence covers the the second half day (or the whole day), false otherwise
is_recurring boolean Whether or not this absence is recurring
weekly_repeat_interval integer The weekly repeat interval (is_recurring must be true)
user object User object
time_type object Time Type object

List absences

curl -X "GET" "https://{example}.hakuna.ch/api/v1/absences?year=2016" \
     -H "Accept-Version: v1" \
     -H "X-Auth-Token: your-token"
GET /api/v1/absences?year=2016 HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

GET /api/v1/absences?year={year}

Retrieves your absences in the supplied year.

Users

{
  "id": 1,
  "name": "Ursula Schneider",
  "teams": [
    "Administration"
  ]
}
Attribute Description
id integer
name string User name
teams array List of teams this user is a member of

List users you can manage

curl -X "GET" "https://{example}.hakuna.ch/api/v1/users" \
     -H "X-Auth-Token: your-token"
GET /api/v1/users HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

GET /api/v1/users

Retrieves all user you can manage (as admin or team leader). See here how to make requests for these users.

Global

Time Types

{
  "id": 1,
  "name": "Arbeit",
  "type": "work",
  "archived": false,
  "excluded_from_calculations": false
}

Time types are used for categorizing time entries (e.g. work, on-call) and absences (e.g. vacation, sickness).

Attribute Description
id integer The ID to reference this time type
name string The name of the time type
type string work (used for time entries) or absence (used for absences)
archived boolean true if the time type has been archived
excluded_from_calculations boolean if true, the corresponding time type only describes informative entries (e.g. a ‘home office’ absence which does not yield a time credit)

List time types

curl -X "GET" "https://{example}.hakuna.ch/api/v1/time_types" \
     -H "X-Auth-Token: your-token"
GET /api/v1/time_types HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

GET /api/v1/time_types

Retrieves all available time types

Projects

{
  "id": 3,
  "name": "HR",
  "archived": false,
  "teams": null
}

Projects can be assigned to the timer and time entries. This allows to differentiate time spent between different tasks or projects.

Attribute Description
id integer
name string The name of the project
archived boolean true if the project has been archived
teams array Teams assigned to this project, null if the project is global

List projects

curl -X "GET" "https://{example}.hakuna.ch/api/v1/projects" \
     -H "X-Auth-Token: your-token"
GET /api/v1/projects HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

GET /api/v1/projects

Retrieves a list of all active and archived projects.

Organization

Retrieve organization status

curl -X "GET" "https://{example}.hakuna.ch/api/v1/organization/status" \
     -H "Accept-Version: v1" \
     -H "X-Auth-Token: your-token"
GET /api/v1/organization/status HTTP/1.1
X-Auth-Token: your-token
Host: {example}.hakuna.ch

Response:

[
  {
    "user": {
      "id": 1,
      "name": "Ursula Schneider",
      "teams": [
        "Administration"
      ]
    },
    "absent_first_half_day": false,
    "absent_second_half_day": false,
    "has_timer_running": true
  },
  {
    "user": {
      "id": 2,
      "name": "Urs Schneider",
      "teams": [
        "Marketing"
      ]
    },
    "absent_first_half_day": false,
    "absent_second_half_day": true,
    "has_timer_running": false
  }
]

GET /api/v1/organization/status

Retrieves today’s presence/absence information about all users in your organization.

Attribute Description
user object User object
absent_first_half_day boolean 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).
absent_second_half_day boolean 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).
has_timer_running boolean true if the user has a timer running