Developers

Local HTTP Server

The Inkdrop client app can open a simple HTTP server so that you can access the data from an external program easily, which gives you a flexible ability to import/export your notes. Read this page to learn how to configure the local HTTP server.

GET/

Get the server information

Accessing the root of a HTTP server returns meta information about the app.

Parameters

No parameters

Request

GET
/
curl -G https://localhost:19840/ \
  -H "Authorization: Basic {token}"
GET/notes

List of all notes

Returns a list of all the Notes in the local database.

Query parameters

  • Name
    keyword
    Type
    string
    Description

    The search keyword to filter notes. You can use the same qualifiers for searching notes.

  • Name
    limit
    Type
    number
    Description

    Limit the number of the returned documents to the specified number.

  • Name
    skip
    Type
    number
    Description

    Skip this number of documents before starting to return the results. Default is 0.

  • Name
    sort
    Type
    string
    Description

    Sort the documents by the specified field. One of: 'updatedAt', 'createdAt', 'title'.

  • Name
    descending
    Type
    boolean
    Description

    Reverse the order of the output documents.

Request

GET
/notes
curl "https://localhost:19840/notes/?limit=1" \
  -H "Authorization: Basic {token}"

Response

[
  {
    "doctype": "markdown",
    "bookId": "book:tjnPbJakw",
    "createdAt": 1589165355584,
    "updatedAt": 1592532006000,
    "status": "active",
    "share": "private",
    "numOfTasks": 0,
    "numOfCheckedTasks": 0,
    "pinned": true,
    "title": "hello",
    "body": "example note",
    "tags": ["tag:HyBgJ94gx", "tag:h11OMPbSs"],
    "_id": "note:BKzzd8iGK",
    "_rev": "19-d882f96ee27f7b9f71f6183b0cab9193"
  }
]
POST/notes

Create/update a note

The POST method creates a new Note, or update an existing note. The document ID _id is optional and will be automatically generated for new note. If the note already exists, you must specify its revision _rev, otherwise a conflict will occur.

Response JSON Object

  • Name
    id
    Type
    string
    Description

    Document ID

  • Name
    ok
    Type
    boolean
    Description

    Operation status

  • Name
    rev
    Type
    string
    Description

    Revision MVCC token

Request

POST
/notes
curl -X POST "https://localhost:19840/notes/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {token}" \
  -d '{
    "doctype": "markdown",
    "bookId": "book:tjnPbJakw",
    "status": "active",
    "share": "private",
    "title": "hello",
    "body": "example note",
    "tags": ["tag:HyBgJ94gx", "tag:h11OMPbSs"]
  }'

Response

{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "1-d882f96ee27f7b9f71f6183b0cab9193"
}
GET/books

List of all notebooks

Returns a list of all the Books in the local database.

Query parameters

  • Name
    limit
    Type
    number
    Description

    Limit the number of the returned documents to the specified number.

  • Name
    skip
    Type
    number
    Description

    Skip this number of documents before starting to return the results. Default is 0.

Request

GET
/books
curl "https://localhost:19840/books" \
  -H "Authorization: Basic {token}"

Response

[
  {
    "parentBookId": "book:Bk5Ivk0T",
    "updatedAt": 1598593031080,
    "createdAt": 1598593007103,
    "name": "Desktop app",
    "_id": "book:0cFae6lCc",
    "_rev": "2-7f29bee428d16b6f5a05ece8abf7f571"
  },
  ...
]
POST/books

Create/update a notebook

The POST method creates a new Book document, or update an existing document. The document ID _id is optional and will be automatically generated. If the notebook already exists, you must specify its revision _rev, otherwise a conflict will occur.

Response JSON Object

  • Name
    id
    Type
    string
    Description

    Document ID

  • Name
    ok
    Type
    boolean
    Description

    Operation status

  • Name
    rev
    Type
    string
    Description

    Revision MVCC token

Request

POST
/books
curl "https://localhost:19840/books" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {token}" \
  -d '{ "name": "New notebook" }'

Response

{
  "ok": true,
  "id": "book:Bk5Ivk0T",
  "rev": "1-7f29bee428d16b6f5a05ece8abf7f571"
}
GET/tags

List of all tags

Returns a list of all the Tags in the local database.

Query parameters

  • Name
    limit
    Type
    number
    Description

    Limit the number of the returned documents to the specified number.

  • Name
    skip
    Type
    number
    Description

    Skip this number of documents before starting to return the results. Default is 0.

Request

GET
/tags
curl "https://localhost:19840/tags" \
  -H "Authorization: Basic {token}"

Response

[
  {
    "count": 4,
    "color": "orange",
    "createdAt": 1489212448648,
    "updatedAt": 1607068381327,
    "name": "Lifehack",
    "_id": "tag:h11OMPbSs",
    "_rev": "3-bceb5835af6be6ae277762a877b884d1"
  },
  ...
]
POST/tags

