### Tag message format example

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/AGENTS.md

Example of the required format for Git tag messages, including a subject line and bulleted list of changes.

```text
Release X.Y.Z

- Adds/Fixes/Updates/Removes [description of change]. (#issue if applicable; Thanks @contributor if applicable.)
- Adds/Fixes/Updates/Removes [description of change].

```

--------------------------------

### GET /commands/ — List available Obsidian commands

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Returns all commands that can be executed via Obsidian's command palette, with their IDs and display names.

```APIDOC
## GET /commands/

### Description
Returns all commands that can be executed via Obsidian's command palette, with their IDs and display names.

### Method
GET

### Endpoint
/commands/

### Response
#### Success Response (200)
- **commands** (array) - An array of command objects.
  - **id** (string) - The unique identifier for the command.
  - **name** (string) - The display name of the command.
```

--------------------------------

### GET /vault/ and GET /vault/{pathToDirectory}/ — List vault files and directories

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Lists all files and subdirectories at the vault root or within a given directory path. Directories are returned with a trailing `/`. Empty directories are not returned.

```APIDOC
## GET /vault/ and GET /vault/{pathToDirectory}/

### Description
Lists all files and subdirectories at the vault root or within a given directory path. Directories are returned with a trailing `/`. Empty directories are not returned.

### Method
GET

### Endpoint
/vault/
/vault/{pathToDirectory}/

### Parameters
#### Path Parameters
- **pathToDirectory** (string) - Optional. The path to the directory within the vault to list. If omitted, lists the vault root.

### Request Example
```bash
API_KEY="YOUR_API_KEY"

# List vault root
curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/vault/

# List a subdirectory
curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/vault/projects/
```

### Response
#### Success Response (200)
- **files** (array of strings) - A list of files and directories within the specified path. Directories have a trailing '/'.

#### Response Example
```json
{ "files": ["daily/", "projects/", "README.md", "index.md"] }
```
```

--------------------------------

### GET / — Server status and authentication check

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Returns basic server metadata and indicates whether the current request is authenticated. This is the only endpoint that does not require an API key.

```APIDOC
## GET /

### Description
Returns basic server metadata and indicates whether the current request is authenticated. This is the only endpoint that does not require an API key.

### Method
GET

### Endpoint
/

### Request Example
```bash
# Check server liveness (no auth required)
curl -k https://127.0.0.1:27124/

# With a valid API key
curl -k -H "Authorization: Bearer YOUR_API_KEY" https://127.0.0.1:27124/
```

### Response
#### Success Response (200)
- **ok** (string) - Server status indicator, typically "OK".
- **authenticated** (boolean) - Indicates if the request was authenticated.
- **service** (string) - Name of the service.
- **versions** (object) - Object containing version information.
  - **obsidian** (string) - Obsidian version.
  - **self** (string) - Plugin version.

#### Response Example
```json
{
  "ok": "OK",
  "authenticated": false,
  "service": "Obsidian Local REST API",
  "versions": {
    "obsidian": "1.7.4",
    "self": "3.6.1"
  }
}
```
```

--------------------------------

### Get Document Structure

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/docs/src/lib/descriptions/patch.md

Retrieve a JSON object detailing the headings, block references, and frontmatter fields within a document by making a GET request with a specific Accept header.

```http
GET /vault/files/{path} HTTP/1.1
Accept: application/vnd.olrapi.document-map+json
```

--------------------------------

### Get Specific Date's Periodic Note with GET /periodic/{period}/{year}/{month}/{day}/

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Retrieve a periodic note for a specific date, including daily, weekly, monthly, quarterly, or yearly notes. The API key is required for authentication.

```bash
API_KEY="YOUR_API_KEY"

```

--------------------------------

### GET /active/ — Read the currently open file

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Retrieves the content or metadata of the currently active note in Obsidian. It supports the same targeting and Accept header options as `GET /vault/{filename}`.

```APIDOC
## GET /active/ — Read the currently open file

### Description
Returns the content or metadata of whichever note is currently active in Obsidian. Supports the same targeting and Accept header options as `GET /vault/{filename}`.

### Method
GET

### Endpoint
/active/

### Headers
- **Authorization**: Bearer YOUR_API_KEY
- **Accept**: application/vnd.olrapi.note+json (optional, for JSON response)
- **Target-Type**: heading (optional, for targeting specific sections)
- **Target**: Section Name (optional, used with Target-Type)

### Response Example (Raw Markdown)
```markdown
# Content of the active note
```

### Response Example (JSON)
```json
{
  "content": "# Content of the active note"
}
```
```

