General

Introduction

You can get an API secret from our developer page.

All of our endpoints expect POST requests, and the Content-Type is application/json.

Rate limit explanation

Our API uses a token bucket rate limit model. Each endpoint sets a limit on a steady-state rate and a burst of requests. In the token bucket algorithm, the burst is the maximum bucket size.

If you exceed this limit, you'll get a TooManyRequests error response.

Common Error reference

All responses contain the field _code and _msg.

_code being OK means the request succeeded through. Any other value means something went wrong; you can find the meaning of each below. The _msg field gives you more information about the error.

Here are all the errors returned by the Dynalist API and their meaning:

Code	Meaning
`InvalidToken`	Your secret token is invalid.
`TooManyRequests`	You've hit the limit on how many requests you can send.
`Invalid`	Your request is not valid JSON.
`LockFail`	The server was unable to handle the request.

File-level API

Get all documents and folders

Example request:

{
  "token": "<your api secret token>"
}

Example response:

{
  "_code": "OK",
  "_msg": "",
  "root_file_id": "<root folder id>",
  "files": [
    {
      "id": "<document 1 id>",
      "title": "Todo list",
      "type": "document",
      "permission": 2
    },
    {
      "id": "<document 2 id>",
      "title": "Meeting notes",
      "type": "document",
      "permission": 2
    },
    {
      "id": "<folder id>",
      "title": "Study notes",
      "type": "folder",
      "permission": 2,
      "collapsed": false,
      "children": [
          "<document 1 id>",
          "<document 2 id>"
      ]
    },
    {
      "id": "<root folder id>",
      "title": "Untitled",
      "type": "folder",
      "permission": 4,
      "collapsed": false,
      "children": [
          "<folder id>"
      ]
    }
  ]
}

This endpoint fetches all your documents and folders.

HTTP Request

POST https://dynalist.io/api/v1/file/list

Request Parameters

Parameter	Type	Description
token	String	Your API secret token.

In the returned response, the "permission" enumerate has the following possible values:

Value	Meaning
0	No access
1	Read only
2	Edit rights
3	Manage
4	Owner

Possible errors

Common errors: Invalid, InvalidToken, TooManyRequests, LockFail

Rate limit policy

You can access this API at a steady rate of 6 times per minute, with a burst of 10 requests at once. See the rate limit section for more information on how it works.

Make changes to documents and folders

Example request:

{
  "token": "<your api secret token>",
  "changes": [
    {
      "action": "edit",
      "type": "document",
      "file_id": "<document id>",
      "title": "New title"
    },
    {
      "action": "move",
      "type": "folder",
      "file_id": "<folder id>",
      "parent_id": "<parent folder id>",
      "index": 3
    },
    {
      "action": "create",
      "type": "document",
      "parent_id": "<parent folder id>",
      "index": 3,
      "title": "New title"
    }
  ]
}

Example response:

{
  "_code": "OK",
  "_msg": "",
  "results": [
    true, // succeeded
    false, // failed
    true
  ],
  "created": [
    "<new document id>"
  ]
}

This endpoint lets you make changes to specific documents and folders.

HTTP Request

POST https://dynalist.io/api/v1/file/edit

Request parameters

Parameter	Type	Description
token	String	Your API scret token.
changes	Array	Array of changes to perform (see below for the required format).

There are two types of file-level change: move and edit. move moves the document or folder under another folder; edit changes the title of the document or folder

`move` format

Parameter	Type	Description
action	String	`move`.
type	String	Type of the target file. Must be either `folder` or `document`.
file_id	String	The ID of the document or folder you're trying to move.
parent_id	String	The file ID of the parent folder you want to move the target file to.
index	Integer	This field is an integer that's the zero-indexed position you want the file to land in the parent folder, supply `-1` to place it at the end, and `0` to place it at the top.

`edit` format

Parameter	Type	Description
action	String	`edit`.
type	String	Type of the target file. Must be either `folder` or `document`.
file_id	String	The ID of the document or folder you're trying to change.
title	String	The new title that you're trying to set.

`create` format

