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:
- bold
- italic
- strikethrough
- links
- code blocks and fences
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. |