openapi: 3.0.0
info:
  description: |
    Welcome to the HumHub cFiles module API reference.
  version: 1.0.0
  title: HumHub - cFiles API
  contact:
    email: info@humhub.com
  license:
    name: AGPLv2
    url: https://www.humhub.org/en/licences
paths:
  "/cfiles/folders/container/{id}":
    get:
      tags:
        - Directory
      summary: Find all folders by content container
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          schema:
            type: integer
        - $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/parameters/pageParam
        - $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/parameters/limitParam
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/pageProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Directory"
            application/xml:
              schema:
                type: object
                properties:
                  total:
                    $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/pageProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Directory"
    post:
      tags:
        - Directory
      summary: Create new directory
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          schema:
            type: integer
      requestBody:
        $ref: "#/components/requestBodies/Body"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Directory"
        "404":
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/ContainerNotFound
        "422":
          description: Validation failed
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while save valid directory!
  "/cfiles/folder/{id}":
    get:
      tags:
        - Directory
      summary: Get directory by id
      description: ""
      parameters:
        - name: id
          in: path
          description: The id of directory
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Directory"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Requested content not found!
    put:
      tags:
        - Directory
      summary: Update directory by id
      description: ""
      parameters:
        - name: id
          in: path
          description: The id of the directory
          required: true
          schema:
            type: integer
      requestBody:
        $ref: "#/components/requestBodies/Body"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Directory"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: cFiles folder not found!
        "422":
          description: Validation failed
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while update cFiles folder!
    delete:
      tags:
        - Directory
      summary: Deletes a directory by id
      parameters:
        - name: id
          in: path
          description: The id of directory
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Selected items are successfully deleted!
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    description: Content record not found!
  "/cfiles/files/container/{id}":
    get:
      tags:
        - File
      summary: Find all files by content container
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          schema:
            type: integer
        - $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/parameters/pageParam
        - $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/parameters/limitParam
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/pageProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/File"
            application/xml:
              schema:
                type: object
                properties:
                  total:
                    $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/pageProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/File"
    post:
      tags:
        - File
      summary: Upload files
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                folder_id:
                  description: Id of directory
                  type: integer
                  format: int64
                files:
                  description: The files to upload.
                  type: array
                  items:
                    type: file
              required:
                - folder_id
                - files
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Files successfully uploaded!
        "400":
          description: Bad Request
        "404":
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/ContainerNotFound
        "422":
          description: Validation failed
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while save valid directory!
  "/cfiles/file/{id}":
    get:
      tags:
        - File
      summary: Get file info by id
      description: ""
      parameters:
        - name: id
          in: path
          description: The id of file
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Requested content not found!
    delete:
      tags:
        - File
      summary: Deletes a file by id
      parameters:
        - name: id
          in: path
          description: The id of file
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Successfully deleted!
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 404
                  message:
                    type: string
                    description: Content record not found!
  "/cfiles/items/container/{id}/make-public":
    patch:
      tags:
        - Items Management
      summary: Make items public
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          schema:
            type: integer
      requestBody:
        $ref: "#/components/requestBodies/Body2"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Items successfully marked public!
        "400":
          description: Bad Request
        "404":
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/ContainerNotFound
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while setting public visibility for cFiles item!
  "/cfiles/items/container/{id}/make-private":
    patch:
      tags:
        - Items Management
      summary: Make items private
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          schema:
            type: integer
      requestBody:
        $ref: "#/components/requestBodies/Body2"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Items successfully marked private!
        "400":
          description: Bad Request
        "404":
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/ContainerNotFound
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while setting private visibility for cFiles item!
  "/cfiles/items/container/{id}/move":
    post:
      tags:
        - Items Management
      summary: Move items to another folder
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - source_id
                - MoveForm
                - selection
              properties:
                source_id:
                  type: integer
                  format: int64
                  example: 14
                MoveForm:
                  type: object
                  required:
                    - destId
                  properties:
                    destId:
                      type: string
                      example: 3
                selection:
                  $ref: "#/components/schemas/Selection"
        description: Directory information
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Items successfully moved.
        "400":
          description: Bad Request
        "404":
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/ContainerNotFound
        "422":
          description: Validation failed
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while move cFiles items!
  "/cfiles/items/container/{id}/delete":
    delete:
      tags:
        - Items Management
      summary: Delete items from folder
      description: ""
      parameters:
        - in: path
          name: id
          description: The id of content container
          required: true
          schema:
            type: integer
      requestBody:
        $ref: "#/components/requestBodies/Body2"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Selected items are successfully deleted!
        "400":
          description: Bad Request
        "404":
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/components/schemas/ContainerNotFound
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal error while deleting cFiles item!
servers:
  - url: /api/v1
components:
  requestBodies:
    Body:
      content:
        application/json:
          schema:
            type: object
            required:
              - target_id
              - Folder
            properties:
              target_id:
                type: integer
                format: int64
                example: 1
              Folder:
                type: object
                required:
                  - title
                properties:
                  title:
                    type: string
                    example: API folder
                  description:
                    type: string
                    example: API folder description
                  visibility:
                    type: integer
                    format: int64
                    enum:
                      - 0
                      - 1
                    description: |
                      Allowed visibility statuses:
                        * 0 - Private
                        * 1 - Public
                    example: 1
      description: Directory information
    Body2:
      content:
        application/json:
          schema:
            type: object
            required:
              - selection
            properties:
              selection:
                $ref: "#/components/schemas/Selection"
      description: Array of items
      required: true
  securitySchemes:
    _ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/common.yaml#/securityDefinitions
  schemas:
    DirectoryShort:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          example: 4
        title:
          type: string
          example: API directory
        description:
          type: string
          example: API directory description
    Directory:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          example: 4
        title:
          type: string
          example: API directory
        description:
          type: string
          example: API directory description
        parent_folder_id:
          type: integer
          format: int64
          example: 1
        type:
          type: string
          example: null
        created_at:
          type: string
          example: 2019-03-05 15:35:02
        created_by:
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/user.yaml#/components/schemas/UserShort
        content:
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/content.yaml#/components/schemas/Content
    File:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          example: 4
        description:
          type: string
          example: API directory description
        parent_folder:
          $ref: "#/components/schemas/DirectoryShort"
        created_at:
          type: string
          example: 2019-03-05 15:35:02
        created_by:
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/user.yaml#/components/schemas/UserShort
        content:
          $ref: https://raw.githubusercontent.com/humhub/rest/master/docs/swagger/content.yaml#/components/schemas/Content
    Selection:
      type: array
      description: Item id in format {type}_{id}
      items:
        type: string
      example:
        - folder_4
        - file_2
    DirectoryParams:
      in: body
      name: body
      description: Directory information
      schema:
        type: object
        required:
          - target_id
          - Folder
        properties:
          target_id:
            type: integer
            format: int64
            example: 1
          Folder:
            type: object
            required:
              - title
            properties:
              title:
                type: string
                example: API folder
              description:
                type: string
                example: API folder description
              visibility:
                type: integer
                format: int64
                enum:
                  - 0
                  - 1
                description: |
                  Allowed visibility statuses:
                    * 0 - Private
                    * 1 - Public
                example: 1
      x-s2o-delete: true
    MoveFormParams:
      in: body
      name: body
      description: Directory information
      schema:
        type: object
        required:
          - source_id
          - MoveForm
          - selection
        properties:
          source_id:
            type: integer
            format: int64
            example: 14
          MoveForm:
            type: object
            required:
              - destId
            properties:
              destId:
                type: string
                example: 3
          selection:
            $ref: "#/components/schemas/Selection"
      x-s2o-delete: true
