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 the desktop application, head to settings, "Access tokens" section, and create a new access token.

Lunatask API expects the API key to be included in all API requests in Authorization header.

Authorization: bearer <access-token>

Encryption

All user data in your Lunatask account is end-to-end encrypted and is never transmitted out of the 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 the 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, in minutes)
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 updated
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 The source specified when creating the task (optional)
source_id The source_id specified when creating the task (optional)

If no source is 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 Area ID of the list where the task should be created (UUID, can be found in the desktop application in the area settings)
name The name of the task (optional, but impractical if empty)
note The note attached to task (optional, formatted in markdown)
status The status of the task (optional, see possible values below)
motivation The motivation value of the task (optional, see possible values below)
estimate The estimate of the task (optional, in minutes)
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 The 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. The API does not enforce uniqueness of source/source_id.

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 note (formatted in Markdown)

Markdown support

See the list of supported formatting in our Markdown Reference.

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 updates the status 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
status New value for task status
previous_status Previous value for task status (optional, it will be automatically assigned if not provided, 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 a 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" ISO-8601 formatted time

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 by setting the priority value to 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 by 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.