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.