Introduction

The Tali API v2 is the best way to interact with the Tali Time Tracking Platform. The API is designed with a familiar REST interface around our key resources.

This documentation will remain evergreen until we feel confident that it's accurate to our API. In the meantime, if you find an error, please let us know at [email protected].

Request Access

Ready to build something great on the Tali platform? Contact us at [email protected].

Let us know about your project, and we'll provide you with the client_id and client_secret that you'll need for authorizing users.

Usage

Example Request

Every request will require an authorization header with an access token. See Authorization for details on obtaining an access token.

GET /api/v2/users/me HTTP/1.1
Host: www.telltali.com
Accept: application/json
Authorization: Bearer <access_token>

Example Response

Every response will be returned as JSON containing meta and data keys. The resource data is returned in data as either an object, or an array of objects.

{
  "meta": {
    "self": "/users/me"
  },
  "data": {
    "id": "5b7b26d142f87d2dd2518a9f",
    "created_at": "2018-08-20T20:38:41.040Z",
    "email": "[email protected]",
    "first_name": "Matt",
    "last_name": "Hoiland"
  }
}

Pagination

For endpoints that return multiple resources, the meta object will contain many goodies to aid in easy pagination. You can think of this as our crude attempt at a HATEOAS type of system.

{
  "meta": {
    "self": "/api/v2/activity?page=2&per_page=10",
    "next": "/api/v2/activity?page=3&per_page=10",
    "prev": "/api/v2/activity?page=1&per_page=10",
    "count": 10,
    "total": 35
    "pages": 4,
    "page": 2
  },
  "data": [ ... ]
}

Errors

The Tali API v2 uses this subset of HTTP status codes.

Code Description
200 OK - It worked and here's proof.
201 Created - New resource created.
204 No Content - It worked but there's no proof.
304 Not Modified - You tried to update something that hasn't changed.
400 Bad Request - Whoops. You probably made a syntax error.
401 Unauthorized - Missing or expired access token.
403 Forbidden - Valid access token, but for the wrong user.
404 Not Found - Unknown endpoint.
410 Gone - Ustacould, now it ain't.
500 Internal Server Error - Tali broke. You win. Contact us.