swagger.yaml

swagger: "2.0"

info:
  title: IPFSWebService
  description:
    This specification defines a minimalist subset of the HTTP API for IPFS.
  version: 4.1.1

host: 127.0.0.1:5001
basePath: /api/v0
schemes:
  - http

consumes:
  - application/json
produces:
  - application/json

paths:

  /add:
    post:
      summary:
        Add a file or directory to ipfs.
      operationId: add
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: file
          type: file
          description: |
            This endpoint expects a file in the body of the request
            as ‘multipart/form-data’.
          required: true
        - in: query
          name: pin
          type: boolean
          description: |
            Pin this object when adding.
          required: false
          default: false
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/AddResponse'

  /cat:
    get:
      summary:
        Show IPFS object data.
      operationId: cat
      produces:
        - text/plain
      parameters:
        - in: query
          name: arg
          type: string
          description: |
             The path to the IPFS object(s) to be outputted.
          required: true
      responses:
        200:
          description: OK
          schema:
            type: string
            format: binary

  /pin/add:
    get:
      summary:
        Pin objects to local storage.
      operationId: pin
      parameters:
        - in: query
          name: arg
          type: string
          description: |
             Path to object(s) to be pinned.
          required: true
        - in: query
          name: recursive
          type: boolean
          description: |
             Recursively pin the object linked to by the specified object(s).
          required: false
          default: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/PinResponse'

  /pin/rm:
    get:
      summary:
        Remove pinned objects from local storage.
      operationId: unpin
      parameters:
        - in: query
          name: arg
          type: string
          description: |
             Path to object(s) to be unpinned.
          required: true
        - in: query
          name: recursive
          type: boolean
          description: |
             Recursively unpin the object linked to by the specified object(s).
          required: false
          default: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/PinResponse'

  /name/publish:
    get:
      summary:
        IPNS is a PKI namespace, where names are the hashes of public keys, and
        the private key enables publishing new (signed) values. In both publish
        and resolve, the default name used is the node's own PeerID,
        which is the hash of its public key.
      operationId: publish
      parameters:
        - in: query
          name: arg
          type: string
          description: |
              ipfs path of the object to be published.
          required: true
        - in: query
          name: key
          type: string
          description: |
              Name of the key to be used, as listed by ‘ipfs key list’.
              Default is “self”.
          required: false
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/PublishResponse'

  /name/resolve:
    get:
      summary:
        IPNS is a PKI namespace, where names are the hashes of public keys, and
        the private key enables publishing new (signed) values. In both publish
        and resolve, the default name used is the node's own PeerID,
        which is the hash of its public key.
      operationId: resolve
      parameters:
        - in: query
          name: arg
          type: string
          description: |
              The IPNS name to resolve.
          required: true
        - in: query
          name: recursive
          type: boolean
          description: |
              Resolve until the result is not an IPNS name. Default is false.
          required: false
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ResolveResponse'

  /key/gen:
    get:
      summary:
        Create a new keypair
      operationId: keygen
      parameters:
        - in: query
          name: arg
          description: Name of key to create.
          type: string
          required: true
        - in: query
          name: type
          description: Type of the key to create.
          type: string
          enum:
            - rsa
            - ed25519
          required: true
        - in: query
          name: size
          description: Size of the key to generate
          type: integer
          required: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/KeygenResponse'

  /key/list:
    get:
      summary:
        List all local keypairs
      operationId: listKeys
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ListKeysResponse'

  /key/rm:
    get:
      summary:
        List all local keypairs
      operationId: removeKey
      parameters:
        - in: query
          name: arg
          description: Name of key to remove.
          type: string
          required: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/RemoveKeyResponse'

  /key/rename:
    get:
      summary:
        Renames a given keypair
      operationId: renameKey
      parameters:
        - in: query
          name: arg
          description: Name of key to rename.
          type: string
          required: true
        - in: query
          name: arg
          description: |
            The new name for the key. The duplicate 'arg' is not a typo.
            This is how the IPFS API expects the query parameters.
          type: string
          required: true
        - in: query
          name: force
          description: Allow to overwrite an existing key.
          type: boolean
          required: false
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/RenameKeyResponse'

definitions:

    Key:
      type: object
      properties:
        Name:
          type: string
          description: The name of the key as given to the keygen API.
          example: "Max Musterman"
        Id:
          type: string
          description: The generated key for usage with IPNS.
          example: "QmerDzHK1aRgh9dP1KxZXqEBFgQonRnxWfqeHTvt8h1PAm"
      required:
      - Name
      - Id

    KeyList:
      type: object
      properties:
        Keys:
          type: array
          description: A list of keypairs.
          items:
            $ref: '#/definitions/Key'
      required:
      - Keys

    AddResponse:
      type: object
      properties:
        Name:
          type: string
          example: "The Cathedral and the Bazaar.pdf"
        Hash:
          type: string
          example: "QmU6A9DYK4N7dvgcrmr9YRjJ4RNxAE6HnMjBBPLGedqVT7"
        Size:
          type: string
          example: "193960"
      required:
      - Name
      - Hash
      - Size

    PinResponse:
      type: object
      properties:
        Pins:
          type: array
          description: A list of pinned objects.
          items:
            type: string
        Progress:
          type: string
          example: "<int>"
      required:
      - Pins

    PublishResponse:
      type: object
      properties:
        Name:
          type: string
          description: |
            The name under which the value was published. By default, this
            will be the peer ID (i.e. the hash of the node's public key).
          example: "QmXXcnBhtXB7dFFxwEyzG1YctDU8ZpcKweQcKp1JHXktn8"
        Value:
          type: string
          description: |
            The resource to which the name now resolves.
          example: "/ipfs/QmU6A9DYK4N7dvgcrmr9YRjJ4RNxAE6HnMjBBPLGedqVT7"
      required:
      - Name
      - Value

    ResolveResponse:
      type: object
      properties:
        Path:
          type: string
          description: |
            The path to which the name resolved.
          example: "/ipfs/QmU6A9DYK4N7dvgcrmr9YRjJ4RNxAE6HnMjBBPLGedqVT7"
      required:
      - Path

    KeygenResponse:
      allOf:
        - $ref: '#/definitions/Key'
        - type: object

    ListKeysResponse:
      allOf:
        - $ref: '#/definitions/KeyList'
        - type: object

    RemoveKeyResponse:
      allOf:
        - $ref: '#/definitions/KeyList'
        - type: object

    RenameKeyResponse:
      type: object
      properties:
        Was:
          type: string
          description: The previous name of the key.
          example: "my-key"
        Now:
          type: string
          description: The new name of the key.
          example: "my-new-key-name"
        Id:
          type: string
          description: The generated key for usage with IPNS.
          example: "QmerDzHK1aRgh9dP1KxZXqEBFgQonRnxWfqeHTvt8h1PAm"
        Overwrite:
          type: boolean
          description: Indicates whether an existing key was overriden.
      required:
      - Was
      - Now
      - Id