Notes | Build with Micro.blog

POST


                          /notes

Creates a note, or updates one of the user’s notes when id is provided. Creating needs the create scope and updating needs update.

Note: Micro.blog doesn’t encrypt notes. Your app encrypts text before sending it and decrypts content_text after reading it. New notes are marked encrypted unless you send is_encrypted=0, so send it when text is plain text.

Example Request

curl -X POST "https://micro.blog/notes" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD" \
  --data-urlencode "text=Draft note text" \
  --data-urlencode "is_encrypted=0"

Header Parameters

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

Request Body

Name	Type	Required	Description
`text`	string	Required	Note text, encrypted by your app unless `is_encrypted` is `0`. Also required when updating, because it replaces the stored text. Example: `Draft note text`
`id`	integer	Optional	ID of the note to update. Leave it out to create a note. Example: `12345`
`notebook_id`	integer	Optional	Notebook for the note. Defaults to the Reading notebook when `attached_book_isbn` is set, and to the user’s default notebook otherwise. Returns 404 when the notebook isn’t the user’s. Example: `2`
`is_encrypted`	boolean	Optional	Whether `text` is encrypted. Defaults to `true` for new notes and to the current value when updating.
`attached_post_id`	integer	Optional	ID of a Micro.blog post to attach to the note. Send `0` to remove the attached post. Example: `77479242`
`attached_book_isbn`	string	Optional	ISBN of a book to attach the note to. Example: `9780143127796`
`is_sharing`	boolean	Optional	Publishes the note to the user’s default blog at a random URL, returned as `shared_url`. Any value turns sharing on, so leave it out otherwise. Example: `1`
`is_unsharing`	boolean	Optional	Removes a shared note from the blog. Any value turns sharing off. Example: `1`

Response

200 OK application/json

Returns the note. content_html is empty for encrypted notes. shared_url is empty unless the note is shared, and attached_book_title falls back to the ISBN when the book isn’t on the user’s bookshelves. Returns 403 with {"error": "..."} when a trial account without a payment method creates a note.

Example Response

{
  "id": 12345,
  "title": "",
  "content_text": "Draft note text",
  "content_html": "<p>Draft note text</p>\n",
  "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": false,
    "is_shared": false,
    "shared_url": "",
    "attached_book_isbn": "9780143127796",
    "attached_book_title": "The Book Title"
  }
}

POST


                          /notes/audio

Uploads an audio recording to be transcribed for a new note. Transcription runs in the background; poll GET /notes/audio for the text, then create the note with POST /notes. Requires a token with the media scope and AI features turned on for the account.

Note: Each account can upload 10 recordings a day. Audio must be 25 MB or smaller, in mp3, mp4, mpeg, mpga, m4a, wav, or webm format, taken from the file name’s extension. Tasks and their text are kept for 24 hours.

Example Request

curl -X POST "https://micro.blog/notes/audio" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD" \
  --form "file=@/path/to/recording.m4a"

Header Parameters

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

Request Body

Name	Type	Required	Description
`file`	file	Required	The audio recording, as a multipart file upload. Example: `@/path/to/recording.m4a`

Response

202 OK application/json

Returns the queued task, with Location pointing to GET /notes/audio. Errors return {"error": "..."} with 400 for a missing or empty file, 403 when AI features are off, 413 for a file over 25 MB, 415 for an unsupported format, 429 after the daily limit, and 503 when transcription is unavailable.

Example Response

{
  "id": "0123456789abcdef0123456789abcdef",
  "status": "queued",
  "format": "m4a",
  "created_at": "2026-04-26T12:00:00Z",
  "expires_at": "2026-04-27T12:00:00Z"
}

GET


                          /notes/audio

Lists the user’s audio transcription tasks from the last 24 hours, most recently updated first. Requires a token with the read scope.

Example Request

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

Header Parameters

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

Response

200 OK application/json

status is queued, processing, completed, or failed. Completed tasks include text and failed tasks include error. Returns 503 with {"error": "..."} when the status is unavailable.

Example Response

{
  "tasks": [
    {
      "id": "0123456789abcdef0123456789abcdef",
      "status": "completed",
      "format": "m4a",
      "created_at": "2026-04-26T12:00:00Z",
      "expires_at": "2026-04-27T12:01:00Z",
      "text": "Remember to pick up the book from the library."
    }
  ]
}

GET


                          /notes/for_book

Returns the user’s notes attached to a book, most recently updated first, in JSON Feed format. Requires a token with the read scope.

Example Request

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

Query Parameters