Create/update a tag

The POST method creates a new Tag document, or update an existing tag. The document ID _id is optional and will be automatically generated. If the tag already exists, you must specify its revision _rev, otherwise a conflict will occur.

Response JSON Object

  • Name
    id
    Type
    string
    Description

    Document ID

  • Name
    ok
    Type
    boolean
    Description

    Operation status

  • Name
    rev
    Type
    string
    Description

    Revision MVCC token

Request

POST
/tags
curl "https://localhost:19840/tags" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {token}" \
  -d '{ "color": "red", "name": "Important" }'

Response

{
  "ok": true,
  "id": "tag:HyBgJ94gx",
  "rev": "1-e5ad1c150a30e1ad5a781755466b19a1"
}
GET/files

List of all files

Returns a list of all the Files in the local database.

Query parameters

  • Name
    limit
    Type
    number
    Description

    Limit the number of the returned documents to the specified number.

  • Name
    skip
    Type
    number
    Description

    Skip this number of documents before starting to return the results. Default is 0.

Request

GET
/files
curl "https://localhost:19840/files?limit=1" \
  -H "Authorization: Basic {token}"

Response

[
  {
    "name": "dog.png",
    "createdAt": 1613887605720,
    "contentType": "image/png",
    "contentLength": 10389,
    "publicIn": [],
    "_attachments": {
      "index": {
        "digest": "md5-if+yj7slT2E8u2JG7ee3yw==",
        "content_type": "image/png",
        "revpos": 5,
        "data": "iVBORw0K...AElFTkSuQmCC"
      }
    },
    "_id": "file:-dKJeWShi",
    "_rev": "5-541c58ffdbec966840709683c658c7dc"
  }
]
POST/files

Create a new file

The POST method creates a new File document, or creates a new revision of the existing document. The document ID _id is optional and will be automatically generated.

Response JSON Object

  • Name
    id
    Type
    string
    Description

    Document ID

  • Name
    ok
    Type
    boolean
    Description

    Operation status

  • Name
    rev
    Type
    string
    Description

    Revision MVCC token

Request

POST
/files
curl "https://localhost:19840/files" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {token}" \
  -d '{
    "name": "dog.png",
    "contentType": "image/png",
    "contentLength": 10389,
    "publicIn": [],
    "_attachments": {
      "index": {
        "content_type": "image/png",
        "data": "iVBORw0K...AElFTkSuQmCC"
      }
    }
  }'

Response

{
  "ok": true,
  "id": "file:HyBgJ94gx",
  "rev": "1-e5ad1c150a30e1ad5a781755466b19a1"
}
GET/note:{id}

Fetch a note

Returns the Note with the specified document ID.

{id} is the document _id without its note: prefix, so note:BKzzd8iGK is at /note:BKzzd8iGK — or /note/BKzzd8iGK.

If no note has that ID, an official note template with the same ID is returned instead, when one exists. Specifying rev skips that fallback.

Query parameters

All parameters are optional.

  • Name
    rev
    Type
    string
    Description

    Fetch specific revision of the note. Defaults to the latest revision.

  • Name
    attachments
    Type
    boolean
    Description

    Include attachment data.

Request

GET
/note:BKzzd8iGK
curl "https://localhost:19840/note:BKzzd8iGK" \
  -H "Authorization: Basic {token}"

Response

{
  "doctype": "markdown",
  "bookId": "book:tjnPbJakw",
  "createdAt": 1589165355584,
  "updatedAt": 1592532006000,
  "status": "active",
  "share": "private",
  "numOfTasks": 0,
  "numOfCheckedTasks": 0,
  "pinned": true,
  "title": "hello",
  "body": "example note",
  "tags": ["tag:HyBgJ94gx", "tag:h11OMPbSs"],
  "_id": "note:BKzzd8iGK",
  "_rev": "19-d882f96ee27f7b9f71f6183b0cab9193"
}
POST/note:{id}

Update a note

Updates the Note with the specified document ID.

{id} is the document _id without its note: prefix, so note:BKzzd8iGK is at /note:BKzzd8iGK — or /note/BKzzd8iGK. Unlike POST /notes, the request body only has to carry the fields you want to change. They are merged into the latest revision of the note, so you don't have to specify _rev.

Official note templates are read-only, so updating one responds with 403.

Response JSON Object

  • Name
    id
    Type
    string
    Description

    Document ID

  • Name
    ok
    Type
    boolean
    Description

    Operation status

  • Name
    rev
    Type
    string
    Description

    Revision MVCC token

Request

POST
/note:BKzzd8iGK
curl "https://localhost:19840/note:BKzzd8iGK" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {token}" \
  -d '{ "title": "hello again", "pinned": false }'

