# Notes

Page: https://microblog.dev/api/notes/
API base URL: https://micro.blog

Endpoints for notes and notebooks.

## Endpoints
### POST /notes

URL: `https://micro.blog/notes`

Creates a note, or updates an existing note when `id` is provided.




Query parameters:
- `id` (integer, optional): Identifier for the resource.
  Example: `12345`
- `text` (string, required): Text content.
  Example: `Draft note text`
- `attached_post_id` (integer, optional): Post ID to attach to the note.
  Example: `77479242`
- `attached_book_isbn` (string, optional): Book ISBN to attach to the note.
  Example: `9780143127796`
- `notebook_id` (integer, optional): Notebook ID for the note.
  Example: `2`
- `is_encrypted` (boolean, optional): Whether the note is encrypted.
  Example: `1`
- `is_sharing` (boolean, optional): Set to share the note publicly.
  Example: `1`
- `is_unsharing` (boolean, optional): Set to stop sharing a note.
  Example: `1`



Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X POST "https://micro.blog/notes?text=Draft+note+text" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns the created or updated note.
Example response:

```json
{
  "id": 12345,
  "title": "",
  "content_text": "Draft note text",
  "content_html": "",
  "url": "https://micro.blog/notes/12345",
  "date_published": "2026-04-26T12:00:00+00:00",
  "date_modified": "2026-04-26T12:00:00+00:00",
  "_microblog": {
    "is_encrypted": true,
    "is_shared": false,
    "shared_url": "",
    "attached_book_isbn": "9780143127796",
    "attached_book_title": "Book title"
  }
}
```

### GET /notes/for_book

URL: `https://micro.blog/notes/for_book`

Returns notes attached to a book ISBN in JSON Feed format.




Query parameters:
- `isbn` (string, required): Book ISBN.
  Example: `9780143127796`
- `count` (integer, optional): count parameter.
  Example: `example`
- `offset` (integer, optional): Number of items to skip before returning results.



Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X GET "https://micro.blog/notes/for_book?isbn=9780143127796" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns a JSON Feed response.
Example response:

```json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Notes for Book",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/notes/for_book?isbn=9780143127796",
  "items": [
    {
      "id": 12345,
      "title": "",
      "content_text": "Notes about this chapter.",
      "content_html": "",
      "url": "https://micro.blog/notes/12345",
      "date_published": "2026-04-26T12:00:00+00:00",
      "date_modified": "2026-04-26T12:30:00+00:00",
      "_microblog": {
        "is_encrypted": true,
        "is_shared": false,
        "shared_url": "",
        "attached_book_isbn": "9780143127796",
        "attached_book_title": "Book title"
      }
    }
  ]
}
```

### GET /notes/notebooks

URL: `https://micro.blog/notes/notebooks`

Returns notebooks for the authenticated user in JSON Feed format.






Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X GET "https://micro.blog/notes/notebooks" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns a JSON Feed response.
Example response:

```json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/notes/notebooks",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": 2,
      "title": "Reading",
      "content_text": "",
      "url": "https://micro.blog/notes/notebooks/2",
      "date_published": "2026-04-26T12:00:00+00:00",
      "_microblog": {
        "type": "reading",
        "colors": {
          "light": "#ffffff",
          "dark": "#111827"
        }
      }
    }
  ]
}
```

### POST /notes/notebooks

URL: `https://micro.blog/notes/notebooks`

Creates a notebook or updates an existing notebook when `id` is provided.




Query parameters:
- `name` (string, optional): Title or notebook name, depending on the endpoint.
  Example: `Test Notebook`
- `id` (integer, optional): Identifier for the resource.
  Example: `33`
- `color_light` (string, optional): Light-mode notebook colour.
  Example: `#ffffff`
- `color_dark` (string, optional): Dark-mode notebook colour.
  Example: `#111827`



Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X POST "https://micro.blog/notes/notebooks" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns the created or updated notebook.
Example response:

