Obsidian Search API

openapi: 3.2.0
info:
  description: You can use this interface for trying out your Local REST API in Obsidian.
  title: Local REST API for Obsidian 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''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''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
      operationId: postSearch
      x-operation-id-source: derived
  /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
      operationId: postSearchSimple
      x-operation-id-source: derived
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