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