openapi: 3.1.0
info:
  contact:
    email: contact@passbolt.com
  description: This is a low-level overview of the API and its endpoints, if you need higher-level guides for interacting with the endpoints, use the Developer guide.
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  termsOfService: https://www.passbolt.com/terms
  title: Passbolt Authentication (GPGAuth) Authentication (GPGAuth) Comments API
  version: 5.0.0
servers:
- url: https://passbolt.local
  description: API Passbolt
tags:
- name: Comments
  description: Manipulate comments for resources.
paths:
  /comments/{commentId}.json:
    put:
      summary: Update a comment.
      operationId: updateComment
      security:
      - bearerHttpAuthentication: []
      x-codeSamples:
      - lang: cURL
        source: "curl --request PUT \\\n  --url {{API_BASE_URL}}/comments/41aca4aa-430c-4b60-a1f1-c0de1b52a1ce.json \\\n  --header 'Authorization: Bearer {{JWT_TOKEN}}' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"content\": \"no comment\"\n  }'\n"
      - lang: JavaScript
        source: "const url = '{{API_BASE_URL}}/comments/41aca4aa-430c-4b60-a1f1-c0de1b52a1ce.json';\nconst options = {\n  method: 'PUT',\n  headers: {Authorization: 'Bearer {{JWT_TOKEN}}'},\n  body: '{\"content\":\"no comment\"}'\n};\n\ntry {\n  const response = await fetch(url, options);\n  const data = await response.json();\n  console.log(data);\n} catch (error) {\n  console.error(error);\n}\n"
      - lang: PHP
        source: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"{{API_BASE_URL}}/comments/41aca4aa-430c-4b60-a1f1-c0de1b52a1ce.json\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"PUT\",\n  CURLOPT_POSTFIELDS => json_encode([\n    'content' => 'no comment'\n  ]),\n  CURLOPT_HTTPHEADER => [\n    \"Authorization: Bearer {{JWT_TOKEN}}\"\n  ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}\n"
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/commentId'
      requestBody:
        $ref: '#/components/requestBodies/commentUpdate'
      responses:
        '200':
          $ref: '#/components/responses/update'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/authenticationRequired'
        '404':
          $ref: '#/components/responses/notFound'
    delete:
      summary: Delete a comment.
      operationId: deleteComment
      security:
      - bearerHttpAuthentication: []
      x-codeSamples:
      - lang: cURL
        source: "curl --request DELETE \\\n  --url {{API_BASE_URL}}/comments/9149d7d7-e191-41d5-a263-cfccbd775f0b.json \\\n  --header 'Authorization: Bearer {{JWT_TOKEN}}'\n"
      - lang: JavaScript
        source: "const url = '{{API_BASE_URL}}/comments/9149d7d7-e191-41d5-a263-cfccbd775f0b.json';\nconst options = {method: 'DELETE', headers: {Authorization: 'Bearer {{JWT_TOKEN}}'}};\n\ntry {\n  const response = await fetch(url, options);\n  const data = await response.json();\n  console.log(data);\n} catch (error) {\n  console.error(error);\n}\n"
      - lang: PHP
        source: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"{{API_BASE_URL}}/comments/9149d7d7-e191-41d5-a263-cfccbd775f0b.json\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"DELETE\",\n  CURLOPT_HTTPHEADER => [\n    \"Authorization: Bearer {{JWT_TOKEN}}\"\n  ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}\n"
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/commentId'
      responses:
        '200':
          $ref: '#/components/responses/nullBody'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/authenticationRequired'
        '404':
          $ref: '#/components/responses/notFound'
  /comments/resource/{resourceId}.json:
    get:
      summary: Get comments for a resource.
      operationId: indexComments
      security:
      - bearerHttpAuthentication: []
      x-codeSamples:
      - lang: cURL
        source: "curl --request GET \\\n  --url {{API_BASE_URL}}/comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json \\\n  --header 'Authorization: Bearer {{JWT_TOKEN}}'\n"
      - lang: JavaScript
        source: "const url = '{{API_BASE_URL}}/comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json';\nconst options = {method: 'GET', headers: {Authorization: 'Bearer {{JWT_TOKEN}}'}};\n\ntry {\n  const response = await fetch(url, options);\n  const data = await response.json();\n  console.log(data);\n} catch (error) {\n  console.error(error);\n}\n"
      - lang: PHP
        source: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"{{API_BASE_URL}}/comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"GET\",\n  CURLOPT_HTTPHEADER => [\n    \"Authorization: Bearer {{JWT_TOKEN}}\"\n  ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}\n"
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/resourceId'
      - $ref: '#/components/parameters/containCreator'
      - $ref: '#/components/parameters/containModifier'
      responses:
        '200':
          $ref: '#/components/responses/index'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/authenticationRequired'
        '404':
          $ref: '#/components/responses/notFound'
    post:
      summary: Add a comment.
      operationId: addComment
      security:
      - bearerHttpAuthentication: []
      x-codeSamples:
      - lang: cURL
        source: "curl --request POST \\\n  --url {{API_BASE_URL}}/comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json \\\n  --header 'Authorization: Bearer {{JWT_TOKEN}}' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"content\": \"no comment\"\n  }'\n"
      - lang: JavaScript
        source: "const url = '{{API_BASE_URL}}/comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json';\nconst options = {\n  method: 'POST',\n  headers: {Authorization: 'Bearer {{JWT_TOKEN}}'},\n  body: '{\"content\":\"no comment\"}'\n};\n\ntry {\n  const response = await fetch(url, options);\n  const data = await response.json();\n  console.log(data);\n} catch (error) {\n  console.error(error);\n}\n"
      - lang: PHP
        source: "<?php\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"{{API_BASE_URL}}/comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"POST\",\n  CURLOPT_POSTFIELDS => json_encode([\n    'content' => 'no comment'\n  ]),\n  CURLOPT_HTTPHEADER => [\n    \"Authorization: Bearer {{JWT_TOKEN}}\"\n  ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}\n"
      tags:
      - Comments
      parameters:
      - $ref: '#/components/parameters/resourceId'
      requestBody:
        $ref: '#/components/requestBodies/commentAdd'
      responses:
        '200':
          $ref: '#/components/responses/add'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/authenticationRequired'
        '404':
          $ref: '#/components/responses/notFound'