--------------------------------

### Get Periodic Note with GET /periodic/{period}/

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Retrieve the current daily, weekly, monthly, quarterly, or yearly note. Supports reading as markdown or JSON, and targeting specific headings. The note will be created if it doesn't exist when using POST.

```bash
API_KEY="YOUR_API_KEY"

# Get today's daily note as markdown
curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/periodic/daily/
```

```bash
# Get today's daily note as JSON
curl -k \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/vnd.olrapi.note+json" \
  https://127.0.0.1:27124/periodic/daily/
```

```bash
# Get current weekly note, reading only the "Tasks" heading
curl -k \
  -H "Authorization: Bearer $API_KEY" \
  -H "Target-Type: heading" \
  -H "Target: Tasks" \
  https://127.0.0.1:27124/periodic/weekly/
```

--------------------------------

### Get Daily Note for a Specific Date

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Retrieves the daily note for a specified date. Ensure the API key is set in the environment variable `API_KEY`.

```bash
curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/periodic/daily/2024/01/15/
```

--------------------------------

### Get Note Metadata

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/docs/src/lib/descriptions/get-shared.md

Retrieve a JSON representation of your note, including parsed tag and frontmatter data, along with filesystem metadata. This is achieved by setting the `Accept` header to `application/vnd.olrapi.note+json`.

```APIDOC
## GET /notes/{noteId}

### Description
Retrieves a JSON representation of a specific note, including parsed tag and frontmatter data, as well as filesystem metadata.

### Method
GET

### Endpoint
/notes/{noteId}

### Headers
- **Accept**: application/vnd.olrapi.note+json

### Response
#### Success Response (200)
- **metadata** (object) - Contains parsed tag, frontmatter, and filesystem metadata.

### Response Example
```json
{
  "metadata": {
    "tags": ["tag1", "tag2"],
    "frontmatter": {
      "key": "value"
    },
    "filesystem": {
      "createdAt": "2023-10-27T10:00:00Z",
      "modifiedAt": "2023-10-27T10:00:00Z"
    }
  }
}
```
```

--------------------------------

### Read Active Note Content with GET /active/

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Retrieve the raw markdown, rich JSON object, or a specific heading from the currently active note in Obsidian. Ensure your API key is set.

```bash
API_KEY="YOUR_API_KEY"

# Get raw markdown of the active note
curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/active/
```

```bash
# Get the active note as a rich JSON object
curl -k \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/vnd.olrapi.note+json" \
  https://127.0.0.1:27124/active/
```

```bash
# Read a specific heading from the active note
curl -k \
  -H "Authorization: Bearer $API_KEY" \
  -H "Target-Type: heading" \
  -H "Target: Today's Tasks" \
  https://127.0.0.1:27124/active/
```

--------------------------------

### GET /tags/ — List all tags with usage counts

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Returns every tag used across the vault (from inline `#tag` syntax and frontmatter), without the `#` prefix. Hierarchical tags (e.g. `work/tasks`) also increment all parent prefixes (e.g. `work`).

```APIDOC
## GET /tags/

### Description
Returns every tag used across the vault (from inline `#tag` syntax and frontmatter), without the `#` prefix. Hierarchical tags (e.g. `work/tasks`) also increment all parent prefixes (e.g. `work`).

### Method
GET

### Endpoint
/tags/

### Response
#### Success Response (200)
- **tags** (array) - An array of tag objects.
  - **name** (string) - The name of the tag.
  - **count** (integer) - The number of times the tag is used.
```

--------------------------------

### GET /vault/{filename} — Read a vault file

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Returns the raw content of any file as text/markdown, as a rich JSON object, or as a document map of patchable targets. Supports sub-document targeting via headers or URL path segments.

```APIDOC
## GET /vault/{filename}

### Description
Returns the raw content of any file as `text/markdown` (default), as a rich JSON object (`application/vnd.olrapi.note+json`), or as a document map of patchable targets (`application/vnd.olrapi.document-map+json`). Supports sub-document targeting via headers or URL path segments.

### Method
GET

### Endpoint
/vault/{filename}

### Parameters
#### Path Parameters
- **filename** (string) - Required. The path to the file within the vault.

