Cumulocity Retention Rules API

openapi: 3.2.0
info:
  version: Latest
  title: Cumulocity Retention rules API
  x-logo:
    url: https://www.cumulocity.com/docs/images/logo-platform.svg
    backgroundColor: '#F8F8F8'
    altText: Cumulocity
    href: https://www.cumulocity.com/api
  description: '# REST implementation


    This section describes the aspects common to all REST-based interfaces of Cumulocity. The interfaces are based on the Hypertext Transfer Protocol 1.1 using HTTPS. ## HTTP usage


    ### Application management


    Cumulocity uses a so-called "application key" to distinguish requests coming from devices and traffic from applications. If you write an application, pass the following header as part of all requests:


    ```markup

    X-Cumulocity-Application-Key:

    ```


    For example, if you registered your application in the Cumulocity Administration application with the key "myapp", your requests should contain the header:


    ```markup

    X-Cumulocity-Application-Key: myapp

    ```


    This makes your application subscribable and billable. If you implement a device, do not pass the key. > **ⓘ Info:** Make sure that you pass the key in **all** requests coming from an application. If you leave out the key,

    > the request will be considered as a device request, and the corresponding device will be marked as "available". ### Limited HTTP clients


    If you use an HTTP client that can only perform GET and POST methods in HTTP, you can emulate the other methods through an additional "X-HTTP-METHOD" header. Simply issue a POST request and add the header, specifying the actual REST method to be executed. For example, to emulate the "PUT" (modify) method, you can use:


    ```http

    POST ... X-HTTP-METHOD: PUT

    ```


    ### Processing mode


    Every update request (PUT, POST, DELETE) executes with a so-called *processing mode*. The processing modes are as follows:


    |Processing mode|Description|

    |---|---|

    |PERSISTENT (default)|Stores data in the Cumulocity database and sends data to the Streaming Analytics engine. Afterwards, Cumulocity returns the result of the request. This is the default mode.|

    |TRANSIENT|Sends data to the Streaming Analytics engine and immediately returns the results asynchronously but does not store data in Cumulocity’s database. This mode saves storage and processing costs and is useful for example when tracking devices in real time without requiring data to be stored.|

    |QUIESCENT|Behaves similar to the persistent mode with the exception that no real-time notifications will be sent.|

    |CEP|Behaves like the transient mode with the exception that no real-time notifications are sent.|


    To explicitly control the processing mode of an update request, you can use the "X-Cumulocity-Processing-Mode" header with a value of either "PERSISTENT", "TRANSIENT", "QUIESCENT" or "CEP":


    ```markup

    X-Cumulocity-Processing-Mode: PERSISTENT

    ```


    > **ⓘ Info:** Events are always delivered to CEP/Apama for all processing modes. This is independent from real-time notifications. ### Authorization


    All requests issued to Cumulocity are subject to authorization. To determine the required permissions, see the "Required role" entries for the individual requests. To learn more about the different permissions and the concept of ownership in Cumulocity, see Getting started > Technical concepts > Security aspects > Access control > Managing roles and assigning permissions in the Cumulocity user documentation. > **⚠️ Important:** In the Cumulocity API, each granular permission is identified by a unique “permission” string, which is prefixed with ROLE_ (for example, ROLE_ALARM_READ, ROLE_INVENTORY_ADMIN). Therefore, permissions are frequently referred to as “roles” throughout the API as well as in the configuration files. For example, the microservice manifest includes a requiredRoles field, which actually expects a permission string. See also the Glossary of the Cumulocity user documentation for the usage of the terms “permission” and “role” in the Cumulocity context. ### Media types


    Each type of data is associated with an own media type. The general format of media types is:


    ```markup

    application/vnd.com.nsn.cumulocity.+json;ver=;charset=UTF-8

    ```


    Each media type contains a parameter `ver` indicating the version of the type.'
servers:
- description: Cumulocity tenant
  url: https://<TENANT_DOMAIN>
security:
- Basic: []
- OAI-Secure: []
- SSO: []
- JWT-IAM: []
tags:
- name: Retention rules
  description: 'It is possible to define rules that make the platform remove certain data. A retention rule shows which data will be deleted. For example, a retention rule with `dataType=EVENT` and `maximumAge=30` removes from the system all events older than 30 days.


    > **ⓘ Info:** The Accept header should be provided in all POST/PUT requests, otherwise an empty response body will be returned.'
