# Tasks API

## Aurinko Tasks API

***

The Aurinko Tasks API is part of the Aurinko Unified API platform, enabling developers to integrate task management functionalities effortlessly into their applications. This API abstracts the differences between task management services such as Google Tasks, Microsoft To Do, and Outlook Tasks, offering a consistent interface for task-related operations.

### Functionality

***

The Aurinko Tasks API offers robust functionalities for managing tasks:

* **Create Tasks:** Create new tasks with various attributes like titles, descriptions, due dates, priorities, and custom fields, depending on the capabilities of the underlying service.
* **Read Tasks:** Retrieve details of existing tasks, including titles, statuses, due dates, and completion status.
* **Update Tasks:** Modify existing tasks by updating attributes like titles, descriptions, due dates, and priorities, or by marking tasks as completed or uncompleted.
* **Delete Tasks:** Permanently remove tasks from the user’s account.
* **Lists:** Manage task lists, including creating, reading, updating, and deleting lists, subject to the capabilities of the underlying service.

### Aurinko account setup

***

First, create your account in the [Aurinko portal](https://app.aurinko.io/), then follow the guide to [get your developer API keys](https://docs.aurinko.io/getting-started/get-your-developer-api-keys).

### Tasks API Endpoints

***

#### Task lists

Each account connected to Aurinko can have zero or more [task lists](https://apirefs.aurinko.io/#tag/TaskLists), and each task list contains a collection of individual tasks.

#### Tasks

[Tasks](https://apirefs.aurinko.io/#tag/Tasks) are objects within a task list that generally support all features and attributes of modern task management apps like task subject, description, priority, due date, status, etc. Aurinko supports key task functionality: creating and modifying tasks.

#### **Synchronization**

[Tasks sync](https://apirefs.aurinko.io/#tag/TaskSync) methods allow developers to implement incremental synchronization of task list data in a uniform manner across different providers. Aurinko supports requesting updated as well as deleted tasks.

### Tasks sync quickstart

***

#### **Start a new sync**

A new sync needs to be provisioned by calling the *sync-start* method <mark style="color:red;">`/calendars/{calendarId}/sync`</mark> The sync is available per task list, hence {taskListId} or *default*. <mark style="color:red;">`skipCompletedBeforeDate`</mark> applies for the initial full load.

```bash
curl -X POST -H 'Authorization: Bearer <access token>' 
    -G https://api.aurinko.io/v1/tasklists/default/sync[?awaitReady=false]
    -d skipCompletedBeforeDate='2023-05-29T10:58:27Z'
```

The Aurinko platform will initialize all necessary internal resources and let you know when it's ready to serve data. The response should look like this:

```json
{
    "syncUpdatedToken": "asdfghjklpoiuytrew",
    "syncDeletedToken": "zxcvbnmlkjhgfdsaq",
    "ready": true
}
```

If the response shows <mark style="color:red;">`ready: false`</mark> call the *sync-start* method again. Once the sync is ready you will get delta tokens <mark style="color:red;">`syncUpdatedToken`</mark>, <mark style="color:red;">`syncDeletedToken`</mark> and can start loading updated and deleted events.

#### **Initial full sync**

Initial requests <mark style="color:red;">`/tasklists/{taskListId}/sync/updated`</mark> and <mark style="color:red;">`/tasklists/{taskListId}/sync/deleted`</mark> are equivalent to a full sync with the <mark style="color:red;">`skipCompletedBeforeDate`</mark> filter, plus loading all updated tasks (deleted tasks) since the sync start.

```bash
curl -X GET -H 'Authorization: Bearer <access_token>'
    -G https:/api.aurinko.io/v1/tasklists/default/sync/updated
    -d deltaToken='{syncUpdatedToken}'
```

*Response:*

```json
{
    "nextPageToken": "string",
    "nextDeltaToken": "string",
    "records": [{...}]
}
```

Continue loading pages using provided <mark style="color:red;">`nextPageToken`</mark> until you find another <mark style="color:red;">`nextDeltaToken`</mark>.

```bash
curl -X GET -H 'Authorization: Bearer <access_token>'
    -G https:/api.aurinko.io/v1/tasklists/default/sync/updated
    -d pageToken='{nextPageToken}'
```

#### **Incremental sync**

A new deltaToken (nextDeltaToken in response) is provided for loading tasks that have been modified/deleted since the last *sync-updated/sync-deleted* request. In cases where a large number of tasks have changed since the last incremental sync request, you may find a <mark style="color:red;">`nextPageToken`</mark> instead of the <mark style="color:red;">`nextDeltaToken`</mark> in the response. Continue loading pages using the provided <mark style="color:red;">`nextPageToken`</mark> until you find another <mark style="color:red;">`nextDeltaToken`</mark>.

### Other examples

***

#### Task lists

To view a list of all task lists a user has access to, make a request to the <mark style="color:red;">`/tasklists`</mark> endpoint.

```bash
curl -H 'Authorization: Bearer <access_token>'
    -X GET https:/api.aurinko.io/v1/tasklists
```

You can get information for a single task list by providing the appropriate list id, <mark style="color:red;">`/tasklists/{id}`</mark>. You can use *default* as an ID to get your default list.

```bash
curl -H 'Authorization: Bearer <access_token>'
    -X GET https:/api.aurinko.io/v1/tasklists/default
```

#### Tasks

To get a list of tasks from a list, make a request to the <mark style="color:red;">`/tasklists/{id}/tasks`</mark> endpoint.

```bash
curl -X POST -H 'Authorization: Bearer <access_token>'
    -G https:/api.aurinko.io/v1/tasklists/default/tasks
```

To create a new task POST json payload to <mark style="color:red;">`/tasklists/{id}/tasks`</mark> endpoint:

```bash
curl -H 'Authorization: Bearer <access_token>'
    -X POST https:/api.aurinko.io/v1/tasklists/default/tasks
    -d '{
    "title": "My Task",
    "parentId": "string",
    "notes": "Task description...",
    "status": "notStarted",
    "importance": "low",
    "due": "2024-10-24T14:00:00Z",
    "startDateTime": "2024-10-23T14:00:00Z",
}'
```

Use PATCH request to update existing tasks:

```bash
curl -X POST -H 'Authorization: Bearer <access_token>'
    https:/api.aurinko.io/v1/tasklists/default/tasks/{taskId}
    -d '{
    -d '{
    "title": "My Task (updated)",
    "parentId": "string",
    "notes": "Task description...",
    "status": "notStarted",
    "importance": "high",
    "due": "2024-10-24T14:00:00Z",
    "startDateTime": "2024-10-23T14:00:00Z",
}'
```