Name	Type	Required	Description
`isbn`	string	Required	Book ISBN. Example: `9780143127796`
`count`	integer	Optional	Maximum number of notes to return. Example: `20`
`offset`	integer	Optional	Number of notes to skip. Example: `20`

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 whose items are notes, in the same shape as GET /notes/{note_id}. Returns 400 without isbn.

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": "<p>Notes about this chapter.</p>\n",
      "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": false,
        "is_shared": false,
        "shared_url": "",
        "attached_book_isbn": "9780143127796",
        "attached_book_title": "The Book Title"
      }
    }
  ]
}

GET


                          /notes/notebooks

Returns the user’s notebooks in JSON Feed format, creating a default notebook first if the user has none. Requires a token with the read scope.

Example Request

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

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 whose items are notebooks. title is the notebook name. _microblog.type is reading for the Reading notebook and empty or null for others.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Notebooks",
  "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 renames or recolours one of the user’s notebooks when id is provided. Creating needs the create scope and updating needs update.

Example Request

curl -X POST "https://micro.blog/notes/notebooks" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD" \
  --data-urlencode "name=Ideas"

Header Parameters

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

Request Body

Name	Type	Required	Description
`name`	string	Optional	Notebook name. Required unless `color_light` is sent. Example: `Ideas`
`id`	integer	Optional	ID of the notebook to update. Leave it out to create a notebook. Example: `33`
`color_light`	string	Optional	Notebook colour in light mode. New notebooks get a random colour. Example: `#ffffff`
`color_dark`	string	Optional	Notebook colour in dark mode. Example: `#111827`

Response

200 OK application/json

Returns the notebook. When neither name nor color_light is sent, nothing is saved and the status is still 200, with {"error": "Notebook name cannot be blank."}.

Example Response

{
  "id": 33,
  "name": "Ideas",
  "colors": {
    "light": "#ffffff",
    "dark": "#111827"
  }
}

DELETE


                          /notes/notebooks/{id}

Deletes one of the user’s notebooks and every note in it. Requires a token with the delete scope.

Example Request

curl -X DELETE "https://micro.blog/notes/notebooks/33" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

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	Notebook ID. Example: `33`

Response

200 OK application/json

Returns an empty JSON object, also when the notebook doesn’t exist or belongs to someone else.

Example Response

{}

GET


                          /notes/notebooks/{id}

Returns the notes in one of the user’s notebooks, most recently updated first, in JSON Feed format. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/notes/notebooks/2?count=60" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name	Type	Required	Description
`count`	integer	Optional	Maximum number of notes to return. Example: `60`
`offset`	integer	Optional	Number of notes to skip. Example: `60`

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	Notebook ID. Example: `2`

Response

200 OK application/json

Returns a JSON Feed whose items are notes, in the same shape as GET /notes/{note_id}, with the notebook under _microblog.notebook. Returns 404 when the notebook isn’t found.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Notes",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/notes/notebooks/2",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "notebook": {
      "id": 2,
      "name": "Reading",
      "colors": {
        "light": "#ffffff",
        "dark": "#111827"
      }
    }
  },
  "items": [
    {
      "id": 12345,
      "title": "",
      "content_text": "ENCRYPTED_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": "The Book Title"
      }
    }
  ]
}

DELETE


                          /notes/{note_id}

Deletes one of the user’s notes, removing it from the blog first if it was shared. Requires a token with the delete scope.

Example Request

curl -X DELETE "https://micro.blog/notes/12345" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

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 ID. Example: `12345`

Response

200 OK application/json

Returns an empty JSON object, also when the note doesn’t exist or belongs to someone else.

Example Response

{}

GET


                          /notes/{note_id}

Returns one of the user’s notes. Requires a token with the read scope.

Example Request

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

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 ID. Example: `12345`

Response

200 OK application/json

Returns the note. For encrypted notes, content_text holds the encrypted text and content_html is empty. Returns 404 when the note isn’t found.

Example Response

{
  "id": 12345,
  "title": "",
  "content_text": "Draft note text",
  "content_html": "<p>Draft note text</p>\n",
  "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": false,
    "is_shared": true,
    "shared_url": "https://example.micro.blog/notes/0123456789abcdef0123456789abcd.html",
    "attached_book_isbn": "9780143127796",
    "attached_book_title": "The Book Title"
  }
}

GET


                          /notes/{note_id}/versions

Returns every saved version of one of the user’s notes, including the current text, newest first, in JSON Feed format. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/notes/12345/versions" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

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 ID. Example: `12345`

Response

200 OK application/json

Returns a JSON Feed whose items are versions. Each item’s id is the version ID, url points to the note, and content_html is always empty. Returns 404 when the note isn’t found.

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": false,
        "is_shared": false,
        "shared_url": ""
      }
    }
  ]
}