Parameter	Type	Description
action	String	`create`.
type	String	Type of the target file. Must be either `folder` or `document`.
parent_id	String	The file ID of the parent folder you want to move the target file to.
index	Integer	This field is an integer that's the zero-indexed position you want the file to land in the parent folder, supply `-1` to place it at the end, and `0` to place it at the top.
title	String	(optional) The title for the new file.

Response

The response contains a results field, which is an array of boolean values. Each boolean value represents if a change succeeded or not. The booleans are in the same order as the incoming changes.

For all successful create changes, a created array in the response will contain the newly created document/folder IDs in the order they were requested, and only if the creation was successful.

Possible errors

Common errors: Invalid, InvalidToken, TooManyRequests, LockFail

Rate limit policy

You can access this API at a steady rate of 60 times per minute, with a burst of 50 requests at once. See the rate limit section for more information on how it works.

Document-level API

Get content of a document

Example request:

{
  "token": "<your api secret token>",
  "file_id": "<document id>"
}

Example response:

{
  "_code": "OK",
  "_msg": "",
  "file_id": "<document id>",
  "title": "Todo list",
  "version": 15,
  "nodes": [
    {
      "id": "<node #1 id>",
      "content": "Buy milk",
      "note": "2L whole milk",
      "created": 1552959309804, // timestamp in milliseconds of the creation time
      "modified": 1552959335182, // timestamp in milliseconds of the last modified time
      "children": []
    },
    {
      "id": "<node #2 id>",
      "content": "Send Jason photos",
      "note": "",
      "checked": true,
      "checkbox": true, // whether this item has checkbox
      "color": 4, // color label, 0~6
      "heading": 3, // heading level, 0~3
      "created": 1552959309804,
      "modified": 1552959335182,
      "collapsed": true,
      "children": [
        "<node #3 id>",
      ]
    },
    {
      "id": "<node #3 id>",
      "content": "Picnic photos",
      "note": "",
      "created": 1552959309904,
      "modified": 1552959359783
      "children": []
    }
  ]
}

This endpoint fetches the content of a specific document.

HTTP Request

POST https://dynalist.io/api/v1/doc/read

Request parameters

Parameter	Type	Description
token	String	Your API secret token.
file_id	String	The ID of the document to fetch.

Possible errors

Common errors: Invalid, InvalidToken, TooManyRequests, LockFail

Code	Meaning
`Unauthorized`	You don't have permission to access this document.
`NotFound`	The document you're requesting is not found.

Rate limit policy

You can access this API at a steady rate of 30 times per minute, with a burst of 100 requests at once. See the rate limit section for more information on how it works.

Check if documents has been updated

Example request:

{
  "token": "<your api secret token>",
  "file_ids": [
    "<document id 1>",
    "<document id 2>"
  ]
}

Example response:

{
  "_code": "OK",
  "_msg": "",
  "versions": {
    "<document id 1>": 15,
    "<document id 2>": 28
  }
}

This endpoint returns the latest version numbers of any documents listed in the request.

Note: any inaccessible document or non-existent document will simply be dropped and not show up in the response.

HTTP Request

POST https://dynalist.io/api/v1/doc/check_for_updates

Request parameters

Parameter	Type	Description
token	String	Your API secret token.
file_ids	Array(String)	The IDs of the documents to check for versions.

Possible errors

Common errors: Invalid, InvalidToken, TooManyRequests

Rate limit policy

You can access this API at a steady rate of 60 times per minute, with a burst of 50 requests at once. See the rate limit section for more information on how it works.

Make change to the content of a document

Example request:

{
  "file_id": "<document id>",
  "changes": [
    {
      "action": "insert",
      "parent_id": "<parent node id>",
      "index": 0,
      "content": "Read the second book in the series",
      "note": "Return the book to the library by 04/23."
      "checked": false
    },
    {
      "action": "edit",
      "node_id": "<target node id>",
      "checked": true
    },
    {
      "action": "move",
      "node_id": "<target item ID>",
      "parent_id": "<parent item ID>",
      "index": 2
    },
    {
      "action": "delete",
      "node_id": "<target item ID>"
    }
  ]
}

Example response:

{
  "_code": "OK", // succeeded, an error code will be returned otherwise
  "_msg": "",
  "new_node_ids": [ // ids of the newly inserted items in the order they were sent in
    "<new item ID>"
  ]
}

