openapi: 3.1.0
info:
  title: Manticore Search Client Index API
  description: 'Сlient for Manticore Search.

    '
  version: 5.0.0
  contact:
    name: Manticore Software Ltd.
    email: info@manticoresearch.com
    url: https://manticoresearch.com/contact-us/
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
servers:
- description: Default Manticore Search HTTP
  url: http://127.0.0.1:9308/
tags:
- name: Index
  description: Operations regarding adding, updating or deleting documents
paths:
  /bulk:
    post:
      summary: Bulk table operations
      description: "Sends multiple operatons like inserts, updates, replaces or deletes. \nFor each operation it's object must have same format as in their dedicated method. \nThe method expects a raw string as the batch in NDJSON.\n Each operation object needs to be serialized to \n JSON and separated by endline (\\n). \n \n  An example of raw input:\n  \n  ```\n  {\"insert\": {\"table\": \"movies\", \"doc\": {\"plot\": \"A secret team goes to North Pole\", \"rating\": 9.5, \"language\": [2, 3], \"title\": \"This is an older movie\", \"lon\": 51.99, \"meta\": {\"keywords\":[\"travel\",\"ice\"],\"genre\":[\"adventure\"]}, \"year\": 1950, \"lat\": 60.4, \"advise\": \"PG-13\"}}}\n  \\n\n  {\"delete\": {\"table\": \"movies\",\"id\":700}}\n  ```\n  \n  Responds with an object telling whenever any errors occured and an array with status for each operation:\n  \n  ```\n  {\n    'items':\n    [\n      {\n        'update':{'table':'products','id':1,'result':'updated'}\n      },\n      {\n        'update':{'table':'products','id':2,'result':'updated'}\n      }\n    ],\n    'errors':false\n  }\n  ```\n"
      operationId: bulk
      tags:
      - Index
      externalDocs:
        url: https://manual.manticoresearch.com/Updating_documents/UPDATE
      requestBody:
        required: true
        content:
          application/x-ndjson:
            schema:
              type: string
      responses:
        '200':
          description: item updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bulkResponse'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /delete:
    post:
      summary: Delete a document in a table
      operationId: delete
      description: "Delete one or several documents.\nThe method has 2 ways of deleting: either by id, in case only one document is deleted or by using a  match query, in which case multiple documents can be delete .\nExample of input to delete by id:\n\n  ```\n  {'table':'movies','id':100}\n  ```\n\nExample of input to delete using a query:\n\n  ```\n  {\n    'table':'movies',\n    'query':\n    {\n      'bool':\n      {\n        'must':\n        [\n          {'query_string':'new movie'}\n        ]\n      }\n    }\n  }\n  ```\n\nThe match query has same syntax as in for searching.\nResponds with an object telling how many documents got deleted: \n\n  ```\n  {'table':'products','updated':1}\n  ```\n"
      tags:
      - Index
      externalDocs:
        url: https://manual.manticoresearch.com/Updating_documents/UPDATE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deleteDocumentRequest'
            example:
              table: test
              query:
                match:
                  title: apple
      responses:
        '200':
          description: item updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deleteResponse'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /insert:
    post:
      summary: Create a new document in a table
      x-is_indexapi: true
      x-is_insert: true
      operationId: insert
      description: "Insert a document. \nExpects an object like:\n \n  ```\n  {\n    'table':'movies',\n    'id':701,\n    'doc':\n    {\n      'title':'This is an old movie',\n      'plot':'A secret team goes to North Pole',\n      'year':1950,\n      'rating':9.5,\n      'lat':60.4,\n      'lon':51.99,\n      'advise':'PG-13',\n      'meta':'{\"keywords\":{\"travel\",\"ice\"},\"genre\":{\"adventure\"}}',\n      'language':[2,3]\n    }\n  }\n  ```\n \nThe document id can also be missing, in which case an autogenerated one will be used:\n         \n  ```\n  {\n    'table':'movies',\n    'doc':\n    {\n      'title':'This is a new movie',\n      'plot':'A secret team goes to North Pole',\n      'year':2020,\n      'rating':9.5,\n      'lat':60.4,\n      'lon':51.99,\n      'advise':'PG-13',\n      'meta':'{\"keywords\":{\"travel\",\"ice\"},\"genre\":{\"adventure\"}}',\n      'language':[2,3]\n    }\n  }\n  ```\n \nIt responds with an object in format:\n  \n  ```\n  {'table':'products','id':701,'created':true,'result':'created','status':201}\n  ```\n"
      tags:
      - Index
      externalDocs:
        url: https://manual.manticoresearch.com/Adding_documents_to_a_table/Adding_documents_to_a_real-time_table#Adding-documents-to-a-real-time-table
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/insertDocumentRequest'
            example:
              table: test
              id: 1
              doc:
                title: sample title
                gid: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/successResponse'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /replace:
    post:
      summary: Replace new document in a table
      x-is_indexapi: true
      x-is_replace: true
      operationId: replace
      description: "Replace an existing document. Input has same format as `insert` operation.\nResponds with an object in format:\n\n  ```\n  {'table':'products','id':1,'created':false,'result':'updated','status':200}\n  ```\n"
      tags:
      - Index
      externalDocs:
        url: https://manual.manticoresearch.com/Adding_documents_to_a_table/Adding_documents_to_a_real-time_table#Adding-documents-to-a-real-time-table
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/insertDocumentRequest'
            example:
              table: test
              id: 1
              doc:
                title: updated title
                gid: 15
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/successResponse'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /update:
    post:
      summary: Update a document in a table
      x-is_indexapi: true
      x-is_update: true
      x-is_modify: true
      operationId: update
      description: "Update one or several documents.\nThe update can be made by passing the id or by using a match query in case multiple documents can be updated.  For example update a document using document id:\n\n  ```\n  {'table':'movies','doc':{'rating':9.49},'id':100}\n  ```\n\nAnd update by using a match query:\n\n  ```\n  {\n    'table':'movies',\n    'doc':{'rating':9.49},\n    'query':\n    {\n      'bool':\n      {\n        'must':\n        [\n          {'query_string':'new movie'}\n        ]\n      }\n    }\n  }\n  ``` \n\nThe match query has same syntax as for searching.\nResponds with an object that tells how many documents where updated in format: \n\n  ```\n  {'table':'products','updated':1}\n  ```\n"
      tags:
      - Index
      externalDocs:
        url: https://manual.manticoresearch.com/Updating_documents/UPDATE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateDocumentRequest'
            example:
              table: test
              doc:
                gid: 20
              query:
                equals:
                  cat_id: 2
      responses:
        '200':
          description: item updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updateResponse'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /{table}/_update/{id}:
    post:
      summary: Partially replaces a document in a table
      operationId: partial_replace
      description: "Partially replaces a document with given id in a table\nResponds with an object of the following format: \n\n  ```\n  {'table':'products','updated':1}\n  ```\n"
      tags:
      - Index
      externalDocs:
        url: https://manual.manticoresearch.com/Updating_documents/REPLACE#JSON-REPLACE
      parameters:
      - in: path
        name: table
        schema:
          type: string
        required: true
        description: Name of the percolate table
      - in: path
        name: id
        schema:
          type: integer
          format: uint64
        required: true
        description: Id of the document to replace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/replaceDocumentRequest'
            example:
              doc:
                price: 20
      responses:
        '200':
          description: item updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updateResponse'
        default:
          description: error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
