Developers

Local HTTP Server

Source

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/: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
}
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!