openapi.yaml

components:
  schemas:
    DatabaseEntry:
      properties:
        embedding:
          items:
            type: number
          title: Embedding
          type: array
        metadata:
          description: >-
            The metadata is parsed as JSON to ensure its validity and regenerated
            to possibly minimise it (e.g. removing unnecessary white spaces). The
            regenerated JSON should at most 65535 characters long.
          example:
            language: ja
            tags:
            - text
          title: Optional, arbitrary JSON object to attach to the image
          type: object
        url:
          description: "The url serves as the primary key in the Milvus collection.\
            \ For consistancy, image URLs should not have escape characters. Optionally,\
            \ additional metadata can be associated with the image as an arbitrary\
            \ JSON object.\n\nAssumptions\n- Url follows pydantics' [HttpUrl](https://docs.pydantic.dev/usage/types/#urls):\
            \ scheme http or https, TLD required, host required, max length 2083.\n\
            - Images should have persitant URLs that will not change over time.\n\
            - Images are accessible from the server where Idios is hosted and do not\
            \ require authentication.\n- Only JPEG images are supported\n- Images\
            \ must have their\_dimensions\_above\_150 x 150 pixels, otherwise the\
            \ API will return an error `IMAGE_SIZE_TOO_SMALL`\n- If one of the image\
            \ dimension exceeds 1000 pixels, Idios will resize the image so that the\
            \ maximum dimension is set to 1000 pixels and the original aspect ratio\
            \ is kept.\n- Some image links may be permalinks from library or museum\
            \ image collections or be hosted on IIIF servers that only accept certain\
            \ request headers, additionally, the URL may return a 303 redirect to\
            \ point you to the actual image. The API should be able to handle the\
            \ redirect silently and still use the original URL as the primary key."
          example: https://iiif.itatti.harvard.edu/iiif/2/yashiro!letters-jp!letter_001.pdf/full/full/0/default.jpg
          title: URL of the image
          type: string
      required:
      - url
      - embedding
      title: DatabaseEntry
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ImageAndMetada:
      properties:
        metadata:
          description: >-
            The metadata is parsed as JSON to ensure its validity and regenerated
            to possibly minimise it (e.g. removing unnecessary white spaces). The
            regenerated JSON should at most 65535 characters long.
          example:
            language: ja
            tags:
            - text
          title: Optional, arbitrary JSON object to attach to the image
          type: object
        url:
          description: "The url serves as the primary key in the Milvus collection.\
            \ For consistancy, image URLs should not have escape characters. Optionally,\
            \ additional metadata can be associated with the image as an arbitrary\
            \ JSON object.\n\nAssumptions\n- Url follows pydantics' [HttpUrl](https://docs.pydantic.dev/usage/types/#urls):\
            \ scheme http or https, TLD required, host required, max length 2083.\n\
            - Images should have persitant URLs that will not change over time.\n\
            - Images are accessible from the server where Idios is hosted and do not\
            \ require authentication.\n- Only JPEG images are supported\n- Images\
            \ must have their\_dimensions\_above\_150 x 150 pixels, otherwise the\
            \ API will return an error `IMAGE_SIZE_TOO_SMALL`\n- If one of the image\
            \ dimension exceeds 1000 pixels, Idios will resize the image so that the\
            \ maximum dimension is set to 1000 pixels and the original aspect ratio\
            \ is kept.\n- Some image links may be permalinks from library or museum\
            \ image collections or be hosted on IIIF servers that only accept certain\
            \ request headers, additionally, the URL may return a 303 redirect to\
            \ point you to the actual image. The API should be able to handle the\
            \ redirect silently and still use the original URL as the primary key."
          example: https://iiif.itatti.harvard.edu/iiif/2/yashiro!letters-jp!letter_001.pdf/full/full/0/default.jpg
          title: URL of the image
          type: string
      required:
      - url
      title: ImageAndMetada
      type: object
    ImagePair:
      properties:
        other:
          description: "The url serves as the primary key in the Milvus collection.\
            \ For consistancy, image URLs should not have escape characters. Optionally,\
            \ additional metadata can be associated with the image as an arbitrary\
            \ JSON object.\n\nAssumptions\n- Url follows pydantics' [HttpUrl](https://docs.pydantic.dev/usage/types/#urls):\
            \ scheme http or https, TLD required, host required, max length 2083.\n\
            - Images should have persitant URLs that will not change over time.\n\
            - Images are accessible from the server where Idios is hosted and do not\
            \ require authentication.\n- Only JPEG images are supported\n- Images\
            \ must have their\_dimensions\_above\_150 x 150 pixels, otherwise the\
            \ API will return an error `IMAGE_SIZE_TOO_SMALL`\n- If one of the image\
            \ dimension exceeds 1000 pixels, Idios will resize the image so that the\
            \ maximum dimension is set to 1000 pixels and the original aspect ratio\
            \ is kept.\n- Some image links may be permalinks from library or museum\
            \ image collections or be hosted on IIIF servers that only accept certain\
            \ request headers, additionally, the URL may return a 303 redirect to\
            \ point you to the actual image. The API should be able to handle the\
            \ redirect silently and still use the original URL as the primary key."
          example: https://iiif.itatti.harvard.edu/iiif/2/yashiro!letters-jp!letter_001.pdf/full/full/0/default.jpg
          title: URL of the image
          type: string
        url:
          description: "The url serves as the primary key in the Milvus collection.\
            \ For consistancy, image URLs should not have escape characters. Optionally,\
            \ additional metadata can be associated with the image as an arbitrary\
            \ JSON object.\n\nAssumptions\n- Url follows pydantics' [HttpUrl](https://docs.pydantic.dev/usage/types/#urls):\
            \ scheme http or https, TLD required, host required, max length 2083.\n\
            - Images should have persitant URLs that will not change over time.\n\
            - Images are accessible from the server where Idios is hosted and do not\
            \ require authentication.\n- Only JPEG images are supported\n- Images\
            \ must have their\_dimensions\_above\_150 x 150 pixels, otherwise the\
            \ API will return an error `IMAGE_SIZE_TOO_SMALL`\n- If one of the image\
            \ dimension exceeds 1000 pixels, Idios will resize the image so that the\
            \ maximum dimension is set to 1000 pixels and the original aspect ratio\
            \ is kept.\n- Some image links may be permalinks from library or museum\
            \ image collections or be hosted on IIIF servers that only accept certain\
            \ request headers, additionally, the URL may return a 303 redirect to\
            \ point you to the actual image. The API should be able to handle the\
            \ redirect silently and still use the original URL as the primary key."
          example: https://iiif.itatti.harvard.edu/iiif/2/yashiro!letters-jp!letter_001.pdf/full/full/0/default.jpg
          title: URL of the image
          type: string
      required:
      - url
      - other
      title: ImagePair
      type: object
    ModelName:
      description: >-
        The enumeration of supported models to extract embeddings from images
      enum:
      - vit_b32
      title: ModelName
    Pagination:
      properties:
        cursor:
          description: >-
            The cursor parameter is used for pagination purposes to allow clients
            to retrieve a large set of results in smaller, more manageable chunks.
            The cursor is a string that represents the position of the last item returned
            in the previous API call.


            When making a request to retrieve a set of images, the client can include
            the cursor parameter in the request to specify where in the set of results
            they want to start from. The API will return a subset of the results starting
            after the url specified by the cursor.
          title: Enumeration cursor
          type: string
        limit:
          maximum: 16384.0
          minimum: 1.0
          title: Limit
          type: integer
      title: Pagination
      type: object
    SearchParameters:
      properties:
        limit:
          default: 10
          minimum: 1.0
          title: Limit
          type: integer
        text:
          title: Text
          type: string
        url:
          description: "The url serves as the primary key in the Milvus collection.\
            \ For consistancy, image URLs should not have escape characters. Optionally,\
            \ additional metadata can be associated with the image as an arbitrary\
            \ JSON object.\n\nAssumptions\n- Url follows pydantics' [HttpUrl](https://docs.pydantic.dev/usage/types/#urls):\
            \ scheme http or https, TLD required, host required, max length 2083.\n\
            - Images should have persitant URLs that will not change over time.\n\
            - Images are accessible from the server where Idios is hosted and do not\
            \ require authentication.\n- Only JPEG images are supported\n- Images\
            \ must have their\_dimensions\_above\_150 x 150 pixels, otherwise the\
            \ API will return an error `IMAGE_SIZE_TOO_SMALL`\n- If one of the image\
            \ dimension exceeds 1000 pixels, Idios will resize the image so that the\
            \ maximum dimension is set to 1000 pixels and the original aspect ratio\
            \ is kept.\n- Some image links may be permalinks from library or museum\
            \ image collections or be hosted on IIIF servers that only accept certain\
            \ request headers, additionally, the URL may return a 303 redirect to\
            \ point you to the actual image. The API should be able to handle the\
            \ redirect silently and still use the original URL as the primary key."
          example: https://iiif.itatti.harvard.edu/iiif/2/yashiro!letters-jp!letter_001.pdf/full/full/0/default.jpg
          title: URL of the image
          type: string
      title: SearchParameters
      type: object
    SearchResult:
      properties:
        metadata:
          description: >-
            The metadata is parsed as JSON to ensure its validity and regenerated
            to possibly minimise it (e.g. removing unnecessary white spaces). The
            regenerated JSON should at most 65535 characters long.
          example:
            language: ja
            tags:
            - text
          title: Optional, arbitrary JSON object to attach to the image
          type: object
        similarity:
          $ref: '#/components/schemas/SimilarityScore'
        url:
          description: "The url serves as the primary key in the Milvus collection.\
            \ For consistancy, image URLs should not have escape characters. Optionally,\
            \ additional metadata can be associated with the image as an arbitrary\
            \ JSON object.\n\nAssumptions\n- Url follows pydantics' [HttpUrl](https://docs.pydantic.dev/usage/types/#urls):\
            \ scheme http or https, TLD required, host required, max length 2083.\n\
            - Images should have persitant URLs that will not change over time.\n\
            - Images are accessible from the server where Idios is hosted and do not\
            \ require authentication.\n- Only JPEG images are supported\n- Images\
            \ must have their\_dimensions\_above\_150 x 150 pixels, otherwise the\
            \ API will return an error `IMAGE_SIZE_TOO_SMALL`\n- If one of the image\
            \ dimension exceeds 1000 pixels, Idios will resize the image so that the\
            \ maximum dimension is set to 1000 pixels and the original aspect ratio\
            \ is kept.\n- Some image links may be permalinks from library or museum\
            \ image collections or be hosted on IIIF servers that only accept certain\
            \ request headers, additionally, the URL may return a 303 redirect to\
            \ point you to the actual image. The API should be able to handle the\
            \ redirect silently and still use the original URL as the primary key."
          example: https://iiif.itatti.harvard.edu/iiif/2/yashiro!letters-jp!letter_001.pdf/full/full/0/default.jpg
          title: URL of the image
          type: string
      required:
      - url
      - similarity
      title: SearchResult
      type: object
    SearchResults:
      items:
        $ref: '#/components/schemas/SearchResult'
      title: SearchResults
      type: array
    SimilarityScore:
      description: Scores range from 0 to 100, with 100 being a perfect match.
      maximum: 100.0
      minimum: 0.0
      title: SimilarityScore
      type: number
    SingleImage:
      properties:
        url:
          description: "The url serves as the primary key in the Milvus collection.\
            \ For consistancy, image URLs should not have escape characters. Optionally,\
            \ additional metadata can be associated with the image as an arbitrary\
            \ JSON object.\n\nAssumptions\n- Url follows pydantics' [HttpUrl](https://docs.pydantic.dev/usage/types/#urls):\
            \ scheme http or https, TLD required, host required, max length 2083.\n\
            - Images should have persitant URLs that will not change over time.\n\
            - Images are accessible from the server where Idios is hosted and do not\
            \ require authentication.\n- Only JPEG images are supported\n- Images\
            \ must have their\_dimensions\_above\_150 x 150 pixels, otherwise the\
            \ API will return an error `IMAGE_SIZE_TOO_SMALL`\n- If one of the image\
            \ dimension exceeds 1000 pixels, Idios will resize the image so that the\
            \ maximum dimension is set to 1000 pixels and the original aspect ratio\
            \ is kept.\n- Some image links may be permalinks from library or museum\
            \ image collections or be hosted on IIIF servers that only accept certain\
            \ request headers, additionally, the URL may return a 303 redirect to\
            \ point you to the actual image. The API should be able to handle the\
            \ redirect silently and still use the original URL as the primary key."
          example: https://iiif.itatti.harvard.edu/iiif/2/yashiro!letters-jp!letter_001.pdf/full/full/0/default.jpg
          title: URL of the image
          type: string
      required:
      - url
      title: SingleImage
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
info:
  description: >-
    Idios is a reverse image search application with an HTTP API that allows you to
    search for images that are visually similar.


    It supports several embedding models. Images can be added to each of these models
    separately. To do so, their embedding will be combuted and indexed in a milvus
    collection. This will later allow to search, or compare other images in this collection.
    Images of each model can also be deleted, listed and counted.
  title: Idios
  version: 0.1.0
