path-gateway-openapi.yaml

openapi: 3.0.3
info:
  title: IPFS Gateway API
  description: |
    This is an OpenAPI 3.0 specification for the IPFS Gateway API, following the specs.ipfs.tech/http-gateways/path-gateway specification.
    You can find more information about IPFS at [https://ipfs.tech](https://ipfs.tech).
  version: 1.0.0
servers:
  - url: https://ipfs.io
paths:
  /ipfs/{cid}:
    get:
      security: []
      summary: Retrieve content from IPFS by CID
      description: |
        Retrieves content from the InterPlanetary File System (IPFS) by the Content Identifier (CID).
      parameters:
        - name: cid
          in: path
          description: Content Identifier (CID)
          required: true
          schema:
            type: string
            example: "QmHash123"
        - name: path
          in: query
          description: Optional path parameter pointing at a file or a directory under the CID content root.
          schema:
            type: string
            example: "/index.html"
        - name: params
          in: query
          description: Optional query parameters that adjust response behavior.
          schema:
            type: object
            example: {"recursive": true}
        - name: Range
          in: header
          description: Request a specific range of bytes from the resource
          required: false
          schema:
            type: string
            example: "bytes=0-100"
        - name: Accept
          in: header
          description: Request a specific content type for the response
          required: false
          schema:
            type: string
            example: "application/json"
        - name: If-None-Match
          in: header
          description: Perform conditional retrieval based on the presence of a matching ETag
          required: false
          schema:
            type: string
            example: "123456789"
        - name: If-Modified-Since
          in: header
          description: Perform conditional retrieval based on the modification time of the resource
          required: false
          schema:
            type: string
            format: date-time
            example: "2024-03-16T12:00:00Z"
        - name: If-Unmodified-Since
          in: header
          description: Perform conditional retrieval based on the absence of modification since the specified time
          required: false
          schema:
            type: string
            format: date-time
            example: "2024-03-16T12:00:00Z"
        - name: Accept-Encoding
          in: header
          description: Request a specific content encoding for the response
          required: false
          schema:
            type: string
            example: "gzip"
        - name: User-Agent
          in: header
          description: Information about the client user agent
          required: false
          schema:
            type: string
            example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
      responses:
        '200':
          description: Content retrieved successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: "Hello, World!"
        '301':
          description: Permanent redirection
        '400':
          description: Generic client error
        '404':
          description: Content not found
        '410':
          description: Gateway refuses to return requested data
        '412':
          description: Gateway is unable to return requested data under additional conditions sent by the client
        '429':
          description: Client has sent too many requests in a given amount of time
        '451':
          description: Gateway is unable to return requested data due to legal reasons
        '500':
          description: Generic server error
        '502':
          description: Gateway was not able to produce response for a known reason
        '504':
          description: Gateway was not able to produce response under set time limits