Passbolt Metadata types settings API

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) Metadata types settings API
  version: 5.0.0
servers:
- url: https://passbolt.local
  description: API Passbolt
tags:
- name: Metadata types settings
  description: Retrieve information about the resource types settings selected by the administrators
paths:
  /metadata/types/settings.json:
    get:
      summary: Get metadata types settings
      description: Get information from the resource types settings, as selected by the administrators.
      security:
      - bearerHttpAuthentication: []
      operationId: viewMetadataTypesSettings
      x-codeSamples:
      - lang: cURL
        source: "curl --request GET \\\n  --url {{API_BASE_URL}}/metadata/types/settings.json \\\n  --header 'authorization: Bearer {{JWT_TOKEN}}'\n"
      - lang: JavaScript
        source: "const url = '{{API_BASE_URL}}/metadata/types/settings.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\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n  CURLOPT_URL => \"{{API_BASE_URL}}/metadata/types/settings.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:
      - Metadata types settings
      responses:
        '200':
          $ref: '#/components/responses/viewMetadataTypesSettings'
        '401':
          $ref: '#/components/responses/authenticationRequired'
        '404':
          $ref: '#/components/responses/notFound'
    post:
      summary: Upgrade a resource types settings
      description: Administrators can define which resource type is the default
      operationId: upgradeMetadataTypesSettings
      security:
      - bearerHttpAuthentication: []
      x-codeSamples:
      - lang: cURL
        source: 'curl --request POST \

          --url {{API_BASE_URL}}/metadata/types/settings.json \

          --header ''authorization: Bearer {{JWT_TOKEN}}'' \

          --header ''content-type: application/json'' \

          --data ''{

          "default_resource_types": "v5",

          "default_folder_type": "v5",

          "default_tag_type": "v5",

          "default_comment_type": "v5",

          "allow_creation_of_v5_resources": true,

          "allow_creation_of_v5_folders": false,

          "allow_creation_of_v5_tags": false,

          "allow_creation_of_v5_comments": false,

          "allow_creation_of_v4_resources": true,

          "allow_creation_of_v4_folders": true,

          "allow_creation_of_v4_tags": true,

          "allow_creation_of_v4_comments": true,

          "allow_v5_v4_downgrade": false,

          "allow_v4_v5_upgrade": true

          }''

          '
      - lang: JavaScript
        source: "const url = '{{API_BASE_URL}}/metadata/types/settings.json';\nconst options = {\nmethod: 'POST',\nheaders: {\n  authorization: 'Bearer {{JWT_TOKEN}}',\n  'content-type': 'application/json'\n},\nbody: '{\"default_resource_types\":\"v5\",\"default_folder_type\":\"v5\",\"default_tag_type\":\"v5\",\"default_comment_type\":\"v5\",\"allow_creation_of_v5_resources\":true,\"allow_creation_of_v5_folders\":false,\"allow_creation_of_v5_tags\":false,\"allow_creation_of_v5_comments\":false,\"allow_creation_of_v4_resources\":true,\"allow_creation_of_v4_folders\":true,\"allow_creation_of_v4_tags\":true,\"allow_creation_of_v4_comments\":true,\"allow_v5_v4_downgrade\":false,\"allow_v4_v5_upgrade\":true}'\n};\n\n  try {\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\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\nCURLOPT_URL => \"{{API_BASE_URL}}metadata/types/settings.json\",\nCURLOPT_RETURNTRANSFER => true,\nCURLOPT_ENCODING => \"\",\nCURLOPT_MAXREDIRS => 10,\nCURLOPT_TIMEOUT => 30,\nCURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\nCURLOPT_CUSTOMREQUEST => \"POST\",\nCURLOPT_POSTFIELDS => json_encode([\n'default_resource_types' => 'v5',\n'default_folder_type' => 'v5',\n'default_tag_type' => 'v5',\n'default_comment_type' => 'v5',\n'allow_creation_of_v5_resources' => null,\n'allow_creation_of_v5_folders' => null,\n'allow_creation_of_v5_tags' => null,\n'allow_creation_of_v5_comments' => null,\n'allow_creation_of_v4_resources' => null,\n'allow_creation_of_v4_folders' => null,\n'allow_creation_of_v4_tags' => null,\n'allow_creation_of_v4_comments' => null,\n'allow_v5_v4_downgrade' => null,\n'allow_v4_v5_upgrade' => null\n]),\n  CURLOPT_HTTPHEADER => [\n  \"authorization: Bearer {{JWT_TOKEN}}\",\n  \"content-type: application/json\"\n],\n]);\n\n  $response = curl_exec($curl);\n  $err = curl_error($curl);\n\n  curl_close($curl);\n\n  if ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}\n"
      tags:
      - Metadata types settings
      responses:
        '200':
          $ref: '#/components/responses/upgradeMetadataTypesSettings'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/authenticationRequired'
        '403':
          $ref: '#/components/responses/accessRestrictedToAdministrators'
      requestBody:
        $ref: '#/components/requestBodies/upgradeMetadataTypesSettings'
