> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Update session retention settings

> Turn the after-closing and after-inactivity retention rules on or off, set their thresholds from 15 to 120 days, and choose what an erasure also removes.

Needs the `session-retention:write` scope. Send only the fields you want to change; omitted fields
keep their current values. Each threshold is a whole number of days from 15 to 120. The response is
the saved settings.

> [!WARNING]
>
> Erasure is permanent. Turning a rule on, or lowering a threshold, starts erasing matching
> sessions within about 30 minutes, and the API doesn't ask for confirmation. Read the current
> settings with [Get settings](https://docs.open.cx/api-reference/session-retention/get-settings.md) before you change
> them.

Every change is recorded in the [audit log](https://docs.open.cx/security/audit-logs.md). Erased sessions are closed for
good, and their history gets a `session_erased_by_system_due_to_retention_threshold` event; see
[List history](https://docs.open.cx/api-reference/chat-sessions/list_history.md#retention-erasures).

For what each rule and setting does, see [Session retention](https://docs.open.cx/security/session-retention.md).


## OpenAPI

````yaml put /session-retention/settings
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /session-retention/settings:
    put:
      tags:
        - Session retention
      summary: Update session retention settings
      description: >-
        Partial update: omit a field to leave it unchanged. Turning a rule on or
        lowering its threshold permanently erases every session that already
        matches, starting within about 30 minutes. Erased content cannot be
        recovered. Every change is recorded in the audit log. Returns the saved
        settings.
      operationId: updateSessionRetentionSettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSessionRetentionSettingsDto'
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionRetentionSettingsDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    UpdateSessionRetentionSettingsDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/UpdateSessionRetentionSettingsDtoInput'
      type: object
      properties:
        after_closing_enabled:
          type: boolean
          description: >-
            Erase a session once it has stayed closed for `after_closing_days`
            days. A reopened session never matches.
        after_closing_days:
          type: integer
          minimum: 15
          maximum: 120
          description: >-
            Days after a session is closed before it is erased: a whole number
            from 15 to 120.
        after_inactivity_enabled:
          type: boolean
          description: >-
            Erase a session once it has had no activity for
            `after_inactivity_days` days. An open session is closed first.
        after_inactivity_days:
          type: integer
          minimum: 15
          maximum: 120
          description: >-
            Days without activity before a session is erased: a whole number
            from 15 to 120.
        erase_title:
          type: boolean
          description: Erasure also replaces the session title.
        erase_custom_data:
          type: boolean
          description: Erasure also empties the session custom data.
        erase_ai_traces:
          type: boolean
          description: Erasure also removes the AI traces recorded for the session.
        erase_summary:
          type: boolean
          description: Erasure also clears the session summary.
        anonymize_contact:
          type: boolean
          description: Erasure also removes every link between the session and its contact.
    SessionRetentionSettingsDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/SessionRetentionSettingsDto'
      type: object
      properties:
        after_closing_enabled:
          type: boolean
          description: >-
            Erase a session once it has stayed closed for `after_closing_days`
            days. A reopened session never matches.
        after_closing_days:
          type: integer
          minimum: 15
          maximum: 120
          description: >-
            Days after a session is closed before it is erased: a whole number
            from 15 to 120.
        after_inactivity_enabled:
          type: boolean
          description: >-
            Erase a session once it has had no activity for
            `after_inactivity_days` days. An open session is closed first.
        after_inactivity_days:
          type: integer
          minimum: 15
          maximum: 120
          description: >-
            Days without activity before a session is erased: a whole number
            from 15 to 120.
        erase_title:
          type: boolean
          description: Erasure also replaces the session title.
        erase_custom_data:
          type: boolean
          description: Erasure also empties the session custom data.
        erase_ai_traces:
          type: boolean
          description: Erasure also removes the AI traces recorded for the session.
        erase_summary:
          type: boolean
          description: Erasure also clears the session summary.
        anonymize_contact:
          type: boolean
          description: Erasure also removes every link between the session and its contact.
      required:
        - after_closing_enabled
        - after_closing_days
        - after_inactivity_enabled
        - after_inactivity_days
        - erase_title
        - erase_custom_data
        - erase_ai_traces
        - erase_summary
        - anonymize_contact
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.