NAV Navbar
javascript

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.