This endpoint lets you make changes to the content of a specific document.

HTTP Request

POST https://dynalist.io/api/v1/doc/edit

Request parameters

Parameter	Type	Description
token	String	Your API secret token.
file_id	String	The ID of the document you're trying to change.
changes	Array	Array of changes to perform (see below for the required format).

There are four types of node-level change: insert, edit, move, and delete.

`insert` format

Parameter	Type	Description
action	String	`insert`.
parent_id	String	The ID of the parent item to insert under.
index	Integer	This field is an integer that's the zero-indexed position you want the file to land in the parent folder, supply `-1` to place it at the end, and `0` to place it at the top.
content	String	New item title.
note (optional)	String	New item note.
checked (optional)	Boolean	New item checked status.
checkbox (optional)	Boolean	Whether the new item should be a checklist. Default: false.
heading (optional)	Integer	What heading level is new item, from level 1 to level 3. Default: 0.
color (optional)	Integer	What color label does the new item have, from color 1 to color 6. Default: 0.

`edit` format

Parameter	Type	Description
action	String	`edit`.
node_id	String	The ID of the item to edit.
content (optional)	String	New item title.
note (optional)	String	New item note.
checked (optional)	Boolean	New item checked status.
checkbox (optional)	Boolean	Whether the new item should be a checklist. Default: false.
heading (optional)	Integer	What heading level is new item, from level 1 to level 3. Default: 0.
color (optional)	Integer	What color label does the new item have, from color 1 to color 6. Default: 0.

`move` format

Parameter	Type	Description
action	String	`move`.
node_id	String	The ID of the item to change.
parent_id	String	The ID of the parent item to move item under.
index	Integer	This field is an integer that's the zero-indexed position you want the file to land in the parent folder, supply `-1` to place it at the end, and `0` to place it at the top.

`delete` format

Parameter	Type	Description
action	String	`delete`
node_id	String	The ID of the item to delete.

Response

The response contains a results field, which is an array of boolean values. Each boolean value represents if a change succeeded or not. The booleans are in the same order as the incoming changes.

Possible errors

Common errors: Invalid, InvalidToken, TooManyRequests, LockFail

Code	Meaning
`Unauthorized`	You don't have permission to access this document.
`NotFound`	The document you're requesting is not found.
`NodeNotFound`	The node (item) you're requesting is not found.

Rate limit policy

You can access this API at a steady rate of 60 times per minute, with a burst of 20 requests at once. See the rate limit section for more information on how it works.

The rate limit above is for number of requests. There's another rate limit for the number of changes you can send. You can send changes at a steady rate of 240 changes per minute, with a burst of 500 changes.

Account Level API

Send to inbox

Example request:

{
  "token": "<your api secret token>",
  "index": 0,
  "content": "Get the book recommended by Jerry",
  "note": "Should be available in the city library, or on Amazon for around $25"
  "checked": true,
  "checkbox": true,
}

Example response:

{
  "_code": "OK", // succeeded, an error code will be returned otherwise
  "_msg": "",
  "file_id": "<inbox document ID>",
  "node_id": "<new node ID>",
  "index": 0 // where the new item was placed in the inbox
}

This endpoint lets you send a new item to your inbox location.

HTTP Request

POST https://dynalist.io/api/v1/inbox/add

Request parameters

Parameter	Type	Description
token	String	Your API secret token.
index	Integer	Zero-indexed position you want the file to land in the inbox item. Use `-1` to place it at the end, and `0` to place it at the top. If not given, the user setting will be used (default to bottom).
content	String	Title of the new item. Default: empty.
note (optional)	String	Note of the new item. Default: empty.
checked (optional)	Boolean	Checked status of the new item. Default: false.
checkbox (optional)	Boolean	Whether the new item should be a checklist. Default: false.
heading (optional)	Integer	What heading level is new item, from level 1 to level 3. Default: 0.
color (optional)	Integer	What color label does the new item have, from color 1 to color 6. Default: 0.

Possible errors

Common errors: Invalid, InvalidToken, TooManyRequests, LockFail