#### Headers
- **Accept** (string) - Optional. Specifies the desired response format. Defaults to `text/markdown`. Use `application/vnd.olrapi.note+json` for metadata or `application/vnd.olrapi.document-map+json` for patchable targets.
- **Target-Type** (string) - Optional. Used with `Target` header to specify the type of sub-document to retrieve (e.g., `heading`, `block`, `frontmatter`).
- **Target** (string) - Optional. Used with `Target-Type` header to specify the identifier of the sub-document (e.g., heading name, block ID, frontmatter field name).

### Request Example
```bash
API_KEY="YOUR_API_KEY"

# Read raw markdown
curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/vault/projects/project-alpha.md

# Read full note metadata as JSON
curl -k \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/vnd.olrapi.note+json" \
  https://127.0.0.1:27124/vault/projects/project-alpha.md

# Read only the content under a specific heading (via headers)
curl -k \
  -H "Authorization: Bearer $API_KEY" \
  -H "Target-Type: heading" \
  -H "Target: Goals" \
  https://127.0.0.1:27124/vault/projects/project-alpha.md

# Equivalent using URL-embedded target for heading
curl -k -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/vault/projects/project-alpha.md/heading/Goals"

# Read a nested heading (levels separated by ::)
curl -k -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/vault/projects/project-alpha.md/heading/Goals/Q1"

# Read a frontmatter field value
curl -k -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/vault/projects/project-alpha.md/frontmatter/status"

# Get document map (all patchable targets)
curl -k \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/vnd.olrapi.document-map+json" \
  https://127.0.0.1:27124/vault/projects/project-alpha.md
```

### Response
#### Success Response (200)
- **Content**: (string) Raw markdown content if `Accept` is `text/markdown`.
- **path** (string) - File path.
- **content** (string) - Full markdown content if `Accept` is `application/vnd.olrapi.note+json`.
- **frontmatter** (object) - Frontmatter fields if `Accept` is `application/vnd.olrapi.note+json`.
- **tags** (array of strings) - List of tags if `Accept` is `application/vnd.olrapi.note+json`.
- **stat** (object) - File statistics (creation time, modification time, size) if `Accept` is `application/vnd.olrapi.note+json`.
- **headings** (array of strings) - List of headings if `Accept` is `application/vnd.olrapi.document-map+json`.
- **blocks** (array of strings) - List of block IDs if `Accept` is `application/vnd.olrapi.document-map+json`.
- **frontmatterFields** (array of strings) - List of frontmatter field names if `Accept` is `application/vnd.olrapi.document-map+json`.

#### Response Example (application/vnd.olrapi.note+json)
```json
{
  "path": "projects/project-alpha.md",
  "content": "# Project Alpha\n...",
  "frontmatter": { "status": "active", "tags": ["project"] },
  "tags": ["project"],
  "stat": { "ctime": 1700000000000, "mtime": 1710000000000, "size": 1024 }
}
```

#### Response Example (application/vnd.olrapi.document-map+json)
```json
{
  "headings": ["Goals", "Goals::Q1", "Risks"],
  "blocks": ["^abc123", "^def456"],
  "frontmatterFields": ["status", "tags", "created"]
}
```
```

--------------------------------

### List and Execute Commands

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

List available Obsidian commands and execute them via the API.

```APIDOC
## List and Execute Commands

### Description
Allows you to retrieve a list of all available commands within Obsidian and to execute specific commands programmatically.

### Methods
GET (for listing commands), POST (for executing commands)

### Endpoint
`/commands/` - Lists available Obsidian commands.
`/commands/{commandId}/` - Executes a specific command.

### Parameters
#### Path Parameters
- **commandId** (string) - Required - The unique identifier of the command to execute.

### Request Example (List commands)
```sh
curl -k -H "Authorization: Bearer <your-api-key>" https://127.0.0.1:27124/commands/
```

### Request Example (Execute a command)
```sh
curl -k -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/commands/obsidian.action.create-new-note/
```
```

--------------------------------

### POST /open/{filename} — Open a file in the Obsidian UI

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Tells Obsidian to open the specified note in its user interface. Creates the file if it does not already exist. Optionally opens it in a new leaf (tab/pane).

```APIDOC
## POST /open/{filename}/

### Description
Tells Obsidian to open the specified note in its user interface. Creates the file if it does not already exist. Optionally opens it in a new leaf (tab/pane).

### Method
POST

### Endpoint
/open/{filename}/

#### Path Parameters
- **filename** (string) - Required - The path to the file to open within the vault.

#### Query Parameters
- **newLeaf** (boolean) - Optional - If true, opens the file in a new leaf (tab/pane). Defaults to false.