paths:
  /retention/retentions:
    post:
      operationId: postRetentionRuleCollectionResource
      x-codegen-resource-name: createRetentionRule
      parameters:
      - $ref: '#/components/parameters/acceptHeader'
      tags:
      - Retention rules
      security:
      - Basic: []
      - OAI-Secure: []
      - SSO: []
      summary: Create a retention rule
      description: 'Create a retention rule on your tenant.


        Required roles


        ROLE_RETENTION_RULE_ADMIN'
      requestBody:
        required: true
        content:
          application/vnd.com.nsn.cumulocity.retentionrule+json:
            example:
              dataType: ALARM
              fragmentType: '*'
              maximumAge: 20
            schema:
              allOf:
              - $ref: '#/components/schemas/retentionRule'
              - required:
                - maximumAge
      x-code-samples:
      - lang: cURL
        source: 'curl --location --request POST "https://<TENANT_DOMAIN>/retention/retentions" \

          --header "Authorization: Basic <AUTHORIZATION>" \

          --header "Accept: application/json" \

          --header "Content-Type: application/json" \

          --data-raw ''<Payload>''

          '
      - lang: C#
        source: 'var client = new RestClient("https://<TENANT_DOMAIN>/retention/retentions");

          client.Timeout = -1;


          var request = new RestRequest(Method.POST);

          request.AddHeader("Authorization", "Basic <AUTHORIZATION>");

          request.AddHeader("Content-Type", "application/json");

          request.AddHeader("Accept", "application/json");

          request.AddParameter("application/json", "<Payload>",  ParameterType.RequestBody);


          IRestResponse response = client.Execute(request);

          Console.WriteLine(response.Content);

          '
      - lang: Java
        source: "Unirest.setTimeouts(0, 0);\nHttpResponse<String> response = Unirest.post(\"https://<TENANT_DOMAIN>/retention/retentions\")\n    .header(\"Authorization\", \"Basic <AUTHORIZATION>\")\n    .header(\"Content-Type\", \"application/json\")\n    .header(\"Accept\", \"application/json\")\n    .body(\"<Payload>\")\n    .asString();\nSystem.out.println(response);\n"
      - lang: Node.js
        source: "var unirest = require(\"unirest\");\nvar req = unirest(\"POST\", \"https://<TENANT_DOMAIN>/retention/retentions\")\n    .headers({\n        \"Authorization\": \"Basic <AUTHORIZATION>\",\n        \"Accept\": \"application/json\",\n        \"Content-Type\": \"application/json\"\n    })\n    .send(JSON.stringify( <Payload> ))\n    .end(function (res) {\n        if (res.error) throw new Error(res.error);\n        console.log(res.raw_body);\n    });\n"
      - lang: Python
        source: "import requests\nimport json\n\nurl = \"https://<TENANT_DOMAIN>/retention/retentions\"\nheaders = {\n  \"Authorization\": \"Basic <AUTHORIZATION>\",\n  \"Accept\": \"application/json\",\n  \"Content-Type\": \"application/json\"\n}\nresponse = requests.request(\"POST\", url, headers=headers, data = json.dumps(<Payload>))\nprint(response.text.encode(\"utf8\"))\n"
      responses:
        '201':
          description: A retention rule was created.
          content:
            application/vnd.com.nsn.cumulocity.retentionrule+json:
              schema:
                $ref: '#/components/schemas/retentionRule'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/operationNotAuthorized'
        '422':
          $ref: '#/components/responses/invalidPayload'
    get:
      operationId: getRetentionRuleCollectionResource
      x-codegen-resource-name: getRetentionRules
      parameters:
      - $ref: '#/components/parameters/queryParam_currentPage'
      - $ref: '#/components/parameters/queryParam_pageSize'
      - $ref: '#/components/parameters/queryParam_withTotalElements'
      - $ref: '#/components/parameters/queryParam_withTotalPages'
      tags:
      - Retention rules
      security:
      - Basic: []
      - OAI-Secure: []
      - SSO: []
      summary: Retrieve all retention rules
      description: 'Retrieve all retention rules on your tenant.


        Required roles


        ROLE_RETENTION_RULE_READ'
      x-code-samples:
      - lang: cURL
        source: 'curl --location --request GET "https://<TENANT_DOMAIN>/retention/retentions" \

          --header "Authorization: Basic <AUTHORIZATION>"

          '
      - lang: C#
        source: 'var client = new RestClient("https://<TENANT_DOMAIN>/retention/retentions");

          client.Timeout = -1;


          var request = new RestRequest(Method.GET);

          request.AddHeader("Authorization", "Basic <AUTHORIZATION>");


          IRestResponse response = client.Execute(request);

          Console.WriteLine(response.Content);

          '
      - lang: Java
        source: "Unirest.setTimeouts(0, 0);\nHttpResponse<String> response = Unirest.get(\"https://<TENANT_DOMAIN>/retention/retentions\")\n    .header(\"Authorization\", \"Basic <AUTHORIZATION>\").asString();\n"
      - lang: Node.js
        source: "var unirest = require(\"unirest\");\nvar req = unirest(\"GET\", \"https://<TENANT_DOMAIN>/retention/retentions\")\n    .headers({\n        \"Authorization\": \"Basic <AUTHORIZATION>\"\n    })\n    .end(function (res) {\n        if (res.error) throw new Error(res.error);\n        console.log(res.raw_body);\n    });\n"
      - lang: Python
        source: "import requests\n\nurl = \"https://<TENANT_DOMAIN>/retention/retentions\"\nheaders = {\n  \"Authorization\": \"Basic <AUTHORIZATION>\"\n}\nresponse = requests.request(\"GET\", url, headers=headers)\nprint(response.text.encode(\"utf8\"))\n"
      responses:
        '200':
          $ref: '#/components/responses/retentionRuleCollectionFound'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/operationNotAuthorized'
  /retention/retentions/{id}:
    parameters:
    - $ref: '#/components/parameters/retentionRuleId'
    get:
      operationId: getRetentionRuleResource
      x-codegen-resource-name: getRetentionRule
      tags:
      - Retention rules
      security:
      - Basic: []
      - OAI-Secure: []
      - SSO: []
      summary: Retrieve a retention rule
      description: 'Retrieve a specific retention rule by a given ID.


        Required roles


        ROLE_RETENTION_RULE_READ'
      x-code-samples:
      - lang: cURL
        source: 'curl --location --request GET "https://<TENANT_DOMAIN>/retention/retentions/{id}" \

          --header "Authorization: Basic <AUTHORIZATION>"

          '
      - lang: C#
        source: 'var client = new RestClient("https://<TENANT_DOMAIN>/retention/retentions/{id}");

          client.Timeout = -1;


          var request = new RestRequest(Method.GET);

          request.AddHeader("Authorization", "Basic <AUTHORIZATION>");


          IRestResponse response = client.Execute(request);

          Console.WriteLine(response.Content);

          '
      - lang: Java
        source: "Unirest.setTimeouts(0, 0);\nHttpResponse<String> response = Unirest.get(\"https://<TENANT_DOMAIN>/retention/retentions/{id}\")\n    .header(\"Authorization\", \"Basic <AUTHORIZATION>\").asString();\n"
      - lang: Node.js
        source: "var unirest = require(\"unirest\");\nvar req = unirest(\"GET\", \"https://<TENANT_DOMAIN>/retention/retentions/{id}\")\n    .headers({\n        \"Authorization\": \"Basic <AUTHORIZATION>\"\n    })\n    .end(function (res) {\n        if (res.error) throw new Error(res.error);\n        console.log(res.raw_body);\n    });\n"
      - lang: Python
        source: "import requests\n\nurl = \"https://<TENANT_DOMAIN>/retention/retentions/{id}\"\nheaders = {\n  \"Authorization\": \"Basic <AUTHORIZATION>\"\n}\nresponse = requests.request(\"GET\", url, headers=headers)\nprint(response.text.encode(\"utf8\"))\n"
      responses:
        '200':
          $ref: '#/components/responses/retentionRuleFound'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/operationNotAuthorized'
        '404':
          $ref: '#/components/responses/retentionRuleNotFound'
    put:
      operationId: putRetentionRuleResource
      x-codegen-resource-name: updateRetentionRule
      parameters:
      - $ref: '#/components/parameters/acceptHeader'
      tags:
      - Retention rules
      security:
      - Basic: []
      - OAI-Secure: []
      - SSO: []
      summary: Update a retention rule
      description: 'Update a specific retention rule by a given ID.


        Required roles


        ROLE_RETENTION_RULE_ADMIN AND (the rule is editable OR it''s the tenant management)'
      requestBody:
        required: true
        content:
          application/vnd.com.nsn.cumulocity.retentionrule+json:
            example:
              dataType: ALARM
              maximumAge: 20
            schema:
              $ref: '#/components/schemas/retentionRule'
      x-code-samples:
      - lang: cURL
        source: 'curl --location --request PUT "https://<TENANT_DOMAIN>/retention/retentions/{id}" \

          --header "Authorization: Basic <AUTHORIZATION>" \

          --header "Accept: application/json" \

          --header "Content-Type: application/json" \

          --data-raw ''<Payload>''

          '
      - lang: C#
        source: 'var client = new RestClient("https://<TENANT_DOMAIN>/retention/retentions/{id}");

          client.Timeout = -1;


          var request = new RestRequest(Method.PUT);

          request.AddHeader("Authorization", "Basic <AUTHORIZATION>");

          request.AddHeader("Content-Type", "application/json");

          request.AddHeader("Accept", "application/json");

          request.AddParameter("application/json", "<Payload>",  ParameterType.RequestBody);


          IRestResponse response = client.Execute(request);

          Console.WriteLine(response.Content);

          '
      - lang: Java
        source: "Unirest.setTimeouts(0, 0);\nHttpResponse<String> response = Unirest.put(\"https://<TENANT_DOMAIN>/retention/retentions/{id}\")\n    .header(\"Authorization\", \"Basic <AUTHORIZATION>\")\n    .header(\"Content-Type\", \"application/json\")\n    .header(\"Accept\", \"application/json\")\n    .body(\"<Payload>\")\n    .asString();\nSystem.out.println(response);\n"
      - lang: Node.js
        source: "var unirest = require(\"unirest\");\nvar req = unirest(\"PUT\", \"https://<TENANT_DOMAIN>/retention/retentions/{id}\")\n    .headers({\n        \"Authorization\": \"Basic <AUTHORIZATION>\",\n        \"Accept\": \"application/json\",\n        \"Content-Type\": \"application/json\"\n    })\n    .send(JSON.stringify( <Payload> ))\n    .end(function (res) {\n        if (res.error) throw new Error(res.error);\n        console.log(res.raw_body);\n    });\n"
      - lang: Python
        source: "import requests\nimport json\n\nurl = \"https://<TENANT_DOMAIN>/retention/retentions/{id}\"\nheaders = {\n  \"Authorization\": \"Basic <AUTHORIZATION>\",\n  \"Accept\": \"application/json\",\n  \"Content-Type\": \"application/json\"\n}\nresponse = requests.request(\"PUT\", url, headers=headers, json.dumps(<Payload>))\nprint(response.text.encode(\"utf8\"))\n"
      responses:
        '200':
          description: A retention rule was updated.
          content:
            application/vnd.com.nsn.cumulocity.retentionrule+json:
              schema:
                $ref: '#/components/schemas/retentionRule'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/operationNotAuthorized'
        '404':
          $ref: '#/components/responses/retentionRuleNotFound'
        '422':
          $ref: '#/components/responses/invalidPayload'
    delete:
      operationId: deleteRetentionRuleResource
      x-codegen-resource-name: deleteRetentionRule
      tags:
      - Retention rules
      security:
      - Basic: []
      - OAI-Secure: []
      - SSO: []
      summary: Remove a retention rule
      description: 'Remove a specific retention rule by a given ID.


        Required roles


        ROLE_RETENTION_RULE_ADMIN AND the rule is editable'
      x-code-samples:
      - lang: cURL
        source: 'curl --location --request DELETE "https://<TENANT_DOMAIN>/retention/retentions/{id}" \

          --header "Authorization: Basic <AUTHORIZATION>"

          '
      - lang: C#
        source: 'var client = new RestClient("https://<TENANT_DOMAIN>/retention/retentions/{id}");

          client.Timeout = -1;


          var request = new RestRequest(Method.DELETE);

          request.AddHeader("Authorization", "Basic <AUTHORIZATION>");


          IRestResponse response = client.Execute(request);

          Console.WriteLine(response.Content);

          '
      - lang: Java
        source: "Unirest.setTimeouts(0, 0);\nHttpResponse<String> response = Unirest.delete(\"https://<TENANT_DOMAIN>/retention/retentions/{id}\")\n    .header(\"Authorization\", \"Basic <AUTHORIZATION>\").asString();\nSystem.out.println(response);\n"
      - lang: Node.js
        source: "var unirest = require(\"unirest\");\nvar req = unirest(\"DELETE\", \"https://<TENANT_DOMAIN>/retention/retentions/{id}\")\n    .headers({\n        \"Authorization\": \"Basic <AUTHORIZATION>\"\n    })\n    .end(function (res) {\n        if (res.error) throw new Error(res.error);\n        console.log(res.raw_body);\n    });\n"
      - lang: Python
        source: "import requests\n\nurl = \"https://<TENANT_DOMAIN>/retention/retentions/{id}\"\nheaders = {\n  \"Authorization\": \"Basic <AUTHORIZATION>\"\n}\nresponse = requests.request(\"DELETE\", url, headers=headers)\nprint(response.text.encode(\"utf8\"))\n"
      responses:
        '204':
          description: A retention rule was removed.
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/operationNotAuthorized'
        '404':
          $ref: '#/components/responses/retentionRuleNotFound'
