# Table of Contents - [Update note | Lunatask](#update-note-lunatask) - [Track activity | Lunatask](#track-activity-lunatask) - [Retrieve all notes | Lunatask](#retrieve-all-notes-lunatask) - [API | Lunatask](#api-lunatask) - [Create note | Lunatask](#create-note-lunatask) - [Create entry | Lunatask](#create-entry-lunatask) - [Delete note | Lunatask](#delete-note-lunatask) - [Create note | Lunatask](#create-note-lunatask) - [Delete person | Lunatask](#delete-person-lunatask) - [Authentication | Lunatask](#authentication-lunatask) - [Retrieve person | Lunatask](#retrieve-person-lunatask) - [Create person | Lunatask](#create-person-lunatask) - [Create task | Lunatask](#create-task-lunatask) - [Retrieve all people | Lunatask](#retrieve-all-people-lunatask) - [Retrieve all tasks | Lunatask](#retrieve-all-tasks-lunatask) - [Delete task | Lunatask](#delete-task-lunatask) - [Entities | Lunatask](#entities-lunatask) - [Update task | Lunatask](#update-task-lunatask) - [Retrieve task | Lunatask](#retrieve-task-lunatask) --- # Update note | Lunatask [Skip to main content](https://lunatask.app/api/notes-api/update#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint updates a specific note. HTTP Request[​](https://lunatask.app/api/notes-api/update#http-request "Direct link to HTTP Request") ------------------------------------------------------------------------------------------------------ `PUT https://api.lunatask.app/v1/notes/` URL Parameters[​](https://lunatask.app/api/notes-api/update#url-parameters "Direct link to URL Parameters") ------------------------------------------------------------------------------------------------------------ | Parameter | Description | | --- | --- | | `id` | The ID of the note to update | Body Parameters[​](https://lunatask.app/api/notes-api/update#body-parameters "Direct link to Body Parameters") --------------------------------------------------------------------------------------------------------------- The attributes you want to update – only `name`, `content`, `notebook_id`, and `date_on` (ISO-8601 formatted) are available for updating. info Updating a note replaces its entire content when new `content` is provided. Because your data is end-to-end encrypted and can’t be decrypted by our servers, appending text to existing notes isn’t possible. Example in Ruby[​](https://lunatask.app/api/notes-api/update#example-in-ruby "Direct link to Example in Ruby") --------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'payload = { content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit...' }RestClient.put('https://api.lunatask.app/v1/notes/5999b945-b2b1-48c6-aa72-b251b75b3c2e', payload.to_json, { Authorization: "bearer #{access_token}", "Content-Type": 'application/json' }) Response[​](https://lunatask.app/api/notes-api/update#response "Direct link to Response") ------------------------------------------------------------------------------------------ The request returns JSON structured like this: { "note": { "id": "5999b945-b2b1-48c6-aa72-b251b75b3c2e", "notebook_id": "d1ff35f5-6b25-4199-ab6e-c19fe3fe27f1", "date_on": null, "sources": [], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z", }} * [HTTP Request](https://lunatask.app/api/notes-api/update#http-request) * [URL Parameters](https://lunatask.app/api/notes-api/update#url-parameters) * [Body Parameters](https://lunatask.app/api/notes-api/update#body-parameters) * [Example in Ruby](https://lunatask.app/api/notes-api/update#example-in-ruby) * [Response](https://lunatask.app/api/notes-api/update#response) --- # Track activity | Lunatask [Skip to main content](https://lunatask.app/api/habits-api/track-activity#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint records activity for a specific habit on a given date. HTTP Request[​](https://lunatask.app/api/habits-api/track-activity#http-request "Direct link to HTTP Request") --------------------------------------------------------------------------------------------------------------- `POST https://api.lunatask.app/v1/habits//track` URL Parameters[​](https://lunatask.app/api/habits-api/track-activity#url-parameters "Direct link to URL Parameters") --------------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `id` | The ID of the habit (UUID, can be found in our apps in the habit settings) | Body Parameters[​](https://lunatask.app/api/habits-api/track-activity#body-parameters "Direct link to Body Parameters") ------------------------------------------------------------------------------------------------------------------------ | Parameter | Description | | --- | --- | | `performed_on` | ISO-8601 formatted date when the activity was performed (required) | Example in Ruby[​](https://lunatask.app/api/habits-api/track-activity#example-in-ruby "Direct link to Example in Ruby") ------------------------------------------------------------------------------------------------------------------------ require 'rest-client'access_token = 'xxx'RestClient.post( 'https://api.lunatask.app/v1/habits/25b8ad7e-a89b-4f05-8173-83fcd2e21ae2/track', { performed_on: '2024-08-26' }.to_json, { Authorization: "bearer #{access_token}", "Content-Type": 'application/json' }) Response[​](https://lunatask.app/api/habits-api/track-activity#response "Direct link to Response") --------------------------------------------------------------------------------------------------- The request returns JSON structured like this: { "status": "ok"} In case of missing or malformed date provided: { "status": "error", "message": "performed_on date missing or is not a valid ISO-8601 formatted date"} * [HTTP Request](https://lunatask.app/api/habits-api/track-activity#http-request) * [URL Parameters](https://lunatask.app/api/habits-api/track-activity#url-parameters) * [Body Parameters](https://lunatask.app/api/habits-api/track-activity#body-parameters) * [Example in Ruby](https://lunatask.app/api/habits-api/track-activity#example-in-ruby) * [Response](https://lunatask.app/api/habits-api/track-activity#response) --- # Retrieve all notes | Lunatask [Skip to main content](https://lunatask.app/api/notes-api/list#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint retrieves all notes in your account. You can narrow down the data returned by filtering on the source of the note (see our article on creating notes for more information). HTTP Request[​](https://lunatask.app/api/notes-api/list#http-request "Direct link to HTTP Request") ---------------------------------------------------------------------------------------------------- `GET https://api.lunatask.app/v1/notes` Query Parameters[​](https://lunatask.app/api/notes-api/list#query-parameters "Direct link to Query Parameters") ---------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `source` | The `source` specified when creating the note (optional) | | `source_id` | The `source_id` specified when creating the note (optional) | If no source is specified, all note are returned. Example in Ruby[​](https://lunatask.app/api/notes-api/list#example-in-ruby "Direct link to Example in Ruby") ------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.get('https://api.lunatask.app/v1/notes', { Authorization: "bearer #{access_token}" }) Response[​](https://lunatask.app/api/notes-api/list#response "Direct link to Response") ---------------------------------------------------------------------------------------- The request returns JSON structured like this: { "notes": [ { "id": "5999b945-b2b1-48c6-aa72-b251b75b3c2e", "notebook_id": "d1ff35f5-6b25-4199-ab6e-c19fe3fe27f1", "date_on": null, "sources": [ { "source": "evernote", "source_id": "352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7" } ], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z", }, { "id": "2ca8eb4c-4825-47e4-84de-2bbe0017b6c0", "notebook_id": "fc2aa380-3320-4525-8611-7332d5060478", "date_on": null, "sources": [], "created_at": "2021-01-13T08:12:25Z", "updated_at": "2021-01-15T10:39:25Z", } ]} * [HTTP Request](https://lunatask.app/api/notes-api/list#http-request) * [Query Parameters](https://lunatask.app/api/notes-api/list#query-parameters) * [Example in Ruby](https://lunatask.app/api/notes-api/list#example-in-ruby) * [Response](https://lunatask.app/api/notes-api/list#response) --- # API | Lunatask [Skip to main content](https://lunatask.app/api/overview#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page You can use our API to manage data in your Lunatask account, build powerful automations, integrations with your favorite tools, or perform one-time data imports. Encryption[​](https://lunatask.app/api/overview#encryption "Direct link to Encryption") ---------------------------------------------------------------------------------------- All text entered into Lunatask is end-to-end encrypted and never transmitted out of our apps or stored on our servers in a plain readable form. The only way to decrypt such data is by using your master password inside our client apps. Access tokens don’t replace your master password. caution **Lunatask API doesn’t provide a way to read end-to-end encrypted data**. Names of entities, notes, and other encrypted data can’t be read using the API, therefore the API doesn’t return such data in its responses. However, updating this data is allowed as well as creating new entities. To export your data out of the app, use our [data export](https://lunatask.app/docs/features/import-export) feature instead. Info Your data gets encrypted as soon as it reaches our servers and we keep no logs. You can learn more about our approach to encryption and privacy [here](https://lunatask.app/docs/getting-started/privacy) . Webhooks[​](https://lunatask.app/api/overview#webhooks "Direct link to Webhooks") ---------------------------------------------------------------------------------- We often get asked about webhooks and allowing sharing or syncing of data with other tools this way. That said, Lunatask is an [end-to-end encrypted app](https://lunatask.app/docs/getting-started/privacy) , and as such, Lunatask servers don’t have access to your data – therefore, they naturally can’t share it with other tools. Info This is a common limitation of encrypted apps – encryption and sharing don’t usually work well together. On one hand, you want your data to be secure and accessible only to you. On the other, you want to share it with other systems via our servers, APIs, or webhooks. That’s where the inherent conflict comes in. Errors[​](https://lunatask.app/api/overview#errors "Direct link to Errors") ---------------------------------------------------------------------------- The API uses the following error codes: | Code | Meaning | | --- | --- | | 400 | Bad Request -- Provided parameters are invalid, malformed, or missing. | | 401 | Unauthorized -- Your access token is missing, is wrong, or was revoked. | | 402 | Limit Reached on Free Plan -- A subscription is required to continue. | | 404 | Not Found -- The specified entity couldn’t be found. | | 422 | Unprocessable Entity -- The provided entity isn’t valid. Check what data you’re sending. | | 500 | Internal Server Error -- We encountered a problem processing your request and have been notified. Please, try again later. If the problem persists, please [contact us](https://lunatask.app/contact)
. | | 503 | Service Unavailable -- We’re temporarily offline for maintenance. Please, try again later. | | 524 | Request Timed Out -- Please, try again. | * [Encryption](https://lunatask.app/api/overview#encryption) * [Webhooks](https://lunatask.app/api/overview#webhooks) * [Errors](https://lunatask.app/api/overview#errors) --- # Create note | Lunatask [Skip to main content](https://lunatask.app/api/notes-api/create#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint creates a new note. HTTP Request[​](https://lunatask.app/api/notes-api/create#http-request "Direct link to HTTP Request") ------------------------------------------------------------------------------------------------------ `POST https://api.lunatask.app/v1/notes` Body Parameters[​](https://lunatask.app/api/notes-api/create#body-parameters "Direct link to Body Parameters") --------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `notebook_id` | The Notebook ID of the notebook where the note should be created (optional, can be found in our apps in the notebook settings) | | `name` | The name of the note (optional, but impractical if empty) | | `content` | The content of the note (optional, but impractical if empty, formatted in Markdown) | | `date_on` | A date assigned to the note (optional, ISO-8601 formatted) | | `source` | Identification of external system where the note is coming from (optional, e.g. `"evernote"`) | | `source_id` | The ID of the record in the external system (optional, e.g. `"352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7"`) | When creating a note, given there’s already an existing note in the same notebook with the same `source`/`source_id`, the endpoint will return `204 No Content` without creating a duplicate. Example in Ruby[​](https://lunatask.app/api/notes-api/create#example-in-ruby "Direct link to Example in Ruby") --------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'payload = { name: 'My new note', content: 'My important note content', source: 'evernote', source_id: '352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7', notebook_id: '11b37775-5a34-41bb-b109-f0e5a6084799'}RestClient.post('https://api.lunatask.app/v1/notes', payload.to_json, { Authorization: "bearer #{access_token}", "Content-Type": 'application/json' }) Response[​](https://lunatask.app/api/notes-api/create#response "Direct link to Response") ------------------------------------------------------------------------------------------ The request returns JSON structured like this: { "note": { "id": "5999b945-b2b1-48c6-aa72-b251b75b3c2e", "notebook_id": "d1ff35f5-6b25-4199-ab6e-c19fe3fe27f1", "date_on": null, "sources": [ { "source": "evernote", "source_id": "352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7" } ], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z", }} * [HTTP Request](https://lunatask.app/api/notes-api/create#http-request) * [Body Parameters](https://lunatask.app/api/notes-api/create#body-parameters) * [Example in Ruby](https://lunatask.app/api/notes-api/create#example-in-ruby) * [Response](https://lunatask.app/api/notes-api/create#response) --- # Create entry | Lunatask [Skip to main content](https://lunatask.app/api/journal-api/create#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint creates a new journal entry for a given date. HTTP Request[​](https://lunatask.app/api/journal-api/create#http-request "Direct link to HTTP Request") -------------------------------------------------------------------------------------------------------- `POST https://api.lunatask.app/v1/journal_entries` Body Parameters[​](https://lunatask.app/api/journal-api/create#body-parameters "Direct link to Body Parameters") ----------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `date_on` | ISO-8601 formatted date (required) | | `name` | The name for the entry (optional, usually left empty, and the app will fill it in with the given date, for example, _“Tuesday, July 1st”_) | | `content` | The content of the entry (formatted in Markdown) | Example in Ruby[​](https://lunatask.app/api/journal-api/create#example-in-ruby "Direct link to Example in Ruby") ----------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.post( 'https://api.lunatask.app/v1/journal_entries', { date_on: '2021-01-10', content: 'Today was a tough day, but on the other side...' }.to_json, { Authorization: "bearer #{access_token}", "Content-Type": 'application/json' }) Response[​](https://lunatask.app/api/journal-api/create#response "Direct link to Response") -------------------------------------------------------------------------------------------- The request returns JSON structured like this: { "journal_entry": { "id": "6aa0d6e8-3b07-40a2-ae46-1bc272a0f472", "date_on": "2021-01-10", "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z", }} * [HTTP Request](https://lunatask.app/api/journal-api/create#http-request) * [Body Parameters](https://lunatask.app/api/journal-api/create#body-parameters) * [Example in Ruby](https://lunatask.app/api/journal-api/create#example-in-ruby) * [Response](https://lunatask.app/api/journal-api/create#response) --- # Delete note | Lunatask [Skip to main content](https://lunatask.app/api/notes-api/delete#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint deletes a specific note. HTTP Request[​](https://lunatask.app/api/notes-api/delete#http-request "Direct link to HTTP Request") ------------------------------------------------------------------------------------------------------ `DELETE https://api.lunatask.app/v1/notes/` URL Parameters[​](https://lunatask.app/api/notes-api/delete#url-parameters "Direct link to URL Parameters") ------------------------------------------------------------------------------------------------------------ | Parameter | Description | | --- | --- | | `id` | The ID of the note to delete | Example in Ruby[​](https://lunatask.app/api/notes-api/delete#example-in-ruby "Direct link to Example in Ruby") --------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.delete('https://api.lunatask.app/v1/notes/5999b945-b2b1-48c6-aa72-b251b75b3c2e', { Authorization: "bearer #{access_token}" }) Response[​](https://lunatask.app/api/notes-api/delete#response "Direct link to Response") ------------------------------------------------------------------------------------------ The request returns JSON structured like this: { "note": { "id": "5999b945-b2b1-48c6-aa72-b251b75b3c2e", "notebook_id": "d1ff35f5-6b25-4199-ab6e-c19fe3fe27f1", "date_on": null, "sources": [], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z", }} * [HTTP Request](https://lunatask.app/api/notes-api/delete#http-request) * [URL Parameters](https://lunatask.app/api/notes-api/delete#url-parameters) * [Example in Ruby](https://lunatask.app/api/notes-api/delete#example-in-ruby) * [Response](https://lunatask.app/api/notes-api/delete#response) --- # Create note | Lunatask [Skip to main content](https://lunatask.app/api/person-timeline-notes-api/create#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint creates a [new note](https://lunatask.app/docs/features/relationships#person-notes) for given date on a person’s memory timeline in the [relationships](https://lunatask.app/docs/features/relationships) section of the app. HTTP Request[​](https://lunatask.app/api/person-timeline-notes-api/create#http-request "Direct link to HTTP Request") ---------------------------------------------------------------------------------------------------------------------- `POST https://api.lunatask.app/v1/person_timeline_notes` Body Parameters[​](https://lunatask.app/api/person-timeline-notes-api/create#body-parameters "Direct link to Body Parameters") ------------------------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `person_id` | The Person ID of the person (can be found in our apps in a person’s profile or [looked up](https://lunatask.app/api/people-api/list)
using `source`/`source_id` attributes) | | `date_on` | ISO-8601 formatted date (optional, if not provided today will be used) | | `content` | The content of the note (optional, but impractical if empty, formatted in Markdown) | Example in Ruby[​](https://lunatask.app/api/person-timeline-notes-api/create#example-in-ruby "Direct link to Example in Ruby") ------------------------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'payload = { person_id: '5999b945-b2b1-48c6-aa72-b251b75b3c2e', date_on: '2021-01-10', content: 'Today we talked about ...'}RestClient.post('https://api.lunatask.app/v1/person_timeline_notes', payload.to_json, { Authorization: "bearer #{access_token}", "Content-Type": 'application/json' }) Response[​](https://lunatask.app/api/person-timeline-notes-api/create#response "Direct link to Response") ---------------------------------------------------------------------------------------------------------- The request returns JSON structured like this: { "person_timeline_note": { "id": "6aa0d6e8-3b07-40a2-ae46-1bc272a0f472", "date_on": "2021-01-10", "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z", }} * [HTTP Request](https://lunatask.app/api/person-timeline-notes-api/create#http-request) * [Body Parameters](https://lunatask.app/api/person-timeline-notes-api/create#body-parameters) * [Example in Ruby](https://lunatask.app/api/person-timeline-notes-api/create#example-in-ruby) * [Response](https://lunatask.app/api/person-timeline-notes-api/create#response) --- # Delete person | Lunatask [Skip to main content](https://lunatask.app/api/people-api/delete#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint deletes a specific person/relationship. HTTP Request[​](https://lunatask.app/api/people-api/delete#http-request "Direct link to HTTP Request") ------------------------------------------------------------------------------------------------------- `DELETE https://api.lunatask.app/v1/people/` URL Parameters[​](https://lunatask.app/api/people-api/delete#url-parameters "Direct link to URL Parameters") ------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `id` | The ID of the person to delete | Example in Ruby[​](https://lunatask.app/api/people-api/delete#example-in-ruby "Direct link to Example in Ruby") ---------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.delete('https://api.lunatask.app/v1/5999b945-b2b1-48c6-aa72-b251b75b3c2e', { Authorization: "bearer #{access_token}" }) Response[​](https://lunatask.app/api/people-api/delete#response "Direct link to Response") ------------------------------------------------------------------------------------------- The request returns JSON structured like this: { "person": { "id": "5999b945-b2b1-48c6-aa72-b251b75b3c2e", "relationship_strength": "business-contacts", "sources": [ { "source": "salesforce", "source_id": "352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7" } ], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T12:52:04Z", }} * [HTTP Request](https://lunatask.app/api/people-api/delete#http-request) * [URL Parameters](https://lunatask.app/api/people-api/delete#url-parameters) * [Example in Ruby](https://lunatask.app/api/people-api/delete#example-in-ruby) * [Response](https://lunatask.app/api/people-api/delete#response) --- # Authentication | Lunatask [Skip to main content](https://lunatask.app/api/authentication#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 In order to communicate with our API, you must first generate an access token – in our desktop app, visit _**Settings → Access tokens**_. Info Our API expects an access token to be included in all API requests in `Authorization` header. To verify that the integration works correctly and you’re able to call our APIs, test the connection by hitting our `/v1/ping` endpoint. Here is an example in Ruby programming language: ping.rb require 'rest-client'RestClient.get('https://api.lunatask.app/v1/ping', { Authorization: "bearer #{access_token}" }) The request returns JSON structured like this: { "message": "pong"} If you see this response, authentication works as expected 🎉 --- # Retrieve person | Lunatask [Skip to main content](https://lunatask.app/api/people-api/show#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint retrieves a specific person/relationship. HTTP Request[​](https://lunatask.app/api/people-api/show#http-request "Direct link to HTTP Request") ----------------------------------------------------------------------------------------------------- `GET https://api.lunatask.app/v1/people/` URL Parameters[​](https://lunatask.app/api/people-api/show#url-parameters "Direct link to URL Parameters") ----------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `id` | The ID of the person to retrieve | Example in Ruby[​](https://lunatask.app/api/people-api/show#example-in-ruby "Direct link to Example in Ruby") -------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.get('https://api.lunatask.app/v1/people/5999b945-b2b1-48c6-aa72-b251b75b3c2e', { Authorization: "bearer #{access_token}" }) Response[​](https://lunatask.app/api/people-api/show#response "Direct link to Response") ----------------------------------------------------------------------------------------- The request returns JSON structured like this: { "person": { "id": "5999b945-b2b1-48c6-aa72-b251b75b3c2e", "relationship_strength": "business-contacts", "sources": [ { "source": "salesforce", "source_id": "352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7" } ], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z" }} * [HTTP Request](https://lunatask.app/api/people-api/show#http-request) * [URL Parameters](https://lunatask.app/api/people-api/show#url-parameters) * [Example in Ruby](https://lunatask.app/api/people-api/show#example-in-ruby) * [Response](https://lunatask.app/api/people-api/show#response) --- # Create person | Lunatask [Skip to main content](https://lunatask.app/api/people-api/create#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint creates a new person/relationship. HTTP Request[​](https://lunatask.app/api/people-api/create#http-request "Direct link to HTTP Request") ------------------------------------------------------------------------------------------------------- `POST https://api.lunatask.app/v1/people` Body Parameters[​](https://lunatask.app/api/people-api/create#body-parameters "Direct link to Body Parameters") ---------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `first_name` | A person’s first name | | `last_name` | A person’s last name | | `relationship_strength` | One of `family`, `extended-family`, `intimate-friends`, `close-friends`, `casual-friends`, `acquaintances`, `business-contacts`, or `almost-strangers` (optional, `casual-friends` will be used if not provided) | | `source` | Identification of external system where the note is coming from (optional, e.g. `"salesforce"`) | | `source_id` | The ID of the record in the external system (optional, e.g. `"352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7"`) | When creating a person, given there’s already an existing person with the same `source`/`source_id`, the endpoint will return `204 No Content` without creating a duplicate. For convenience, you can provide values for a few selected fields while creating people: | Parameter | Description | | --- | --- | | `email` | A person’s email address | | `birthday` | A person’s birthday (ISO-8601 formatted date) | | `phone` | A person’s phone number | caution Custom fields for email, birthday, or phone number first have to be defined in the app. Otherwise the API will return 422 error code. Example in Ruby[​](https://lunatask.app/api/people-api/create#example-in-ruby "Direct link to Example in Ruby") ---------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'payload = { first_name: 'John', last_name: 'Doe', relationship_strength: 'business-contacts', source: 'salesforce', source_id: '352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7',}RestClient.post('https://api.lunatask.app/v1/people', payload.to_json, { Authorization: "bearer #{access_token}", "Content-Type": 'application/json' }) Response[​](https://lunatask.app/api/people-api/create#response "Direct link to Response") ------------------------------------------------------------------------------------------- The request returns JSON structured like this: { "person": { "id": "5999b945-b2b1-48c6-aa72-b251b75b3c2e", "relationship_strength": "business-contacts", "sources": [ { "source": "salesforce", "source_id": "352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7" } ], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z" }} caution When the number of people on Free plan reaches its limit, this API will respond with a 402 HTTP status code. * [HTTP Request](https://lunatask.app/api/people-api/create#http-request) * [Body Parameters](https://lunatask.app/api/people-api/create#body-parameters) * [Example in Ruby](https://lunatask.app/api/people-api/create#example-in-ruby) * [Response](https://lunatask.app/api/people-api/create#response) --- # Create task | Lunatask [Skip to main content](https://lunatask.app/api/tasks-api/create#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint creates a new task. HTTP Request[​](https://lunatask.app/api/tasks-api/create#http-request "Direct link to HTTP Request") ------------------------------------------------------------------------------------------------------ `POST https://api.lunatask.app/v1/tasks` Body Parameters[​](https://lunatask.app/api/tasks-api/create#body-parameters "Direct link to Body Parameters") --------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `area_id` | The Area ID of the list where the task should be created (UUID, can be found in our apps in the area settings) | | `goal_id` | The ID of the goal where the task should be created (optional, can be found in our apps in the goal’s 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](https://lunatask.app/api/tasks-api/entity#status)
) | | `motivation` | The motivation value of the task (optional, [see possible values](https://lunatask.app/api/tasks-api/entity#motivation)
) | | `eisenhower` | The quadrant on Eisenhower matrix (optional, [see possible values](https://lunatask.app/api/tasks-api/entity#eisenhower)
) | | `estimate` | The estimate of the task (optional, in minutes) | | `priority` | Priority of the task (optional, [see possible values](https://lunatask.app/api/tasks-api/entity#priority)
) | | `scheduled_on` | ISO-8601 formatted date the task is scheduled on (optional) | | `completed_at` | ISO-8601 formatted time when the task was completed (optional) | | `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 useful for later lookup of previously created tasks when updating without a need to remember task IDs. The API doesn’t 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. tip If you wish to add tasks to different areas at various times, you may also consider using an Inbox approach – create a separate “Inbox” area where incoming tasks would collect to be sorted later. Example in Ruby[​](https://lunatask.app/api/tasks-api/create#example-in-ruby "Direct link to Example in Ruby") --------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'payload = { name: 'My task', area_id: '11b37775-5a34-41bb-b109-f0e5a6084799', source: 'github', source_id: '123'}RestClient.post('https://api.lunatask.app/v1/tasks', payload.to_json, { Authorization: "bearer #{access_token}", "Content-Type": 'application/json' }) Response[​](https://lunatask.app/api/tasks-api/create#response "Direct link to Response") ------------------------------------------------------------------------------------------ The request returns JSON structured like this: { "task": { "id": "066b5835-184f-4fd9-be60-7d735aa94708", "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799", "goal_id": null, "status": "later", "previous_status": null, "estimate": null, "priority": 0, "progress": null, "motivation": "unknown", "eisenhower": 0, "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", }} * [HTTP Request](https://lunatask.app/api/tasks-api/create#http-request) * [Body Parameters](https://lunatask.app/api/tasks-api/create#body-parameters) * [Example in Ruby](https://lunatask.app/api/tasks-api/create#example-in-ruby) * [Response](https://lunatask.app/api/tasks-api/create#response) --- # Retrieve all people | Lunatask [Skip to main content](https://lunatask.app/api/people-api/list#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint retrieves all people in your account. You can narrow down the data returned by filtering on the source of the person (see the section about creating people for more information). HTTP Request[​](https://lunatask.app/api/people-api/list#http-request "Direct link to HTTP Request") ----------------------------------------------------------------------------------------------------- `GET https://api.lunatask.app/v1/people` Query Parameters[​](https://lunatask.app/api/people-api/list#query-parameters "Direct link to Query Parameters") ----------------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `source` | The `source` specified when creating the person (optional) | | `source_id` | The `source_id` specified when creating the person (optional) | If no source is specified, all people are returned. Example in Ruby[​](https://lunatask.app/api/people-api/list#example-in-ruby "Direct link to Example in Ruby") -------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.get('https://api.lunatask.app/v1/people', { Authorization: "bearer #{access_token}" }) Response[​](https://lunatask.app/api/people-api/list#response "Direct link to Response") ----------------------------------------------------------------------------------------- The request returns JSON structured like this: { "people": [ { "id": "5999b945-b2b1-48c6-aa72-b251b75b3c2e", "relationship_strength": "business-contacts", "sources": [ { "source": "salesforce", "source_id": "352fd2d7-cdc0-4e91-a0a3-9d6cc9d440e7" } ], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z" }, { "id": "109cbf01-dba9-4136-8cf1-a02084ba3977", "relationship_strength": "family", "sources": [], "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z" } ]} * [HTTP Request](https://lunatask.app/api/people-api/list#http-request) * [Query Parameters](https://lunatask.app/api/people-api/list#query-parameters) * [Example in Ruby](https://lunatask.app/api/people-api/list#example-in-ruby) * [Response](https://lunatask.app/api/people-api/list#response) --- # Retrieve all tasks | Lunatask [Skip to main content](https://lunatask.app/api/tasks-api/list#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint retrieves all tasks in your account. You can narrow down the data returned by filtering on the source of the task (see our article on creating tasks for more information). HTTP Request[​](https://lunatask.app/api/tasks-api/list#http-request "Direct link to HTTP Request") ---------------------------------------------------------------------------------------------------- `GET https://api.lunatask.app/v1/tasks` Query Parameters[​](https://lunatask.app/api/tasks-api/list#query-parameters "Direct link to 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. Example in Ruby[​](https://lunatask.app/api/tasks-api/list#example-in-ruby "Direct link to Example in Ruby") ------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.get('https://api.lunatask.app/v1/tasks', { Authorization: "bearer #{access_token}" }) Response[​](https://lunatask.app/api/tasks-api/list#response "Direct link to Response") ---------------------------------------------------------------------------------------- The request returns JSON structured like this: { "tasks": [ { "id": "066b5835-184f-4fd9-be60-7d735aa94708", "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799", "goal_id": null, "status": "next", "previous_status": "later", "estimate": 10, "priority": 0, "progress": 25, "motivation": "unknown", "eisenhower": 0, "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", }, { "id": "0e0cff5c-c334-4a24-b15a-4fca6cfbf25f", "area_id": "f557287e-ae43-4472-9478-497887362dcb", "goal_id": null, "status": "later", "previous_status": null, "estimate": 120, "priority": 0, "motivation": "unknown", "eisenhower": 0, "progress": null, "sources": [], "scheduled_on": null, "completed_at": null, "created_at": "2021-01-10T10:39:26Z", "updated_at": "2021-01-10T10:39:26Z", } ]} * [HTTP Request](https://lunatask.app/api/tasks-api/list#http-request) * [Query Parameters](https://lunatask.app/api/tasks-api/list#query-parameters) * [Example in Ruby](https://lunatask.app/api/tasks-api/list#example-in-ruby) * [Response](https://lunatask.app/api/tasks-api/list#response) --- # Delete task | Lunatask [Skip to main content](https://lunatask.app/api/tasks-api/delete#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint deletes a specific task. HTTP Request[​](https://lunatask.app/api/tasks-api/delete#http-request "Direct link to HTTP Request") ------------------------------------------------------------------------------------------------------ `DELETE https://api.lunatask.app/v1/tasks/` URL Parameters[​](https://lunatask.app/api/tasks-api/delete#url-parameters "Direct link to URL Parameters") ------------------------------------------------------------------------------------------------------------ | Parameter | Description | | --- | --- | | `id` | The ID of the task to delete | Example in Ruby[​](https://lunatask.app/api/tasks-api/delete#example-in-ruby "Direct link to Example in Ruby") --------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.delete('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { Authorization: "bearer #{access_token}" }) Response[​](https://lunatask.app/api/tasks-api/delete#response "Direct link to Response") ------------------------------------------------------------------------------------------ The request returns JSON structured like this: { "task": { "id": "066b5835-184f-4fd9-be60-7d735aa94708", "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799", "goal_id": null, "status": "later", "previous_status": null, "estimate": null, "priority": 0, "progress": null, "motivation": "unknown", "eisenhower": 0, "sources": [], "scheduled_on": null, "completed_at": null, "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T12:52:04Z", }} * [HTTP Request](https://lunatask.app/api/tasks-api/delete#http-request) * [URL Parameters](https://lunatask.app/api/tasks-api/delete#url-parameters) * [Example in Ruby](https://lunatask.app/api/tasks-api/delete#example-in-ruby) * [Response](https://lunatask.app/api/tasks-api/delete#response) --- # Entities | Lunatask [Skip to main content](https://lunatask.app/api/tasks-api/entity#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page 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) | | `goal_id` | The ID of the goal 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 for estimate (optional, in minutes) | | `priority` | Current priority (see possible values below) | | `progress` | Progress on the task (in percent or `null`) | | `motivation` | Current value of the motivation (see possible values below) | | `eisenhower` | Current value on Eisenhower matrix (see possible values below) | | `sources` | Array of references to data records in external systems (see documentation for creating tasks for more information) | | `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 | Example JSON representation might like this: { "id": "066b5835-184f-4fd9-be60-7d735aa94708", "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799", "goal_id": null, "status": "next", "previous_status": "later", "estimate": 10, "priority": 0, "progress": null, "motivation": "unknown", "eisenhower": 0, "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",} Attributes[​](https://lunatask.app/api/tasks-api/entity#attributes "Direct link to Attributes") ------------------------------------------------------------------------------------------------ ### `status`[​](https://lunatask.app/api/tasks-api/entity#status "Direct link to status") Allowed values for `status` attribute: | Value | Description | | --- | --- | | `"later"` | Represents later status (default) | | `"next"` | Represents next status | | `"started"` | Represents started status (now named `In progress` in the app) | | `"waiting"` | Represents waiting status | | `"completed"` | Represents done status | ### `priority`[​](https://lunatask.app/api/tasks-api/entity#priority "Direct link to priority") Priority is represented as an integer value in range `-2..2`. | Value | Description | | --- | --- | | `2` | Highest priority | | `1` | High priority | | `0` | Normal priority (default) | | `-1` | Low priority | | `-2` | Lowest priority | Clearing the priority is done by setting the priority value to `0`. ### `motivation`[​](https://lunatask.app/api/tasks-api/entity#motivation "Direct link to motivation") Allowed values for `motivation` attribute: | 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"`. ### `eisenhower`[​](https://lunatask.app/api/tasks-api/entity#eisenhower "Direct link to eisenhower") Allowed values for `eisenhower` attribute: | Value | Description | | --- | --- | | `1` | Urgent and Important | | `2` | Urgent, not important | | `3` | Important, not urgent | | `4` | Not urgent or important | | `0` | Uncategorized | Clearing the value is done by assigning the value of `0`. * [Attributes](https://lunatask.app/api/tasks-api/entity#attributes) * [`status`](https://lunatask.app/api/tasks-api/entity#status) * [`priority`](https://lunatask.app/api/tasks-api/entity#priority) * [`motivation`](https://lunatask.app/api/tasks-api/entity#motivation) * [`eisenhower`](https://lunatask.app/api/tasks-api/entity#eisenhower) --- # Update task | Lunatask [Skip to main content](https://lunatask.app/api/tasks-api/update#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint updates a specific task. HTTP Request[​](https://lunatask.app/api/tasks-api/update#http-request "Direct link to HTTP Request") ------------------------------------------------------------------------------------------------------ `PUT https://api.lunatask.app/v1/tasks/` URL Parameters[​](https://lunatask.app/api/tasks-api/update#url-parameters "Direct link to URL Parameters") ------------------------------------------------------------------------------------------------------------ | Parameter | Description | | --- | --- | | `id` | The ID of the task to update | Body Parameters[​](https://lunatask.app/api/tasks-api/update#body-parameters "Direct link to Body Parameters") --------------------------------------------------------------------------------------------------------------- The attributes you want to update. Besides `name` and `note`, other options like `status`, `motivation`, or `scheduled_on` are available (see [Task entity](https://lunatask.app/api/tasks-api/entity) for allowed attribute values). Example in Ruby[​](https://lunatask.app/api/tasks-api/update#example-in-ruby "Direct link to Example in Ruby") --------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'payload = { name: 'My new name', motivation: 'must' }RestClient.put('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', payload.to_json, { Authorization: "bearer #{access_token}", "Content-Type": 'application/json' }) Response[​](https://lunatask.app/api/tasks-api/update#response "Direct link to Response") ------------------------------------------------------------------------------------------ The request returns JSON structured like this: { "task": { "id": "066b5835-184f-4fd9-be60-7d735aa94708", "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799", "goal_id": null, "status": "later", "previous_status": null, "estimate": null, "priority": null, "progress": null, "motivation": "must", "eisenhower": 0, "sources": [], "scheduled_on": null, "completed_at": null, "created_at": "2021-01-10T10:39:25Z", "updated_at": "2021-01-10T10:39:25Z", }} * [HTTP Request](https://lunatask.app/api/tasks-api/update#http-request) * [URL Parameters](https://lunatask.app/api/tasks-api/update#url-parameters) * [Body Parameters](https://lunatask.app/api/tasks-api/update#body-parameters) * [Example in Ruby](https://lunatask.app/api/tasks-api/update#example-in-ruby) * [Response](https://lunatask.app/api/tasks-api/update#response) --- # Retrieve task | Lunatask [Skip to main content](https://lunatask.app/api/tasks-api/show#__docusaurus_skipToContent_fallback) We’re working on the next major evolution of Lunatask: Lunatask 3.0. More details and an official announcement are coming soon 🎉 On this page This endpoint retrieves a specific task. HTTP Request[​](https://lunatask.app/api/tasks-api/show#http-request "Direct link to HTTP Request") ---------------------------------------------------------------------------------------------------- `GET https://api.lunatask.app/v1/tasks/` URL Parameters[​](https://lunatask.app/api/tasks-api/show#url-parameters "Direct link to URL Parameters") ---------------------------------------------------------------------------------------------------------- | Parameter | Description | | --- | --- | | `id` | The ID of the task to retrieve | Example in Ruby[​](https://lunatask.app/api/tasks-api/show#example-in-ruby "Direct link to Example in Ruby") ------------------------------------------------------------------------------------------------------------- require 'rest-client'access_token = 'xxx'RestClient.get('https://api.lunatask.app/v1/tasks/066b5835-184f-4fd9-be60-7d735aa94708', { Authorization: "bearer #{access_token}" }) Response[​](https://lunatask.app/api/tasks-api/show#response "Direct link to Response") ---------------------------------------------------------------------------------------- The request returns JSON structured like this: { "task": { "id": "066b5835-184f-4fd9-be60-7d735aa94708", "area_id": "11b37775-5a34-41bb-b109-f0e5a6084799", "goal_id": null, "status": "next", "previous_status": "later", "estimate": 10, "priority": 0, "progress": null, "motivation": "unknown", "eisenhower": 0, "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", }} * [HTTP Request](https://lunatask.app/api/tasks-api/show#http-request) * [URL Parameters](https://lunatask.app/api/tasks-api/show#url-parameters) * [Example in Ruby](https://lunatask.app/api/tasks-api/show#example-in-ruby) * [Response](https://lunatask.app/api/tasks-api/show#response) ---