### Request Example
```bash
API_KEY="YOUR_API_KEY"

# Open a specific note in Obsidian
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/open/projects/project-alpha.md"

# Open in a new leaf (new tab/split)
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/open/projects/project-alpha.md?newLeaf=true"
```

### Response
#### Success Response (200)
Indicates the file was successfully opened or scheduled to be opened.
```

--------------------------------

### Upload Binary File

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Use PUT with the appropriate Content-Type (e.g., image/png) and --data-binary to upload binary files like images.

```bash
curl -k -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @screenshot.png \
  https://127.0.0.1:27124/vault/attachments/screenshot.png
```

--------------------------------

### GET /periodic/{period}/{year}/{month}/{day}/ — Get a specific date's periodic note

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Retrieves a periodic note for a specific date. The period can be daily, weekly, monthly, quarterly, or yearly.

```APIDOC
## GET /periodic/{period}/{year}/{month}/{day}/ — Get a specific date's periodic note

### Description
Returns the periodic note for a specific date. The `{period}` can be `daily`, `weekly`, `monthly`, `quarterly`, or `yearly`.

### Method
GET

### Endpoint
/periodic/{period}/{year}/{month}/{day}/

### Parameters
#### Path Parameters
- **period** (string) - Required - The type of periodic note (daily, weekly, monthly, quarterly, yearly).
- **year** (integer) - Required - The year of the note.
- **month** (integer) - Required - The month of the note.
- **day** (integer) - Required - The day of the note.

### Headers
- **Authorization**: Bearer YOUR_API_KEY

### Request Example
```bash
API_KEY="YOUR_API_KEY"

curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/periodic/daily/2023/10/26/
```
```

--------------------------------

### Stage release files

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/AGENTS.md

Add package.json and package-lock.json to the staging area for the next commit.

```bash
git add package.json package-lock.json
```

--------------------------------

### Create or Overwrite Entire Note

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Use PUT to create a new note or replace the entire content of an existing one. Ensure Content-Type is text/markdown for note content.

```bash
curl -k -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/markdown" \
  --data "# New Note

This note was created via the REST API." \
  https://127.0.0.1:27124/vault/new-note.md
```

--------------------------------

### Initialize Swagger UI for Obsidian Local Rest API

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/docs/index.html

Initializes the Swagger UI with the OpenAPI specification for the Obsidian Local Rest API. Includes custom sorting for operations and a request interceptor to clean up URLs.

```javascript
window.onload = function () { // Begin Swagger UI call region window.ui = ui; }; window.onload = function () { window.ui = SwaggerUIBundle({
    url: "./openapi.yaml",
    dom_id: '#swagger-ui',
    deepLinking: true,
    tagsSorter: null,
    operationsSorter: (a, b) => {
      const order = ['get', 'post', 'put', 'patch', 'delete'];
      return order.indexOf(a.get('method')) - order.indexOf(b.get('method'));
    },
    requestInterceptor: (request) => {
      if (request.url.indexOf('%2F') > -1) {
        request.url = request.url.replaceAll('%2F', '/')
      }
      console.log(request)
      return request
    },
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  }); };
```

--------------------------------

### GET /periodic/{period}/ — Get current periodic note

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Retrieves the current periodic note for a specified period (daily, weekly, monthly, quarterly, yearly). Supports all targeting and Accept options. The note is created if it does not exist when using POST.

```APIDOC
## GET /periodic/{period}/ — Get current periodic note

### Description
Returns the current periodic note for `daily`, `weekly`, `monthly`, `quarterly`, or `yearly`. Supports all targeting and Accept options. Creates the note if it does not yet exist when using POST.

### Method
GET

### Endpoint
/periodic/{period}/

### Parameters
#### Path Parameters
- **period** (string) - Required - The type of periodic note (daily, weekly, monthly, quarterly, yearly).

### Headers
- **Authorization**: Bearer YOUR_API_KEY
- **Accept**: application/vnd.olrapi.note+json (optional, for JSON response)
- **Target-Type**: heading (optional, for targeting specific sections)
- **Target**: Section Name (optional, used with Target-Type)

### Request Example (Get today's daily note as markdown)
```bash
curl -k -H "Authorization: Bearer YOUR_API_KEY" \
  https://127.0.0.1:27124/periodic/daily/
```

### Request Example (Get today's daily note as JSON)
```bash
curl -k \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.olrapi.note+json" \
  https://127.0.0.1:27124/periodic/daily/
```

