NAV
ruby

Introduction

Welcome to the Lunatask API! You can use our API to manage data in your Lunatask account, build integrations with your favorite tools, or perform one-time data imports.

Authentication

To test the authentication, use this code:

require 'rest-client'

RestClient.get('https://api.lunatask.app/v1/ping', { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "message": "pong"
}

In order to communicate with Lunatask API you must first generate an Access Token. Make sure you have the latest version of Lunatask desktop application, head to Settings, Access Tokens section and create a new access token.

Lunatask API expects for the API key to be included in all API requests to the server in Authorization header that looks like the following:

Authorization: bearer <access-token>

Encryption

All user data in your Lunatask account is end-to-end encrypted and is never transmitted out of Lunatask desktop application or stored on our servers in a plain readable form. The only way to decrypt the user data is by using your master password inside Lunatask desktop application. Access tokens do replace your master password.

Tasks API

Task entity

The JSON representation of Task entity might look like this:

{
  "id": "066b5835-184f-4fd9-be60-7d735aa94708",
  "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
  "status": "next",
  "previous_status": "later",
  "estimate": 10,
  "priority": 0,
  "motivation": "unknown",
  "sources": [
    {
      "source": "github",
      "source_id": "123"
    }
  ],
  "scheduled_on": null,
  "completed_at": null,
  "created_at": "2021-01-10T10:39:25Z",
  "updated_at": "2021-01-10T10:39:25Z",
  "deleted_at": null
}

All operations on Tasks API return the latest representation of Task entity.

Attribute Description
id The ID of the task (UUID)
area_id The ID of the area of life the task belongs in (UUID)
status Current status of the task (see possible values below)
previous_status Previous status of the task (optional, see possible values below)
estimate Current value of the estimate (optional, see possible values below)
priority Current value of the priority (see possible values below)
motivation Current value of the motivation (see possible values below)
sources Array of references to data records in external systems (see usage below)
scheduled_on ISO-8601 formatted date when the task is scheduled on (optional)
completed_at ISO-8601 formatted time when the task was completed (optional)
created_at ISO-8601 formatted time when the task was created
updated_at ISO-8601 formatted time when the task was last created
deleted_at ISO-8601 formatted time when the task was last deleted (optional)

Retrieve all tasks

require 'rest-client'

RestClient.get('https://api.lunatask.app/v1/tasks', { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "tasks": [
    {
      "id": "066b5835-184f-4fd9-be60-7d735aa94708",
      "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
      "status": "next",
      "previous_status": "later",
      "estimate": 10,
      "priority": 0,
      "motivation": "unknown",
      "sources": [
        {
          "source": "github",
          "source_id": "123"
        }
      ],
      "scheduled_on": null,
      "completed_at": null,
      "created_at": "2021-01-10T10:39:25Z",
      "updated_at": "2021-01-10T10:39:25Z",
      "deleted_at": null
    },
    {
      "id": "0e0cff5c-c334-4a24-b15a-4fca6cfbf25f",
      "area_id": "f557287e-ae43-4472-9478-497887362dcb",
      "status": "later",
      "previous_status": null,
      "estimate": 120,
      "priority": 0,
      "motivation": "unknown",
      "sources": [],
      "scheduled_on": null,
      "completed_at": null,
      "created_at": "2021-01-10T10:39:26Z",
      "updated_at": "2021-01-10T10:39:26Z",
      "deleted_at": null
    }
  ]
}

This endpoint retrieves all tasks in your account. You can narrow down the data returned by filtering on the source of the task (see the section about creating tasks for more information).

HTTP Request

GET https://api.lunatask.app/v1/tasks

Query Parameters

Parameter Description
source source specified when creating the task (optional)
source_id source_id specified when creating the task (optional)

If no source specified, all tasks are returned.

Retrieve a specific task

require 'rest-client'

RestClient.get('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "next",
    "previous_status": "later",
    "estimate": 10,
    "priority": 0,
    "motivation": "unknown",
    "sources": [
      {
        "source": "github",
        "source_id": "123"
      }
    ],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T10:39:25Z",
    "deleted_at": null
  }
}

This endpoint retrieves a specific task.

HTTP Request

GET https://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to retrieve

Creating a task

require 'rest-client'

RestClient.post('https://api.lunatask.app/v1/tasks', { name: 'My task', source: 'github', source_id: '123', area_id: '11b37775-5a34-41bb-b109-f0e5a6084799' }, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "later",
    "previous_status": null,
    "estimate": null,
    "priority": 0,
    "motivation": "unknown",
    "sources": [
      {
        "source": "github",
        "source_id": "123"
      }
    ],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T10:39:25Z",
    "deleted_at": null
  }
}

