openapi: 3.0.0
info:
  description: |
    Welcome to the HumHub post module API reference.
  version: 1.0.0
  title: HumHub - Post API
  contact:
    email: info@humhub.com
  license:
    name: AGPLv2
    url: https://www.humhub.org/en/licences
paths:
  "/post/container/{id}":
    get:
      summary: Find all posts by container
      description: ""
      parameters:
        - name: id
          in: path
          description: ID of content container
          required: true
          schema:
            type: integer
        - $ref: content.yaml#/components/parameters/topicsParam
        - $ref: common.yaml#/components/parameters/pageParam
        - $ref: common.yaml#/components/parameters/limitParam
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  pages:
                    $ref: common.yaml#/components/schemas/pagesProperty
                  links:
                    $ref: common.yaml#/components/schemas/linksProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Post"
            application/xml:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  pages:
                    $ref: common.yaml#/components/schemas/pagesProperty
                  links:
                    $ref: common.yaml#/components/schemas/linksProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Post"
    post:
      summary: Creates a new post
      description: ""
      parameters:
        - name: id
          in: path
          description: ID of content container to post to
          required: true
          schema:
            type: integer
      requestBody:
        $ref: "#/components/requestBodies/Body"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
        "400":
          description: Invalid post id supplied
        "404":
          description: Post not found
  /post:
    get:
      summary: Find all posts
      description: ""
      parameters:
        - $ref: common.yaml#/components/parameters/pageParam
        - $ref: common.yaml#/components/parameters/limitParam
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  pages:
                    $ref: common.yaml#/components/schemas/pagesProperty
                  links:
                    $ref: common.yaml#/components/schemas/linksProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Post"
            application/xml:
              schema:
                type: object
                properties:
                  total:
                    $ref: common.yaml#/components/schemas/totalProperty
                  page:
                    $ref: common.yaml#/components/schemas/pageProperty
                  pages:
                    $ref: common.yaml#/components/schemas/pagesProperty
                  links:
                    $ref: common.yaml#/components/schemas/linksProperty
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Post"
  "/post/{id}":
    get:
      summary: Get post by id
      description: ""
      parameters:
        - name: id
          in: path
          description: The id of the post
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
        "400":
          description: Invalid post id supplied
        "404":
          description: Post not found
    put:
      summary: Updates a post by id
      parameters:
        - name: id
          in: path
          description: The id of post
          required: true
          schema:
            type: integer
      requestBody:
        $ref: "#/components/requestBodies/Body"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
        "404":
          description: Post not found
    delete:
      summary: Deletes a post by id
      parameters:
        - name: id
          in: path
          description: The id of post
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: successful operation
        "404":
          description: Post not found
  "/post/{id}/upload-files":
    post:
      summary: Upload files to Post by id
      description: ""
      parameters:
        - name: id
          in: path
          description: The id of the Post
          required: true
          schema:
            type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                hiddenInStream:
                  type: array
                  description: Names of the attached files which should be hidden in stream
                  example:
                    - scheme.jpg
                    - picture.png
                    - info.txt
                  items: {}
                files:
                  description: The files to upload.
                  type: array
                  items:
                    type: file
              required:
                - files
      responses:
        "200":
          description: Files successfully uploaded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  files:
                    type: array
                    items:
                      $ref: file.yaml#/components/schemas/File
        "400":
          description: Invalid content id supplied
        "403":
          description: You are not allowed to upload files to this content!
        "404":
          description: Content record not found!
        "500":
          description: Internal error while saving file.
servers:
  - url: /api/v1
components:
  requestBodies:
    Body:
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              data:
                $ref: "#/components/schemas/Post"
      description: The post
      required: true
  securitySchemes:
    _ref: common.yaml#/securityDefinitions
  schemas:
    Post:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          example: 14
        message:
          type: string
          example: Calvin Klein – Between love and madness lies obsession.
        content:
          $ref: content.yaml#/components/schemas/Content