### Request Example (Read a specific heading from the weekly note)
```bash
curl -k \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Target-Type: heading" \
  -H "Target: Tasks" \
  https://127.0.0.1:27124/periodic/weekly/
```
```

--------------------------------

### Get Document Map

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/docs/src/lib/descriptions/get-shared.md

Retrieve a JSON object outlining the available PATCH targets for a document. This is achieved by setting the `Accept` header to `application/vnd.olrapi.document-map+json`.

```APIDOC
## GET /notes/{noteId}/map

### Description
Retrieves a JSON object outlining the available PATCH targets for a specific document.

### Method
GET

### Endpoint
/notes/{noteId}/map

### Headers
- **Accept**: application/vnd.olrapi.document-map+json

### Response
#### Success Response (200)
- **documentMap** (object) - An object detailing available PATCH targets.

### Response Example
```json
{
  "documentMap": {
    "targets": [
      {
        "path": "/frontmatter/key",
        "method": "PATCH"
      }
    ]
  }
}
```
```

--------------------------------

### List Available Obsidian Commands

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Fetches a list of all executable Obsidian commands, including their IDs and display names. Requires API key.

```bash
API_KEY="YOUR_API_KEY"

curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/commands/
```

--------------------------------

### Update manifest and versions

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/AGENTS.md

Run the version script to automatically update manifest.json and versions.json. This command also stages the updated files.

```bash
npm run version
```

--------------------------------

### Check Server Status and Authentication

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Use this endpoint to verify server liveness and check authentication status. It does not require an API key for the basic status check.

```bash
# Check server liveness (no auth required)
curl -k https://127.0.0.1:27124/
```

```json
# Expected response:
# {
#   "ok": "OK",
#   "authenticated": false,
#   "service": "Obsidian Local REST API",
#   "versions": {
#     "obsidian": "1.7.4",
#     "self": "3.6.1"
#   }
# }
```

```bash
# With a valid API key
curl -k -H "Authorization: Bearer YOUR_API_KEY" https://127.0.0.1:27124/
# "authenticated" will be true
```

--------------------------------

### Read a Note

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

Fetch the content of a specific note from your vault. Ensure you replace `<your-api-key>` with your actual API key and provide the correct file path.

```sh
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md
```

--------------------------------

### Append to Active File with POST /active/

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Add content to the end of the currently open note or to a targeted sub-section. Use appropriate Content-Type for the data being appended.

```bash
API_KEY="YOUR_API_KEY"

# Append to end of active file
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/markdown" \
  --data "

---
*Last updated via REST API*"
  https://127.0.0.1:27124/active/
```

```bash
# Append within a heading in the active file
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/markdown" \
  -H "Target-Type: heading" \
  -H "Target: Log" \
  --data "- $(date): automated entry"
  https://127.0.0.1:27124/active/
```

--------------------------------

### Open a File in Obsidian UI

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Instructs Obsidian to open a specified file in its user interface. The file can be created if it doesn't exist. An optional `newLeaf` parameter can open the file in a new tab or pane.

```bash
API_KEY="YOUR_API_KEY"

# Open a specific note in Obsidian
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/open/projects/project-alpha.md"
# Returns: 200

# Open in a new leaf (new tab/split)
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/open/projects/project-alpha.md?newLeaf=true"
```

--------------------------------

### Open File in Obsidian

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

Instruct Obsidian to open a specific file in its user interface.

```APIDOC
## Open File in Obsidian

### Description
Sends a request to Obsidian to open a specified file in the application's UI, bringing it to the foreground for the user.

### Method
POST

### Endpoint
`/open/{path}`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file within your vault that you want to open.

### Request Example
```sh
curl -k -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/open/path/to/your/note.md
```
```

--------------------------------

### Create Frontmatter Field if Missing

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/docs/src/lib/descriptions/patch.md

Use the 'Create-Target-If-Missing' header to ensure a frontmatter field is created if it does not already exist before setting its value.

```http
Operation: replace
Target-Type: frontmatter
Target: beep
Create-Target-If-Missing: true

2
```

--------------------------------

### Check Server Status

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

Use this command to verify if the Local REST API server is running. No authentication is required for this basic check.

```sh
curl -k https://127.0.0.1:27124/
```

--------------------------------

### Upload a binary file

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

This endpoint is used to upload binary files, such as images, to your vault. The `Content-Type` header should reflect the MIME type of the file.

```APIDOC
## PUT /vault/attachments/{filename}

