This is page 5 of 5. Use http://codebase.md/cyanheads/obsidian-mcp-server?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .clinerules
├── .github
│ ├── FUNDING.yml
│ └── workflows
│ └── publish.yml
├── .gitignore
├── .ncurc.json
├── CHANGELOG.md
├── Dockerfile
├── docs
│ ├── obsidian_mcp_tools_spec.md
│ ├── obsidian-api
│ │ ├── obsidian_rest_api_spec.json
│ │ └── obsidian_rest_api_spec.yaml
│ └── tree.md
├── env.json
├── LICENSE
├── mcp.json
├── package-lock.json
├── package.json
├── README.md
├── repomix.config.json
├── scripts
│ ├── clean.ts
│ ├── fetch-openapi-spec.ts
│ ├── make-executable.ts
│ └── tree.ts
├── smithery.yaml
├── src
│ ├── config
│ │ └── index.ts
│ ├── index.ts
│ ├── mcp-server
│ │ ├── server.ts
│ │ ├── tools
│ │ │ ├── obsidianDeleteNoteTool
│ │ │ │ ├── index.ts
│ │ │ │ ├── logic.ts
│ │ │ │ └── registration.ts
│ │ │ ├── obsidianGlobalSearchTool
│ │ │ │ ├── index.ts
│ │ │ │ ├── logic.ts
│ │ │ │ └── registration.ts
│ │ │ ├── obsidianListNotesTool
│ │ │ │ ├── index.ts
│ │ │ │ ├── logic.ts
│ │ │ │ └── registration.ts
│ │ │ ├── obsidianManageFrontmatterTool
│ │ │ │ ├── index.ts
│ │ │ │ ├── logic.ts
│ │ │ │ └── registration.ts
│ │ │ ├── obsidianManageTagsTool
│ │ │ │ ├── index.ts
│ │ │ │ ├── logic.ts
│ │ │ │ └── registration.ts
│ │ │ ├── obsidianReadNoteTool
│ │ │ │ ├── index.ts
│ │ │ │ ├── logic.ts
│ │ │ │ └── registration.ts
│ │ │ ├── obsidianSearchReplaceTool
│ │ │ │ ├── index.ts
│ │ │ │ ├── logic.ts
│ │ │ │ └── registration.ts
│ │ │ └── obsidianUpdateNoteTool
│ │ │ ├── index.ts
│ │ │ ├── logic.ts
│ │ │ └── registration.ts
│ │ └── transports
│ │ ├── auth
│ │ │ ├── core
│ │ │ │ ├── authContext.ts
│ │ │ │ ├── authTypes.ts
│ │ │ │ └── authUtils.ts
│ │ │ ├── index.ts
│ │ │ └── strategies
│ │ │ ├── jwt
│ │ │ │ └── jwtMiddleware.ts
│ │ │ └── oauth
│ │ │ └── oauthMiddleware.ts
│ │ ├── httpErrorHandler.ts
│ │ ├── httpTransport.ts
│ │ └── stdioTransport.ts
│ ├── services
│ │ └── obsidianRestAPI
│ │ ├── index.ts
│ │ ├── methods
│ │ │ ├── activeFileMethods.ts
│ │ │ ├── commandMethods.ts
│ │ │ ├── openMethods.ts
│ │ │ ├── patchMethods.ts
│ │ │ ├── periodicNoteMethods.ts
│ │ │ ├── searchMethods.ts
│ │ │ └── vaultMethods.ts
│ │ ├── service.ts
│ │ ├── types.ts
│ │ └── vaultCache
│ │ ├── index.ts
│ │ └── service.ts
│ ├── types-global
│ │ └── errors.ts
│ └── utils
│ ├── index.ts
│ ├── internal
│ │ ├── asyncUtils.ts
│ │ ├── errorHandler.ts
│ │ ├── index.ts
│ │ ├── logger.ts
│ │ └── requestContext.ts
│ ├── metrics
│ │ ├── index.ts
│ │ └── tokenCounter.ts
│ ├── obsidian
│ │ ├── index.ts
│ │ ├── obsidianApiUtils.ts
│ │ └── obsidianStatUtils.ts
│ ├── parsing
│ │ ├── dateParser.ts
│ │ ├── index.ts
│ │ └── jsonParser.ts
│ └── security
│ ├── idGenerator.ts
│ ├── index.ts
│ ├── rateLimiter.ts
│ └── sanitization.ts
├── tsconfig.json
└── typedoc.json
```
# Files
--------------------------------------------------------------------------------
/docs/obsidian-api/obsidian_rest_api_spec.yaml:
--------------------------------------------------------------------------------
```yaml
1 | components:
2 | schemas:
3 | Error:
4 | properties:
5 | errorCode:
6 | description: >
7 | A 5-digit error code uniquely identifying this particular type of
8 | error.
9 | example: 40149
10 | type: number
11 | message:
12 | description: Message describing the error.
13 | example: A brief description of the error.
14 | type: string
15 | type: object
16 | NoteJson:
17 | properties:
18 | content:
19 | type: string
20 | frontmatter:
21 | type: object
22 | path:
23 | type: string
24 | stat:
25 | properties:
26 | ctime:
27 | type: number
28 | mtime:
29 | type: number
30 | size:
31 | type: number
32 | required:
33 | - ctime
34 | - mtime
35 | - size
36 | type: object
37 | tags:
38 | items:
39 | type: string
40 | type: array
41 | required:
42 | - tags
43 | - frontmatter
44 | - stat
45 | - path
46 | - content
47 | type: object
48 | securitySchemes:
49 | apiKeyAuth:
50 | description: |
51 | Find your API Key in your Obsidian settings
52 | in the "Local REST API" section under "Plugins".
53 | scheme: bearer
54 | type: http
55 | info:
56 | description: >
57 | You can use this interface for trying out your Local REST API in Obsidian.
58 |
59 |
60 | Before trying the below tools, you will want to make sure you press the
61 | "Authorize" button below and provide the API Key you are shown when you open
62 | the "Local REST API" section of your Obsidian settings. All requests to the
63 | API require a valid API Key; so you won't get very far without doing that.
64 |
65 |
66 | When using this tool you may see browser security warnings due to your
67 | browser not trusting the self-signed certificate the plugin will generate on
68 | its first run. If you do, you can make those errors disappear by adding the
69 | certificate as a "Trusted Certificate" in your browser or operating system's
70 | settings.
71 | title: Local REST API for Obsidian
72 | version: '1.0'
73 | openapi: 3.0.2
74 | paths:
75 | /:
76 | get:
77 | description: >
78 | Returns basic details about the server as well as your authentication
79 | status.
80 |
81 |
82 | This is the only API request that does *not* require authentication.
83 | responses:
84 | '200':
85 | content:
86 | application/json:
87 | schema:
88 | properties:
89 | authenticated:
90 | description: Is your current request authenticated?
91 | type: boolean
92 | ok:
93 | description: '''OK'''
94 | type: string
95 | service:
96 | description: '''Obsidian Local REST API'''
97 | type: string
98 | versions:
99 | properties:
100 | obsidian:
101 | description: Obsidian plugin API version
102 | type: string
103 | self:
104 | description: Plugin version.
105 | type: string
106 | type: object
107 | type: object
108 | description: Success
109 | summary: |
110 | Returns basic details about the server.
111 | tags:
112 | - Status
113 | /active/:
114 | delete:
115 | parameters: []
116 | responses:
117 | '204':
118 | description: Success
119 | '404':
120 | content:
121 | application/json:
122 | schema:
123 | $ref: '#/components/schemas/Error'
124 | description: File does not exist.
125 | '405':
126 | content:
127 | application/json:
128 | schema:
129 | $ref: '#/components/schemas/Error'
130 | description: >
131 | Your path references a directory instead of a file; this request
132 | method is valid only for updating files.
133 | summary: |
134 | Deletes the currently-active file in Obsidian.
135 | tags:
136 | - Active File
137 | get:
138 | description: >
139 | Returns the content of the currently active file in Obsidian.
140 |
141 |
142 | If you specify the header `Accept: application/vnd.olrapi.note+json`,
143 | will return a JSON representation of your note including parsed tag and
144 | frontmatter data as well as filesystem metadata. See "responses" below
145 | for details.
146 | parameters: []
147 | responses:
148 | '200':
149 | content:
150 | application/vnd.olrapi.note+json:
151 | schema:
152 | $ref: '#/components/schemas/NoteJson'
153 | text/markdown:
154 | schema:
155 | example: |
156 | # This is my document
157 |
158 | something else here
159 | type: string
160 | description: Success
161 | '404':
162 | description: File does not exist
163 | summary: |
164 | Return the content of the active file open in Obsidian.
165 | tags:
166 | - Active File
167 | patch:
168 | description: >
169 | Inserts content into the currently-open note relative to a heading
170 | within that note.
171 |
172 |
173 | Allows you to modify the content relative to a heading, block reference,
174 | or frontmatter field in your document.
175 |
176 |
177 | Note that this API was changed in Version 3.0 of this extension and the
178 | earlier PATCH API is now deprecated. Requests made using the previous
179 | version of this API will continue to work until Version 4.0 is
180 | released. See
181 | https://github.com/coddingtonbear/obsidian-local-rest-api/wiki/Changes-to-PATCH-requests-between-versions-2.0-and-3.0
182 | for more details and migration instructions.
183 |
184 |
185 | # Examples
186 |
187 |
188 | All of the below examples assume you have a document that looks like
189 |
190 | this:
191 |
192 |
193 | ```markdown
194 |
195 | ---
196 |
197 | alpha: 1
198 |
199 | beta: test
200 |
201 | delta:
202 |
203 | zeta: 1
204 |
205 | yotta: 1
206 |
207 | gamma:
208 |
209 | - one
210 |
211 | - two
212 |
213 | ---
214 |
215 |
216 | # Heading 1
217 |
218 |
219 | This is the content for heading one
220 |
221 |
222 | Also references some [[#^484ef2]]
223 |
224 |
225 | ## Subheading 1:1
226 |
227 | Content for Subheading 1:1
228 |
229 |
230 | ### Subsubheading 1:1:1
231 |
232 |
233 | ### Subsubheading 1:1:2
234 |
235 |
236 | Testing how block references work for a table.[[#^2c7cfa]]
237 |
238 | Some content for Subsubheading 1:1:2
239 |
240 |
241 | More random text.
242 |
243 |
244 | ^2d9b4a
245 |
246 |
247 | ## Subheading 1:2
248 |
249 |
250 | Content for Subheading 1:2.
251 |
252 |
253 | some content with a block reference ^484ef2
254 |
255 |
256 | ## Subheading 1:3
257 |
258 | | City | Population |
259 |
260 | | ------------ | ---------- |
261 |
262 | | Seattle, WA | 8 |
263 |
264 | | Portland, OR | 4 |
265 |
266 |
267 | ^2c7cfa
268 |
269 | ```
270 |
271 |
272 | ## Append Content Below a Heading
273 |
274 |
275 | If you wanted to append the content "Hello" below "Subheading 1:1:1"
276 | under "Heading 1",
277 |
278 | you could send a request with the following headers:
279 |
280 |
281 | - `Operation`: `append`
282 |
283 | - `Target-Type`: `heading`
284 |
285 | - `Target`: `Heading 1::Subheading 1:1:1`
286 |
287 | - with the request body: `Hello`
288 |
289 |
290 | The above would work just fine for `prepend` or `replace`, too, of
291 | course,
292 |
293 | but with different results.
294 |
295 |
296 | ## Append Content to a Block Reference
297 |
298 |
299 | If you wanted to append the content "Hello" below the block referenced
300 | by
301 |
302 | "2d9b4a" above ("More random text."), you could send the following
303 | headers:
304 |
305 |
306 | - `Operation`: `append`
307 |
308 | - `Target-Type`: `block`
309 |
310 | - `Target`: `2d9b4a`
311 |
312 | - with the request body: `Hello`
313 |
314 |
315 | The above would work just fine for `prepend` or `replace`, too, of
316 | course,
317 |
318 | but with different results.
319 |
320 |
321 | ## Add a Row to a Table Referenced by a Block Reference
322 |
323 |
324 | If you wanted to add a new city ("Chicago, IL") and population ("16")
325 | pair to the table above
326 |
327 | referenced by the block reference `2c7cfa`, you could send the following
328 |
329 | headers:
330 |
331 |
332 | - `Operation`: `append`
333 |
334 | - `TargetType`: `block`
335 |
336 | - `Target`: `2c7cfa`
337 |
338 | - `Content-Type`: `application/json`
339 |
340 | - with the request body: `[["Chicago, IL", "16"]]`
341 |
342 |
343 | The use of a `Content-Type` of `application/json` allows the API
344 |
345 | to infer that member of your array represents rows and columns of your
346 |
347 | to append to the referenced table. You can of course just use a
348 |
349 | `Content-Type` of `text/markdown`, but in such a case you'll have to
350 |
351 | format your table row manually instead of letting the library figure
352 |
353 | it out for you.
354 |
355 |
356 | You also have the option of using `prepend` (in which case, your new
357 |
358 | row would be the first -- right below the table heading) or `replace`
359 | (in which
360 |
361 | case all rows except the table heading would be replaced by the new
362 | row(s)
363 |
364 | you supplied).
365 |
366 |
367 | ## Setting a Frontmatter Field
368 |
369 |
370 | If you wanted to set the frontmatter field `alpha` to `2`, you could
371 |
372 | send the following headers:
373 |
374 |
375 | - `Operation`: `replace`
376 |
377 | - `TargetType`: `frontmatter`
378 |
379 | - `Target`: `beep`
380 |
381 | - with the request body `2`
382 |
383 |
384 | If you're setting a frontmatter field that might not already exist
385 |
386 | you may want to use the `Create-Target-If-Missing` header so the
387 |
388 | new frontmatter field is created and set to your specified value
389 |
390 | if it doesn't already exist.
391 |
392 |
393 | You may find using a `Content-Type` of `application/json` to be
394 |
395 | particularly useful in the case of frontmatter since frontmatter
396 |
397 | fields' values are JSON data, and the API can be smarter about
398 |
399 | interpreting yoru `prepend` or `append` requests if you specify
400 |
401 | your data as JSON (particularly when appending, for example,
402 |
403 | list items).
404 | parameters:
405 | - description: Patch operation to perform
406 | in: header
407 | name: Operation
408 | required: true
409 | schema:
410 | enum:
411 | - append
412 | - prepend
413 | - replace
414 | type: string
415 | - description: Type of target to patch
416 | in: header
417 | name: Target-Type
418 | required: true
419 | schema:
420 | enum:
421 | - heading
422 | - block
423 | - frontmatter
424 | type: string
425 | - description: Delimiter to use for nested targets (i.e. Headings)
426 | in: header
427 | name: Target-Delimiter
428 | required: false
429 | schema:
430 | default: '::'
431 | type: string
432 | - description: |
433 | Target to patch; this value can be URL-Encoded and *must*
434 | be URL-Encoded if it includes non-ASCII characters.
435 | in: header
436 | name: Target
437 | required: true
438 | schema:
439 | type: string
440 | - description: Trim whitespace from Target before applying patch?
441 | in: header
442 | name: Trim-Target-Whitespace
443 | required: false
444 | schema:
445 | default: 'false'
446 | enum:
447 | - 'true'
448 | - 'false'
449 | type: string
450 | requestBody:
451 | content:
452 | application/json:
453 | schema:
454 | example: '[''one'', ''two'']'
455 | type: string
456 | text/markdown:
457 | schema:
458 | example: |
459 | # This is my document
460 |
461 | something else here
462 | type: string
463 | description: Content you would like to insert.
464 | required: true
465 | responses:
466 | '200':
467 | description: Success
468 | '400':
469 | content:
470 | application/json:
471 | schema:
472 | $ref: '#/components/schemas/Error'
473 | description: Bad Request; see response message for details.
474 | '404':
475 | content:
476 | application/json:
477 | schema:
478 | $ref: '#/components/schemas/Error'
479 | description: Does not exist
480 | '405':
481 | content:
482 | application/json:
483 | schema:
484 | $ref: '#/components/schemas/Error'
485 | description: >
486 | Your path references a directory instead of a file; this request
487 | method is valid only for updating files.
488 | summary: >
489 | Insert content into the currently open note in Obsidian relative to a
490 | heading within that document.
491 | tags:
492 | - Active File
493 | post:
494 | description: >
495 | Appends content to the end of the currently-open note.
496 |
497 |
498 | If you would like to insert text relative to a particular heading
499 | instead of appending to the end of the file, see 'patch'.
500 | parameters: []
501 | requestBody:
502 | content:
503 | text/markdown:
504 | schema:
505 | example: |
506 | # This is my document
507 |
508 | something else here
509 | type: string
510 | description: Content you would like to append.
511 | required: true
512 | responses:
513 | '204':
514 | description: Success
515 | '400':
516 | content:
517 | application/json:
518 | schema:
519 | $ref: '#/components/schemas/Error'
520 | description: Bad Request
521 | '405':
522 | content:
523 | application/json:
524 | schema:
525 | $ref: '#/components/schemas/Error'
526 | description: >
527 | Your path references a directory instead of a file; this request
528 | method is valid only for updating files.
529 | summary: |
530 | Append content to the active file open in Obsidian.
531 | tags:
532 | - Active File
533 | put:
534 | requestBody:
535 | content:
536 | '*/*':
537 | schema:
538 | type: string
539 | text/markdown:
540 | schema:
541 | example: |
542 | # This is my document
543 |
544 | something else here
545 | type: string
546 | description: Content of the file you would like to upload.
547 | required: true
548 | responses:
549 | '204':
550 | description: Success
551 | '400':
552 | content:
553 | application/json:
554 | schema:
555 | $ref: '#/components/schemas/Error'
556 | description: >
557 | Incoming file could not be processed. Make sure you have specified
558 | a reasonable file name, and make sure you have set a reasonable
559 | 'Content-Type' header; if you are uploading a note, 'text/markdown'
560 | is likely the right choice.
561 | '405':
562 | content:
563 | application/json:
564 | schema:
565 | $ref: '#/components/schemas/Error'
566 | description: >
567 | Your path references a directory instead of a file; this request
568 | method is valid only for updating files.
569 | summary: |
570 | Update the content of the active file open in Obsidian.
571 | tags:
572 | - Active File
573 | /commands/:
574 | get:
575 | responses:
576 | '200':
577 | content:
578 | application/json:
579 | example:
580 | commands:
581 | - id: global-search:open
582 | name: 'Search: Search in all files'
583 | - id: graph:open
584 | name: 'Graph view: Open graph view'
585 | schema:
586 | properties:
587 | commands:
588 | items:
589 | properties:
590 | id:
591 | type: string
592 | name:
593 | type: string
594 | type: object
595 | type: array
596 | type: object
597 | description: A list of available commands.
598 | summary: |
599 | Get a list of available commands.
600 | tags:
601 | - Commands
602 | /commands/{commandId}/:
603 | post:
604 | parameters:
605 | - description: The id of the command to execute
606 | in: path
607 | name: commandId
608 | required: true
609 | schema:
610 | type: string
611 | responses:
612 | '204':
613 | description: Success
614 | '404':
615 | content:
616 | application/json:
617 | schema:
618 | $ref: '#/components/schemas/Error'
619 | description: The command you specified does not exist.
620 | summary: |
621 | Execute a command.
622 | tags:
623 | - Commands
624 | /open/{filename}:
625 | post:
626 | description: |
627 | Opens the specified document in Obsidian.
628 |
629 | Note: Obsidian will create a new document at the path you have
630 | specified if such a document did not already exist.
631 | parameters:
632 | - description: |
633 | Path to the file to return (relative to your vault root).
634 | in: path
635 | name: filename
636 | required: true
637 | schema:
638 | format: path
639 | type: string
640 | - description: Open this as a new leaf?
641 | in: query
642 | name: newLeaf
643 | required: false
644 | schema:
645 | type: boolean
646 | responses:
647 | '200':
648 | description: Success
649 | summary: |
650 | Open the specified document in Obsidian
651 | tags:
652 | - Open
653 | /periodic/{period}/:
654 | delete:
655 | description: |
656 | Deletes the periodic note for the specified period.
657 | parameters:
658 | - description: >-
659 | The name of the period for which you would like to grab the current
660 | note.
661 | in: path
662 | name: period
663 | required: true
664 | schema:
665 | default: daily
666 | enum:
667 | - daily
668 | - weekly
669 | - monthly
670 | - quarterly
671 | - yearly
672 | type: string
673 | responses:
674 | '204':
675 | description: Success
676 | '404':
677 | content:
678 | application/json:
679 | schema:
680 | $ref: '#/components/schemas/Error'
681 | description: File does not exist.
682 | '405':
683 | content:
684 | application/json:
685 | schema:
686 | $ref: '#/components/schemas/Error'
687 | description: >
688 | Your path references a directory instead of a file; this request
689 | method is valid only for updating files.
690 | summary: |
691 | Delete a periodic note.
692 | tags:
693 | - Periodic Notes
694 | get:
695 | parameters:
696 | - description: >-
697 | The name of the period for which you would like to grab the current
698 | note.
699 | in: path
700 | name: period
701 | required: true
702 | schema:
703 | default: daily
704 | enum:
705 | - daily
706 | - weekly
707 | - monthly
708 | - quarterly
709 | - yearly
710 | type: string
711 | responses:
712 | '200':
713 | content:
714 | application/vnd.olrapi.note+json:
715 | schema:
716 | $ref: '#/components/schemas/NoteJson'
717 | text/markdown:
718 | schema:
719 | example: |
720 | # This is my document
721 |
722 | something else here
723 | type: string
724 | description: Success
725 | '404':
726 | description: File does not exist
727 | summary: |
728 | Get current periodic note for the specified period.
729 | tags:
730 | - Periodic Notes
731 | patch:
732 | description: >
733 | Inserts content into an existing note relative to a heading within your
734 | note.
735 |
736 |
737 | Allows you to modify the content relative to a heading, block reference,
738 | or frontmatter field in your document.
739 |
740 |
741 | Note that this API was changed in Version 3.0 of this extension and the
742 | earlier PATCH API is now deprecated. Requests made using the previous
743 | version of this API will continue to work until Version 4.0 is
744 | released. See
745 | https://github.com/coddingtonbear/obsidian-local-rest-api/wiki/Changes-to-PATCH-requests-between-versions-2.0-and-3.0
746 | for more details and migration instructions.
747 |
748 |
749 | # Examples
750 |
751 |
752 | All of the below examples assume you have a document that looks like
753 |
754 | this:
755 |
756 |
757 | ```markdown
758 |
759 | ---
760 |
761 | alpha: 1
762 |
763 | beta: test
764 |
765 | delta:
766 |
767 | zeta: 1
768 |
769 | yotta: 1
770 |
771 | gamma:
772 |
773 | - one
774 |
775 | - two
776 |
777 | ---
778 |
779 |
780 | # Heading 1
781 |
782 |
783 | This is the content for heading one
784 |
785 |
786 | Also references some [[#^484ef2]]
787 |
788 |
789 | ## Subheading 1:1
790 |
791 | Content for Subheading 1:1
792 |
793 |
794 | ### Subsubheading 1:1:1
795 |
796 |
797 | ### Subsubheading 1:1:2
798 |
799 |
800 | Testing how block references work for a table.[[#^2c7cfa]]
801 |
802 | Some content for Subsubheading 1:1:2
803 |
804 |
805 | More random text.
806 |
807 |
808 | ^2d9b4a
809 |
810 |
811 | ## Subheading 1:2
812 |
813 |
814 | Content for Subheading 1:2.
815 |
816 |
817 | some content with a block reference ^484ef2
818 |
819 |
820 | ## Subheading 1:3
821 |
822 | | City | Population |
823 |
824 | | ------------ | ---------- |
825 |
826 | | Seattle, WA | 8 |
827 |
828 | | Portland, OR | 4 |
829 |
830 |
831 | ^2c7cfa
832 |
833 | ```
834 |
835 |
836 | ## Append Content Below a Heading
837 |
838 |
839 | If you wanted to append the content "Hello" below "Subheading 1:1:1"
840 | under "Heading 1",
841 |
842 | you could send a request with the following headers:
843 |
844 |
845 | - `Operation`: `append`
846 |
847 | - `Target-Type`: `heading`
848 |
849 | - `Target`: `Heading 1::Subheading 1:1:1`
850 |
851 | - with the request body: `Hello`
852 |
853 |
854 | The above would work just fine for `prepend` or `replace`, too, of
855 | course,
856 |
857 | but with different results.
858 |
859 |
860 | ## Append Content to a Block Reference
861 |
862 |
863 | If you wanted to append the content "Hello" below the block referenced
864 | by
865 |
866 | "2d9b4a" above ("More random text."), you could send the following
867 | headers:
868 |
869 |
870 | - `Operation`: `append`
871 |
872 | - `Target-Type`: `block`
873 |
874 | - `Target`: `2d9b4a`
875 |
876 | - with the request body: `Hello`
877 |
878 |
879 | The above would work just fine for `prepend` or `replace`, too, of
880 | course,
881 |
882 | but with different results.
883 |
884 |
885 | ## Add a Row to a Table Referenced by a Block Reference
886 |
887 |
888 | If you wanted to add a new city ("Chicago, IL") and population ("16")
889 | pair to the table above
890 |
891 | referenced by the block reference `2c7cfa`, you could send the following
892 |
893 | headers:
894 |
895 |
896 | - `Operation`: `append`
897 |
898 | - `TargetType`: `block`
899 |
900 | - `Target`: `2c7cfa`
901 |
902 | - `Content-Type`: `application/json`
903 |
904 | - with the request body: `[["Chicago, IL", "16"]]`
905 |
906 |
907 | The use of a `Content-Type` of `application/json` allows the API
908 |
909 | to infer that member of your array represents rows and columns of your
910 |
911 | to append to the referenced table. You can of course just use a
912 |
913 | `Content-Type` of `text/markdown`, but in such a case you'll have to
914 |
915 | format your table row manually instead of letting the library figure
916 |
917 | it out for you.
918 |
919 |
920 | You also have the option of using `prepend` (in which case, your new
921 |
922 | row would be the first -- right below the table heading) or `replace`
923 | (in which
924 |
925 | case all rows except the table heading would be replaced by the new
926 | row(s)
927 |
928 | you supplied).
929 |
930 |
931 | ## Setting a Frontmatter Field
932 |
933 |
934 | If you wanted to set the frontmatter field `alpha` to `2`, you could
935 |
936 | send the following headers:
937 |
938 |
939 | - `Operation`: `replace`
940 |
941 | - `TargetType`: `frontmatter`
942 |
943 | - `Target`: `beep`
944 |
945 | - with the request body `2`
946 |
947 |
948 | If you're setting a frontmatter field that might not already exist
949 |
950 | you may want to use the `Create-Target-If-Missing` header so the
951 |
952 | new frontmatter field is created and set to your specified value
953 |
954 | if it doesn't already exist.
955 |
956 |
957 | You may find using a `Content-Type` of `application/json` to be
958 |
959 | particularly useful in the case of frontmatter since frontmatter
960 |
961 | fields' values are JSON data, and the API can be smarter about
962 |
963 | interpreting yoru `prepend` or `append` requests if you specify
964 |
965 | your data as JSON (particularly when appending, for example,
966 |
967 | list items).
968 | parameters:
969 | - description: Patch operation to perform
970 | in: header
971 | name: Operation
972 | required: true
973 | schema:
974 | enum:
975 | - append
976 | - prepend
977 | - replace
978 | type: string
979 | - description: Type of target to patch
980 | in: header
981 | name: Target-Type
982 | required: true
983 | schema:
984 | enum:
985 | - heading
986 | - block
987 | - frontmatter
988 | type: string
989 | - description: Delimiter to use for nested targets (i.e. Headings)
990 | in: header
991 | name: Target-Delimiter
992 | required: false
993 | schema:
994 | default: '::'
995 | type: string
996 | - description: |
997 | Target to patch; this value can be URL-Encoded and *must*
998 | be URL-Encoded if it includes non-ASCII characters.
999 | in: header
1000 | name: Target
1001 | required: true
1002 | schema:
1003 | type: string
1004 | - description: Trim whitespace from Target before applying patch?
1005 | in: header
1006 | name: Trim-Target-Whitespace
1007 | required: false
1008 | schema:
1009 | default: 'false'
1010 | enum:
1011 | - 'true'
1012 | - 'false'
1013 | type: string
1014 | - description: >-
1015 | The name of the period for which you would like to grab the current
1016 | note.
1017 | in: path
1018 | name: period
1019 | required: true
1020 | schema:
1021 | default: daily
1022 | enum:
1023 | - daily
1024 | - weekly
1025 | - monthly
1026 | - quarterly
1027 | - yearly
1028 | type: string
1029 | requestBody:
1030 | content:
1031 | application/json:
1032 | schema:
1033 | example: '[''one'', ''two'']'
1034 | type: string
1035 | text/markdown:
1036 | schema:
1037 | example: |
1038 | # This is my document
1039 |
1040 | something else here
1041 | type: string
1042 | description: Content you would like to insert.
1043 | required: true
1044 | responses:
1045 | '200':
1046 | description: Success
1047 | '400':
1048 | content:
1049 | application/json:
1050 | schema:
1051 | $ref: '#/components/schemas/Error'
1052 | description: Bad Request; see response message for details.
1053 | '404':
1054 | content:
1055 | application/json:
1056 | schema:
1057 | $ref: '#/components/schemas/Error'
1058 | description: Does not exist
1059 | '405':
1060 | content:
1061 | application/json:
1062 | schema:
1063 | $ref: '#/components/schemas/Error'
1064 | description: >
1065 | Your path references a directory instead of a file; this request
1066 | method is valid only for updating files.
1067 | summary: >
1068 | Insert content into a periodic note relative to a heading within that
1069 | document.
1070 | tags:
1071 | - Periodic Notes
1072 | post:
1073 | description: >
1074 | Appends content to the periodic note for the specified period. This
1075 | will create the relevant periodic note if necessary.
1076 | parameters:
1077 | - description: >-
1078 | The name of the period for which you would like to grab the current
1079 | note.
1080 | in: path
1081 | name: period
1082 | required: true
1083 | schema:
1084 | default: daily
1085 | enum:
1086 | - daily
1087 | - weekly
1088 | - monthly
1089 | - quarterly
1090 | - yearly
1091 | type: string
1092 | requestBody:
1093 | content:
1094 | text/markdown:
1095 | schema:
1096 | example: |
1097 | # This is my document
1098 |
1099 | something else here
1100 | type: string
1101 | description: Content you would like to append.
1102 | required: true
1103 | responses:
1104 | '204':
1105 | description: Success
1106 | '400':
1107 | content:
1108 | application/json:
1109 | schema:
1110 | $ref: '#/components/schemas/Error'
1111 | description: Bad Request
1112 | '405':
1113 | content:
1114 | application/json:
1115 | schema:
1116 | $ref: '#/components/schemas/Error'
1117 | description: >
1118 | Your path references a directory instead of a file; this request
1119 | method is valid only for updating files.
1120 | summary: |
1121 | Append content to a periodic note.
1122 | tags:
1123 | - Periodic Notes
1124 | put:
1125 | parameters:
1126 | - description: >-
1127 | The name of the period for which you would like to grab the current
1128 | note.
1129 | in: path
1130 | name: period
1131 | required: true
1132 | schema:
1133 | default: daily
1134 | enum:
1135 | - daily
1136 | - weekly
1137 | - monthly
1138 | - quarterly
1139 | - yearly
1140 | type: string
1141 | requestBody:
1142 | content:
1143 | '*/*':
1144 | schema:
1145 | type: string
1146 | text/markdown:
1147 | schema:
1148 | example: |
1149 | # This is my document
1150 |
1151 | something else here
1152 | type: string
1153 | description: Content of the file you would like to upload.
1154 | required: true
1155 | responses:
1156 | '204':
1157 | description: Success
1158 | '400':
1159 | content:
1160 | application/json:
1161 | schema:
1162 | $ref: '#/components/schemas/Error'
1163 | description: >
1164 | Incoming file could not be processed. Make sure you have specified
1165 | a reasonable file name, and make sure you have set a reasonable
1166 | 'Content-Type' header; if you are uploading a note, 'text/markdown'
1167 | is likely the right choice.
1168 | '405':
1169 | content:
1170 | application/json:
1171 | schema:
1172 | $ref: '#/components/schemas/Error'
1173 | description: >
1174 | Your path references a directory instead of a file; this request
1175 | method is valid only for updating files.
1176 | summary: |
1177 | Update the content of a periodic note.
1178 | tags:
1179 | - Periodic Notes
1180 | /search/:
1181 | post:
1182 | description: >
1183 | Evaluates a provided query against each file in your vault.
1184 |
1185 |
1186 | This endpoint supports multiple query formats. Your query should be
1187 | specified in your request's body, and will be interpreted according to
1188 | the `Content-type` header you specify from the below options.Additional
1189 | query formats may be added in the future.
1190 |
1191 |
1192 | # Dataview DQL (`application/vnd.olrapi.dataview.dql+txt`)
1193 |
1194 |
1195 | Accepts a `TABLE`-type Dataview query as a text string. See
1196 | [Dataview](https://blacksmithgu.github.io/obsidian-dataview/query/queries/)'s
1197 | query documentation for information on how to construct a query.
1198 |
1199 |
1200 | # JsonLogic (`application/vnd.olrapi.jsonlogic+json`)
1201 |
1202 |
1203 | Accepts a JsonLogic query specified as JSON. See
1204 | [JsonLogic](https://jsonlogic.com/operations.html)'s documentation for
1205 | information about the base set of operators available, but in addition
1206 | to those operators the following operators are available:
1207 |
1208 |
1209 | - `glob: [PATTERN, VALUE]`: Returns `true` if a string matches a glob
1210 | pattern. E.g.: `{"glob": ["*.foo", "bar.foo"]}` is `true` and `{"glob":
1211 | ["*.bar", "bar.foo"]}` is `false`.
1212 |
1213 | - `regexp: [PATTERN, VALUE]`: Returns `true` if a string matches a
1214 | regular expression. E.g.: `{"regexp": [".*\.foo", "bar.foo"]` is `true`
1215 | and `{"regexp": [".*\.bar", "bar.foo"]}` is `false`.
1216 |
1217 |
1218 | Returns only non-falsy results. "Non-falsy" here treats the following
1219 | values as "falsy":
1220 |
1221 |
1222 | - `false`
1223 |
1224 | - `null` or `undefined`
1225 |
1226 | - `0`
1227 |
1228 | - `[]`
1229 |
1230 | - `{}`
1231 |
1232 |
1233 | Files are represented as an object having the schema described
1234 |
1235 | in the Schema named 'NoteJson' at the bottom of this page.
1236 |
1237 | Understanding the shape of a JSON object from a schema can be
1238 |
1239 | tricky; so you may find it helpful to examine the generated metadata
1240 |
1241 | for individual files in your vault to understand exactly what values
1242 |
1243 | are returned. To see that, access the `GET` `/vault/{filePath}`
1244 |
1245 | route setting the header:
1246 |
1247 | `Accept: application/vnd.olrapi.note+json`. See examples below
1248 |
1249 | for working examples of queries performing common search operations.
1250 | requestBody:
1251 | content:
1252 | application/vnd.olrapi.dataview.dql+txt:
1253 | examples:
1254 | find_fields_by_tag:
1255 | summary: 'List data from files having the #game tag.'
1256 | value: |
1257 | TABLE
1258 | time-played AS "Time Played",
1259 | length AS "Length",
1260 | rating AS "Rating"
1261 | FROM #game
1262 | SORT rating DESC
1263 | schema:
1264 | externalDocs:
1265 | url: >-
1266 | https://blacksmithgu.github.io/obsidian-dataview/query/queries/
1267 | type: object
1268 | application/vnd.olrapi.jsonlogic+json:
1269 | examples:
1270 | find_by_frontmatter_url_glob:
1271 | summary: >-
1272 | Find notes having URL or a matching URL glob frontmatter
1273 | field.
1274 | value: |
1275 | {
1276 | "or": [
1277 | {"===": [{"var": "frontmatter.url"}, "https://myurl.com/some/path/"]},
1278 | {"glob": [{"var": "frontmatter.url-glob"}, "https://myurl.com/some/path/"]}
1279 | ]
1280 | }
1281 | find_by_frontmatter_value:
1282 | summary: Find notes having a certain frontmatter field value.
1283 | value: |
1284 | {
1285 | "==": [
1286 | {"var": "frontmatter.myField"},
1287 | "myValue"
1288 | ]
1289 | }
1290 | find_by_tag:
1291 | summary: Find notes having a certain tag
1292 | value: |
1293 | {
1294 | "in": [
1295 | "myTag",
1296 | {"var": "tags"}
1297 | ]
1298 | }
1299 | schema:
1300 | externalDocs:
1301 | url: https://jsonlogic.com/operations.html
1302 | type: object
1303 | required: true
1304 | responses:
1305 | '200':
1306 | content:
1307 | application/json:
1308 | schema:
1309 | items:
1310 | properties:
1311 | filename:
1312 | description: Path to the matching file
1313 | type: string
1314 | result:
1315 | oneOf:
1316 | - type: string
1317 | - type: number
1318 | - type: array
1319 | - type: object
1320 | - type: boolean
1321 | required:
1322 | - filename
1323 | - result
1324 | type: object
1325 | type: array
1326 | description: Success
1327 | '400':
1328 | content:
1329 | application/json:
1330 | schema:
1331 | $ref: '#/components/schemas/Error'
1332 | description: |
1333 | Bad request. Make sure you have specified an acceptable
1334 | Content-Type for your search query.
1335 | summary: |
1336 | Search for documents matching a specified search query
1337 | tags:
1338 | - Search
1339 | /search/simple/:
1340 | post:
1341 | parameters:
1342 | - description: Your search query
1343 | in: query
1344 | name: query
1345 | required: true
1346 | schema:
1347 | type: string
1348 | - description: How much context to return around the matching string
1349 | in: query
1350 | name: contextLength
1351 | required: false
1352 | schema:
1353 | default: 100
1354 | type: number
1355 | responses:
1356 | '200':
1357 | content:
1358 | application/json:
1359 | schema:
1360 | items:
1361 | properties:
1362 | filename:
1363 | description: Path to the matching file
1364 | type: string
1365 | matches:
1366 | items:
1367 | properties:
1368 | context:
1369 | type: string
1370 | match:
1371 | properties:
1372 | end:
1373 | type: number
1374 | start:
1375 | type: number
1376 | required:
1377 | - start
1378 | - end
1379 | type: object
1380 | required:
1381 | - match
1382 | - context
1383 | type: object
1384 | type: array
1385 | score:
1386 | type: number
1387 | type: object
1388 | type: array
1389 | description: Success
1390 | summary: |
1391 | Search for documents matching a specified text query
1392 | tags:
1393 | - Search
1394 | /vault/:
1395 | get:
1396 | description: >
1397 | Lists files in the root directory of your vault.
1398 |
1399 |
1400 | Note: that this is exactly the same API endpoint as the below "List
1401 | files that exist in the specified directory." and exists here only due
1402 | to a quirk of this particular interactive tool.
1403 | responses:
1404 | '200':
1405 | content:
1406 | application/json:
1407 | example:
1408 | files:
1409 | - mydocument.md
1410 | - somedirectory/
1411 | schema:
1412 | properties:
1413 | files:
1414 | items:
1415 | type: string
1416 | type: array
1417 | type: object
1418 | description: Success
1419 | '404':
1420 | content:
1421 | application/json:
1422 | schema:
1423 | $ref: '#/components/schemas/Error'
1424 | description: Directory does not exist
1425 | summary: |
1426 | List files that exist in the root of your vault.
1427 | tags:
1428 | - Vault Directories
1429 | /vault/{filename}:
1430 | delete:
1431 | parameters:
1432 | - description: |
1433 | Path to the relevant file (relative to your vault root).
1434 | in: path
1435 | name: filename
1436 | required: true
1437 | schema:
1438 | format: path
1439 | type: string
1440 | responses:
1441 | '204':
1442 | description: Success
1443 | '404':
1444 | content:
1445 | application/json:
1446 | schema:
1447 | $ref: '#/components/schemas/Error'
1448 | description: File does not exist.
1449 | '405':
1450 | content:
1451 | application/json:
1452 | schema:
1453 | $ref: '#/components/schemas/Error'
1454 | description: >
1455 | Your path references a directory instead of a file; this request
1456 | method is valid only for updating files.
1457 | summary: |
1458 | Delete a particular file in your vault.
1459 | tags:
1460 | - Vault Files
1461 | get:
1462 | description: >
1463 | Returns the content of the file at the specified path in your vault
1464 | should the file exist.
1465 |
1466 |
1467 | If you specify the header `Accept: application/vnd.olrapi.note+json`,
1468 | will return a JSON representation of your note including parsed tag and
1469 | frontmatter data as well as filesystem metadata. See "responses" below
1470 | for details.
1471 | parameters:
1472 | - description: |
1473 | Path to the relevant file (relative to your vault root).
1474 | in: path
1475 | name: filename
1476 | required: true
1477 | schema:
1478 | format: path
1479 | type: string
1480 | responses:
1481 | '200':
1482 | content:
1483 | application/vnd.olrapi.note+json:
1484 | schema:
1485 | $ref: '#/components/schemas/NoteJson'
1486 | text/markdown:
1487 | schema:
1488 | example: |
1489 | # This is my document
1490 |
1491 | something else here
1492 | type: string
1493 | description: Success
1494 | '404':
1495 | description: File does not exist
1496 | summary: |
1497 | Return the content of a single file in your vault.
1498 | tags:
1499 | - Vault Files
1500 | patch:
1501 | description: >
1502 | Inserts content into an existing note relative to a heading within your
1503 | note.
1504 |
1505 |
1506 | Allows you to modify the content relative to a heading, block reference,
1507 | or frontmatter field in your document.
1508 |
1509 |
1510 | Note that this API was changed in Version 3.0 of this extension and the
1511 | earlier PATCH API is now deprecated. Requests made using the previous
1512 | version of this API will continue to work until Version 4.0 is
1513 | released. See
1514 | https://github.com/coddingtonbear/obsidian-local-rest-api/wiki/Changes-to-PATCH-requests-between-versions-2.0-and-3.0
1515 | for more details and migration instructions.
1516 |
1517 |
1518 | # Examples
1519 |
1520 |
1521 | All of the below examples assume you have a document that looks like
1522 |
1523 | this:
1524 |
1525 |
1526 | ```markdown
1527 |
1528 | ---
1529 |
1530 | alpha: 1
1531 |
1532 | beta: test
1533 |
1534 | delta:
1535 |
1536 | zeta: 1
1537 |
1538 | yotta: 1
1539 |
1540 | gamma:
1541 |
1542 | - one
1543 |
1544 | - two
1545 |
1546 | ---
1547 |
1548 |
1549 | # Heading 1
1550 |
1551 |
1552 | This is the content for heading one
1553 |
1554 |
1555 | Also references some [[#^484ef2]]
1556 |
1557 |
1558 | ## Subheading 1:1
1559 |
1560 | Content for Subheading 1:1
1561 |
1562 |
1563 | ### Subsubheading 1:1:1
1564 |
1565 |
1566 | ### Subsubheading 1:1:2
1567 |
1568 |
1569 | Testing how block references work for a table.[[#^2c7cfa]]
1570 |
1571 | Some content for Subsubheading 1:1:2
1572 |
1573 |
1574 | More random text.
1575 |
1576 |
1577 | ^2d9b4a
1578 |
1579 |
1580 | ## Subheading 1:2
1581 |
1582 |
1583 | Content for Subheading 1:2.
1584 |
1585 |
1586 | some content with a block reference ^484ef2
1587 |
1588 |
1589 | ## Subheading 1:3
1590 |
1591 | | City | Population |
1592 |
1593 | | ------------ | ---------- |
1594 |
1595 | | Seattle, WA | 8 |
1596 |
1597 | | Portland, OR | 4 |
1598 |
1599 |
1600 | ^2c7cfa
1601 |
1602 | ```
1603 |
1604 |
1605 | ## Append Content Below a Heading
1606 |
1607 |
1608 | If you wanted to append the content "Hello" below "Subheading 1:1:1"
1609 | under "Heading 1",
1610 |
1611 | you could send a request with the following headers:
1612 |
1613 |
1614 | - `Operation`: `append`
1615 |
1616 | - `Target-Type`: `heading`
1617 |
1618 | - `Target`: `Heading 1::Subheading 1:1:1`
1619 |
1620 | - with the request body: `Hello`
1621 |
1622 |
1623 | The above would work just fine for `prepend` or `replace`, too, of
1624 | course,
1625 |
1626 | but with different results.
1627 |
1628 |
1629 | ## Append Content to a Block Reference
1630 |
1631 |
1632 | If you wanted to append the content "Hello" below the block referenced
1633 | by
1634 |
1635 | "2d9b4a" above ("More random text."), you could send the following
1636 | headers:
1637 |
1638 |
1639 | - `Operation`: `append`
1640 |
1641 | - `Target-Type`: `block`
1642 |
1643 | - `Target`: `2d9b4a`
1644 |
1645 | - with the request body: `Hello`
1646 |
1647 |
1648 | The above would work just fine for `prepend` or `replace`, too, of
1649 | course,
1650 |
1651 | but with different results.
1652 |
1653 |
1654 | ## Add a Row to a Table Referenced by a Block Reference
1655 |
1656 |
1657 | If you wanted to add a new city ("Chicago, IL") and population ("16")
1658 | pair to the table above
1659 |
1660 | referenced by the block reference `2c7cfa`, you could send the following
1661 |
1662 | headers:
1663 |
1664 |
1665 | - `Operation`: `append`
1666 |
1667 | - `TargetType`: `block`
1668 |
1669 | - `Target`: `2c7cfa`
1670 |
1671 | - `Content-Type`: `application/json`
1672 |
1673 | - with the request body: `[["Chicago, IL", "16"]]`
1674 |
1675 |
1676 | The use of a `Content-Type` of `application/json` allows the API
1677 |
1678 | to infer that member of your array represents rows and columns of your
1679 |
1680 | to append to the referenced table. You can of course just use a
1681 |
1682 | `Content-Type` of `text/markdown`, but in such a case you'll have to
1683 |
1684 | format your table row manually instead of letting the library figure
1685 |
1686 | it out for you.
1687 |
1688 |
1689 | You also have the option of using `prepend` (in which case, your new
1690 |
1691 | row would be the first -- right below the table heading) or `replace`
1692 | (in which
1693 |
1694 | case all rows except the table heading would be replaced by the new
1695 | row(s)
1696 |
1697 | you supplied).
1698 |
1699 |
1700 | ## Setting a Frontmatter Field
1701 |
1702 |
1703 | If you wanted to set the frontmatter field `alpha` to `2`, you could
1704 |
1705 | send the following headers:
1706 |
1707 |
1708 | - `Operation`: `replace`
1709 |
1710 | - `TargetType`: `frontmatter`
1711 |
1712 | - `Target`: `beep`
1713 |
1714 | - with the request body `2`
1715 |
1716 |
1717 | If you're setting a frontmatter field that might not already exist
1718 |
1719 | you may want to use the `Create-Target-If-Missing` header so the
1720 |
1721 | new frontmatter field is created and set to your specified value
1722 |
1723 | if it doesn't already exist.
1724 |
1725 |
1726 | You may find using a `Content-Type` of `application/json` to be
1727 |
1728 | particularly useful in the case of frontmatter since frontmatter
1729 |
1730 | fields' values are JSON data, and the API can be smarter about
1731 |
1732 | interpreting yoru `prepend` or `append` requests if you specify
1733 |
1734 | your data as JSON (particularly when appending, for example,
1735 |
1736 | list items).
1737 | parameters:
1738 | - description: Patch operation to perform
1739 | in: header
1740 | name: Operation
1741 | required: true
1742 | schema:
1743 | enum:
1744 | - append
1745 | - prepend
1746 | - replace
1747 | type: string
1748 | - description: Type of target to patch
1749 | in: header
1750 | name: Target-Type
1751 | required: true
1752 | schema:
1753 | enum:
1754 | - heading
1755 | - block
1756 | - frontmatter
1757 | type: string
1758 | - description: Delimiter to use for nested targets (i.e. Headings)
1759 | in: header
1760 | name: Target-Delimiter
1761 | required: false
1762 | schema:
1763 | default: '::'
1764 | type: string
1765 | - description: |
1766 | Target to patch; this value can be URL-Encoded and *must*
1767 | be URL-Encoded if it includes non-ASCII characters.
1768 | in: header
1769 | name: Target
1770 | required: true
1771 | schema:
1772 | type: string
1773 | - description: Trim whitespace from Target before applying patch?
1774 | in: header
1775 | name: Trim-Target-Whitespace
1776 | required: false
1777 | schema:
1778 | default: 'false'
1779 | enum:
1780 | - 'true'
1781 | - 'false'
1782 | type: string
1783 | - description: |
1784 | Path to the relevant file (relative to your vault root).
1785 | in: path
1786 | name: filename
1787 | required: true
1788 | schema:
1789 | format: path
1790 | type: string
1791 | requestBody:
1792 | content:
1793 | application/json:
1794 | schema:
1795 | example: '[''one'', ''two'']'
1796 | type: string
1797 | text/markdown:
1798 | schema:
1799 | example: |
1800 | # This is my document
1801 |
1802 | something else here
1803 | type: string
1804 | description: Content you would like to insert.
1805 | required: true
1806 | responses:
1807 | '200':
1808 | description: Success
1809 | '400':
1810 | content:
1811 | application/json:
1812 | schema:
1813 | $ref: '#/components/schemas/Error'
1814 | description: Bad Request; see response message for details.
1815 | '404':
1816 | content:
1817 | application/json:
1818 | schema:
1819 | $ref: '#/components/schemas/Error'
1820 | description: Does not exist
1821 | '405':
1822 | content:
1823 | application/json:
1824 | schema:
1825 | $ref: '#/components/schemas/Error'
1826 | description: >
1827 | Your path references a directory instead of a file; this request
1828 | method is valid only for updating files.
1829 | summary: >
1830 | Insert content into an existing note relative to a heading within that
1831 | document.
1832 | tags:
1833 | - Vault Files
1834 | post:
1835 | description: >
1836 | Appends content to the end of an existing note. If the specified file
1837 | does not yet exist, it will be created as an empty file.
1838 |
1839 |
1840 | If you would like to insert text relative to a particular heading
1841 | instead of appending to the end of the file, see 'patch'.
1842 | parameters:
1843 | - description: |
1844 | Path to the relevant file (relative to your vault root).
1845 | in: path
1846 | name: filename
1847 | required: true
1848 | schema:
1849 | format: path
1850 | type: string
1851 | requestBody:
1852 | content:
1853 | text/markdown:
1854 | schema:
1855 | example: |
1856 | # This is my document
1857 |
1858 | something else here
1859 | type: string
1860 | description: Content you would like to append.
1861 | required: true
1862 | responses:
1863 | '204':
1864 | description: Success
1865 | '400':
1866 | content:
1867 | application/json:
1868 | schema:
1869 | $ref: '#/components/schemas/Error'
1870 | description: Bad Request
1871 | '405':
1872 | content:
1873 | application/json:
1874 | schema:
1875 | $ref: '#/components/schemas/Error'
1876 | description: >
1877 | Your path references a directory instead of a file; this request
1878 | method is valid only for updating files.
1879 | summary: |
1880 | Append content to a new or existing file.
1881 | tags:
1882 | - Vault Files
1883 | put:
1884 | description: >
1885 | Creates a new file in your vault or updates the content of an existing
1886 | one if the specified file already exists.
1887 | parameters:
1888 | - description: |
1889 | Path to the relevant file (relative to your vault root).
1890 | in: path
1891 | name: filename
1892 | required: true
1893 | schema:
1894 | format: path
1895 | type: string
1896 | requestBody:
1897 | content:
1898 | '*/*':
1899 | schema:
1900 | type: string
1901 | text/markdown:
1902 | schema:
1903 | example: |
1904 | # This is my document
1905 |
1906 | something else here
1907 | type: string
1908 | description: Content of the file you would like to upload.
1909 | required: true
1910 | responses:
1911 | '204':
1912 | description: Success
1913 | '400':
1914 | content:
1915 | application/json:
1916 | schema:
1917 | $ref: '#/components/schemas/Error'
1918 | description: >
1919 | Incoming file could not be processed. Make sure you have specified
1920 | a reasonable file name, and make sure you have set a reasonable
1921 | 'Content-Type' header; if you are uploading a note, 'text/markdown'
1922 | is likely the right choice.
1923 | '405':
1924 | content:
1925 | application/json:
1926 | schema:
1927 | $ref: '#/components/schemas/Error'
1928 | description: >
1929 | Your path references a directory instead of a file; this request
1930 | method is valid only for updating files.
1931 | summary: >
1932 | Create a new file in your vault or update the content of an existing
1933 | one.
1934 | tags:
1935 | - Vault Files
1936 | /vault/{pathToDirectory}/:
1937 | get:
1938 | parameters:
1939 | - description: >
1940 | Path to list files from (relative to your vault root). Note that
1941 | empty directories will not be returned.
1942 |
1943 |
1944 | Note: this particular interactive tool requires that you provide an
1945 | argument for this field, but the API itself will allow you to list
1946 | the root folder of your vault. If you would like to try listing
1947 | content in the root of your vault using this interactive tool, use
1948 | the above "List files that exist in the root of your vault" form
1949 | above.
1950 | in: path
1951 | name: pathToDirectory
1952 | required: true
1953 | schema:
1954 | format: path
1955 | type: string
1956 | responses:
1957 | '200':
1958 | content:
1959 | application/json:
1960 | example:
1961 | files:
1962 | - mydocument.md
1963 | - somedirectory/
1964 | schema:
1965 | properties:
1966 | files:
1967 | items:
1968 | type: string
1969 | type: array
1970 | type: object
1971 | description: Success
1972 | '404':
1973 | content:
1974 | application/json:
1975 | schema:
1976 | $ref: '#/components/schemas/Error'
1977 | description: Directory does not exist
1978 | summary: |
1979 | List files that exist in the specified directory.
1980 | tags:
1981 | - Vault Directories
1982 | security:
1983 | - apiKeyAuth: []
1984 | servers:
1985 | - description: HTTPS (Secure Mode)
1986 | url: https://{host}:{port}
1987 | variables:
1988 | host:
1989 | default: 127.0.0.1
1990 | description: Binding host
1991 | port:
1992 | default: '27124'
1993 | description: HTTPS port
1994 | - description: HTTP (Insecure Mode)
1995 | url: http://{host}:{port}
1996 | variables:
1997 | host:
1998 | default: 127.0.0.1
1999 | description: Binding host
2000 | port:
2001 | default: '27123'
2002 | description: HTTP port
2003 |
```
--------------------------------------------------------------------------------
/docs/obsidian-api/obsidian_rest_api_spec.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "components": {
3 | "schemas": {
4 | "Error": {
5 | "properties": {
6 | "errorCode": {
7 | "description": "A 5-digit error code uniquely identifying this particular type of error.\n",
8 | "example": 40149,
9 | "type": "number"
10 | },
11 | "message": {
12 | "description": "Message describing the error.",
13 | "example": "A brief description of the error.",
14 | "type": "string"
15 | }
16 | },
17 | "type": "object"
18 | },
19 | "NoteJson": {
20 | "properties": {
21 | "content": {
22 | "type": "string"
23 | },
24 | "frontmatter": {
25 | "type": "object"
26 | },
27 | "path": {
28 | "type": "string"
29 | },
30 | "stat": {
31 | "properties": {
32 | "ctime": {
33 | "type": "number"
34 | },
35 | "mtime": {
36 | "type": "number"
37 | },
38 | "size": {
39 | "type": "number"
40 | }
41 | },
42 | "required": ["ctime", "mtime", "size"],
43 | "type": "object"
44 | },
45 | "tags": {
46 | "items": {
47 | "type": "string"
48 | },
49 | "type": "array"
50 | }
51 | },
52 | "required": ["tags", "frontmatter", "stat", "path", "content"],
53 | "type": "object"
54 | }
55 | },
56 | "securitySchemes": {
57 | "apiKeyAuth": {
58 | "description": "Find your API Key in your Obsidian settings\nin the \"Local REST API\" section under \"Plugins\".\n",
59 | "scheme": "bearer",
60 | "type": "http"
61 | }
62 | }
63 | },
64 | "info": {
65 | "description": "You can use this interface for trying out your Local REST API in Obsidian.\n\nBefore trying the below tools, you will want to make sure you press the \"Authorize\" button below and provide the API Key you are shown when you open the \"Local REST API\" section of your Obsidian settings. All requests to the API require a valid API Key; so you won't get very far without doing that.\n\nWhen using this tool you may see browser security warnings due to your browser not trusting the self-signed certificate the plugin will generate on its first run. If you do, you can make those errors disappear by adding the certificate as a \"Trusted Certificate\" in your browser or operating system's settings.\n",
66 | "title": "Local REST API for Obsidian",
67 | "version": "1.0"
68 | },
69 | "openapi": "3.0.2",
70 | "paths": {
71 | "/": {
72 | "get": {
73 | "description": "Returns basic details about the server as well as your authentication status.\n\nThis is the only API request that does *not* require authentication.\n",
74 | "responses": {
75 | "200": {
76 | "content": {
77 | "application/json": {
78 | "schema": {
79 | "properties": {
80 | "authenticated": {
81 | "description": "Is your current request authenticated?",
82 | "type": "boolean"
83 | },
84 | "ok": {
85 | "description": "'OK'",
86 | "type": "string"
87 | },
88 | "service": {
89 | "description": "'Obsidian Local REST API'",
90 | "type": "string"
91 | },
92 | "versions": {
93 | "properties": {
94 | "obsidian": {
95 | "description": "Obsidian plugin API version",
96 | "type": "string"
97 | },
98 | "self": {
99 | "description": "Plugin version.",
100 | "type": "string"
101 | }
102 | },
103 | "type": "object"
104 | }
105 | },
106 | "type": "object"
107 | }
108 | }
109 | },
110 | "description": "Success"
111 | }
112 | },
113 | "summary": "Returns basic details about the server.\n",
114 | "tags": ["Status"]
115 | }
116 | },
117 | "/active/": {
118 | "delete": {
119 | "parameters": [],
120 | "responses": {
121 | "204": {
122 | "description": "Success"
123 | },
124 | "404": {
125 | "content": {
126 | "application/json": {
127 | "schema": {
128 | "$ref": "#/components/schemas/Error"
129 | }
130 | }
131 | },
132 | "description": "File does not exist."
133 | },
134 | "405": {
135 | "content": {
136 | "application/json": {
137 | "schema": {
138 | "$ref": "#/components/schemas/Error"
139 | }
140 | }
141 | },
142 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
143 | }
144 | },
145 | "summary": "Deletes the currently-active file in Obsidian.\n",
146 | "tags": ["Active File"]
147 | },
148 | "get": {
149 | "description": "Returns the content of the currently active file in Obsidian.\n\nIf you specify the header `Accept: application/vnd.olrapi.note+json`, will return a JSON representation of your note including parsed tag and frontmatter data as well as filesystem metadata. See \"responses\" below for details.\n",
150 | "parameters": [],
151 | "responses": {
152 | "200": {
153 | "content": {
154 | "application/vnd.olrapi.note+json": {
155 | "schema": {
156 | "$ref": "#/components/schemas/NoteJson"
157 | }
158 | },
159 | "text/markdown": {
160 | "schema": {
161 | "example": "# This is my document\n\nsomething else here\n",
162 | "type": "string"
163 | }
164 | }
165 | },
166 | "description": "Success"
167 | },
168 | "404": {
169 | "description": "File does not exist"
170 | }
171 | },
172 | "summary": "Return the content of the active file open in Obsidian.\n",
173 | "tags": ["Active File"]
174 | },
175 | "patch": {
176 | "description": "Inserts content into the currently-open note relative to a heading within that note.\n\nAllows you to modify the content relative to a heading, block reference, or frontmatter field in your document.\n\nNote that this API was changed in Version 3.0 of this extension and the earlier PATCH API is now deprecated. Requests made using the previous version of this API will continue to work until Version 4.0 is released. See https://github.com/coddingtonbear/obsidian-local-rest-api/wiki/Changes-to-PATCH-requests-between-versions-2.0-and-3.0 for more details and migration instructions.\n\n# Examples\n\nAll of the below examples assume you have a document that looks like\nthis:\n\n```markdown\n---\nalpha: 1\nbeta: test\ndelta:\nzeta: 1\nyotta: 1\ngamma:\n- one\n- two\n---\n\n# Heading 1\n\nThis is the content for heading one\n\nAlso references some [[#^484ef2]]\n\n## Subheading 1:1\nContent for Subheading 1:1\n\n### Subsubheading 1:1:1\n\n### Subsubheading 1:1:2\n\nTesting how block references work for a table.[[#^2c7cfa]]\nSome content for Subsubheading 1:1:2\n\nMore random text.\n\n^2d9b4a\n\n## Subheading 1:2\n\nContent for Subheading 1:2.\n\nsome content with a block reference ^484ef2\n\n## Subheading 1:3\n| City | Population |\n| ------------ | ---------- |\n| Seattle, WA | 8 |\n| Portland, OR | 4 |\n\n^2c7cfa\n```\n\n## Append Content Below a Heading\n\nIf you wanted to append the content \"Hello\" below \"Subheading 1:1:1\" under \"Heading 1\",\nyou could send a request with the following headers:\n\n- `Operation`: `append`\n- `Target-Type`: `heading`\n- `Target`: `Heading 1::Subheading 1:1:1`\n- with the request body: `Hello`\n\nThe above would work just fine for `prepend` or `replace`, too, of course,\nbut with different results.\n\n## Append Content to a Block Reference\n\nIf you wanted to append the content \"Hello\" below the block referenced by\n\"2d9b4a\" above (\"More random text.\"), you could send the following headers:\n\n- `Operation`: `append`\n- `Target-Type`: `block`\n- `Target`: `2d9b4a`\n- with the request body: `Hello`\n\nThe above would work just fine for `prepend` or `replace`, too, of course,\nbut with different results.\n\n## Add a Row to a Table Referenced by a Block Reference\n\nIf you wanted to add a new city (\"Chicago, IL\") and population (\"16\") pair to the table above\nreferenced by the block reference `2c7cfa`, you could send the following\nheaders:\n\n- `Operation`: `append`\n- `TargetType`: `block`\n- `Target`: `2c7cfa`\n- `Content-Type`: `application/json`\n- with the request body: `[[\"Chicago, IL\", \"16\"]]`\n\nThe use of a `Content-Type` of `application/json` allows the API\nto infer that member of your array represents rows and columns of your\nto append to the referenced table. You can of course just use a\n`Content-Type` of `text/markdown`, but in such a case you'll have to\nformat your table row manually instead of letting the library figure\nit out for you.\n\nYou also have the option of using `prepend` (in which case, your new\nrow would be the first -- right below the table heading) or `replace` (in which\ncase all rows except the table heading would be replaced by the new row(s)\nyou supplied).\n\n## Setting a Frontmatter Field\n\nIf you wanted to set the frontmatter field `alpha` to `2`, you could\nsend the following headers:\n\n- `Operation`: `replace`\n- `TargetType`: `frontmatter`\n- `Target`: `beep`\n- with the request body `2`\n\nIf you're setting a frontmatter field that might not already exist\nyou may want to use the `Create-Target-If-Missing` header so the\nnew frontmatter field is created and set to your specified value\nif it doesn't already exist.\n\nYou may find using a `Content-Type` of `application/json` to be\nparticularly useful in the case of frontmatter since frontmatter\nfields' values are JSON data, and the API can be smarter about\ninterpreting yoru `prepend` or `append` requests if you specify\nyour data as JSON (particularly when appending, for example,\nlist items).\n",
177 | "parameters": [
178 | {
179 | "description": "Patch operation to perform",
180 | "in": "header",
181 | "name": "Operation",
182 | "required": true,
183 | "schema": {
184 | "enum": ["append", "prepend", "replace"],
185 | "type": "string"
186 | }
187 | },
188 | {
189 | "description": "Type of target to patch",
190 | "in": "header",
191 | "name": "Target-Type",
192 | "required": true,
193 | "schema": {
194 | "enum": ["heading", "block", "frontmatter"],
195 | "type": "string"
196 | }
197 | },
198 | {
199 | "description": "Delimiter to use for nested targets (i.e. Headings)",
200 | "in": "header",
201 | "name": "Target-Delimiter",
202 | "required": false,
203 | "schema": {
204 | "default": "::",
205 | "type": "string"
206 | }
207 | },
208 | {
209 | "description": "Target to patch; this value can be URL-Encoded and *must*\nbe URL-Encoded if it includes non-ASCII characters.\n",
210 | "in": "header",
211 | "name": "Target",
212 | "required": true,
213 | "schema": {
214 | "type": "string"
215 | }
216 | },
217 | {
218 | "description": "Trim whitespace from Target before applying patch?",
219 | "in": "header",
220 | "name": "Trim-Target-Whitespace",
221 | "required": false,
222 | "schema": {
223 | "default": "false",
224 | "enum": ["true", "false"],
225 | "type": "string"
226 | }
227 | }
228 | ],
229 | "requestBody": {
230 | "content": {
231 | "application/json": {
232 | "schema": {
233 | "example": "['one', 'two']",
234 | "type": "string"
235 | }
236 | },
237 | "text/markdown": {
238 | "schema": {
239 | "example": "# This is my document\n\nsomething else here\n",
240 | "type": "string"
241 | }
242 | }
243 | },
244 | "description": "Content you would like to insert.",
245 | "required": true
246 | },
247 | "responses": {
248 | "200": {
249 | "description": "Success"
250 | },
251 | "400": {
252 | "content": {
253 | "application/json": {
254 | "schema": {
255 | "$ref": "#/components/schemas/Error"
256 | }
257 | }
258 | },
259 | "description": "Bad Request; see response message for details."
260 | },
261 | "404": {
262 | "content": {
263 | "application/json": {
264 | "schema": {
265 | "$ref": "#/components/schemas/Error"
266 | }
267 | }
268 | },
269 | "description": "Does not exist"
270 | },
271 | "405": {
272 | "content": {
273 | "application/json": {
274 | "schema": {
275 | "$ref": "#/components/schemas/Error"
276 | }
277 | }
278 | },
279 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
280 | }
281 | },
282 | "summary": "Insert content into the currently open note in Obsidian relative to a heading within that document.\n",
283 | "tags": ["Active File"]
284 | },
285 | "post": {
286 | "description": "Appends content to the end of the currently-open note.\n\nIf you would like to insert text relative to a particular heading instead of appending to the end of the file, see 'patch'.\n",
287 | "parameters": [],
288 | "requestBody": {
289 | "content": {
290 | "text/markdown": {
291 | "schema": {
292 | "example": "# This is my document\n\nsomething else here\n",
293 | "type": "string"
294 | }
295 | }
296 | },
297 | "description": "Content you would like to append.",
298 | "required": true
299 | },
300 | "responses": {
301 | "204": {
302 | "description": "Success"
303 | },
304 | "400": {
305 | "content": {
306 | "application/json": {
307 | "schema": {
308 | "$ref": "#/components/schemas/Error"
309 | }
310 | }
311 | },
312 | "description": "Bad Request"
313 | },
314 | "405": {
315 | "content": {
316 | "application/json": {
317 | "schema": {
318 | "$ref": "#/components/schemas/Error"
319 | }
320 | }
321 | },
322 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
323 | }
324 | },
325 | "summary": "Append content to the active file open in Obsidian.\n",
326 | "tags": ["Active File"]
327 | },
328 | "put": {
329 | "requestBody": {
330 | "content": {
331 | "*/*": {
332 | "schema": {
333 | "type": "string"
334 | }
335 | },
336 | "text/markdown": {
337 | "schema": {
338 | "example": "# This is my document\n\nsomething else here\n",
339 | "type": "string"
340 | }
341 | }
342 | },
343 | "description": "Content of the file you would like to upload.",
344 | "required": true
345 | },
346 | "responses": {
347 | "204": {
348 | "description": "Success"
349 | },
350 | "400": {
351 | "content": {
352 | "application/json": {
353 | "schema": {
354 | "$ref": "#/components/schemas/Error"
355 | }
356 | }
357 | },
358 | "description": "Incoming file could not be processed. Make sure you have specified a reasonable file name, and make sure you have set a reasonable 'Content-Type' header; if you are uploading a note, 'text/markdown' is likely the right choice.\n"
359 | },
360 | "405": {
361 | "content": {
362 | "application/json": {
363 | "schema": {
364 | "$ref": "#/components/schemas/Error"
365 | }
366 | }
367 | },
368 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
369 | }
370 | },
371 | "summary": "Update the content of the active file open in Obsidian.\n",
372 | "tags": ["Active File"]
373 | }
374 | },
375 | "/commands/": {
376 | "get": {
377 | "responses": {
378 | "200": {
379 | "content": {
380 | "application/json": {
381 | "example": {
382 | "commands": [
383 | {
384 | "id": "global-search:open",
385 | "name": "Search: Search in all files"
386 | },
387 | {
388 | "id": "graph:open",
389 | "name": "Graph view: Open graph view"
390 | }
391 | ]
392 | },
393 | "schema": {
394 | "properties": {
395 | "commands": {
396 | "items": {
397 | "properties": {
398 | "id": {
399 | "type": "string"
400 | },
401 | "name": {
402 | "type": "string"
403 | }
404 | },
405 | "type": "object"
406 | },
407 | "type": "array"
408 | }
409 | },
410 | "type": "object"
411 | }
412 | }
413 | },
414 | "description": "A list of available commands."
415 | }
416 | },
417 | "summary": "Get a list of available commands.\n",
418 | "tags": ["Commands"]
419 | }
420 | },
421 | "/commands/{commandId}/": {
422 | "post": {
423 | "parameters": [
424 | {
425 | "description": "The id of the command to execute",
426 | "in": "path",
427 | "name": "commandId",
428 | "required": true,
429 | "schema": {
430 | "type": "string"
431 | }
432 | }
433 | ],
434 | "responses": {
435 | "204": {
436 | "description": "Success"
437 | },
438 | "404": {
439 | "content": {
440 | "application/json": {
441 | "schema": {
442 | "$ref": "#/components/schemas/Error"
443 | }
444 | }
445 | },
446 | "description": "The command you specified does not exist."
447 | }
448 | },
449 | "summary": "Execute a command.\n",
450 | "tags": ["Commands"]
451 | }
452 | },
453 | "/open/{filename}": {
454 | "post": {
455 | "description": "Opens the specified document in Obsidian.\n\nNote: Obsidian will create a new document at the path you have\nspecified if such a document did not already exist.\n",
456 | "parameters": [
457 | {
458 | "description": "Path to the file to return (relative to your vault root).\n",
459 | "in": "path",
460 | "name": "filename",
461 | "required": true,
462 | "schema": {
463 | "format": "path",
464 | "type": "string"
465 | }
466 | },
467 | {
468 | "description": "Open this as a new leaf?",
469 | "in": "query",
470 | "name": "newLeaf",
471 | "required": false,
472 | "schema": {
473 | "type": "boolean"
474 | }
475 | }
476 | ],
477 | "responses": {
478 | "200": {
479 | "description": "Success"
480 | }
481 | },
482 | "summary": "Open the specified document in Obsidian\n",
483 | "tags": ["Open"]
484 | }
485 | },
486 | "/periodic/{period}/": {
487 | "delete": {
488 | "description": "Deletes the periodic note for the specified period.\n",
489 | "parameters": [
490 | {
491 | "description": "The name of the period for which you would like to grab the current note.",
492 | "in": "path",
493 | "name": "period",
494 | "required": true,
495 | "schema": {
496 | "default": "daily",
497 | "enum": ["daily", "weekly", "monthly", "quarterly", "yearly"],
498 | "type": "string"
499 | }
500 | }
501 | ],
502 | "responses": {
503 | "204": {
504 | "description": "Success"
505 | },
506 | "404": {
507 | "content": {
508 | "application/json": {
509 | "schema": {
510 | "$ref": "#/components/schemas/Error"
511 | }
512 | }
513 | },
514 | "description": "File does not exist."
515 | },
516 | "405": {
517 | "content": {
518 | "application/json": {
519 | "schema": {
520 | "$ref": "#/components/schemas/Error"
521 | }
522 | }
523 | },
524 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
525 | }
526 | },
527 | "summary": "Delete a periodic note.\n",
528 | "tags": ["Periodic Notes"]
529 | },
530 | "get": {
531 | "parameters": [
532 | {
533 | "description": "The name of the period for which you would like to grab the current note.",
534 | "in": "path",
535 | "name": "period",
536 | "required": true,
537 | "schema": {
538 | "default": "daily",
539 | "enum": ["daily", "weekly", "monthly", "quarterly", "yearly"],
540 | "type": "string"
541 | }
542 | }
543 | ],
544 | "responses": {
545 | "200": {
546 | "content": {
547 | "application/vnd.olrapi.note+json": {
548 | "schema": {
549 | "$ref": "#/components/schemas/NoteJson"
550 | }
551 | },
552 | "text/markdown": {
553 | "schema": {
554 | "example": "# This is my document\n\nsomething else here\n",
555 | "type": "string"
556 | }
557 | }
558 | },
559 | "description": "Success"
560 | },
561 | "404": {
562 | "description": "File does not exist"
563 | }
564 | },
565 | "summary": "Get current periodic note for the specified period.\n",
566 | "tags": ["Periodic Notes"]
567 | },
568 | "patch": {
569 | "description": "Inserts content into an existing note relative to a heading within your note.\n\nAllows you to modify the content relative to a heading, block reference, or frontmatter field in your document.\n\nNote that this API was changed in Version 3.0 of this extension and the earlier PATCH API is now deprecated. Requests made using the previous version of this API will continue to work until Version 4.0 is released. See https://github.com/coddingtonbear/obsidian-local-rest-api/wiki/Changes-to-PATCH-requests-between-versions-2.0-and-3.0 for more details and migration instructions.\n\n# Examples\n\nAll of the below examples assume you have a document that looks like\nthis:\n\n```markdown\n---\nalpha: 1\nbeta: test\ndelta:\nzeta: 1\nyotta: 1\ngamma:\n- one\n- two\n---\n\n# Heading 1\n\nThis is the content for heading one\n\nAlso references some [[#^484ef2]]\n\n## Subheading 1:1\nContent for Subheading 1:1\n\n### Subsubheading 1:1:1\n\n### Subsubheading 1:1:2\n\nTesting how block references work for a table.[[#^2c7cfa]]\nSome content for Subsubheading 1:1:2\n\nMore random text.\n\n^2d9b4a\n\n## Subheading 1:2\n\nContent for Subheading 1:2.\n\nsome content with a block reference ^484ef2\n\n## Subheading 1:3\n| City | Population |\n| ------------ | ---------- |\n| Seattle, WA | 8 |\n| Portland, OR | 4 |\n\n^2c7cfa\n```\n\n## Append Content Below a Heading\n\nIf you wanted to append the content \"Hello\" below \"Subheading 1:1:1\" under \"Heading 1\",\nyou could send a request with the following headers:\n\n- `Operation`: `append`\n- `Target-Type`: `heading`\n- `Target`: `Heading 1::Subheading 1:1:1`\n- with the request body: `Hello`\n\nThe above would work just fine for `prepend` or `replace`, too, of course,\nbut with different results.\n\n## Append Content to a Block Reference\n\nIf you wanted to append the content \"Hello\" below the block referenced by\n\"2d9b4a\" above (\"More random text.\"), you could send the following headers:\n\n- `Operation`: `append`\n- `Target-Type`: `block`\n- `Target`: `2d9b4a`\n- with the request body: `Hello`\n\nThe above would work just fine for `prepend` or `replace`, too, of course,\nbut with different results.\n\n## Add a Row to a Table Referenced by a Block Reference\n\nIf you wanted to add a new city (\"Chicago, IL\") and population (\"16\") pair to the table above\nreferenced by the block reference `2c7cfa`, you could send the following\nheaders:\n\n- `Operation`: `append`\n- `TargetType`: `block`\n- `Target`: `2c7cfa`\n- `Content-Type`: `application/json`\n- with the request body: `[[\"Chicago, IL\", \"16\"]]`\n\nThe use of a `Content-Type` of `application/json` allows the API\nto infer that member of your array represents rows and columns of your\nto append to the referenced table. You can of course just use a\n`Content-Type` of `text/markdown`, but in such a case you'll have to\nformat your table row manually instead of letting the library figure\nit out for you.\n\nYou also have the option of using `prepend` (in which case, your new\nrow would be the first -- right below the table heading) or `replace` (in which\ncase all rows except the table heading would be replaced by the new row(s)\nyou supplied).\n\n## Setting a Frontmatter Field\n\nIf you wanted to set the frontmatter field `alpha` to `2`, you could\nsend the following headers:\n\n- `Operation`: `replace`\n- `TargetType`: `frontmatter`\n- `Target`: `beep`\n- with the request body `2`\n\nIf you're setting a frontmatter field that might not already exist\nyou may want to use the `Create-Target-If-Missing` header so the\nnew frontmatter field is created and set to your specified value\nif it doesn't already exist.\n\nYou may find using a `Content-Type` of `application/json` to be\nparticularly useful in the case of frontmatter since frontmatter\nfields' values are JSON data, and the API can be smarter about\ninterpreting yoru `prepend` or `append` requests if you specify\nyour data as JSON (particularly when appending, for example,\nlist items).\n",
570 | "parameters": [
571 | {
572 | "description": "Patch operation to perform",
573 | "in": "header",
574 | "name": "Operation",
575 | "required": true,
576 | "schema": {
577 | "enum": ["append", "prepend", "replace"],
578 | "type": "string"
579 | }
580 | },
581 | {
582 | "description": "Type of target to patch",
583 | "in": "header",
584 | "name": "Target-Type",
585 | "required": true,
586 | "schema": {
587 | "enum": ["heading", "block", "frontmatter"],
588 | "type": "string"
589 | }
590 | },
591 | {
592 | "description": "Delimiter to use for nested targets (i.e. Headings)",
593 | "in": "header",
594 | "name": "Target-Delimiter",
595 | "required": false,
596 | "schema": {
597 | "default": "::",
598 | "type": "string"
599 | }
600 | },
601 | {
602 | "description": "Target to patch; this value can be URL-Encoded and *must*\nbe URL-Encoded if it includes non-ASCII characters.\n",
603 | "in": "header",
604 | "name": "Target",
605 | "required": true,
606 | "schema": {
607 | "type": "string"
608 | }
609 | },
610 | {
611 | "description": "Trim whitespace from Target before applying patch?",
612 | "in": "header",
613 | "name": "Trim-Target-Whitespace",
614 | "required": false,
615 | "schema": {
616 | "default": "false",
617 | "enum": ["true", "false"],
618 | "type": "string"
619 | }
620 | },
621 | {
622 | "description": "The name of the period for which you would like to grab the current note.",
623 | "in": "path",
624 | "name": "period",
625 | "required": true,
626 | "schema": {
627 | "default": "daily",
628 | "enum": ["daily", "weekly", "monthly", "quarterly", "yearly"],
629 | "type": "string"
630 | }
631 | }
632 | ],
633 | "requestBody": {
634 | "content": {
635 | "application/json": {
636 | "schema": {
637 | "example": "['one', 'two']",
638 | "type": "string"
639 | }
640 | },
641 | "text/markdown": {
642 | "schema": {
643 | "example": "# This is my document\n\nsomething else here\n",
644 | "type": "string"
645 | }
646 | }
647 | },
648 | "description": "Content you would like to insert.",
649 | "required": true
650 | },
651 | "responses": {
652 | "200": {
653 | "description": "Success"
654 | },
655 | "400": {
656 | "content": {
657 | "application/json": {
658 | "schema": {
659 | "$ref": "#/components/schemas/Error"
660 | }
661 | }
662 | },
663 | "description": "Bad Request; see response message for details."
664 | },
665 | "404": {
666 | "content": {
667 | "application/json": {
668 | "schema": {
669 | "$ref": "#/components/schemas/Error"
670 | }
671 | }
672 | },
673 | "description": "Does not exist"
674 | },
675 | "405": {
676 | "content": {
677 | "application/json": {
678 | "schema": {
679 | "$ref": "#/components/schemas/Error"
680 | }
681 | }
682 | },
683 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
684 | }
685 | },
686 | "summary": "Insert content into a periodic note relative to a heading within that document.\n",
687 | "tags": ["Periodic Notes"]
688 | },
689 | "post": {
690 | "description": "Appends content to the periodic note for the specified period. This will create the relevant periodic note if necessary.\n",
691 | "parameters": [
692 | {
693 | "description": "The name of the period for which you would like to grab the current note.",
694 | "in": "path",
695 | "name": "period",
696 | "required": true,
697 | "schema": {
698 | "default": "daily",
699 | "enum": ["daily", "weekly", "monthly", "quarterly", "yearly"],
700 | "type": "string"
701 | }
702 | }
703 | ],
704 | "requestBody": {
705 | "content": {
706 | "text/markdown": {
707 | "schema": {
708 | "example": "# This is my document\n\nsomething else here\n",
709 | "type": "string"
710 | }
711 | }
712 | },
713 | "description": "Content you would like to append.",
714 | "required": true
715 | },
716 | "responses": {
717 | "204": {
718 | "description": "Success"
719 | },
720 | "400": {
721 | "content": {
722 | "application/json": {
723 | "schema": {
724 | "$ref": "#/components/schemas/Error"
725 | }
726 | }
727 | },
728 | "description": "Bad Request"
729 | },
730 | "405": {
731 | "content": {
732 | "application/json": {
733 | "schema": {
734 | "$ref": "#/components/schemas/Error"
735 | }
736 | }
737 | },
738 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
739 | }
740 | },
741 | "summary": "Append content to a periodic note.\n",
742 | "tags": ["Periodic Notes"]
743 | },
744 | "put": {
745 | "parameters": [
746 | {
747 | "description": "The name of the period for which you would like to grab the current note.",
748 | "in": "path",
749 | "name": "period",
750 | "required": true,
751 | "schema": {
752 | "default": "daily",
753 | "enum": ["daily", "weekly", "monthly", "quarterly", "yearly"],
754 | "type": "string"
755 | }
756 | }
757 | ],
758 | "requestBody": {
759 | "content": {
760 | "*/*": {
761 | "schema": {
762 | "type": "string"
763 | }
764 | },
765 | "text/markdown": {
766 | "schema": {
767 | "example": "# This is my document\n\nsomething else here\n",
768 | "type": "string"
769 | }
770 | }
771 | },
772 | "description": "Content of the file you would like to upload.",
773 | "required": true
774 | },
775 | "responses": {
776 | "204": {
777 | "description": "Success"
778 | },
779 | "400": {
780 | "content": {
781 | "application/json": {
782 | "schema": {
783 | "$ref": "#/components/schemas/Error"
784 | }
785 | }
786 | },
787 | "description": "Incoming file could not be processed. Make sure you have specified a reasonable file name, and make sure you have set a reasonable 'Content-Type' header; if you are uploading a note, 'text/markdown' is likely the right choice.\n"
788 | },
789 | "405": {
790 | "content": {
791 | "application/json": {
792 | "schema": {
793 | "$ref": "#/components/schemas/Error"
794 | }
795 | }
796 | },
797 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
798 | }
799 | },
800 | "summary": "Update the content of a periodic note.\n",
801 | "tags": ["Periodic Notes"]
802 | }
803 | },
804 | "/search/": {
805 | "post": {
806 | "description": "Evaluates a provided query against each file in your vault.\n\nThis 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 from the below options.Additional query formats may be added in the future.\n\n# Dataview DQL (`application/vnd.olrapi.dataview.dql+txt`)\n\nAccepts a `TABLE`-type Dataview query as a text string. See [Dataview](https://blacksmithgu.github.io/obsidian-dataview/query/queries/)'s query documentation for information on how to construct a query.\n\n# JsonLogic (`application/vnd.olrapi.jsonlogic+json`)\n\nAccepts a JsonLogic query specified as JSON. See [JsonLogic](https://jsonlogic.com/operations.html)'s documentation for information about the base set of operators available, but in addition to those operators the following operators are available:\n\n- `glob: [PATTERN, VALUE]`: Returns `true` if a string matches a glob pattern. E.g.: `{\"glob\": [\"*.foo\", \"bar.foo\"]}` is `true` and `{\"glob\": [\"*.bar\", \"bar.foo\"]}` is `false`.\n- `regexp: [PATTERN, VALUE]`: Returns `true` if a string matches a regular expression. E.g.: `{\"regexp\": [\".*\\.foo\", \"bar.foo\"]` is `true` and `{\"regexp\": [\".*\\.bar\", \"bar.foo\"]}` is `false`.\n\nReturns only non-falsy results. \"Non-falsy\" here treats the following values as \"falsy\":\n\n- `false`\n- `null` or `undefined`\n- `0`\n- `[]`\n- `{}`\n\nFiles are represented as an object having the schema described\nin the Schema named 'NoteJson' at the bottom of this page.\nUnderstanding the shape of a JSON object from a schema can be\ntricky; so you may find it helpful to examine the generated metadata\nfor individual files in your vault to understand exactly what values\nare returned. To see that, access the `GET` `/vault/{filePath}`\nroute setting the header:\n`Accept: application/vnd.olrapi.note+json`. See examples below\nfor working examples of queries performing common search operations.\n",
807 | "requestBody": {
808 | "content": {
809 | "application/vnd.olrapi.dataview.dql+txt": {
810 | "examples": {
811 | "find_fields_by_tag": {
812 | "summary": "List data from files having the #game tag.",
813 | "value": "TABLE\n time-played AS \"Time Played\",\n length AS \"Length\",\n rating AS \"Rating\"\nFROM #game\nSORT rating DESC\n"
814 | }
815 | },
816 | "schema": {
817 | "externalDocs": {
818 | "url": "https://blacksmithgu.github.io/obsidian-dataview/query/queries/"
819 | },
820 | "type": "object"
821 | }
822 | },
823 | "application/vnd.olrapi.jsonlogic+json": {
824 | "examples": {
825 | "find_by_frontmatter_url_glob": {
826 | "summary": "Find notes having URL or a matching URL glob frontmatter field.",
827 | "value": "{\n \"or\": [\n {\"===\": [{\"var\": \"frontmatter.url\"}, \"https://myurl.com/some/path/\"]},\n {\"glob\": [{\"var\": \"frontmatter.url-glob\"}, \"https://myurl.com/some/path/\"]}\n ]\n}\n"
828 | },
829 | "find_by_frontmatter_value": {
830 | "summary": "Find notes having a certain frontmatter field value.",
831 | "value": "{\n \"==\": [\n {\"var\": \"frontmatter.myField\"},\n \"myValue\"\n ]\n}\n"
832 | },
833 | "find_by_tag": {
834 | "summary": "Find notes having a certain tag",
835 | "value": "{\n \"in\": [\n \"myTag\",\n {\"var\": \"tags\"}\n ]\n}\n"
836 | }
837 | },
838 | "schema": {
839 | "externalDocs": {
840 | "url": "https://jsonlogic.com/operations.html"
841 | },
842 | "type": "object"
843 | }
844 | }
845 | },
846 | "required": true
847 | },
848 | "responses": {
849 | "200": {
850 | "content": {
851 | "application/json": {
852 | "schema": {
853 | "items": {
854 | "properties": {
855 | "filename": {
856 | "description": "Path to the matching file",
857 | "type": "string"
858 | },
859 | "result": {
860 | "oneOf": [
861 | {
862 | "type": "string"
863 | },
864 | {
865 | "type": "number"
866 | },
867 | {
868 | "type": "array"
869 | },
870 | {
871 | "type": "object"
872 | },
873 | {
874 | "type": "boolean"
875 | }
876 | ]
877 | }
878 | },
879 | "required": ["filename", "result"],
880 | "type": "object"
881 | },
882 | "type": "array"
883 | }
884 | }
885 | },
886 | "description": "Success"
887 | },
888 | "400": {
889 | "content": {
890 | "application/json": {
891 | "schema": {
892 | "$ref": "#/components/schemas/Error"
893 | }
894 | }
895 | },
896 | "description": "Bad request. Make sure you have specified an acceptable\nContent-Type for your search query.\n"
897 | }
898 | },
899 | "summary": "Search for documents matching a specified search query\n",
900 | "tags": ["Search"]
901 | }
902 | },
903 | "/search/simple/": {
904 | "post": {
905 | "parameters": [
906 | {
907 | "description": "Your search query",
908 | "in": "query",
909 | "name": "query",
910 | "required": true,
911 | "schema": {
912 | "type": "string"
913 | }
914 | },
915 | {
916 | "description": "How much context to return around the matching string",
917 | "in": "query",
918 | "name": "contextLength",
919 | "required": false,
920 | "schema": {
921 | "default": 100,
922 | "type": "number"
923 | }
924 | }
925 | ],
926 | "responses": {
927 | "200": {
928 | "content": {
929 | "application/json": {
930 | "schema": {
931 | "items": {
932 | "properties": {
933 | "filename": {
934 | "description": "Path to the matching file",
935 | "type": "string"
936 | },
937 | "matches": {
938 | "items": {
939 | "properties": {
940 | "context": {
941 | "type": "string"
942 | },
943 | "match": {
944 | "properties": {
945 | "end": {
946 | "type": "number"
947 | },
948 | "start": {
949 | "type": "number"
950 | }
951 | },
952 | "required": ["start", "end"],
953 | "type": "object"
954 | }
955 | },
956 | "required": ["match", "context"],
957 | "type": "object"
958 | },
959 | "type": "array"
960 | },
961 | "score": {
962 | "type": "number"
963 | }
964 | },
965 | "type": "object"
966 | },
967 | "type": "array"
968 | }
969 | }
970 | },
971 | "description": "Success"
972 | }
973 | },
974 | "summary": "Search for documents matching a specified text query\n",
975 | "tags": ["Search"]
976 | }
977 | },
978 | "/vault/": {
979 | "get": {
980 | "description": "Lists files in the root directory of your vault.\n\nNote: that this is exactly the same API endpoint as the below \"List files that exist in the specified directory.\" and exists here only due to a quirk of this particular interactive tool.\n",
981 | "responses": {
982 | "200": {
983 | "content": {
984 | "application/json": {
985 | "example": {
986 | "files": ["mydocument.md", "somedirectory/"]
987 | },
988 | "schema": {
989 | "properties": {
990 | "files": {
991 | "items": {
992 | "type": "string"
993 | },
994 | "type": "array"
995 | }
996 | },
997 | "type": "object"
998 | }
999 | }
1000 | },
1001 | "description": "Success"
1002 | },
1003 | "404": {
1004 | "content": {
1005 | "application/json": {
1006 | "schema": {
1007 | "$ref": "#/components/schemas/Error"
1008 | }
1009 | }
1010 | },
1011 | "description": "Directory does not exist"
1012 | }
1013 | },
1014 | "summary": "List files that exist in the root of your vault.\n",
1015 | "tags": ["Vault Directories"]
1016 | }
1017 | },
1018 | "/vault/{filename}": {
1019 | "delete": {
1020 | "parameters": [
1021 | {
1022 | "description": "Path to the relevant file (relative to your vault root).\n",
1023 | "in": "path",
1024 | "name": "filename",
1025 | "required": true,
1026 | "schema": {
1027 | "format": "path",
1028 | "type": "string"
1029 | }
1030 | }
1031 | ],
1032 | "responses": {
1033 | "204": {
1034 | "description": "Success"
1035 | },
1036 | "404": {
1037 | "content": {
1038 | "application/json": {
1039 | "schema": {
1040 | "$ref": "#/components/schemas/Error"
1041 | }
1042 | }
1043 | },
1044 | "description": "File does not exist."
1045 | },
1046 | "405": {
1047 | "content": {
1048 | "application/json": {
1049 | "schema": {
1050 | "$ref": "#/components/schemas/Error"
1051 | }
1052 | }
1053 | },
1054 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
1055 | }
1056 | },
1057 | "summary": "Delete a particular file in your vault.\n",
1058 | "tags": ["Vault Files"]
1059 | },
1060 | "get": {
1061 | "description": "Returns the content of the file at the specified path in your vault should the file exist.\n\nIf you specify the header `Accept: application/vnd.olrapi.note+json`, will return a JSON representation of your note including parsed tag and frontmatter data as well as filesystem metadata. See \"responses\" below for details.\n",
1062 | "parameters": [
1063 | {
1064 | "description": "Path to the relevant file (relative to your vault root).\n",
1065 | "in": "path",
1066 | "name": "filename",
1067 | "required": true,
1068 | "schema": {
1069 | "format": "path",
1070 | "type": "string"
1071 | }
1072 | }
1073 | ],
1074 | "responses": {
1075 | "200": {
1076 | "content": {
1077 | "application/vnd.olrapi.note+json": {
1078 | "schema": {
1079 | "$ref": "#/components/schemas/NoteJson"
1080 | }
1081 | },
1082 | "text/markdown": {
1083 | "schema": {
1084 | "example": "# This is my document\n\nsomething else here\n",
1085 | "type": "string"
1086 | }
1087 | }
1088 | },
1089 | "description": "Success"
1090 | },
1091 | "404": {
1092 | "description": "File does not exist"
1093 | }
1094 | },
1095 | "summary": "Return the content of a single file in your vault.\n",
1096 | "tags": ["Vault Files"]
1097 | },
1098 | "patch": {
1099 | "description": "Inserts content into an existing note relative to a heading within your note.\n\nAllows you to modify the content relative to a heading, block reference, or frontmatter field in your document.\n\nNote that this API was changed in Version 3.0 of this extension and the earlier PATCH API is now deprecated. Requests made using the previous version of this API will continue to work until Version 4.0 is released. See https://github.com/coddingtonbear/obsidian-local-rest-api/wiki/Changes-to-PATCH-requests-between-versions-2.0-and-3.0 for more details and migration instructions.\n\n# Examples\n\nAll of the below examples assume you have a document that looks like\nthis:\n\n```markdown\n---\nalpha: 1\nbeta: test\ndelta:\nzeta: 1\nyotta: 1\ngamma:\n- one\n- two\n---\n\n# Heading 1\n\nThis is the content for heading one\n\nAlso references some [[#^484ef2]]\n\n## Subheading 1:1\nContent for Subheading 1:1\n\n### Subsubheading 1:1:1\n\n### Subsubheading 1:1:2\n\nTesting how block references work for a table.[[#^2c7cfa]]\nSome content for Subsubheading 1:1:2\n\nMore random text.\n\n^2d9b4a\n\n## Subheading 1:2\n\nContent for Subheading 1:2.\n\nsome content with a block reference ^484ef2\n\n## Subheading 1:3\n| City | Population |\n| ------------ | ---------- |\n| Seattle, WA | 8 |\n| Portland, OR | 4 |\n\n^2c7cfa\n```\n\n## Append Content Below a Heading\n\nIf you wanted to append the content \"Hello\" below \"Subheading 1:1:1\" under \"Heading 1\",\nyou could send a request with the following headers:\n\n- `Operation`: `append`\n- `Target-Type`: `heading`\n- `Target`: `Heading 1::Subheading 1:1:1`\n- with the request body: `Hello`\n\nThe above would work just fine for `prepend` or `replace`, too, of course,\nbut with different results.\n\n## Append Content to a Block Reference\n\nIf you wanted to append the content \"Hello\" below the block referenced by\n\"2d9b4a\" above (\"More random text.\"), you could send the following headers:\n\n- `Operation`: `append`\n- `Target-Type`: `block`\n- `Target`: `2d9b4a`\n- with the request body: `Hello`\n\nThe above would work just fine for `prepend` or `replace`, too, of course,\nbut with different results.\n\n## Add a Row to a Table Referenced by a Block Reference\n\nIf you wanted to add a new city (\"Chicago, IL\") and population (\"16\") pair to the table above\nreferenced by the block reference `2c7cfa`, you could send the following\nheaders:\n\n- `Operation`: `append`\n- `TargetType`: `block`\n- `Target`: `2c7cfa`\n- `Content-Type`: `application/json`\n- with the request body: `[[\"Chicago, IL\", \"16\"]]`\n\nThe use of a `Content-Type` of `application/json` allows the API\nto infer that member of your array represents rows and columns of your\nto append to the referenced table. You can of course just use a\n`Content-Type` of `text/markdown`, but in such a case you'll have to\nformat your table row manually instead of letting the library figure\nit out for you.\n\nYou also have the option of using `prepend` (in which case, your new\nrow would be the first -- right below the table heading) or `replace` (in which\ncase all rows except the table heading would be replaced by the new row(s)\nyou supplied).\n\n## Setting a Frontmatter Field\n\nIf you wanted to set the frontmatter field `alpha` to `2`, you could\nsend the following headers:\n\n- `Operation`: `replace`\n- `TargetType`: `frontmatter`\n- `Target`: `beep`\n- with the request body `2`\n\nIf you're setting a frontmatter field that might not already exist\nyou may want to use the `Create-Target-If-Missing` header so the\nnew frontmatter field is created and set to your specified value\nif it doesn't already exist.\n\nYou may find using a `Content-Type` of `application/json` to be\nparticularly useful in the case of frontmatter since frontmatter\nfields' values are JSON data, and the API can be smarter about\ninterpreting yoru `prepend` or `append` requests if you specify\nyour data as JSON (particularly when appending, for example,\nlist items).\n",
1100 | "parameters": [
1101 | {
1102 | "description": "Patch operation to perform",
1103 | "in": "header",
1104 | "name": "Operation",
1105 | "required": true,
1106 | "schema": {
1107 | "enum": ["append", "prepend", "replace"],
1108 | "type": "string"
1109 | }
1110 | },
1111 | {
1112 | "description": "Type of target to patch",
1113 | "in": "header",
1114 | "name": "Target-Type",
1115 | "required": true,
1116 | "schema": {
1117 | "enum": ["heading", "block", "frontmatter"],
1118 | "type": "string"
1119 | }
1120 | },
1121 | {
1122 | "description": "Delimiter to use for nested targets (i.e. Headings)",
1123 | "in": "header",
1124 | "name": "Target-Delimiter",
1125 | "required": false,
1126 | "schema": {
1127 | "default": "::",
1128 | "type": "string"
1129 | }
1130 | },
1131 | {
1132 | "description": "Target to patch; this value can be URL-Encoded and *must*\nbe URL-Encoded if it includes non-ASCII characters.\n",
1133 | "in": "header",
1134 | "name": "Target",
1135 | "required": true,
1136 | "schema": {
1137 | "type": "string"
1138 | }
1139 | },
1140 | {
1141 | "description": "Trim whitespace from Target before applying patch?",
1142 | "in": "header",
1143 | "name": "Trim-Target-Whitespace",
1144 | "required": false,
1145 | "schema": {
1146 | "default": "false",
1147 | "enum": ["true", "false"],
1148 | "type": "string"
1149 | }
1150 | },
1151 | {
1152 | "description": "Path to the relevant file (relative to your vault root).\n",
1153 | "in": "path",
1154 | "name": "filename",
1155 | "required": true,
1156 | "schema": {
1157 | "format": "path",
1158 | "type": "string"
1159 | }
1160 | }
1161 | ],
1162 | "requestBody": {
1163 | "content": {
1164 | "application/json": {
1165 | "schema": {
1166 | "example": "['one', 'two']",
1167 | "type": "string"
1168 | }
1169 | },
1170 | "text/markdown": {
1171 | "schema": {
1172 | "example": "# This is my document\n\nsomething else here\n",
1173 | "type": "string"
1174 | }
1175 | }
1176 | },
1177 | "description": "Content you would like to insert.",
1178 | "required": true
1179 | },
1180 | "responses": {
1181 | "200": {
1182 | "description": "Success"
1183 | },
1184 | "400": {
1185 | "content": {
1186 | "application/json": {
1187 | "schema": {
1188 | "$ref": "#/components/schemas/Error"
1189 | }
1190 | }
1191 | },
1192 | "description": "Bad Request; see response message for details."
1193 | },
1194 | "404": {
1195 | "content": {
1196 | "application/json": {
1197 | "schema": {
1198 | "$ref": "#/components/schemas/Error"
1199 | }
1200 | }
1201 | },
1202 | "description": "Does not exist"
1203 | },
1204 | "405": {
1205 | "content": {
1206 | "application/json": {
1207 | "schema": {
1208 | "$ref": "#/components/schemas/Error"
1209 | }
1210 | }
1211 | },
1212 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
1213 | }
1214 | },
1215 | "summary": "Insert content into an existing note relative to a heading within that document.\n",
1216 | "tags": ["Vault Files"]
1217 | },
1218 | "post": {
1219 | "description": "Appends content to the end of an existing note. If the specified file does not yet exist, it will be created as an empty file.\n\nIf you would like to insert text relative to a particular heading instead of appending to the end of the file, see 'patch'.\n",
1220 | "parameters": [
1221 | {
1222 | "description": "Path to the relevant file (relative to your vault root).\n",
1223 | "in": "path",
1224 | "name": "filename",
1225 | "required": true,
1226 | "schema": {
1227 | "format": "path",
1228 | "type": "string"
1229 | }
1230 | }
1231 | ],
1232 | "requestBody": {
1233 | "content": {
1234 | "text/markdown": {
1235 | "schema": {
1236 | "example": "# This is my document\n\nsomething else here\n",
1237 | "type": "string"
1238 | }
1239 | }
1240 | },
1241 | "description": "Content you would like to append.",
1242 | "required": true
1243 | },
1244 | "responses": {
1245 | "204": {
1246 | "description": "Success"
1247 | },
1248 | "400": {
1249 | "content": {
1250 | "application/json": {
1251 | "schema": {
1252 | "$ref": "#/components/schemas/Error"
1253 | }
1254 | }
1255 | },
1256 | "description": "Bad Request"
1257 | },
1258 | "405": {
1259 | "content": {
1260 | "application/json": {
1261 | "schema": {
1262 | "$ref": "#/components/schemas/Error"
1263 | }
1264 | }
1265 | },
1266 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
1267 | }
1268 | },
1269 | "summary": "Append content to a new or existing file.\n",
1270 | "tags": ["Vault Files"]
1271 | },
1272 | "put": {
1273 | "description": "Creates a new file in your vault or updates the content of an existing one if the specified file already exists.\n",
1274 | "parameters": [
1275 | {
1276 | "description": "Path to the relevant file (relative to your vault root).\n",
1277 | "in": "path",
1278 | "name": "filename",
1279 | "required": true,
1280 | "schema": {
1281 | "format": "path",
1282 | "type": "string"
1283 | }
1284 | }
1285 | ],
1286 | "requestBody": {
1287 | "content": {
1288 | "*/*": {
1289 | "schema": {
1290 | "type": "string"
1291 | }
1292 | },
1293 | "text/markdown": {
1294 | "schema": {
1295 | "example": "# This is my document\n\nsomething else here\n",
1296 | "type": "string"
1297 | }
1298 | }
1299 | },
1300 | "description": "Content of the file you would like to upload.",
1301 | "required": true
1302 | },
1303 | "responses": {
1304 | "204": {
1305 | "description": "Success"
1306 | },
1307 | "400": {
1308 | "content": {
1309 | "application/json": {
1310 | "schema": {
1311 | "$ref": "#/components/schemas/Error"
1312 | }
1313 | }
1314 | },
1315 | "description": "Incoming file could not be processed. Make sure you have specified a reasonable file name, and make sure you have set a reasonable 'Content-Type' header; if you are uploading a note, 'text/markdown' is likely the right choice.\n"
1316 | },
1317 | "405": {
1318 | "content": {
1319 | "application/json": {
1320 | "schema": {
1321 | "$ref": "#/components/schemas/Error"
1322 | }
1323 | }
1324 | },
1325 | "description": "Your path references a directory instead of a file; this request method is valid only for updating files.\n"
1326 | }
1327 | },
1328 | "summary": "Create a new file in your vault or update the content of an existing one.\n",
1329 | "tags": ["Vault Files"]
1330 | }
1331 | },
1332 | "/vault/{pathToDirectory}/": {
1333 | "get": {
1334 | "parameters": [
1335 | {
1336 | "description": "Path to list files from (relative to your vault root). Note that empty directories will not be returned.\n\nNote: this particular interactive tool requires that you provide an argument for this field, but the API itself will allow you to list the root folder of your vault. If you would like to try listing content in the root of your vault using this interactive tool, use the above \"List files that exist in the root of your vault\" form above.\n",
1337 | "in": "path",
1338 | "name": "pathToDirectory",
1339 | "required": true,
1340 | "schema": {
1341 | "format": "path",
1342 | "type": "string"
1343 | }
1344 | }
1345 | ],
1346 | "responses": {
1347 | "200": {
1348 | "content": {
1349 | "application/json": {
1350 | "example": {
1351 | "files": ["mydocument.md", "somedirectory/"]
1352 | },
1353 | "schema": {
1354 | "properties": {
1355 | "files": {
1356 | "items": {
1357 | "type": "string"
1358 | },
1359 | "type": "array"
1360 | }
1361 | },
1362 | "type": "object"
1363 | }
1364 | }
1365 | },
1366 | "description": "Success"
1367 | },
1368 | "404": {
1369 | "content": {
1370 | "application/json": {
1371 | "schema": {
1372 | "$ref": "#/components/schemas/Error"
1373 | }
1374 | }
1375 | },
1376 | "description": "Directory does not exist"
1377 | }
1378 | },
1379 | "summary": "List files that exist in the specified directory.\n",
1380 | "tags": ["Vault Directories"]
1381 | }
1382 | }
1383 | },
1384 | "security": [
1385 | {
1386 | "apiKeyAuth": []
1387 | }
1388 | ],
1389 | "servers": [
1390 | {
1391 | "description": "HTTPS (Secure Mode)",
1392 | "url": "https://{host}:{port}",
1393 | "variables": {
1394 | "host": {
1395 | "default": "127.0.0.1",
1396 | "description": "Binding host"
1397 | },
1398 | "port": {
1399 | "default": "27124",
1400 | "description": "HTTPS port"
1401 | }
1402 | }
1403 | },
1404 | {
1405 | "description": "HTTP (Insecure Mode)",
1406 | "url": "http://{host}:{port}",
1407 | "variables": {
1408 | "host": {
1409 | "default": "127.0.0.1",
1410 | "description": "Binding host"
1411 | },
1412 | "port": {
1413 | "default": "27123",
1414 | "description": "HTTP port"
1415 | }
1416 | }
1417 | }
1418 | ]
1419 | }
1420 |
```