openapi-v2.yaml

openapi: 3.0.0
info:
  description: Search files and directories on the [Interplanetary Filesystem](https://ipfs.io/) through the [ipfs-search.com](https://ipfs-search.com) search API.
  version: 2.0.0
  title: ipfs-search API
  contact:
    name: ipfs-search.com
    email: info@ipfs-search.com
    url: https://ipfs-search.com
  license:
    name: AGPL 3.0
    url: 'https://www.gnu.org/licenses/agpl-3.0.nl.html'

servers:
  - url: 'https://api.ipfs-search.com/v2'

paths:
  /search:
    get:
      summary: Search for files and directories on IPFS.
      description:
        Perform search queries on the [ipfs-search.com](ipfs-search.com) index.
      parameters:
        - in: query
          name: q
          required: true
          description: Search string query, based on Elasticsearch's [Query string query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-dsl-query-string-query) syntax.

            Allows filtering on indexed fields, as listed in the [index mapping](https://github.com/ipfs-search/ipfs-search/tree/master/docs/indices).
          schema:
            type: string
          examples:
            simple_example:
              summary: Simple text search.
              value: water
            wildcard_name:
              summary: Wildcard search by reference (file)name.
              value: references.name:*.html
            last_seen:
              summary: Last seen this month.
              value: last-seen:>now-1M
            content_type:
              summary: Exact match on content-type.
              value: metadata.Content-Type:"application/pdf"
            parent_hash:
              summary: Inside a directory.
              value: references.parent_hash:QmVFHYaqPHJ7vg2DcszELhyQ7pJXLjHgx33FBwgbiWRQKi
        - in: query
          name: type
          required: false
          description: Resource type. Omit to return results of any type.
          schema:
            $ref: '#/components/schemas/Type'
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 999
            default: 0
            example: 1
          description: Offset from the first result at which to start returning results. A search with an offset of `10` will start at the 11th result, such that with a `limit` of 10, this effectively returns the 2nd page of results.

            Corresponds to the `from`-parameter in the [Elasticsearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html#search-search-api-query-params).
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 10
            example: 15
          description: Maximum amount of results to return. Used in conjunction with the `offset` parameter for pagination.

            Corresponds to the `size`-parameter in the [Elasticsearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html#search-search-api-query-params).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultList'
  /metadata/${hash}/:
    get:
      summary: Retrieve metadata for resources on IPFS.
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Hash'
          description: Content ID; IPLD [CID](https://specs.ipld.io/block-layer/CID.html).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'

  /thumbnail/${hash}/{width}x{height}:
    get:
      summary: Generate/retrieve thumbnails for resources on IPFS (whenever possible).
      description: Based on [https://www.thumbnailapi.com/documentation/](https://www.thumbnailapi.com/documentation/). Images generated server-side and served through IPFS by providing a redirect.
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Hash'
          description: Content ID; IPLD [CID](https://specs.ipld.io/block-layer/CID.html).
        - name: width
          in: path
          required: true
          schema:
            type: integer
            minimum: 64
            maximum: 1920
        - name: height
          in: path
          required: true
          schema:
            type: integer
            minimum: 48
            maximum: 1080
      responses:
        '308':
          description: Permanent redirect to thumbnail of the exact requested dimensions, in WebP format, served through IPFS.

components:
  schemas:
    SearchResult:
      type: object
      properties:
        hash:
          $ref: '#/components/schemas/Hash'
        title:
          type: string
          example: Marine Combat <em>Water</em> Survival by Anonymous
        description:
          type: string
          example: This publication also teaches Marines to cross <em>water</em> obstacles and perform <em>water</em> rescues correctly and safely.
        type:
          $ref: '#/components/schemas/Type'
        size:
          type: integer
          example: 5605
        first-seen:
          type: string
          example: "2018-08-18T20:49:17Z"
        last-seen:
          type: string
          example: "2020-10-27T12:55:32Z"
        score:
          type: number
          example: 231.37302
          description: Relevance of the result. The score for items with a more recent `last-seen` date are positively boosted while 'unnamed' items (without a `reference` or a `title`) are negatively boosted.
        references:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
          description: Zero or more named references.
        mimetype:
          type: string
          example: text/html
    Reference:
      type: object
      properties:
        parent_hash:
          $ref: '#/components/schemas/Hash'
        name:
          type: string
          description: Filename of a resource, as referred to from `parent_hash`.
          example: marine-combat-water-survival.html
      description: Any resource can have zero or more references, such that a link to it can be created as [`/ipfs/<parent_hash>/<name>`. This can be used to generate more semantic links as well as to give a hint for the resolution of mimetypes. For example [`/ipfs/QmcDCte64xtxqTVzdWnT5MG9yi3dFsNuLZjAyess4RJFWc/marine-combat-water-survival.html`](https://gateway.ipfs.io/ipfs/QmcDCte64xtxqTVzdWnT5MG9yi3dFsNuLZjAyess4RJFWc/marine-combat-water-survival.html)).
    SearchResultList:
      type: object
      properties:
        total:
          type: integer
          example: 10000
        max_score:
          type: number
          example: 255.88916
        hits:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
          description: Search results, sorted in descending order by scoring.
    Metadata:
      type: object
      properties:
        metadata:
          type: object
          example:
            "xmpDM:genre":
              - "Soundtrack"
            "xmpDM:composer":
              - "Nobuo Uematsu"
            "X-Parsed-By":
              - "org.apache.tika.parser.DefaultParser"
              - "org.apache.tika.parser.mp3.Mp3Parser"
            "creator":
              -  ""
            "xmpDM:album":
              -  "\"Final Fantasy IX\" Original Soundtrack, Disk 4"
            "xmpDM:trackNumber":
              -  "24"
            "xmpDM:releaseDate":
              -  "2000"
            "meta:author":
              -  ""
            "xmpDM:artist":
              -  ""
            "dc:creator":
              -  ""
            "xmpDM:audioCompressor":
              -  "MP3"
            "resourceName":
              -  "24-Coca Cola TV CM 1.mp3"
            "title":
              -  "Coca Cola TV CM 1"
            "xmpDM:audioChannelType":
              -  "Stereo"
            "version":
              -  "MPEG 3 Layer III Version 1"
            "xmpDM:logComment":
              -  "eng - \nhttp://www.ffdream.com"
            "xmpDM:audioSampleRate":
              -  "44100"
            "channels":
              - "2"
            "dc:title":
              -  "Coca Cola TV CM 1"
            "Author":
              -  ""
            "xmpDM:duration":
              -  "20218.76953125"
            "Content-Type":
              -  "audio/mpeg"
            "samplerate":
              -"44100"
        version:
          type: integer
          example: 2
        type:
          $ref: '#/components/schemas/Type'
    Hash:
      type: string
      example: QmcDCte64xtxqTVzdWnT5MG9yi3dFsNuLZjAyess4RJFWc
      description: Content ID; IPLD [CID](https://specs.ipld.io/block-layer/CID.html), a globally unique reference to a resource determined by its contents.
    Type:
      type: string
      example: file
      enum: [any, audio, video, document, directory, other]
      default: any
      description: Type of returned items. Audio, video and directories should be self-explanatory. Documents are files which can be natively opened on most systems, which typically have a textual representation, such as PDF/DJVU, eBook, Office, HTML or text-files. Other are any files which do not fall in any of the prior categories, such as binary software packages, container images, research datasets etc.