Marvin API

Use Marvin's API to access data that doesn't live in your user database, or for simplicity's sake. We will be adding more endpoints soon.

Basic structure

Marvin's API involves GET and POST requests to https://serv.amazingmarvin.com/api/:endpoint. POST bodies and most responses are encoded as JSON.

Credentials

Include an HTTP header X-API-Token using the API_TOKEN found here if the endpoint requires limited access, or FULL_ACCESS_TOKEN also found here if the endpoint requires full access. The idea behind this system is that you might want to give Zapier the ability to create tasks, but not to read your data. If there's user demand then we'll make a proper OAuth system with permissions.

Rotation

Accidentally exposed an API_TOKEN? You can get rotate your credentials in the API strategy settings within Marvin.

Endpoints

Test credentials

You can test whether your credentials are correct with a POST:

POST /api/test
X-API-Token: XYZ
=>
"OK"

Create a task (stable)

You can quickly create a task with a POST request:

POST /api/addTask
X-API-Token: XYZ
{
  "done": false,
  "day": "2020-07-17",
  "title": "Work 30m homework #School", // supports some autocompletion (parent, day, dueDate, plannedWeek, plannedMonth, timeEstimate, labels, isStarred)
  "parentId": "xyz", // ID of parent category/project
  "labelIds": ["abc", "def"], // IDs of labels
  "firstScheduled": "2020-07-17",
  "rank": 999,
  "dailySection": "Morning",
  "note": "Problems 1-4",
  "dueDate": "2020-07-20",
  "timeEstimate": 3600000, // ms
  "isReward": false,
  "isStarred": 3,
  "isFrogged": 2,
  "plannedWeek": "2020-07-12",
  "plannedMonth": "2020-07",

  // Time offset in minutes
  //
  // Added to time to fix time zone issues.  So if the user is in Pacific time,
  // this would be -8*60.  If the user added a task with +today at 22:00 local
  // time 2019-12-05, then we want to create the task on 2019-12-05 and not
  // 2019-12-06 (which is the server date).
  "timeZoneOffset": 60,
}

The title will be processed similar to autocompletion within Marvin. So if you use "Example task +today", then the task will be scheduled for today and " +today" will be removed from the title. If you put "#Parent Category" or "@label1 @label2" in the title, they will be resolved to their IDs when you open Marvin.

See Marvin data types for documentation about how these fields work.

Create a project (stable, but new endpoint will be added)

You can also create a project with a POST request. Use the addTask API above and put "p: " or "project: " at the start of the task title.

Read any doc

With the fullAccessToken you can GET any individual document in the couchdb database by ID.

GET /api/doc?id=strategySettings.labelSettings.groups
X-Full-Access-Token: ABC
=>
{
  "qoq4xtw653fGv": {
    "_id": "qoq4xtw653fGv",
    "title": "Example group",
    "rank": 1,
    "createdAt": 1595057624899,
    "isExclusive": true,
    "color": "#29224a",
    "icon": "inbox"
  },
  ...
}

Get the currently tracked task (stable)

GET /api/trackedItem
X-API-Token: XYZ
=>
{
  "_id": "a12345",
  "db": "Tasks",
  "title": "Work 30m on homework",
}

Get tasks and projects scheduled today (including rollover/auto-schedule due items if enabled) (stable, but improvements coming)

GET /api/todayItems
X-API-Token: XYZ
=>
[...]

Get tasks and projects that are due today (stable, but improvements coming)

GET /api/dueItems
X-API-Token: XYZ
=>
[...]

Get a list of all categories (stable)

You can access a list of all your categories with a GET request. See Categories for documentation of the data format.

GET /api/categories
X-API-Token: XYZ
=>
[{ "_id": "a4123412", "title": "Work", "parentId": "root", "color": "#4184a0", ... }, ...]

Get a list of all labels (stable)

Get a list of all labels, in their sort order (used in sort by label).

GET /api/labels
X-API-Token: XYZ
=>
[{ "_id": "abcdefg1234", "title": "quick", "color": "#f0a0a0", "icon": "tag", "groupId": "5421fabcdae" }, ...]

The label groups can be found by [reading the sync database document](#Read any doc) profile.strategySettings.labelSettings.groups.

See documentation for labels and label groups