components:
  responses:
    retentionRuleFound:
      description: The request has succeeded and the retention rule is sent in the response.
      content:
        application/vnd.com.nsn.cumulocity.retentionrule+json:
          schema:
            $ref: '#/components/schemas/retentionRule'
    invalidPayload:
      description: Unprocessable Entity – invalid payload.
    retentionRuleCollectionFound:
      description: The request has succeeded and all retention rules are sent in the response.
      content:
        application/vnd.com.nsn.cumulocity.retentionrulecollection+json:
          schema:
            $ref: '#/components/schemas/RetentionRuleCollection'
    unauthorizedError:
      description: Authentication information is missing or invalid.
      content:
        application/vnd.com.nsn.cumulocity.error+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: security/Unauthorized
            message: 'Invalid credentials! : Bad credentials'
            info: https://www.cumulocity.com/guides/reference-guide/#error_reporting
    operationNotAuthorized:
      description: Not authorized to perform this operation.
    retentionRuleNotFound:
      description: Retention rule not found.
      content:
        application/vnd.com.nsn.cumulocity.error+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: retention/Not Found
            message: Retention rule not found
            info: https://www.cumulocity.com/guides/reference-guide/#error_reporting
  schemas:
    desc_self:
      title: SelfURL
      description: A URL linking to this resource.
      type: string
      format: uri
      readOnly: true
    desc_nextPage:
      title: NextPageURL
      description: A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] to a potential next page of managed objects.
      type: string
      readOnly: true
    retentionRule:
      type: object
      properties:
        dataType:
          description: The data type(s) to which the rule is applied.
          type: string
          enum:
          - ALARM
          - AUDIT
          - BULK_OPERATION
          - EVENT
          - MEASUREMENT
          - OPERATION
          - '*'
          default: '*'
        editable:
          description: Indicates whether the rule is editable or not. It can be updated only by the Management tenant.
          type: boolean
          default: true
        fragmentType:
          description: The fragment type(s) to which the rule is applied. Used by the data types EVENT, MEASUREMENT, OPERATION and BULK_OPERATION.
          type: string
          default: '*'
        id:
          description: Unique identifier of the retention rule.
          type: string
          readOnly: true
        maximumAge:
          description: Maximum age expressed in number of days.
          type: integer
        self:
          $ref: '#/components/schemas/desc_self'
        source:
          description: The source(s) to which the rule is applied. Used by all data types.
          type: string
          default: '*'
        type:
          description: The type(s) to which the rule is applied. Used by the data types ALARM, AUDIT, EVENT and MEASUREMENT.
          type: string
          default: '*'
      example:
        dataType: ALARM
        editable: true
        fragmentType: '*'
        id: '1569'
        maximumAge: 20
        self: https://<TENANT_DOMAIN>/retention/retentions/1569
        source: '*'
        type: '*'
    error:
      type: object
      properties:
        error:
          description: The type of error returned.
          type: string
        message:
          description: A human-readable message providing more details about the error.
          type: string
        info:
          description: A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that identifies the error code reported.
          type: string
    pageStatistics:
      description: Information about paging statistics.
      type: object
      readOnly: true
      properties:
        currentPage:
          description: The current page of the paginated results.
          type: integer
          minimum: 1
          example: 2
        pageSize:
          description: Indicates the number of objects that the collection may contain per page. The upper limit for one page is 2,000 objects.
          type: integer
          minimum: 1
          maximum: 2000
          example: 5
        totalElements:
          description: The total number of results (elements).
          type: integer
          minimum: 0
          example: 12
        totalPages:
          description: 'The total number of paginated results (pages).


            > **&#9432; Info:** This property is returned by default except when an operation retrieves all records where values are between an upper and lower boundary, for example, querying ranges using `dateFrom`–`dateTo`. In such cases, the query parameter `withTotalPages=true` should be used to include the total number of pages (at the expense of slightly slower performance).

            '
          type: integer
          minimum: 0
          example: 3
    RetentionRuleCollection:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/desc_nextPage'
        prev:
          $ref: '#/components/schemas/desc_prevPage'
        retentionRules:
          description: An array containing the results (retention rules) of the request.
          type: array
          items:
            $ref: '#/components/schemas/retentionRule'
        self:
          $ref: '#/components/schemas/desc_self'
        statistics:
          $ref: '#/components/schemas/pageStatistics'
      example:
        prev: https://<TENANT_DOMAIN>/retention/retentions?pageSize=1&currentPage=1
        self: https://<TENANT_DOMAIN>/retention/retentions?pageSize=1&currentPage=2
        next: https://<TENANT_DOMAIN>/retention/retentions?pageSize=1&currentPage=3
        retentionRules:
        - dataType: ALARM
          editable: true
          fragmentType: '*'
          id: '1569'
          maximumAge: 20
          self: https://<TENANT_DOMAIN>/retention/retentions/1569
          source: '*'
          type: '*'
        statistics:
          totalPages: 3
          pageSize: 1
          currentPage: 2
    desc_prevPage:
      title: PreviousPageURL
      description: A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] to a potential previous page of managed objects.
      type: string
      readOnly: true
  parameters:
    queryParam_withTotalElements:
      name: withTotalElements
      in: query
      description: 'When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)).

        > **&#9432; Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds.

        '
      schema:
        type: boolean
        default: false
        example: true
    retentionRuleId:
      name: id
      in: path
      description: Unique identifier of the retention rule.
      required: true
      schema:
        type: string
        minLength: 1
        example: '1569'
    queryParam_withTotalPages:
      name: withTotalPages
      in: query
      description: 'When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)).

        > **&#9432; Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds.

        '
      schema:
        type: boolean
        default: false
        example: true
    queryParam_currentPage:
      name: currentPage
      in: query
      description: The current page of the paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 3
    acceptHeader:
      name: Accept
      in: header
      description: Advertises which content types, expressed as MIME types, the client is able to understand.
      required: false
      schema:
        type: string
        minLength: 1
        example: application/json
    queryParam_pageSize:
      name: pageSize
      in: query
      description: Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects.
      schema:
        type: integer
        minimum: 1
        maximum: 2000
        default: 5
        example: 10
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: 'The authorization header is formed as `Basic <Base64(<tenantID>/<c8yuser>:<password>)>`. For instance, if your tenantID, username and password are **t0071234**, **testuser** and **secret123** respectively, you can generate the Base64 string with the following command:


        ```shell

        $ echo -n t0071234/testuser:secret123 | base64

        ```


        and your authorization header would look like this:


        ```

        "Authorization": "Basic dDAwNzEyMzQvdGVzdHVzZXI6c2VjcmV0MTIz"

        ```

        '
    OAI-Secure:
      type: http
      scheme: bearer
      description: 'This is the recommended authorization method because it provides high security using authorization tokens to prove the identity of the user, and it is the default login mode on creating new tenants. This mode is an enhancement of the previous OAuth Internal authentication (available prior to 10.13.0).


        For more details about OAI-Secure authentication, see [Platform administration > Authentication > Basic settings > Login settings](https://www.cumulocity.com/docs/authentication/basic-settings/#login-settings) in the Cumulocity user documentation.

        '
    SSO:
      type: oauth2
      description: "The login with SSO requires a correct configuration on the [Cumulocity side](https://www.cumulocity.com/docs/authentication/sso/). With the configuration, an additional button is available on the Login page. After clicking the button, the user is redirected to authenticate with the configured authorization server. On successful login, the user is redirected to Cumulocity.\n\nAuthentication details are exchanged using cookies. There are two parts to it, the first is the authentication cookie that is handled automatically by the Cumulocity platform. The second is the XSRF-TOKEN cookie. When a client receives the cookie, it should take the value and put it in the X-XSRF-TOKEN request header in all subsequent requests.\n\nThe flow of authenticating with authentication code grant is as follows:\n\n![Authentication flow](images/oauth-simple-flow.png)\n\nThe first request executed by the browser is:\n\n```http\nGET /tenant/loginOptions\nHost: https://<TENANT_DOMAIN>\nAccept: application/vnd.com.nsn.cumulocity.loginoptioncollection+json\n```\n\nResponse sample:\n\n```json\n{\n    \"loginOptions\": [\n        {\n            \"buttonName\": \"Login with oauth\",\n            \"grantType\": \"<AUTHORIZATION_CODE>\",\n            \"initRequest\": \"https://<TENANT_DOMAIN>/tenant/oauth?response_type=code&tenant_id=<TENANT_ID>\",\n            \"self\": \"https://<TENANT_DOMAIN>/tenant/loginOptions/oauth2\",\n            \"type\": \"oauth2\"\n        },\n        ...\n    ],\n    \"self\": \"http://<TENANT_DOMAIN>/tenant/loginOptions/\"\n}\n```\n\nThe browser must invoke the request provided in the initRequest parameter.\n\nThe initRequest initiates the redirect, in which the user is prompted for credentials. After successful login, the user is redirected back to the browser, where it must capture the code request parameter. Then the request to exchange the code for the token is as follows:\n\n```http\nPOST /tenant/oauth?grant_type=authorization_code&code=<CODE>\nHost: https://<TENANT_DOMAIN>\n```\n\nA successful response will have no body but the following response headers:\n\n```\nSet-Cookie: authorization=<TOKEN>;\nSet-Cookie: XSRF-TOKEN=<XSRF-TOKEN>;\n```\n\nThe authorization cookie is valid for two weeks.\n"
      flows:
        clientCredentials:
          tokenUrl: /tenant/oauth?grant_type=authorization_code&code=<CODE>
          scopes: {}
    JWT-IAM:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'This kind of authentication substitutes the JWT authentication with OAuth2 access tokens from your Identity and Access Management (IAM).

        You can enable this in the [SSO configuration](https://www.cumulocity.com/docs/authentication/sso/).


        The HTTP header must include:


        ```

        "Authorization": "Bearer <Access token>"

        ```


        When a request with a bearer token in the header is received, Cumulocity checks if the access token is from your IAM (that is, if authentication is enabled in your SSO configuration), and verifies the authenticity of

        the token remotely against the IAM.

        '
x-tagGroups:
- name: Platform
  tags:
  - Platform API
- name: Alarms
  tags:
  - Alarm API
  - Alarm notification API
  - Alarms
- name: Applications
  tags:
  - Application API
  - Applications
  - Application versions
  - Application binaries
  - Bootstrap user
  - Current application
- name: Audits
  tags:
  - Audit API
  - Audits
- name: Device control
  tags:
  - Device control API
  - Device control notification API
  - Operations
  - Bulk operations
  - Device credentials


# --- truncated at 32 KB (33 KB total) ---
# Full source: https://artifacts.apis.io/cumulocity/openapi/cumulocity-retention-rules-api-openapi.yml