This endpoint creates a new task.

HTTP Request

POST https://api.lunatask.app/v1/tasks

Body Parameters

Parameter Description
area_id The ID of the area of life the task belongs in (UUID, can be found in the desktop application in Area settings)
name Name of the task (optional, but impractical if empty)
note Note attached to task (optional, formatted in markdown)
status Status of the task (optional, see possible values below)
motivation Motivation of the task (optional, see possible values below)
estimate Estimate of the task (optional, see possible values below)
priority Priority of the task (optional, see possible values below)
scheduled_on Date when the task is scheduled on (optional, see possible values below)
completed_at Time when the task was completed (optional, see possible values below)
source Identification of external system where the task is coming from (optional, e.g. "github")
source_id ID of the record in the external system (optional, e.g. "123")

source/source_id attributes are for later lookup of previously created tasks when updating without a need to remember task IDs in Lunatask. The API does not enforce uniqueness of source/source_id though.

When creating a task given there's already an existing not completed task in the same area with the same source/source_id, the endpoint will return 204 No Content without creating a duplicate.

Update a specific task

require 'rest-client'

RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', {}, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "later",
    "previous_status": null,
    "estimate": null,
    "priority": null,
    "motivation": "unknown",
    "sources": [],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T10:39:25Z",
    "deleted_at": null
  }
}

This endpoint updates a specific task.

HTTP Request

PUT https://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to update

Body Parameters

See common use cases below. All the use cases use this single update endpoint and you can update as many attributes as you wish in one API call.

Set name or note of a specific task

require 'rest-client'

RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { name: 'New name', note: 'New note' }, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "later",
    "previous_status": null,
    "estimate": null,
    "priority": null,
    "motivation": "unknown",
    "sources": [],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T12:52:04Z",
    "deleted_at": null
  }
}

This endpoint updates name or note of a specific task.

HTTP Request

PUT http://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to update

Body Parameters

Parameter Description
name New value for task name
note New value for task name (formatted in markdown)

Markdown support

Lunatask currently supports a subset of Markdown formatting:

To support additional formatting, please, visit our idea voting portal and vote for the corresponding features.

Set status of a specific task

require 'rest-client'

RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { status: 'started' }, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "started",
    "previous_status": "later",
    "estimate": null,
    "priority": null,
    "motivation": "unknown",
    "sources": [],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T12:52:04Z",
    "deleted_at": null
  }
}

This endpoint deletes a specific task.

HTTP Request

PUT http://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to update

Body Parameters

Parameter Description
status New value for task status
previous_status Previous value for task status (optional, if not provided, will be automatically assigned, cannot be the same as new status)

Allowed values

Value Description
"later" Represents later status (default)
"next" Represents next status
"started" Represents started status
"waiting" Represents waiting status
"completed" Represents completed status

Mark a specific task as complete

require 'rest-client'

RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { status: 'completed' }, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "completed",
    "previous_status": "started",
    "estimate": null,
    "priority": null,
    "motivation": "unknown",
    "sources": [],
    "scheduled_on": null,
    "completed_at": "2021-01-10T12:52:04Z",
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T12:52:04Z",
    "deleted_at": null
  }
}

This endpoint marks a specific task as complete.

HTTP Request

PUT https://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to update

Body Parameters

Parameter Value Description
status "completed" New value for task status
completed_at "2012-04-23T18:25:43.511Z" Timestamp of the action in any commonly supported format, we'll try to do our best to parse it (optional, if not provided, the current time will be used)