openapi: 3.0.2
paths:
  /models/{model_name}/add:
    post:
      operationId: upsert_image_models__model_name__add_post
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageAndMetada'
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: >-
        Adds a new image embedding to the index.

        Adding an existing url will replace the metadata with the provided one.
      tags:
      - model
  /models/{model_name}/compare:
    post:
      operationId: compare_models__model_name__compare_post
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImagePair'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarityScore'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Compute the similarity score between two images
      tags:
      - model
  /models/{model_name}/count:
    get:
      operationId: count_models__model_name__count_get
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Count the number of images in in a given index
      tags:
      - model
  /models/{model_name}/dump:
    post:
      operationId: dump_models__model_name__dump_post
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Pagination'
              default: {}
              title: Pagination
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DatabaseEntry'
                title: Response Dump Models  Model Name  Dump Post
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: >-
        Dump the urls, the embedding and the metadata of all images.

        Use the pagination cursor to make sure that the enumeration reached the end.
      tags:
      - model
  /models/{model_name}/remove:
    post:
      operationId: remove_image_models__model_name__remove_post
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleImage'
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Remove an image embedding from the index.
      tags:
      - model
  /models/{model_name}/restore:
    post:
      operationId: restore_models__model_name__restore_post
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/DatabaseEntry'
              title: Images
              type: array
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: >-
        Adds multiple image embeddings to the index.

        Existing urls will have their metadata replaced with the provided one.
      tags:
      - model
  /models/{model_name}/search:
    post:
      operationId: search_models__model_name__search_post
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchParameters'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Search images with similar embeddings in the index
      tags:
      - model
  /models/{model_name}/search_add:
    post:
      operationId: insert_image_models__model_name__search_add_post
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageAndMetada'
        required: true
      responses:
        '204':
          description: Successful Response
        '409':
          description: Image already inserted
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: >-
        Adds a new image embedding to the index.

        Adding an existing url will trigger a 409 HTTP error.
      tags:
      - model
  /models/{model_name}/urls:
    post:
      operationId: list_images_models__model_name__urls_post
      parameters:
      - in: path
        name: model_name
        required: true
        schema:
          $ref: '#/components/schemas/ModelName'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Pagination'
              default: {}
              title: Pagination
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  description: "The url serves as the primary key in the Milvus collection.\
                    \ For consistancy, image URLs should not have escape characters.\
                    \ Optionally, additional metadata can be associated with the image\
                    \ as an arbitrary JSON object.\n\nAssumptions\n- Url follows pydantics'\
                    \ [HttpUrl](https://docs.pydantic.dev/usage/types/#urls): scheme\
                    \ http or https, TLD required, host required, max length 2083.\n\
                    - Images should have persitant URLs that will not change over\
                    \ time.\n- Images are accessible from the server where Idios is\
                    \ hosted and do not require authentication.\n- Only JPEG images\
                    \ are supported\n- Images must have their\_dimensions\_above\_\
                    150 x 150 pixels, otherwise the API will return an error `IMAGE_SIZE_TOO_SMALL`\n\
                    - If one of the image dimension exceeds 1000 pixels, Idios will\
                    \ resize the image so that the maximum dimension is set to 1000\
                    \ pixels and the original aspect ratio is kept.\n- Some image\
                    \ links may be permalinks from library or museum image collections\
                    \ or be hosted on IIIF servers that only accept certain request\
                    \ headers, additionally, the URL may return a 303 redirect to\
                    \ point you to the actual image. The API should be able to handle\
                    \ the redirect silently and still use the original URL as the\
                    \ primary key."
                  example: https://iiif.itatti.harvard.edu/iiif/2/yashiro!letters-jp!letter_001.pdf/full/full/0/default.jpg
                  title: URL of the image
                  type: string
                title: Response List Images Models  Model Name  Urls Post
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: >-
        List the urls of all images.

        Use the pagination cursor to make sure that the enumeration reached the end.
      tags:
      - model
  /ping:
    get:
      operationId: ping_ping_get
      parameters:
      - description: >-
          Also send an RPC ping to check a round-trip with a worker via the job queue
        in: query
        name: rpc
        required: false
        schema:
          default: false
          description: >-
            Also send an RPC ping to check a round-trip with a worker via the job
            queue
          title: Rpc
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                enum:
                - pong
                title: Response Ping Ping Get
                type: string
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Check for the health of the server.
      tags:
      - misc