Response

{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "20-e5ad1c150a30e1ad5a781755466b19a1"
}
DELETE/note:{id}

Delete a note

Deletes the Note with the specified document ID.

{id} is the document _id without its note: prefix, so note:BKzzd8iGK is at /note:BKzzd8iGK — or /note/BKzzd8iGK.

This removes the note from the database immediately. It does not move it to the trash — set bookId to "trash" with POST /note:{id} if that's what you want.

Request

DELETE
/note:BKzzd8iGK
curl "https://localhost:19840/note:BKzzd8iGK" \
  -X DELETE \
  -H "Authorization: Basic {token}"

Response

{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "20-e5ad1c150a30e1ad5a781755466b19a1"
}
GET/book:{id}

Fetch a notebook

Returns the Book with the specified document ID.

{id} is the document _id without its book: prefix, so book:0cFae6lCc is at /book:0cFae6lCc — or /book/0cFae6lCc.

Query parameters

All parameters are optional.

  • Name
    rev
    Type
    string
    Description

    Fetch specific revision of the notebook. Defaults to the latest revision.

Request

GET
/book:0cFae6lCc
curl "https://localhost:19840/book:0cFae6lCc" \
  -H "Authorization: Basic {token}"

Response

{
  "parentBookId": "book:Bk5Ivk0T",
  "updatedAt": 1598593031080,
  "createdAt": 1598593007103,
  "name": "Desktop app",
  "_id": "book:0cFae6lCc",
  "_rev": "2-7f29bee428d16b6f5a05ece8abf7f571"
}
POST/book:{id}

Update a notebook

Updates the Book with the specified document ID.

{id} is the document _id without its book: prefix, so book:0cFae6lCc is at /book:0cFae6lCc — or /book/0cFae6lCc. Unlike POST /books, the request body only has to carry the fields you want to change. They are merged into the latest revision of the notebook, so you don't have to specify _rev.

Response JSON Object

  • Name
    id
    Type
    string
    Description

    Document ID

  • Name
    ok
    Type
    boolean
    Description

    Operation status

  • Name
    rev
    Type
    string
    Description

    Revision MVCC token

Request

POST
/book:0cFae6lCc
curl "https://localhost:19840/book:0cFae6lCc" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {token}" \
  -d '{ "name": "Desktop app (archived)" }'

Response

{
  "ok": true,
  "id": "book:0cFae6lCc",
  "rev": "3-7f29bee428d16b6f5a05ece8abf7f571"
}
DELETE/book:{id}

Delete a notebook

Deletes the Book with the specified document ID.

{id} is the document _id without its book: prefix, so book:0cFae6lCc is at /book:0cFae6lCc — or /book/0cFae6lCc. The notes in the notebook and in its child notebooks are moved to the trash, and the child notebooks are deleted too.

Request

DELETE
/book:0cFae6lCc
curl "https://localhost:19840/book:0cFae6lCc" \
  -X DELETE \
  -H "Authorization: Basic {token}"

Response

{
  "ok": true
}
GET/tag:{id}

Fetch a tag

Returns the Tag with the specified document ID.

{id} is the document _id without its tag: prefix, so tag:h11OMPbSs is at /tag:h11OMPbSs — or /tag/h11OMPbSs.

Query parameters

All parameters are optional.

  • Name
    rev
    Type
    string
    Description

    Fetch specific revision of the tag. Defaults to the latest revision.

Request

GET
/tag:h11OMPbSs
curl "https://localhost:19840/tag:h11OMPbSs" \
  -H "Authorization: Basic {token}"

Response

{
  "count": 4,
  "color": "orange",
  "createdAt": 1489212448648,
  "updatedAt": 1607068381327,
  "name": "Lifehack",
  "_id": "tag:h11OMPbSs",
  "_rev": "3-bceb5835af6be6ae277762a877b884d1"
}
POST/tag:{id}

Update a tag

Updates the Tag with the specified document ID.

{id} is the document _id without its tag: prefix, so tag:h11OMPbSs is at /tag:h11OMPbSs — or /tag/h11OMPbSs. Unlike POST /tags, the request body only has to carry the fields you want to change. They are merged into the latest revision of the tag, so you don't have to specify _rev.

Response JSON Object

  • Name
    id
    Type
    string
    Description

    Document ID

  • Name
    ok
    Type
    boolean
    Description

    Operation status

  • Name
    rev
    Type
    string
    Description

    Revision MVCC token

Request

POST
/tag:h11OMPbSs
curl "https://localhost:19840/tag:h11OMPbSs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic {token}" \
  -d '{ "color": "blue" }'

Response

{
  "ok": true,
  "id": "tag:h11OMPbSs",
  "rev": "4-bceb5835af6be6ae277762a877b884d1"
}
DELETE/tag:{id}