components:
  responses:
    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: ''
    accessRestrictedToAdministrators:
      description: Access restricted
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                type: string
          examples:
            example:
              value:
                header:
                  id: f7be85c0-afb1-4d8e-a9e1-e05abb0bb71a
                  status: error
                  servertime: 1721727753
                  action: e2aa01a9-84ec-55f8-aaed-24ee23259339
                  message: Access restricted to administrators.
                  url: <API ENDPOINT URL>
                  code: 403
                body: ''
    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: ''
    viewMetadataTypesSettings:
      description: Operation is successful.
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                $ref: '#/components/schemas/metadataTypesSettingsIndexAndView'
          examples:
            base:
              value:
                header:
                  id: 0b2c4b00-561b-4d37-a27d-7499dc659b5f
                  status: success
                  servertime: 1740387841
                  action: 11ffb449-cd7d-5dc0-8dae-501ef3c9e8a7
                  message: The operation was successful.
                  url: /metadata/types/settings.json
                  code: 200
                body:
                  default_resource_types: v5
                  default_folder_type: v4
                  default_tag_type: v4
                  default_comment_type: v4
                  allow_creation_of_v5_resources: true
                  allow_creation_of_v5_folders: false
                  allow_creation_of_v5_tags: false
                  allow_creation_of_v5_comments: false
                  allow_creation_of_v4_resources: true
                  allow_creation_of_v4_folders: true
                  allow_creation_of_v4_tags: true
                  allow_creation_of_v4_comments: true
                  allow_v5_v4_downgrade: false
                  allow_v4_v5_upgrade: true
    upgradeMetadataTypesSettings:
      description: Operation is successful.
      content:
        application/json:
          schema:
            type: object
            required:
            - header
            - body
            properties:
              header:
                $ref: '#/components/schemas/header'
              body:
                $ref: '#/components/schemas/metadataTypesSettingsIndexAndView'
          examples:
            base:
              value:
                header:
                  id: 0b2c4b00-561b-4d37-a27d-7499dc659b5f
                  status: success
                  servertime: 1740387841
                  action: 11ffb449-cd7d-5dc0-8dae-501ef3c9e8a7
                  message: The operation was successful.
                  url: /metadata/types/settings.json
                  code: 200
                body:
                  default_resource_types: v5
                  default_folder_type: v4
                  default_tag_type: v4
                  default_comment_type: v4
                  allow_creation_of_v5_resources: true
                  allow_creation_of_v5_folders: false
                  allow_creation_of_v5_tags: false
                  allow_creation_of_v5_comments: false
                  allow_creation_of_v4_resources: true
                  allow_creation_of_v4_folders: true
                  allow_creation_of_v4_tags: true
                  allow_creation_of_v4_comments: true
                  allow_v5_v4_downgrade: false
                  allow_v4_v5_upgrade: true
  schemas:
    metadataTypesSettingsIndexAndView:
      type: object
      required:
      - default_resource_types
      - default_folder_type
      - default_tag_type
      - default_comment_type
      - allow_creation_of_v5_resources
      - allow_creation_of_v5_folders
      - allow_creation_of_v5_tags
      - allow_creation_of_v5_comments
      - allow_creation_of_v4_resources
      - allow_creation_of_v4_folders
      - allow_creation_of_v4_tags
      - allow_creation_of_v4_comments
      - allow_v5_v4_downgrade
      - allow_v4_v5_upgrade
      properties:
        default_resource_types:
          type: string
          enum:
          - v4
          - v5
        default_folder_type:
          type: string
          enum:
          - v4
          - v5
        default_tag_type:
          type: string
          enum:
          - v4
          - v5
        default_comment_type:
          type: string
          enum:
          - v4
          - v5
        allow_creation_of_v5_resources:
          type: boolean
        allow_creation_of_v5_folders:
          type: boolean
        allow_creation_of_v5_tags:
          type: boolean
        allow_creation_of_v5_comments:
          type: boolean
        allow_creation_of_v4_resources:
          type: boolean
        allow_creation_of_v4_folders:
          type: boolean
        allow_creation_of_v4_tags:
          type: boolean
        allow_creation_of_v4_comments:
          type: boolean
        allow_v5_v4_downgrade:
          type: boolean
        allow_v4_v5_upgrade:
          type: boolean
    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:
    upgradeMetadataTypesSettings:
      description: The metadata types settings you want to update
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/metadataTypesSettingsIndexAndView'
          examples:
            base:
              value:
                default_resource_types: v5
                default_folder_type: v4
                default_tag_type: v4
                default_comment_type: v4
                allow_creation_of_v5_resources: true
                allow_creation_of_v5_folders: false
                allow_creation_of_v5_tags: false
                allow_creation_of_v5_comments: false
                allow_creation_of_v4_resources: true
                allow_creation_of_v4_folders: true
                allow_creation_of_v4_tags: true
                allow_creation_of_v4_comments: true
                allow_v5_v4_downgrade: false
                allow_v4_v5_upgrade: true
  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