components:
  schemas:
    commentView:
      type: object
      required:
      - id
      - parent_id
      - foreign_key
      - foreign_model
      - content
      - created
      - modified
      - created_by
      - modified_by
      - user_id
      properties:
        id:
          type: string
          format: uuid
        parent_id:
          type: string
          format: uuid
        foreign_key:
          type: string
          format: uuid
        foreign_model:
          type: string
          enum:
          - Resource
        content:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        created_by:
          type: string
          format: uuid
        modified_by:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        children:
          type: array
          items:
            $ref: '#/components/schemas/commentView'
        modifier:
          $ref: '#/components/schemas/userIndexAndView'
        creator:
          $ref: '#/components/schemas/userIndexAndView'
    groupsUsersIndexAndView:
      type: object
      required:
      - id
      - group_id
      - user_id
      - is_admin
      - created
      properties:
        id:
          type: string
          format: uuid
        group_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        is_admin:
          type: boolean
        created:
          type: string
          format: date-time
        user:
          $ref: '#/components/schemas/userIndexAndView'
    userIndexAndView:
      type: object
      required:
      - id
      - role_id
      - username
      - active
      - deleted
      - created
      - modified
      - disabled
      properties:
        is_mfa_enabled:
          type: boolean
        id:
          type: string
          format: uuid
        role_id:
          type: string
          format: uuid
        username:
          type: string
        active:
          type: boolean
        deleted:
          type: boolean
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        disabled:
          type: string
          format: date-time
          x-nullable: true
        profile:
          type: object
          required:
          - id
          - user_id
          - first_name
          - last_name
          - created
          - modified
          - avatar
          properties:
            id:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            first_name:
              type: string
            last_name:
              type: string
            created:
              type: string
              format: date-time
            modified:
              type: string
              format: date-time
            avatar:
              type: object
              required:
              - url
              properties:
                id:
                  type: string
                  format: uuid
                profile_id:
                  type: string
                  format: uuid
                created:
                  type: string
                  format: date-time
                modified:
                  type: string
                  format: date-time
                url:
                  type: object
                  required:
                  - medium
                  - small
                  properties:
                    medium:
                      type: string
                      format: url
                    small:
                      type: string
                      format: url
        groups_users:
          $ref: '#/components/schemas/groupsUsersIndexAndView'
        gpgkey:
          $ref: '#/components/schemas/gpgkey'
          x-nullable: true
        role:
          $ref: '#/components/schemas/role'
        missing_metadata_key_ids:
          type: array
          items:
            type: string
            format: uuid
        last_logged_in:
          type: string
          format: date-time
          x-nullable: true
    commentAdd:
      allOf:
      - $ref: '#/components/schemas/commentUpdate'
      - type: object
        properties:
          parent_id:
            type: string
            format: uuid
    commentUpdate:
      type: object
      required:
      - content
      properties:
        content:
          type: string
    gpgkey:
      type: object
      required:
      - id
      - user_id
      - armored_key
      - bits
      - uid
      - key_id
      - fingerprint
      - type
      - expires
      - key_created
      - deleted
      - created
      - modified
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        armored_key:
          type: string
        bits:
          type: integer
        uid:
          type: string
        key_id:
          type: string
        fingerprint:
          type: string
        type:
          type: string
          enum:
          - RSA
          - ECC
        expires:
          type: string
          format: date-time
          x-nullable: true
        deleted:
          type: boolean
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    role:
      type: object
      required:
      - id
      - name
      - description
      - created
      - modified
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          enum:
          - admin
          - guest
          - user
        description:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    header:
      type: object
      required:
      - id
      - status
      - servertime
      - action
      - message
      - url
      - code
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - success
          - error
        servertime:
          type: integer
          example: 1720702619
        action:
          type: string
          format: uuid
        message:
          type: string
          example: The operation was successful.
        url:
          type: string
          format: uri
          example: /auth/verify.json
        code:
          type: integer
          example: 200
  requestBodies:
    commentAdd:
      description: The comment you want to add
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/commentAdd'
          examples:
            base:
              value:
                content: no comment
    commentUpdate:
      description: The comment you want to update
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/commentUpdate'
          examples:
            base:
              value:
                content: no comment
  responses:
    nullBody:
      description: Operation is successful.
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                type: 'null'
          examples:
            base:
              value:
                header:
                  id: f7be85c0-afb1-4d8e-a9e1-e05abb0bb71a
                  status: success
                  servertime: 1721727753
                  action: e2aa01a9-84ec-55f8-aaed-24ee23259339
                  message: <SUCCESS MESSAGE>
                  url: <API ENDPOINT URL>
                  code: 200
                body: null
    index:
      description: Operation is successful.
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                type: array
                items:
                  $ref: '#/components/schemas/commentView'
          examples:
            base:
              value:
                header:
                  id: 7ff2828c-1092-4897-8e0a-1dc64ada889f
                  status: success
                  servertime: 1721207029
                  action: 4d0c0996-ce30-4bce-9918-9062ab35c542
                  message: The operation was successful.
                  url: /comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json
                  code: 200
                body:
                - id: 41aca4aa-430c-4b60-a1f1-c0de1b52a1ce
                  parent_id: null
                  foreign_key: 42968631-0c51-4405-9f2d-c6700c5057be
                  foreign_model: Resource
                  content: no comment
                  created: '2024-09-05T14:15:47+00:00'
                  modified: '2024-09-05T14:43:22+00:00'
                  created_by: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
                  modified_by: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
                  user_id: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
                  children: []
    add:
      description: Operation is successful.
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                $ref: '#/components/schemas/commentView'
          examples:
            base:
              value:
                header:
                  id: 7ff2828c-1092-4897-8e0a-1dc64ada889f
                  status: success
                  servertime: 1721207029
                  action: 4d0c0996-ce30-4bce-9918-9062ab35c542
                  message: The comment was successfully added.
                  url: /comments/resource/42968631-0c51-4405-9f2d-c6700c5057be.json
                  code: 200
                body:
                  id: 41aca4aa-430c-4b60-a1f1-c0de1b52a1ce
                  parent_id: null
                  foreign_key: 42968631-0c51-4405-9f2d-c6700c5057be
                  foreign_model: Resource
                  content: no comment
                  created: '2024-09-05T14:15:47+00:00'
                  modified: '2024-09-05T14:43:22+00:00'
                  created_by: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
                  modified_by: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
                  user_id: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
    authenticationRequired:
      description: Authentication required.
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                type: string
          examples:
            base:
              value:
                header:
                  id: f7be85c0-afb1-4d8e-a9e1-e05abb0bb71a
                  status: error
                  servertime: 1721727753
                  action: e2aa01a9-84ec-55f8-aaed-24ee23259339
                  message: Authentication is required to continue.
                  url: <API ENDPOINT URL>
                  code: 401
                body: ''
    badRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                type: string
          examples:
            example:
              value:
                header:
                  id: 7ff2828c-1092-4897-8e0a-1dc64ada889f
                  status: error
                  servertime: 1721207029
                  action: 4d0c0996-ce30-4bce-9918-9062ab35c542
                  message: <ERROR MESSAGE>
                  url: <API ENDPOINT URL>
                  code: 400
                body: ''
    notFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                type: string
          examples:
            example:
              value:
                header:
                  id: 7ff2828c-1092-4897-8e0a-1dc64ada889f
                  status: error
                  servertime: 1721207029
                  action: 4d0c0996-ce30-4bce-9918-9062ab35c542
                  message: The <MODEL> does not exist.
                  url: <API ENDPOINT URL>
                  code: 404
                body: ''
    update:
      description: Operation is successful.
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                $ref: '#/components/schemas/commentView'
          examples:
            base:
              value:
                header:
                  id: 7ff2828c-1092-4897-8e0a-1dc64ada889f
                  status: success
                  servertime: 1721207029
                  action: 4d0c0996-ce30-4bce-9918-9062ab35c542
                  message: The comment was successfully updated.
                  url: /comments/41aca4aa-430c-4b60-a1f1-c0de1b52a1ce.json
                  code: 200
                body:
                  id: 41aca4aa-430c-4b60-a1f1-c0de1b52a1ce
                  parent_id: null
                  foreign_key: 42968631-0c51-4405-9f2d-c6700c5057be
                  foreign_model: Resource
                  content: no comment
                  created: '2024-09-05T14:15:47+00:00'
                  modified: '2024-09-05T14:43:22+00:00'
                  created_by: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
                  modified_by: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
                  user_id: 8bb80df5-700c-48ce-b568-85a60fc3c8f2
  parameters:
    commentId:
      name: commentId
      description: ID for the comment being manipulated.
      in: path
      required: true
      schema:
        type: string
        format: uuid
    containCreator:
      name: contain[creator]
      description: Add creator to response body.
      in: query
      required: false
      schema:
        type: integer
        enum:
        - 1
        - 0
    resourceId:
      name: resourceId
      description: ID for the resource being manipulated.
      in: path
      required: true
      schema:
        type: string
        format: uuid
    containModifier:
      name: contain[modifier]
      description: Add modifier to response body.
      in: query
      required: false
      schema:
        type: integer
        enum:
        - 1
        - 0
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer token using a JWT
      type: http
      scheme: Bearer
      bearerFormat: JWT
    gpgCookieAuthentication:
      description: Session-based authentication. Note that a CSRF token needs to be provided through a header named `X-CSRF-Token`.
      type: apiKey
      in: cookie
      name: passbolt_session