```json
{
  "id": 33,
  "name": "Test Notebook",
  "colors": {
    "light": "#ffffff",
    "dark": "#111827"
  }
}
```

### DELETE /notes/notebooks/{id}

URL: `https://micro.blog/notes/notebooks/{id}`

Deletes a notebook and its notes.


Path parameters:
- `id` (integer, required): Resource identifier.
  Example: `12345`





Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X DELETE "https://micro.blog/notes/notebooks/{id}" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns an empty JSON object on success.
Example response:

```json
{}
```

### GET /notes/notebooks/{id}

URL: `https://micro.blog/notes/notebooks/{id}`

Returns notes in a notebook in JSON Feed format.


Path parameters:
- `id` (integer, required): Identifier for the resource.
  Example: `12345`



Query parameters:
- `count` (integer, optional): Maximum number of items to return.
  Example: `60`
- `offset` (integer, optional): Number of items to skip before returning results.



Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X GET "https://micro.blog/notes/notebooks/{id}" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns a JSON Feed response.
Example response:

```json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/notes/notebooks/{id}",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "notebook": {
      "id": 2,
      "name": "Reading",
      "colors": {
        "light": "#ffffff",
        "dark": "#111827"
      }
    }
  },
  "items": [
    {
      "id": 12345,
      "title": "",
      "content_text": "Notes about this chapter.",
      "content_html": "",
      "url": "https://micro.blog/notes/12345",
      "date_published": "2026-04-26T12:00:00+00:00",
      "date_modified": "2026-04-26T12:30:00+00:00",
      "_microblog": {
        "is_encrypted": true,
        "is_shared": false,
        "shared_url": "",
        "attached_book_isbn": "9780143127796",
        "attached_book_title": "Book title"
      }
    }
  ]
}
```

### DELETE /notes/{note_id}

URL: `https://micro.blog/notes/{note_id}`

Deletes a note by ID.


Path parameters:
- `note_id` (integer, required): Note identifier.
  Example: `12345`





Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X DELETE "https://micro.blog/notes/{note_id}" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns an empty JSON object on success.
Example response:

```json
{}
```

### GET /notes/{note_id}

URL: `https://micro.blog/notes/{note_id}`

Returns a single note by ID.


Path parameters:
- `note_id` (integer, required): Note identifier.
  Example: `12345`





Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X GET "https://micro.blog/notes/{note_id}" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns a single note object.
Example response:

```json
{
  "id": 12345,
  "title": "",
  "content_text": "Draft note text",
  "content_html": "",
  "url": "https://micro.blog/notes/12345",
  "date_published": "2026-04-26T12:00:00+00:00",
  "date_modified": "2026-04-26T12:30:00+00:00",
  "_microblog": {
    "is_encrypted": true,
    "is_shared": false,
    "shared_url": "",
    "attached_book_isbn": "9780143127796",
    "attached_book_title": "Book title"
  }
}
```

### GET /notes/{note_id}/versions

URL: `https://micro.blog/notes/{note_id}/versions`

Returns note versions in JSON Feed format.


Path parameters:
- `note_id` (string, required): note id parameter.
  Example: `example`





Header parameters:
- `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`.
  Example: `Bearer EF7BB9BCAC1F6D561C93`




Example request:

```sh
curl -X GET "https://micro.blog/notes/{note_id}/versions" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"
```

Response:
- Status: 200
- Content-Type: `application/json`
- Description: Returns a JSON Feed response.
Example response:

```json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Versions",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/notes/12345/versions",
  "items": [
    {
      "id": 987,
      "title": "",
      "content_text": "Earlier note text",
      "content_html": "",
      "url": "https://micro.blog/notes/12345",
      "date_published": "2026-04-26T11:30:00+00:00",
      "_microblog": {
        "is_encrypted": true,
        "is_shared": false,
        "shared_url": ""
      }
    }
  ]
}
```