Build with Micro.blog logo
Build with Micro.blog
API Documentation

Notes

View .md

Endpoints for notes and notebooks.

BASE URL https://micro.blog
POST /notes

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

Example Request

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

Query Parameters

Name Type Required Description
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

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns the created or updated note.

Example Response

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

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

Example Request

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

Query Parameters

Name Type Required Description
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

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns a JSON Feed response.

Example Response

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

Returns notebooks for the authenticated user in JSON Feed format.

Example Request

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

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns a JSON Feed response.

Example Response

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

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

Example Request

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

Query Parameters

Name Type Required Description
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

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns the created or updated notebook.

Example Response

{
  "id": 33,
  "name": "Test Notebook",
  "colors": {
    "light": "#ffffff",
    "dark": "#111827"
  }
}
DELETE /notes/notebooks/{id}

Deletes a notebook and its notes.

Example Request

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

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
id integer Required Resource identifier.
Example: 12345

Response

200 OK application/json

Returns an empty JSON object on success.

Example Response

{}
GET /notes/notebooks/{id}

Returns notes in a notebook in JSON Feed format.

Example Request

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

Query Parameters

Name Type Required Description
count integer Optional Maximum number of items to return.
Example: 60
offset integer Optional Number of items to skip before returning results.

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
id integer Required Identifier for the resource.
Example: 12345

Response

200 OK application/json

Returns a JSON Feed response.

Example Response

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

Deletes a note by ID.

Example Request

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

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
note_id integer Required Note identifier.
Example: 12345

Response

200 OK application/json

Returns an empty JSON object on success.

Example Response

{}
GET /notes/{note_id}

Returns a single note by ID.

Example Request

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

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
note_id integer Required Note identifier.
Example: 12345

Response

200 OK application/json

Returns a single note object.

Example Response

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

Returns note versions in JSON Feed format.

Example Request

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

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
note_id string Required note id parameter.
Example: example

Response

200 OK application/json

Returns a JSON Feed response.

Example Response

{
  "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": ""
      }
    }
  ]
}