Tali API v2

Activities

Overview

Activities are the core resource of Tali and the primary way to manage time entries. At it's core, an activity is simply a description of a task performed for a project with it's date and duration.

Defining an optional task category will set billing details for the activity if your project does not define them. Task categories also help to understand how you use your time across multiple projects.

Reported vs Recorded Time

An important concept to grasp is the idea of "recorded" and "reported" time. Every activity contains separate records that persist the actual start and stop times that the activity actually occured and can't be editted.

Recorded time helps to understand the timekeepers actual patterns and habits whereas reported time allows the user to edit the overall duration and date of the activity as it relates to billing and accounting.

Activity Model

{
  "id": "5b8701a41035549bb57b67e9",
  "created_at": "2018-08-29T20:27:16.405Z",
  "status": "complete",
  "project": {
    "id": "5b85933b1984af0c1bdf0174",
    "name": "Comprehensive Testing - Subject: 1498"
  },
  "category": {
    "id": "5b85933b1984af0c1bdf0161",
    "name": "Non-billable"
  },
  "description": "Explored enrichment center",
  "date": "2018-08-29T20:27:16.405Z",
  "duration": 3600, // seconds
  "tags": ["Development", "Companion Cube"],
  "records": [{
    "id": "5b8701a41035549bb57b67ea",
    "status": "complete",
    "type": "time",
    "start_time": "2018-08-29T19:27:16.407Z",
    "stop_time": "2018-08-29T20:27:16.405Z",
    "quantity": 3600,
    "units": "seconds"
  }]
}

Create Activity

POST /api/v2/activities HTTP/1.1

{
  "source": "Alexa",
  "description": "Explored enrichment center", // required
  "project_id": "5b85933b1984af0c1bdf0174", // required
  "project_name": "Comprehensive Testing – Subject: 1498",
  "category_id": "5b85933b1984af0c1bdf0161",
  "tags": ["Companion Cube", "Turret"],
  "date": "2018-01-15T12:00:00+08:00",
  "duration": 3600
}

Source

Including a source helps us determine what kind of post-processing to do on the activity and helps to improve our voice recognition going forward. Values such as Alexa, Cortana, and likewise are appropriate.

Project ID vs Project Name

It's advised to use the Project Search endpoint first to find the project_id. If you're lazy, and don't mind making a big mess, you can conditionally send a project_name instead and the API will do the search, find the closest match OR create a new project. See how this can create a big mess quickly?

Date and Duration

If you define a duration when creating an activity it will be marked as "completed" – else it will assume it is a "pending" activity to be treated like a running timer. Further, defining the optional date along with duration will log a completed activity.

Stop/Resume Activity

This is the preferred method to stop a running timer (ie. pending activity).

POST /api/v2/activities/{id}/stop HTTP/1.1

POST /api/v2/activities/{id}/resume HTTP/1.1

Note

Don't use the update endpoint to stop a running timer – use this endpoint.

Update Activity

PUT /api/v2/activities/{id} HTTP/1.1

{
  "description": "Searching for the cake",
  "project_id": "5b85933b1984af0c1bdf0174",
  "category_id": "5b85933b1984af0c1bdf0161",
  "tags": ["Cake", "Lie"],
  "date": "2018-08-29T20:27:16.405Z",
  "duration": 2400
}

List Activities

GET /api/v2/activities HTTP/1.1

Optional Query Parameters

{
  "per_page": 25,
  "page": 1,
  "start_date": "2018-01-01",
  "end_date": "2018-02-01",
  "filter": "status:complete",
  "order_by": "date"
}

Single Activity

GET /api/v2/activities/{id} HTTP/1.1

Delete/Recover Activity

DELETE /api/v2/activities/{id} HTTP/1.1

POST /api/v2/activities/{id}/recover HTTP/1.1

Group Activities

Take two or more activities and merge them in to one. They will share the same project and date, and each description will be concatenated into the master description. If you regret it, you can always ungroup it using the endpoint below.

POST /api/v2/activities/group HTTP/1.1

{
  "activity_ids": [
    "5b85933b1984af0c1bdf0174", 
    "5b85933b1984af0c1bdf0161"
  ]
}

Ungroup Activity

POST /api/v2/activities/{id}/ungroup HTTP/1.1

← Categories →