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.

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 a new note

The POST method creates a new Note 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

/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 a new notebook

The POST method creates a new Book 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

/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 a new tag

The POST method creates a new Tag 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

/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/:docid

Fetch a document by ID

Returns document by the specified docid of Note, Book, Tag, or File.

Query parameters

All parameters are optional.

Name
rev
Type
string
Description
Fetch specific revision of a document. Defaults to the latest revision.
Name
attachments
Type
boolean
Description
Include attachment data. It should be true if you fetch a content of the file document.

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

DELETE/:docid

Delete a document by ID

Deletes document by the specified docid of Note, Book, Tag, or File.

Request

DELETE

/note:BKzzd8iGK

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

Response

{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "2-e5ad1c150a30e1ad5a781755466b19a1"
}

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
}