Delete a tag

Deletes the Tag with the specified document ID.

{id} is the document _id without its tag: prefix, so tag:h11OMPbSs is at /tag:h11OMPbSs — or /tag/h11OMPbSs. The tag is removed from every note that carries it before the tag document itself is deleted.

Request

DELETE
/tag:h11OMPbSs
curl "https://localhost:19840/tag:h11OMPbSs" \
  -X DELETE \
  -H "Authorization: Basic {token}"

Response

{
  "ok": true
}
GET/file:{id}

Fetch a file

Returns the File with the specified document ID.

{id} is the document _id without its file: prefix, so file:-dKJeWShi is at /file:-dKJeWShi — or /file/-dKJeWShi.

Query parameters

All parameters are optional.

  • Name
    rev
    Type
    string
    Description

    Fetch specific revision of the file. Defaults to the latest revision.

  • Name
    attachments
    Type
    boolean
    Description

    Include attachment data. It should be true if you want the content of the file.

Request

GET
/file:-dKJeWShi
curl "https://localhost:19840/file:-dKJeWShi?attachments=true" \
  -H "Authorization: Basic {token}"

Response

{
  "name": "dog.png",
  "createdAt": 1613887605720,
  "contentType": "image/png",
  "contentLength": 10389,
  "publicIn": [],
  "_attachments": {
    "index": {
      "digest": "md5-if+yj7slT2E8u2JG7ee3yw==",
      "content_type": "image/png",
      "revpos": 5,
      "data": "iVBORw0K...AElFTkSuQmCC"
    }
  },
  "_id": "file:-dKJeWShi",
  "_rev": "5-541c58ffdbec966840709683c658c7dc"
}
DELETE/file:{id}

Delete a file

Deletes the File with the specified document ID.

{id} is the document _id without its file: prefix, so file:-dKJeWShi is at /file:-dKJeWShi — or /file/-dKJeWShi. Notes that reference the file are not updated, so they end up with a broken image link.

Request

DELETE
/file:-dKJeWShi
curl "https://localhost:19840/file:-dKJeWShi" \
  -X DELETE \
  -H "Authorization: Basic {token}"

Response

{
  "ok": true,
  "id": "file:-dKJeWShi",
  "rev": "6-541c58ffdbec966840709683c658c7dc"
}
GET/_changes

Get changes made to documents

Returns a list of changes made to documents in the database, in the order they were made.

Query parameters

  • Name
    descending
    Type
    boolean
    Description

    Reverse the order of the output documents.

  • Name
    since
    Type
    number
    Description

    Start the results from the change immediately after the given sequence number.

  • Name
    limit
    Type
    number
    Description

    Limit the number of results to this number.

  • Name
    include_docs
    Type
    boolean
    Description

    Include the associated document with each change.

  • Name
    conflicts
    Type
    boolean
    Description

    Include conflicts.

  • Name
    attachments
    Type
    boolean
    Description

    Include attachments.

Note

seq and last_seq correspond to the overall sequence number of the entire database, and it’s what is passed in when using since. It is the primary key for the changes feed, and is also used as a checkpointer by the replication algorithm. The live option is not supported.

Request

GET
/_changes
curl "https://localhost:19840/_changes?limit=1&since=306" \
  -H "Authorization: Basic {token}"

Response

{
  "results": [
    {
      "id": "note:BkS41x0T",
      "changes": [
        {
          "rev": "2-4cd3d27dbda7cbd98cf8474970353460"
        }
      ],
      "doc": {
        "doctype": "markdown",
        "updatedAt": 1475375009783,
        "createdAt": 1475374892611,
        "bookId": "book:Bk5Ivk0T:HJu6tyRT",
        "status": "none",
        "migratedBy": "migrateAddingNumOfTasks",
        "numOfTasks": 0,
        "numOfCheckedTasks": 0,
        "title": "code diff",
        "body": "```\nhello\n```",
        "tags": [],
        "_id": "note:BkS41x0T",
        "_rev": "2-4cd3d27dbda7cbd98cf8474970353460"
      },
      "seq": 307
    }
  ],
  "last_seq": 307
}

Deleted Doc Response

{
  "results": [
    {
      "id": "note:coPJ4TB7u",
      "changes": [
        {
          "rev": "3-2396b4e8542389a6c464826fba8b9ef2"
        }
      ],
      "doc": {
        "_id": "note:coPJ4TB7u",
        "_rev": "3-2396b4e8542389a6c464826fba8b9ef2",
        "_deleted": true
      },
      "deleted": true,
      "seq": 200
    }
  ],
  "last_seq": 200
}
Can you help us improve the docs? 🙏

The source of these docs is here on GitHub. If you see a way these docs can be improved, please fork us!