NAV Navbar
javascript
  • General
  • File-level API
  • Document-level API
  • Account Level API
  • 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": "<folder id>",
          "index": 3
        }
      ]
    }
    

    Example response:

    {
      "_code": "OK",
      "_msg": "",
      "results": [
        true, // succeeded
        false // failed
      ]
    }
    

    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.

    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

    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": "",
      "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.
    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": "",
      "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.