### Description
Uploads a binary file to the vault's attachments directory.

### Method
PUT

### Endpoint
`/vault/attachments/{filename}`

### Headers
- **Content-Type**: MIME type of the file (e.g., `image/png`)

### Request Body
- **File Data** (binary) - The binary content of the file.

### Request Example
```bash
curl -k -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @screenshot.png \
  https://127.0.0.1:27124/vault/attachments/screenshot.png
```
```

--------------------------------

### Server Status and Authentication Check

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

Check if the server is running. No authentication is required for this endpoint.

```APIDOC
## GET /

### Description
Checks the status of the Local REST API server and verifies authentication.

### Method
GET

### Endpoint
/

### Request Example
```sh
curl -k https://127.0.0.1:27124/
```
```

--------------------------------

### Simple Search

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

Perform a simple fuzzy search across your vault. The query terms are appended to the URL.

```bash
POST /search/simple/?query=your+terms
```

--------------------------------

### List Vault Files and Directories

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Retrieve a list of files and subdirectories within the vault root or a specified directory. Directories are indicated by a trailing slash. Ensure your API key is set as an environment variable or directly in the command.

```bash
API_KEY="YOUR_API_KEY"

# List vault root
curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/vault/
```

```json
# Expected response:
# { "files": ["daily/", "projects/", "README.md", "index.md"] }
```

```bash
# List a subdirectory
curl -k -H "Authorization: Bearer $API_KEY" \
  https://127.0.0.1:27124/vault/projects/
```

```json
# Expected response:
# { "files": ["project-alpha.md", "project-beta.md", "archive/"] }
```

--------------------------------

### Create annotated Git tag

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/AGENTS.md

Create an annotated Git tag with the new version number. The tag message should follow a specific format for clarity.

```bash
git tag -a 3.4.7
```

--------------------------------

### Append Content to File End

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Use POST to append content to the end of a file. If the file does not exist, it will be created. Returns 204 No Content on success.

```bash
API_KEY="YOUR_API_KEY"

# Append to end of file
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/markdown" \
  --data "

## New Section Added

Content appended via API." \
  https://127.0.0.1:27124/vault/daily/2024-01-15.md
```

--------------------------------

### Create or Replace Vault File

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

This endpoint allows for the creation of new files or the complete replacement of existing file content. If a specific target (like a heading or block) is provided, only that section will be updated, and the full updated content is returned. Without a target, the entire file is replaced, and a 204 No Content status is returned.

```bash
API_KEY="YOUR_API_KEY"


```

--------------------------------

### Create release commit

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/AGENTS.md

Commit the staged changes with a specific message format indicating the release version.

```bash
Release X.Y.Z
```

--------------------------------

### Search Endpoint

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/docs/src/lib/descriptions/search-post.md

Evaluates a provided query against each file in your vault. The query format is determined by the `Content-type` header.

```APIDOC
## POST /search

### Description
Evaluates a provided query against each file in your vault. This endpoint supports multiple query formats. Your query should be specified in your request's body, and will be interpreted according to the `Content-type` header you specify.

### Method
POST

### Endpoint
/search

### Parameters
#### Request Body
- **query** (string | object) - Required - The query to evaluate. The format depends on the `Content-type` header.

### Request Example (Dataview DQL)
```json
{
  "Content-type": "application/vnd.olrapi.dataview.dql+txt"
}
```

### Request Example (JsonLogic)
```json
{
  "Content-type": "application/vnd.olrapi.jsonlogic+json"
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of non-falsy results from the query.

### Response Example
```json
{
  "results": [
    // ... matching files or data ...
  ]
}
```
```

--------------------------------

### Replace Content Under a Heading

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Use PUT with Target-Type and Target headers to replace content specifically under a heading. This returns the full updated file.

```bash
curl -k -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/plain" \
  -H "Target-Type: heading" \
  -H "Target: Summary" \
  --data "Updated summary content." \
  https://127.0.0.1:27124/vault/projects/project-alpha.md
```

--------------------------------

### POST /search/ — Structured search (Dataview DQL or JsonLogic)

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Evaluates a Dataview DQL query or a JsonLogic expression against all files in the vault and returns matching results.

