NAV Navbar
javascript
  • Introduction
  • File-level
  • Document-level
  • Rate limit explanation
  • Error reference
  • 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.

    File-level

    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

    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 requets 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

    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 requets at once. See the rate limit section for more information on how it works.

    Document-level

    Get content of a document

    Example request:

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

    Example response:

    {
      "_code": "OK",
      "_msg": "",
      "title": "Todo list",
      "nodes": [
        {
          "id": "<node #1 id>",
          "content": "Buy milk",
          "note": "2L whole milk",
          "checked": true,
          "collapsed": false,
          "parent": "root",
          "children": []
        },
        {
          "id": "<node #2 id>",
          "content": "Send Jason photos",
          "checked": false,
          "collapsed": false,
          "parent": "root",
          "children": [
            "<node #3 id>",
            "<node #4 id>"
          ]
        },
        {
          "id": "<node #3 id>",
          "content": "Picnic photos",
          "checked": false,
          "collapsed": false,
          "parent": "<node #2 id>",
          "children": []
        },
        {
          "id": "<node #4 id>",
          "content": "Cruise photos",
          "checked": true,
          "collapsed": false,
          "parent": "<node #2 id>",
          "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

    Invalid, Unauthorized, NotFound, 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 requets 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": ""
    }
    

    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.

    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.

    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

    Invalid, Unauthorized, NotFound, NodeNotFound, InvalidToken, TooManyRequests, LockFail

    Rate limit policy

    You can access this API at a steady rate of 60 times per minute, with a burst of 20 requets 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.

    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": false
    }
    

    Example response:

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

    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.

    Possible errors

    Invalid, NoInbox, InvalidToken, TooManyRequests, LockFail

    Rate limit policy

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

    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.

    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
    Invalid Your request is not valid JSON.
    TooManyRequests You've hit the limit on how many requests you can send.
    InvalidToken Your secret token is invalid.
    LockFail Server unable to handle the request.
    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.
    NoInbox Inbox location is not configured, or invalid.