Skip to content

Changes to PATCH requests between versions 2.0 and 3.0

Jump to bottom
Adam Coddington edited this page Nov 17, 2024 · 1 revision

This API was changed in version 3.0 of Obsidian Local REST API to support making changes to your document relative to "block references" and frontmatter fields in addition to headings within your document. Version 2.0 of this API (now undocumented) is still accessible as long as your incoming request specifies the Heading header and does not specify a Target-Type header. You should upgrade to the current version of the API as soon as possible. Support for the Version 2.0 API is now deprecated and no longer be available in Version 4.0.

You can migrate to the current version of the API by following the below guidelines. The words "heading" and "header" both occur quite a lot in the below paragraphs so it may aid in your understanding if you keep in mind that "heading" here refers to a heading existing within your markdown document and "header" refers to an HTTP Header that you may set to a value as part of using this API.

  1. Rename your Heading header to Target.
  2. Add a new Target-Type header having the value heading.
  3. Set the Operation header such that its value is append if you had either not set the Content-Insertion-Position header or had set it to end. Set it to prepend if you had set Content-Insertion-Position to beginning.
  4. If you had set Content-Insertion-Ignore-Newline to true, set the Trim-Target-Whitespace header value to true also.

Aside from the above, there is one important thing to keep in mind: while the obsolete version of this API allowed you to specify just the terminal heading (e.g. content under ### My Heading could be addressed by setting the Heading header to My Heading), the current version of this API requires that you provide the full path to your target heading (i.e. instead of My Heading, you must find the parent second level heading and and its parent top level heading) delimited by ::. If :: appears in your heading, you can override that value by setting the Target-Delimiter header.

For example, if you had previously set Heading to My Heading for adding content to "MY CONTENT" in a document like:

# Some top-level heading

## Some second-level heading

### My Heading

MY CONTENT

you should now set your Target heading to Some top-level heading::Some second-level heading::My Heading.

Clone this wiki locally