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