Obsidian Search API

openapi: 3.0.2
info:
  description: 'You can use this interface for trying out your Local REST API in Obsidian.


    Before 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.


    When 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.

    '
  title: Local REST API for Obsidian Active File Search API
  version: '1.0'
servers:
- description: HTTPS (Secure Mode)
  url: https://{host}:{port}
  variables:
    host:
      default: 127.0.0.1
      description: Binding host
    port:
      default: '27124'
      description: HTTPS port
- description: HTTP (Insecure Mode)
  url: http://{host}:{port}
  variables:
    host:
      default: 127.0.0.1
      description: Binding host
    port:
      default: '27123'
      description: HTTP port
security:
- apiKeyAuth: []
tags:
- name: Search
paths:
  /search/:
    post:
      description: 'Evaluates a provided query against each file in your vault.


        This endpoint supports multiple query formats.  Your query should be specified in your request''s body, and will be interpreted according to the `Content-type` header you specify from the below options. Additional query formats may be added in the future.


        # Dataview DQL (`application/vnd.olrapi.dataview.dql+txt`)


        Accepts 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.


        # JsonLogic (`application/vnd.olrapi.jsonlogic+json`)


        Accepts 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:


        - `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`.

        - `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`.


        Returns only non-falsy results.  "Non-falsy" here treats the following values as "falsy":


        - `false`

        - `null` or `undefined`

        - `0`

        - `[]`

        - `{}`


        Files are represented as an object having the schema described

        in the Schema named ''NoteJson'' at the bottom of this page.

        Understanding the shape of a JSON object from a schema can be

        tricky; so you may find it helpful to examine the generated metadata

        for individual files in your vault to understand exactly what values

        are returned.  To see that, access the `GET` `/vault/{filePath}`

        route setting the header:

        `Accept: application/vnd.olrapi.note+json`.  See examples below

        for working examples of queries performing common search operations.

        '
      requestBody:
        content:
          application/vnd.olrapi.dataview.dql+txt:
            examples:
              find_fields_by_tag:
                summary: 'List data from files having the #game tag.'
                value: "TABLE\n  time-played AS \"Time Played\",\n  length AS \"Length\",\n  rating AS \"Rating\"\nFROM #game\nSORT rating DESC\n"
            schema:
              externalDocs:
                url: https://blacksmithgu.github.io/obsidian-dataview/query/queries/
              type: object
          application/vnd.olrapi.jsonlogic+json:
            examples:
              find_by_frontmatter_url_glob:
                summary: Find notes having URL or a matching URL glob frontmatter field.
                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"
              find_by_frontmatter_value:
                summary: Find notes having a certain frontmatter field value.
                value: "{\n  \"==\": [\n    {\"var\": \"frontmatter.myField\"},\n    \"myValue\"\n  ]\n}\n"
              find_by_tag:
                summary: Find notes having a certain tag
                value: "{\n  \"in\": [\n    \"myTag\",\n    {\"var\": \"tags\"}\n  ]\n}\n"
            schema:
              externalDocs:
                url: https://jsonlogic.com/operations.html
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  properties:
                    filename:
                      description: Path to the matching file
                      type: string
                    result:
                      oneOf:
                      - type: string
                      - type: number
                      - items: {}
                        type: array
                      - type: object
                      - type: boolean
                  required:
                  - filename
                  - result
                  type: object
                type: array
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Bad request.  Make sure you have specified an acceptable

            Content-Type for your search query.

            '
      summary: 'Search for documents matching a specified search query

        '
      tags:
      - Search
  /search/simple/:
    post:
      parameters:
      - description: Your search query
        in: query
        name: query
        required: true
        schema:
          type: string
      - description: How much context to return around the matching string
        in: query
        name: contextLength
        required: false
        schema:
          default: 100
          type: number
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  properties:
                    filename:
                      description: Path to the matching file
                      type: string
                    matches:
                      items:
                        properties:
                          context:
                            type: string
                          match:
                            properties:
                              end:
                                type: number
                              start:
                                type: number
                            required:
                            - start
                            - end
                            type: object
                        required:
                        - match
                        - context
                        type: object
                      type: array
                    score:
                      type: number
                  type: object
                type: array
          description: Success
      summary: 'Search for documents matching a specified text query

        '
      tags:
      - Search
components:
  schemas:
    Error:
      properties:
        errorCode:
          description: 'A 5-digit error code uniquely identifying this particular type of error.

            '
          example: 40149
          type: number
        message:
          description: Message describing the error.
          example: A brief description of the error.
          type: string
      type: object
  securitySchemes:
    apiKeyAuth:
      description: 'Find your API Key in your Obsidian settings

        in the "Local REST API" section under "Plugins".

        '
      scheme: bearer
      type: http