```APIDOC
## POST /search/

### Description
Evaluates a Dataview DQL query or a JsonLogic expression against all files in the vault and returns matching results.

### Method
POST

### Endpoint
/search/

#### Request Body
- **Content-Type** (string) - Required - Specifies the type of query. Can be `application/vnd.olrapi.dataview.dql+txt` for Dataview DQL or `application/vnd.olrapi.jsonlogic+json` for JsonLogic.
- **Body** - The actual query string (Dataview DQL) or JSON object (JsonLogic).

### Request Example (Dataview DQL)
```bash
API_KEY="YOUR_API_KEY"

# Dataview DQL: list files with a specific tag, sorted by rating
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/vnd.olrapi.dataview.dql+txt" \
  --data 'TABLE
  time-played AS "Time Played",
  rating AS "Rating"
FROM #game
SORT rating DESC' \
  https://127.0.0.1:27124/search/
```

### Request Example (JsonLogic)
```bash
API_KEY="YOUR_API_KEY"

# JsonLogic: find notes where frontmatter.status equals "active"
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/vnd.olrapi.jsonlogic+json" \
  --data '{"==": [{"var": "frontmatter.status"}, "active"]}' \
  https://127.0.0.1:27124/search/

# JsonLogic: find notes having a specific tag
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/vnd.olrapi.jsonlogic+json" \
  --data '{"in": ["project", {"var": "tags"}]}' \
  https://127.0.0.1:27124/search/

# JsonLogic with glob: find notes whose URL frontmatter matches a pattern
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/vnd.olrapi.jsonlogic+json" \
  --data '{"glob": [{"var": "frontmatter.url-glob"}, "https://example.com/docs/*"]}' \
  https://127.0.0.1:27124/search/
```

### Response
#### Success Response (200)
- **filename** (string) - The name of the file that matched the query.
- **result** (object or any) - The result of the query for the given file. The structure depends on the query type (Dataview DQL or JsonLogic).
```

--------------------------------

### Append to Periodic Note with POST /periodic/{period}/

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Append content to the current periodic note (daily, weekly, monthly, etc.), creating it if it does not exist. Use 'Create-Target-If-Missing: true' to ensure creation of targeted sections.

```bash
API_KEY="YOUR_API_KEY"

# Append a task to today's daily note (creates note if missing)
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/markdown" \
  -H "Target-Type: heading" \
  -H "Target: Tasks" \
  -H "Create-Target-If-Missing: true" \
  --data "- [ ] Review pull request"
  https://127.0.0.1:27124/periodic/daily/
```

```bash
# Append a log entry to the current monthly note
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/markdown" \
  --data "
## Week of $(date +%Y-%m-%d)
- Completed sprint planning"
  https://127.0.0.1:27124/periodic/monthly/
```

--------------------------------

### Re-enable AppNap for Obsidian

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/wiki/Obsidian-Local-REST-API-becomes-unresponsive-when-Obsidian-is-not-in-the-foreground-on-OSX;-can-that-be-fixed?

If you wish to re-enable AppNap for Obsidian, use this command in the terminal. This will restore the default power-saving behavior for the application.

```bash
defaults delete md.obsidian NSAppSleepsWhenInactive
```

--------------------------------

### Structured Search with Dataview DQL

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Performs a structured search using Dataview DQL. The query is sent as plain text with the `application/vnd.olrapi.dataview.dql+txt` content type. Ensure your API key is set.

```bash
API_KEY="YOUR_API_KEY"

# Dataview DQL: list files with a specific tag, sorted by rating
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/vnd.olrapi.dataview.dql+txt" \
  --data 'TABLE
  time-played AS "Time Played",
  rating AS "Rating"
FROM #game
SORT rating DESC' \
  https://127.0.0.1:27124/search/
```

--------------------------------

### POST /search/simple/ — Full-text fuzzy search

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Runs Obsidian's built-in fuzzy search across all notes and returns ranked results with context snippets around each match.

```APIDOC
## POST /search/simple/

### Description
Runs Obsidian's built-in fuzzy search across all notes and returns ranked results with context snippets around each match.

### Method
POST

### Endpoint
/search/simple/

#### Query Parameters
- **query** (string) - Required - The search query string.
- **contextLength** (integer) - Optional - The number of characters to include around each match for context. Defaults to 150.

### Request Example
```bash
API_KEY="YOUR_API_KEY"

# Search for notes containing "project alpha"
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/search/simple/?query=project+alpha&contextLength=150"
```

### Response
#### Success Response (200)
- **filename** (string) - The name of the file containing the match.
- **score** (number) - The relevance score of the match.
- **matches** (array) - An array of match objects.
  - **match** (object)
    - **start** (integer) - The starting character index of the match.
    - **end** (integer) - The ending character index of the match.
  - **context** (string) - The text snippet surrounding the match.
```