Code	Meaning
`NoInbox`	Inbox location is not configured, or invalid.

Rate limit policy

You can access this API at a steady rate of 60 times per minute, with a burst of 20 requests at once. See the rate limit section for more information on how it works.

Upload file (Pro only)

Example request:

{
  "token": "<your api secret token>",
  "filename": "sample.txt",
  "content_type": "text/plain",
  "data": "VGVzdCBkYXRh"
}

Example response:

{
  "_code": "OK", // succeeded, an error code will be returned otherwise
  "_msg": "",
  "url": "https://dynalist.io/u/<upload id>"
}

This endpoint lets you upload a file to Dynalist.

HTTP Request

POST https://dynalist.io/api/v1/upload

Request parameters

Parameter	Type	Description
token	String	Your API secret token.
filename	String	The name of the file, including extension.
content_type	String	The mime type of the file, such as "text/plain", "image/jpeg", "application/pdf"
data	String	Base64 encoded data

Possible errors

Common errors: Invalid, InvalidToken, TooManyRequests

Code	Meaning
`Invalid`	One of the request field is invalid. An explanation is included in the response field "_msg".
`NeedPro`	This feature is pro-only and your account is not pro.
`QuotaExceeded`	The upload quota limit has been reached.

Rate limit policy

You can access this API at a steady rate of 2 times per minute, with a burst of 5 requests at once. See the rate limit section for more information on how it works.

Get Preference

Example request:

{
  "token": "<your api secret token>",
  "key": "inbox_location"
}

Example response:

{
  "_code": "OK", // succeeded, an error code will be returned otherwise
  "_msg": "",
  "key": "inbox_location",
  "value": "<file ID>/<node ID>"
}

This endpoint lets you get a user preference value.

HTTP Request

POST https://dynalist.io/api/v1/pref/get

Request parameters

Parameter	Type	Description
token	String	Your API secret token.
key	String	The preference key. A list is available further down.

Possible errors

Common errors: InvalidToken, TooManyRequests

Rate limit policy

You can access this API at a steady rate of 60 times per minute, with a burst of 100 requests at once. See the rate limit section for more information on how it works.

Preference Keys

Key	Description	Typical values
inbox_location	Location of inbox	`<file ID>/<node ID>` or `<file ID>`
inbox_move_position	Whether to insert to top or bottom	`top` or `bottom`

Set Preference

Example request:

{
  "token": "<your api secret token>",
  "key": "inbox_location",
  "value": "<file ID>/<node ID>"
}

Example response:

{
  "_code": "OK", // succeeded, an error code will be returned otherwise
  "_msg": ""
}

This endpoint lets you set a user preference value.

HTTP Request

POST https://dynalist.io/api/v1/pref/set

Request parameters

Parameter	Type	Description
token	String	Your API secret token.
key	String	The preference key. See set preference section.
value	String	The value. The maximum size is 5MB.

Possible errors

Common errors: InvalidToken, TooManyRequests

Rate limit policy

You can access this API at a steady rate of 60 times per minute, with a burst of 100 requests at once. See the rate limit section for more information on how it works.

General

Introduction

Rate limit explanation

Common Error reference

File-level API

Get all documents and folders

HTTP Request

Request Parameters

Possible errors

Rate limit policy

Make changes to documents and folders

HTTP Request

Request parameters

move format

edit format

create format

Response

Possible errors

Rate limit policy

Document-level API

Get content of a document

HTTP Request

Request parameters

Possible errors

Rate limit policy

Check if documents has been updated

HTTP Request

Request parameters

Possible errors

Rate limit policy

Make change to the content of a document

HTTP Request

Request parameters

insert format

edit format

move format

delete format

Response

Possible errors

Rate limit policy

Account Level API

Send to inbox

HTTP Request

Request parameters

Possible errors

Rate limit policy

Upload file (Pro only)

HTTP Request

Request parameters

Possible errors

Rate limit policy

Get Preference

HTTP Request

Request parameters

Possible errors

Rate limit policy

Preference Keys

Set Preference

HTTP Request

Request parameters

Possible errors

Rate limit policy

`move` format

`edit` format

`create` format

`insert` format

`edit` format

`move` format

`delete` format