# 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 [api@telltali.com](mailto:api@telltali.com).

## Request Access

Ready to build something great on the Tali platform? Contact us at [api@telltali.com](mailto:api@telltali.com).

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](/content/api/v2/docs/authorization.html) for details on obtaining an access token.

```http
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.

```json
{
  "meta": {
    "self": "/users/me"
  },
  "data": {
    "id": "5b7b26d142f87d2dd2518a9f",
    "created_at": "2018-08-20T20:38:41.040Z",
    "email": "hoi@threematts.com",
    "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](https://spring.io/understanding/HATEOAS) type of system.

```json
{
  "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](mailto:api@telltali.com). |

[Authorization](/content/api/v2/docs/authorization.html)