Schedule a specific task

require 'rest-client'

RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { status: 'later', scheduled_on: "2021-02-01" }, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "later",
    "previous_status": "started",
    "estimate": null,
    "priority": null,
    "motivation": "unknown",
    "sources": [],
    "scheduled_on": "2021-02-01",
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T12:52:04Z",
    "deleted_at": null
  }
}

This endpoint schedules a specific task to the future date.

HTTP Request

PUT https://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to update

Body Parameters

Parameter Value Description
status "later" New value for task status
scheduled_on "2012-04-23" Date of the action in any commonly supported format, we'll try to do our best to parse it (if full timestamp is sent the time part will be stripped)

Allowed Parameters

We don't validate whether scheduled_on is a future or past date. Setting scheduled_on in the past will not break anything, but the value will be cleared when the data is synced to a running Lunatask desktop application.

To clear the schedule, set scheduled_on to null.

Set estimate of a specific task

require 'rest-client'

RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { estimate: 60 }, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "later",
    "previous_status": null,
    "estimate": 60,
    "priority": 0,
    "motivation": "unknown",
    "sources": [],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T12:52:04Z",
    "deleted_at": null
  }
}

This endpoint updates the estimate of a specific task.

HTTP Request

PUT https://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to update

Body Parameters

Parameter Description
estimate Integer value of new estimate (in minutes) or null to clear the estimate.

Set priority of a specific task

require 'rest-client'

RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { priority: 2 }, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "later",
    "previous_status": null,
    "estimate": null,
    "priority": 2,
    "motivation": "unknown",
    "sources": [],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T12:52:04Z",
    "deleted_at": null
  }
}

This endpoint updates the priority of a specific task.

HTTP Request

PUT https://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to update

Body Parameters

Parameter Description
priority New value for priority

Allowed values

Priority is represented as an integer value in range -2..2.

Value Description
2 Highest priority
1 Low priority
0 Normal priority (default)
-1 Low priority
-2 Lowest priority

Clearing the priority is done via settiing the priority value of 0.

Set motivation of a specific task

require 'rest-client'

RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { motivation: 'must' }, { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "later",
    "previous_status": null,
    "estimate": null,
    "priority": 0,
    "motivation": "must",
    "sources": [],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T12:52:04Z",
    "deleted_at": null
  }
}

This endpoint updates the motivation of a specific task.

HTTP Request

PUT https://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to update

Body Parameters

Parameter Description
motivation New value for motivation

Allowed values

Value Description
"must" Must motivation
"should" Should motivation
"want" Want motivation
"unknown" Unknown motivation (default)

Clearing the motivation is done via assigning the motivation value of "unknown".

Delete a specific task

require 'rest-client'

RestClient.delete('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { Authorization: "bearer #{access_token}" })

The above command returns JSON structured like this:

{
  "task": {
    "id": "066b5835-184f-4fd9-be60-7d735aa94708",
    "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799",
    "status": "later",
    "previous_status": null,
    "estimate": null,
    "priority": 0,
    "motivation": "unknown",
    "sources": [],
    "scheduled_on": null,
    "completed_at": null,
    "created_at": "2021-01-10T10:39:25Z",
    "updated_at": "2021-01-10T12:52:04Z",
    "deleted_at": "2021-01-10T12:52:04Z"
  }
}

This endpoint deletes a specific task.

HTTP Request

DELETE https://api.lunatask.app/v1/tasks/<ID>

URL Parameters

Parameter Description
ID The ID of the task to delete

Errors

The Lunatask API uses the following error codes:

Code Meaning
401 Unauthorized -- Your access token is missing, is wrong, or was revoked.
404 Not Found -- The specified entity could not be found.
422 Unprocessable Entity -- The provided entity is not valid.
500 Internal Server Error -- We encountered a problem processing your request and have been notified. Try again later. If the problem persists, please, contact us.
503 Service Unavailable -- We're temporarily offline for maintenance. Please, try again later.