components:
  schemas:
    boolFilter:
      type: object
      properties:
        must:
          type: array
          items:
            $ref: '#/components/schemas/queryFilter'
          description: Query clauses that must match for the document to be included
        must_not:
          type: array
          items:
            $ref: '#/components/schemas/queryFilterAlias1'
          description: Query clauses that must not match for the document to be included
        should:
          type: array
          items:
            $ref: '#/components/schemas/queryFilterAlias2'
          description: Query clauses that should be matched, but are not required
      additionalProperties: false
    updateDocumentRequest:
      type: object
      description: Payload for updating a document or multiple documents in a table
      required:
      - table
      - doc
      properties:
        table:
          type: string
          description: Name of the document table
        cluster:
          type: string
          description: Name of the document cluster
        doc:
          type: object
          description: Object containing the document fields to update
          additionalProperties: true
          example:
            gid: 10
        id:
          type: integer
          format: uint64
          description: Document ID
        query:
          oneOf:
          - type: null
          - $ref: '#/components/schemas/queryFilter'
          description: Object defining conditions to perform the updates
          example:
            query:
              match:
                title: match me
    bulkResponse:
      type: object
      description: Success response for bulk search requests
      properties:
        items:
          type: array
          items:
            type: object
          description: List of results
        errors:
          type: boolean
          description: Errors occurred during the bulk operation
        error:
          type: string
          description: Error message describing an error if such occurred
        current_line:
          type: integer
          description: Number of the row returned in the response
        skipped_lines:
          type: integer
          description: Number of rows skipped in the response
    queryFilterAlias2:
      $ref: '#/components/schemas/queryFilter'
    responseErrorText:
      type: string
      description: Error message text returned in case of an error
    responseErrorDetails:
      type: object
      description: Detailed error information returned in case of an error response
      required:
      - type
      properties:
        type:
          type: string
          description: Type or category of the error
        reason:
          type:
          - string
          - 'null'
          description: Detailed explanation of why the error occurred
        table:
          type:
          - string
          - 'null'
          description: The table related to the error, if applicable
    responseError:
      oneOf:
      - $ref: '#/components/schemas/responseErrorDetails'
      - $ref: '#/components/schemas/responseErrorText'
    insertDocumentRequest:
      type: object
      description: 'Object containing data for inserting a new document into the table

        '
      required:
      - table
      - doc
      properties:
        table:
          type: string
          description: Name of the table to insert the document into
        cluster:
          type: string
          description: Name of the cluster to insert the document into
        id:
          type: integer
          format: uint64
          description: 'Document ID. If not provided, an ID will be auto-generated

            '
        doc:
          type: object
          additionalProperties: true
          description: 'Object containing document data

            '
      example:
        table: test
        doc:
          title: This is some title
          gid: 100
    deleteDocumentRequest:
      type: object
      description: 'Payload for delete request.

        Documents can be deleted either one by one by specifying the document id or by providing a query object.

        For more information see  [Delete API](https://manual.manticoresearch.com/Deleting_documents)

        '
      required:
      - table
      properties:
        table:
          type: string
          description: Table name
        cluster:
          type: string
          description: Cluster name
        id:
          type: integer
          format: uint64
          description: The ID of document for deletion
        query:
          type: object
          description: Defines the criteria to match documents for deletion
      example:
        table: test
        id: 1
    queryFilter:
      allOf:
      - $ref: '#/components/schemas/fulltextFilter'
      - type: object
        properties:
          bool:
            $ref: '#/components/schemas/boolFilter'
          equals:
            type: {}
            description: Filter to match exact attribute values.
          in:
            type: object
            description: Filter to match a given set of attribute values.
          range:
            type: object
            description: Filter to match a given range of attribute values passed in Range objects
          geo_distance:
            $ref: '#/components/schemas/geoDistance'
        additionalProperties: false
      description: Object used to apply various conditions, such as full-text matching or attribute filtering, to a search query
    fulltextFilter:
      type: object
      properties:
        query_string:
          type: string
          description: Filter object defining a query string
        match:
          type: object
          description: Filter object defining a match keyword passed as a string or in a Match object
        match_phrase:
          type: object
          description: Filter object defining a match phrase
        match_all:
          type: object
          description: Filter object to select all documents
      additionalProperties: false
      description: Defines a type of filter for full-text search queries
    replaceDocumentRequest:
      type: object
      description: Object containing the document data for replacing an existing document in a table.
      required:
      - doc
      properties:
        doc:
          type: object
          additionalProperties: true
          description: Object containing the new document data to replace the existing one.
      example:
        doc:
          title: This is some title
          gid: 100
    errorResponse:
      type: object
      description: Error response object containing information about the error and a status code
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/responseError'
        status:
          type: integer
          description: HTTP status code of the error response
          default: 500
      example:
        status: 500
        error: an error occured
    successResponse:
      type: object
      description: Response object indicating the success of an operation, such as inserting or updating a document
      properties:
        table:
          type: string
          description: Name of the document table
        id:
          type: integer
          format: uint64
          description: ID of the document affected by the request operation
        created:
          type: boolean
          description: Indicates whether the document was created as a result of the operation
        result:
          type: string
          description: Result of the operation, typically 'created', 'updated', or 'deleted'
        found:
          type: boolean
          description: Indicates whether the document was found in the table
        status:
          type: integer
          description: HTTP status code representing the result of the operation
      example:
        table: test
        id: 1
        result: created
        created: true
        status: 201
    geoDistance:
      type: object
      properties:
        location_anchor:
          type: object
          description: Specifies the location of the pin point used for search
          properties:
            lat:
              type: number
              description: Latitude of the anchor point
            lon:
              type: number
              description: Longitude of the anchor point
          additionalProperties: false
        location_source:
          type: string
          description: Field name in the document that contains location data
        distance_type:
          type: string
          enum:
          - adaptive
          - haversine
          description: Algorithm used to calculate the distance
        distance:
          type: string
          pattern: /^\.+(km|m|cm|mm|mi|yd|ft|in|NM|nmi|kilometers|meters|centimeters|millimeters|miles|yards|foots|inches|nauticalmiles|)$/
          description: The distance from the anchor point to filter results by
      additionalProperties: false
      description: Object to perform geo-distance based filtering on queries
    deleteResponse:
      type: object
      description: Response object for successful delete request
      properties:
        table:
          type: string
          description: The name of the table from which the document was deleted
        deleted:
          type: integer
          description: Number of documents deleted
        id:
          type: integer
          format: uint64
          description: The ID of the deleted document. If multiple documents are deleted, the ID of the first deleted document is returned
        found:
          type: boolean
          description: Indicates whether any documents to be deleted were found
        result:
          type: string
          description: Result of the delete operation, typically 'deleted'
      example:
        table: test
        deleted: 29
    updateResponse:
      type: object
      description: Success response returned after updating one or more documents
      properties:
        table:
          type: string
          description: Name of the document table
        updated:
          type: integer
          description: Number of documents updated
        id:
          type: integer
          format: uint64
          description: Document ID
        result:
          type: string
          description: Result of the update operation, typically 'updated'
      example:
        table: test
        updated: 29
    queryFilterAlias1:
      $ref: '#/components/schemas/queryFilter'
externalDocs:
  description: Find out more about Manticore Search
  url: https://manticoresearch.com/