swagger: "2.0"
info:
  title: Pwic.wiki API reference
  version: "1.0"
  description:
    The page lists all the available interfaces to interact with Pwic.wiki.
    The authentication is managed through a cookie.
    The default method is POST.
tags:
  - name: connection
    description: Connection to the API
  - name: document
    description: Management of the documents
  - name: page
    description: Management of the pages
  - name: project
    description: Management of the project
  - name: server
    description: Management of the server
  - name: user
    description: Management of the user
paths:
  /api/login:
    post:
      summary: Connect to the server
      tags:
        - connection
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/html
      parameters:
        - in: query
          name: redirect
          type: string
          description: Redirect to the next screen
          required: false
        - in: formData
          name: user
          type: string
          description: Name of the user
          required: true
        - in: formData
          name: password
          type: string
          description: Password of the user
          required: false
        - in: formData
          name: pin
          type: integer
          description: PIN code if your account uses 2FA TOTP
          required: false
        - in: formData
          name: language
          type: string
          description: Language
          required: false
          default: en
      responses:
        200:
          description: Successful operation if no body, else redirected page from 302
        302:
          description: Redirection with the parameter ?failed if the credentials were rejected
        401:
          description: Unsufficient authorizations
        408:
          description: Expired PIN code for 2FA TOTP
  /api/oauth:
    get:
      summary: Connect through a third-party identity provider
      description: This path is used for the technical implementation of the OAuth protocol. You should not call it voluntarily.
      tags:
        - connection
      consumes:
        - application/json
      responses:
        200:
          description: Successful login
        302:
          description: Successful login
        307:
          description: Redirection with the parameter ?failed if the credentials were rejected
        401:
          description: Unsufficient authorizations
        501:
          description: Invalid OAuth provider
        503:
          description: Connection temporarily unavailable
  /api/document/create:
    post:
      summary: Attach a document to a page
      tags:
        - document
      consumes:
        # https://swagger.io/docs/specification/describing-request-body/multipart-requests/
        - multipart/form-data
      parameters:
        # https://swagger.io/docs/specification/2-0/file-upload/
        - in: formData
          name: project
          type: string
          required: true
        - in: formData
          name: page
          type: string
          required: true
        - in: formData
          name: mime
          type: string
          required: false
        - in: formData
          name: content
          type: file
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        403:
          description: Forbidden content
        409:
          description: Duplicate file name in the project
        413:
          description: File size limit or number of pixels exceeded
        415:
          description: Failed MIME verification
        500:
          description: File incorrectly managed on the server
        503:
          description: Update temporarily unavailable or ongoing server maintenance
  /api/document/convert:
    post:
      summary: Convert a loaded document to Markdown
      tags:
        - document
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/markdown
      parameters:
        - in: formData
          name: id
          type: integer
          description: Identifier of the document
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        403:
          description: Disabled feature
        422:
          description: File cannot be converted
  /api/document/remote/convert:
    post:
      summary: Convert a remote URL to Markdown
      tags:
        - document
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/markdown
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project (declarative)
          required: true
        - in: formData
          name: url
          type: string
          description: Remote URL if allowed by the configuation
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        403:
          description: Disabled feature
        422:
          description: File cannot be converted
  /api/document/delete:
    post:
      summary: Delete a document of a project
      tags:
        - document
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: id
          type: integer
          description: Identifier of the document
          required: true
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations, or not found
        500:
          description: File incorrectly managed on the server
        503:
          description: Update temporarily unavailable or ongoing server maintenance
  /api/document/get:
    post:
      summary: Get one of several documents depending on the parameters
      tags:
        - document
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: false
        - in: formData
          name: page
          type: string
          description: Name of the page
          required: false
        - in: formData
          name: id
          type: integer
          description: Internal identifier of the file
          required: false
        - in: formData
          name: attachment
          type: boolean
          description: Return as attachment
          required: false
      responses:
        200:
          description: Successful operation
        302:
          description: Successful redirection to another location
        400:
          description: Invalid parameters
        404:
          description: Unsufficient authorizations, or not found
  /api/document/list:
    post:
      summary: List the files attached to a page
      tags:
        - document
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: page
          type: string
          description: Name of the page
          required: true
      responses:
        200:
          description: Successful operation
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                filename:
                  type: string
                mime:
                  type: string
                mime_icon:
                  type: string
                size:
                  type: string
                hash:
                  type: string
                author:
                  type: string
                date:
                  type: string
                time:
                  type: string
                exturl:
                  type: string
                  description: External storage link
                used:
                  type: boolean
                  description: According to a static detection
                url:
                  type: string
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        404:
          description: Unknown project or page
  /api/document/rename:
    post:
      summary: Rename a local document
      tags:
        - document
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: id
          type: integer
          description: Identifier of the document
          required: true
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: filename
          type: string
          description: New file name
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations, or not found
        500:
          description: File incorrectly managed on the server
        503:
          description: Update temporarily unavailable or ongoing server maintenance
  /api/markdown/convert:
    post:
      summary: Convert Markdown to HTML
      tags:
        - page
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: markdown
          type: string
          description: Content written in Markdown
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
  /api/page/create:
    post:
      summary: Create a new page
      tags:
        - page
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: kbid
          type: boolean
          description: Generate a knowledge base article
          required: false
        - in: formData
          name: page
          type: string
          description: Name of the page
          required: true
        - in: formData
          name: milestone
          type: string
          description: Planned milestone for the new page
          required: false
        - in: formData
          name: tags
          type: string
          description: Tags separated by a space and with no hash
          required: false
        - in: formData
          name: ref_project
          type: string
          description: Reference project
          required: false
        - in: formData
          name: ref_page
          type: string
          description: Reference page
          required: false
        - in: formData
          name: ref_tags
          type: boolean
          description: Copy the tags of the reference page
          required: false
      responses:
        200:
          description: Successful operation
          schema:
            type: object
            properties:
              project:
                type: string
              page:
                type: string
              revision:
                type: integer
              url:
                type: string
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        403:
          description: Exceeded limitations
        404:
          description: Reference page not found
        503:
          description: Update temporarily unavailable
  /api/page/delete:
    post:
      summary: Delete the revision of a page
      tags:
        - page
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: page
          type: string
          description: Name of the page
          required: true
        - in: formData
          name: revision
          type: integer
          description: Revision of the page
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations, or not found
        500:
          description: Dependent files not fully removed from the system
        503:
          description: Update temporarily unavailable
  /api/page/edit:
    post:
      summary: Create a new revision of a page
      tags:
        - page
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: page
          type: string
          description: Name of the page
          required: true
        - in: formData
          name: title
          type: string
          description: Title of the page
          required: true
        - in: formData
          name: tags
          type: string
          description: Tags separated by a space and with no hash
          required: false
        - in: formData
          name: markdown
          type: string
          description: Content of the page
          required: false
        - in: formData
          name: comment
          type: string
          description: Explanation of the modification
          required: true
        - in: formData
          name: milestone
          type: string
          description: Planned milestone
          required: false
        - in: formData
          name: draft
          type: boolean
          description: Save as draft
          required: false
        - in: formData
          name: final
          type: boolean
          description: Save as final
          required: false
        - in: formData
          name: header
          type: boolean
          description: Attach the page to the headers
          required: false
        - in: formData
          name: protection
          type: boolean
          description: Protect the page
          required: false
        - in: formData
          name: no_quick_fix
          type: boolean
          description: Ignore the option quick_fix
          required: false
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        503:
          description: Update temporarily unavailable
  /api/page/export:
    post:
      summary: Export a page
      tags:
        - page
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: page
          type: string
          description: Name of the page
          required: true
        - in: formData
          name: revision
          type: integer
          description: Revision of the page
          required: false
        - in: formData
          name: format
          type: string
          enum: [html, md, odt]
          description: Format of the export
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations, or not found
        403:
          description: Disabled feature
        404:
          description: Rejected by a custom rule
        415:
          description: Invalid file format
  /api/page/move:
    post:
      summary: Rename and/or move a page
      tags:
        - page
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: ref_project
          type: string
          description: Source project
          required: true
        - in: formData
          name: ref_page
          type: string
          description: Source page
          required: true
        - in: formData
          name: project
          type: string
          description: Target project
          required: true
        - in: formData
          name: page
          type: string
          description: Target page
        - in: formData
          name: ignore_file_errors
          type: boolean
          description: Ignore the failed operations on the files
          default: true
      responses:
        302:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations, or project not found
        403:
          description: Target page already exists
        404:
          description: Unkown source page
        409:
          description: Attachments in conflict with the target project
        500:
          description: Corrupted documents to be repaired
        503:
          description: Update temporarily unavailable
  /api/page/validate:
    post:
      summary: Validate the revision of a page
      tags:
        - page
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: page
          type: string
          description: Name of the page
          required: true
        - in: formData
          name: revision
          type: integer
          description: Revision of the page
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations, or not found
        503:
          description: Update temporarily unavailable
  /api/project/env/set:
    post:
      summary: Change a project-dependent setting
      tags:
        - project
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: key
          type: string
          description: Name of the option (refer to /help)
          required: true
        - in: formData
          name: value
          type: string
          description: Value of the option
          required: false
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
  /api/project/get:
    post:
      summary: Get the details about the project or a page
      tags:
        - project
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: page
          type: string
          description: Name of the page
          required: false
        - in: formData
          name: all
          type: boolean
          description: Include the all the revisions of the pages
          required: false
        - in: formData
          name: no_markdown
          type: boolean
          description: Don't provide the content of the page to reduce the size of the transferred data
          required: false
        - in: formData
          name: no_document
          type: boolean
          description: Don't list the attached documents
          required: false
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        501:
          description: Unsupported combination of options
  /api/project/graph/get:
    post:
      summary: Generate the graph of a project
      tags:
        - project
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/vnd.graphviz
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        403:
          description: Disabled feature
  /api/project/list:
    post:
      summary: List the projects accessible to the user
      tags:
        - project
      produces:
        - application/json
      parameters:
        - in: formData
          name: user
          type: string
          description: Name of the user
          required: false
      responses:
        200:
          description: Successful operation
          schema:
            type: array
            items:
              type: object
              properties:
                project:
                  type: string
                description:
                  type: string
                admin:
                  type: boolean
                manager:
                  type: boolean
                editor:
                  type: boolean
                validator:
                  type: boolean
                reader:
                  type: boolean
        401:
          description: Unsufficient authorizations
  /api/project/progress/get:
    post:
      summary: Show the current progress of the project by tag
      tags:
        - project
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: tags
          type: string
          description: List of the tags separated with a space
          required: true
        - in: formData
          name: combined
          type: boolean
          description: Should match all the tags (true) or at least one tag (false)
          required: false
          default: false
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
  /api/project/users/get:
    post:
      summary: Fetch the users of a project by roles
      tags:
        - project
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: admin
          type: boolean
          description: Administrator
          required: false
        - in: formData
          name: manager
          type: boolean
          description: Manager
          required: false
        - in: formData
          name: editor
          type: boolean
          description: Editor
          required: false
        - in: formData
          name: validator
          type: boolean
          description: Validator
          required: false
        - in: formData
          name: reader
          type: boolean
          description: Reader
          required: false
        - in: formData
          name: operator
          type: string
          enum: [or, and, exact]
          description: Logical operation
          required: true
      responses:
        200:
          description: Successful operation
          schema:
            type: array
            items:
              type: string
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations, or not found
  /api/server/env/get:
    post:
      summary: Get details about the environment variables
      tags:
        - server
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: false
      responses:
        200:
          description: Successful operation
          schema:
            type: object
            properties:
              variable:
                type: object
                properties:
                  value:
                    type: string
                  global:
                    type: boolean
                  project_independent:
                    type: boolean
                  project_dependent:
                    type: boolean
                  changeable:
                    type: boolean
        401:
          description: Unsufficient authorizations, or not found
  /api/server/headers/get:
    get:
      summary: Display the received HTTP headers
      tags:
        - server
      produces:
        - application/json
      responses:
        200:
          description: Successful operation
          schema:
            type: object
            properties:
              ip:
                type: string
                description: Remote IP address
              data:
                type: object
                properties:
                  name:
                    type: array
                    description: Values of the header
                    items:
                      type: string
        401:
          description: Session not active
  /api/server/ping:
    post:
      summary: Ping the server to verify that it is up and not restarted
      tags:
        - server
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      responses:
        200:
          description: Session still alive
        401:
          description: Session not active
  /api/server/shutdown:
    post:
      summary: Shut down the server
      tags:
        - server
      responses:
        403:
          description: Connect from localhost only
        503:
          description: Shutdown temporarily unavailable
  /api/server/unlock:
    post:
      summary: Unlock the database after an internal Python error
      tags:
        - server
      responses:
        200:
          description: Successful operation
        400:
          description: Database not locked
        403:
          description: Connect from localhost only
  /api/user/create:
    post:
      summary: Create or assign a user to a project
      tags:
        - user
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: user
          type: string
          description: Name of the user
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        403:
          description: Forbidden operation
        503:
          description: Update temporarily unavailable
  /api/user/language/set:
    post:
      summary: Change the language of the current session
      tags:
        - user
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: language
          type: string
          description: Language ISO code on 2 characters
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
  /api/user/password/change:
    post:
      summary: Change the password of the logged user
      tags:
        - user
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: password_current
          type: string
          description: Current password
          required: true
        - in: formData
          name: password_new1
          type: string
          description: New password
          required: true
        - in: formData
          name: password_new2
          type: string
          description: New password (confirmation)
          required: true
      responses:
        200:
          description: Successful operation
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        500:
          description: Invalid configuration of the server
        503:
          description: Update temporarily unavailable
  /api/user/roles/set:
    post:
      summary: Toggle or drop the role of a user for a project
      tags:
        - user
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/plain
      parameters:
        - in: formData
          name: project
          type: string
          description: Name of the project
          required: true
        - in: formData
          name: name
          type: string
          description: Name of the user
          required: true
        - in: formData
          name: role
          type: string
          enum: [admin, manager, editor, validator, reader, disabled, delete]
          description: Role to toggle
          required: true
      responses:
        200:
          description: Successful operation, followed by the new value
          schema:
            type: string
            enum: ["", "X", "OK"]
        400:
          description: Invalid parameters
        401:
          description: Unsufficient authorizations
        503:
          description: Update temporarily unavailable