# Local HTTP Server

Source: https://developers.inkdrop.app/data-access/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](https://developers.inkdrop.app/guides/integrate-with-external-programs) to learn how to configure the local HTTP server.

---

## Get the server information `GET /`

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

### Parameters

No parameters

```bash title="cURL"
curl -G https://localhost:19840/ \
  -H "Authorization: Basic {token}"
```

---

## List of all notes `GET /notes`

Returns a list of all the [Notes](https://developers.inkdrop.app/data-access/notes#properties) in the local database.

### Query parameters

- **keyword** (string)

  The search keyword to filter notes. You can use the same qualifiers for searching notes.
- **limit** (number)

  Limit the number of the returned documents to the specified number. Default is `50`.
- **skip** (number)

  Skip this number of documents before starting to return the results. Default is `0`.
- **sort** (string)

  Sort the documents by the specified field. One of: `'updatedAt'`, `'createdAt'`, `'title'`, `'tagCount'`.
  With `keyword`, you can also specify `'rank'` to sort by relevance, as long as the keyword contains words to match rather than only qualifiers such as `book:` or `tag:`.
- **descending** (boolean)

  Reverse the order of the output documents.

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

```json title="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"
  }
]
```

---

## Create/update a note `POST /notes`

The POST method creates a new [Note](https://developers.inkdrop.app/data-access/notes#properties), 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

- **id** (string)

  Document ID
- **ok** (boolean)

  Operation status
- **rev** (string)

  Revision MVCC token

```bash title="cURL"
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"]
  }'
```

```json title="Response"
{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "1-d882f96ee27f7b9f71f6183b0cab9193"
}
```

---

## List of all notebooks `GET /books`

Returns a list of all the [Books](https://developers.inkdrop.app/data-access/books#properties) in the local database.

### Query parameters

- **limit** (number)

  Limit the number of the returned documents to the specified number.
- **skip** (number)

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

```bash title="cURL"
curl "https://localhost:19840/books" \
  -H "Authorization: Basic {token}"
```

```json title="Response"
[
  {
    "parentBookId": "book:Bk5Ivk0T",
    "updatedAt": 1598593031080,
    "createdAt": 1598593007103,
    "name": "Desktop app",
    "_id": "book:0cFae6lCc",
    "_rev": "2-7f29bee428d16b6f5a05ece8abf7f571"
  },
  ...
]
```

---

## Create/update a notebook `POST /books`

The POST method creates a new [Book](https://developers.inkdrop.app/data-access/books#properties) 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

- **id** (string)

  Document ID
- **ok** (boolean)

  Operation status
- **rev** (string)

  Revision MVCC token

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

```json title="Response"
{
  "ok": true,
  "id": "book:Bk5Ivk0T",
  "rev": "1-7f29bee428d16b6f5a05ece8abf7f571"
}
```

---

## List of all tags `GET /tags`

Returns a list of all the [Tags](https://developers.inkdrop.app/data-access/tags#properties) in the local database.

### Query parameters

- **limit** (number)

  Limit the number of the returned documents to the specified number.
- **skip** (number)

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

```bash title="cURL"
curl "https://localhost:19840/tags" \
  -H "Authorization: Basic {token}"
```

```json title="Response"
[
  {
    "color": "orange",
    "createdAt": 1489212448648,
    "updatedAt": 1607068381327,
    "name": "Lifehack",
    "_id": "tag:h11OMPbSs",
    "_rev": "3-bceb5835af6be6ae277762a877b884d1"
  },
  ...
]
```

---

## Create/update a tag `POST /tags`

The POST method creates a new [Tag](https://developers.inkdrop.app/data-access/tags#properties) 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

- **id** (string)

  Document ID
- **ok** (boolean)

  Operation status
- **rev** (string)

  Revision MVCC token

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

```json title="Response"
{
  "ok": true,
  "id": "tag:HyBgJ94gx",
  "rev": "1-e5ad1c150a30e1ad5a781755466b19a1"
}
```

---

## List of all files `GET /files`

Returns a list of all the [Files](https://developers.inkdrop.app/data-access/files) in the local database.

### Query parameters

- **limit** (number)

  Limit the number of the returned documents to the specified number.
- **skip** (number)

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

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

```json title="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"
  }
]
```

---

## Create a new file `POST /files`

The POST method creates a new [File](https://developers.inkdrop.app/data-access/files) document, or creates a new revision of the existing document.
The document ID `_id` is optional and will be automatically generated.

### Response JSON Object

- **id** (string)

  Document ID
- **ok** (boolean)

  Operation status
- **rev** (string)

  Revision MVCC token

```bash title="cURL"
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"
      }
    }
  }'
```

```json title="Response"
{
  "ok": true,
  "id": "file:HyBgJ94gx",
  "rev": "1-e5ad1c150a30e1ad5a781755466b19a1"
}
```

---

## Fetch a note `GET /note:{id}`

Returns the [Note](https://developers.inkdrop.app/data-access/notes#properties) 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.

- **rev** (string)

  Fetch specific revision of the note. Defaults to the latest revision.
- **attachments** (boolean)

  Include attachment data.

```bash title="cURL"
curl "https://localhost:19840/note:BKzzd8iGK" \
  -H "Authorization: Basic {token}"
```

```json title="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"
}
```

---

## Update a note `POST /note:{id}`

Updates the [Note](https://developers.inkdrop.app/data-access/notes#properties) 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`](#create-update-a-note), 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

- **id** (string)

  Document ID
- **ok** (boolean)

  Operation status
- **rev** (string)

  Revision MVCC token

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

```json title="Response"
{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "20-e5ad1c150a30e1ad5a781755466b19a1"
}
```

---

## Delete a note `DELETE /note:{id}`

Deletes the [Note](https://developers.inkdrop.app/data-access/notes#properties) with the specified document ID.

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

> **Warning:**
>
> This removes the note from the database immediately.
> It does not move it to the trash — set `bookId` to `"trash"` with [`POST /note:{id}`](#update-a-note) if that's what you want.

```bash title="cURL"
curl "https://localhost:19840/note:BKzzd8iGK" \
  -X DELETE \
  -H "Authorization: Basic {token}"
```

```json title="Response"
{
  "ok": true,
  "id": "note:BKzzd8iGK",
  "rev": "20-e5ad1c150a30e1ad5a781755466b19a1"
}
```

---

## Fetch a notebook `GET /book:{id}`

Returns the [Book](https://developers.inkdrop.app/data-access/books#properties) 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.

- **rev** (string)

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

```bash title="cURL"
curl "https://localhost:19840/book:0cFae6lCc" \
  -H "Authorization: Basic {token}"
```

```json title="Response"
{
  "parentBookId": "book:Bk5Ivk0T",
  "updatedAt": 1598593031080,
  "createdAt": 1598593007103,
  "name": "Desktop app",
  "_id": "book:0cFae6lCc",
  "_rev": "2-7f29bee428d16b6f5a05ece8abf7f571"
}
```

---

## Update a notebook `POST /book:{id}`

Updates the [Book](https://developers.inkdrop.app/data-access/books#properties) 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`](#create-update-a-notebook), 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

- **id** (string)

  Document ID
- **ok** (boolean)

  Operation status
- **rev** (string)

  Revision MVCC token

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

```json title="Response"
{
  "ok": true,
  "id": "book:0cFae6lCc",
  "rev": "3-7f29bee428d16b6f5a05ece8abf7f571"
}
```

---

## Delete a notebook `DELETE /book:{id}`

Deletes the [Book](https://developers.inkdrop.app/data-access/books#properties) 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.

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

```json title="Response"
{
  "ok": true
}
```

---

## Fetch a tag `GET /tag:{id}`

Returns the [Tag](https://developers.inkdrop.app/data-access/tags#properties) 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.

- **rev** (string)

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

```bash title="cURL"
curl "https://localhost:19840/tag:h11OMPbSs" \
  -H "Authorization: Basic {token}"
```

```json title="Response"
{
  "color": "orange",
  "createdAt": 1489212448648,
  "updatedAt": 1607068381327,
  "name": "Lifehack",
  "_id": "tag:h11OMPbSs",
  "_rev": "3-bceb5835af6be6ae277762a877b884d1"
}
```

---

## Update a tag `POST /tag:{id}`

Updates the [Tag](https://developers.inkdrop.app/data-access/tags#properties) 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`](#create-update-a-tag), 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

- **id** (string)

  Document ID
- **ok** (boolean)

  Operation status
- **rev** (string)

  Revision MVCC token

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

```json title="Response"
{
  "ok": true,
  "id": "tag:h11OMPbSs",
  "rev": "4-bceb5835af6be6ae277762a877b884d1"
}
```

---

## Delete a tag `DELETE /tag:{id}`

Deletes the [Tag](https://developers.inkdrop.app/data-access/tags#properties) 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.

```bash title="cURL"
curl "https://localhost:19840/tag:h11OMPbSs" \
  -X DELETE \
  -H "Authorization: Basic {token}"
```

```json title="Response"
{
  "ok": true
}
```

---

## Fetch a file `GET /file:{id}`

Returns the [File](https://developers.inkdrop.app/data-access/files) 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.

- **rev** (string)

  Fetch specific revision of the file. Defaults to the latest revision.
- **attachments** (boolean)

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

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

```json title="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 a file `DELETE /file:{id}`

Deletes the [File](https://developers.inkdrop.app/data-access/files) 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.

```bash title="cURL"
curl "https://localhost:19840/file:-dKJeWShi" \
  -X DELETE \
  -H "Authorization: Basic {token}"
```

```json title="Response"
{
  "ok": true,
  "id": "file:-dKJeWShi",
  "rev": "6-541c58ffdbec966840709683c658c7dc"
}
```

---

## Get changes made to documents `GET /_changes`

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

### Query parameters

- **descending** (boolean)

  Reverse the order of the output documents.
- **since** (number)

  Start the results from the change immediately after the given sequence number.
- **limit** (number)

  Limit the number of results to this number.
- **include\_docs** (boolean)

  Include the associated document with each change.
- **conflicts** (boolean)

  Include conflicts.
- **attachments** (boolean)

  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.

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

````json title="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
}
````

```json title="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
}
```