--------------------------------

### Replace Heading Content via PUT

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

Use PUT to replace the entire content of a specific heading. The new content is sent as plain text in the request body.

```bash
curl -k -X PUT \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/plain" \
  --data "Updated content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section
```

--------------------------------

### Create or overwrite an entire note

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

This endpoint allows you to create a new note or completely overwrite an existing one with new content. It uses the PUT method and expects the content in the request body.

```APIDOC
## PUT /vault/{filename}

### Description
Creates a new note or overwrites an entire existing note with the provided content.

### Method
PUT

### Endpoint
`/vault/{filename}`

### Request Body
- **Content** (text/markdown) - The content of the note.

### Request Example
```bash
curl -k -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/markdown" \
  --data "# New Note\n\nThis note was created via the REST API." \
  https://127.0.0.1:27124/vault/new-note.md
```

### Response
#### Success Response (204 No Content)
Indicates the note was successfully created or overwritten.
```

--------------------------------

### Simple Search

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

Performs a simple fuzzy search within the Obsidian vault and returns matching filenames with scored context snippets.

```APIDOC
## POST /search/simple/

### Description
Runs Obsidian's built-in fuzzy search and returns matching filenames with scored context snippets.

### Method
POST

### Endpoint
`/search/simple/`

### Parameters
#### Query Parameters
- **query** (string) - Required - The search terms.

### Request Example
```sh
POST /search/simple/?query=your+terms
```

### Response
#### Success Response (200)
- **matches** (array) - An array of search results, each containing filename and context.
```

--------------------------------

### API Extension Interface

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Allows other Obsidian plugins to register custom routes to the Local REST API server, extending its functionality. Requires Local REST API version 2.5+.

```APIDOC
## API Extension Interface — Register custom routes from another plugin

### Description
Other Obsidian plugins can add their own routes to the Local REST API server using the `LocalRestApiPublicApi` class. Requires Local REST API version 2.5+.

### Method
POST (for registering routes), GET/POST/etc. (for custom routes)

### Endpoint
`/my-plugin/hello`, `/my-plugin/echo` (examples of custom routes)

### Usage
Other Obsidian plugins can add their own routes to the Local REST API server using the `LocalRestApiPublicApi` class.

### Registering Routes (TypeScript Example)
```typescript
// In your plugin's onload(), request the LocalRestApiPublicApi instance
// via Obsidian's inter-plugin API, then register routes.

import LocalRestApiPublicApi from "obsidian-local-rest-api";
import express from "express";

// Obtain the API extension object from the Local REST API plugin
const localRestApi = (this.app as any).plugins.plugins["obsidian-local-rest-api"];
const publicApi: LocalRestApiPublicApi = localRestApi.api.getExtensionApi(
  "my-plugin-id",
  () => {
    // Called when your plugin is unloaded — perform cleanup here
  }
);

// Register a GET route
publicApi.addRoute("/my-plugin/hello")
  .get((req: express.Request, res: express.Response) => {
    res.json({ message: "Hello from my plugin!", timestamp: Date.now() });
  });

// Register a POST route with body parsing
publicApi.addRoute("/my-plugin/echo")
  .post((req: express.Request, res: express.Response) => {
    res.json({ echoed: req.body });
  });

// When your plugin unloads, deregister your routes
onunload() {
  publicApi.unregister();
}
```

### Consumer Usage Example
```bash
# curl -k -H "Authorization: Bearer $API_KEY" https://127.0.0.1:27124/my-plugin/hello
```

### Consumer Response Example
```json
{
  "message": "Hello from my plugin!",
  "timestamp": 1710000000000
}
```
```

--------------------------------

### Perform Full-Text Fuzzy Search

Source: https://context7.com/coddingtonbear/obsidian-local-rest-api/llms.txt

Executes a fuzzy search across all notes. The `query` parameter specifies the search term, and `contextLength` determines the snippet size around matches. API key must be provided.

```bash
API_KEY="YOUR_API_KEY"

# Search for notes containing "project alpha"
curl -k -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://127.0.0.1:27124/search/simple/?query=project+alpha&contextLength=150"
```

--------------------------------

### Dataview Search

Source: https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md

Execute a Dataview TABLE query to search for notes and retrieve specific field values. Set the Content-Type header accordingly.

```sh
POST /search/ \
  -H "Content-Type: application/vnd.olrapi.dataview.dql+txt"
```