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

# Change Kafka topic settings

> Changes a topic's retention and tiered storage; send only the settings to change. Potentially destructive: Kafka deletes messages older than the new retention, and on Artie-managed topics that can drop change events before Artie pipelines read them. Kafka-internal (`__`) topics can't change; on a Managed Kafka cluster neither can Cruise Control's (`strimzi.cruisecontrol.*`), and the cluster must be active (409 otherwise). A change the rules refuse is a 400 that says why.



## OpenAPI

````yaml https://raw.githubusercontent.com/artie-labs/artie-api-spec/refs/heads/master/openapi.yaml post /kafka-clusters/{uuid}/topics/{topic}
openapi: 3.1.0
info:
  description: External API endpoints for Artie
  title: Artie API
  version: v1.0.200
servers:
  - url: https://api.artie.com
security:
  - ApiKey: []
paths:
  /kafka-clusters/{uuid}/topics/{topic}:
    post:
      tags:
        - Kafka clusters
      summary: Change Kafka topic settings
      description: >-
        Changes a topic's retention and tiered storage; send only the settings
        to change. Potentially destructive: Kafka deletes messages older than
        the new retention, and on Artie-managed topics that can drop change
        events before Artie pipelines read them. Kafka-internal (`__`) topics
        can't change; on a Managed Kafka cluster neither can Cruise Control's
        (`strimzi.cruisecontrol.*`), and the cluster must be active (409
        otherwise). A change the rules refuse is a 400 that says why.
      operationId: kafka_topic_settings_update
      parameters:
        - in: path
          name: topic
          required: true
          schema:
            type: string
        - in: path
          name: uuid
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouterUpdateKafkaTopicSettingsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayloadsKafkaTopic'
          description: OK
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '409':
          description: Conflict
        '500':
          description: Internal Server Error
        '502':
          description: Bad Gateway
components:
  schemas:
    RouterUpdateKafkaTopicSettingsRequest:
      properties:
        localRetentionMS:
          description: >-
            How long the tiered topic keeps data on broker disks: from 86400000
            (one day) up to retention. Turning tiered storage on without it uses
            7 days, capped at retention; on a Managed Kafka cluster it uses the
            cluster's days on disk.
          type:
            - 'null'
            - integer
        retentionMS:
          description: >-
            New retention.ms: at least 86400000 (one day); or -1 to keep
            messages forever.
          type:
            - 'null'
            - integer
        tieredStorage:
          description: >-
            off, on or paused. A topic that's on can only be paused, and only a
            paused topic can be turned off, which deletes its data in remote
            storage. Pausing keeps that data readable until retention expires
            it.
          enum:
            - 'off'
            - 'on'
            - paused
            - null
          type:
            - 'null'
            - string
      type: object
    PayloadsKafkaTopic:
      properties:
        artieManaged:
          description: >-
            Whether Artie manages this topic: a CDC topic under the company
            prefix outside the customer namespace, or a Kafka-internal __ topic.
          type: boolean
        localRetentionMS:
          description: >-
            How long a tiered topic keeps data on broker disks
            (local.retention.ms). -2 means the same as retention. Left out when
            the brokers don't report it.
          type: string
        partitionCount:
          type: integer
        retentionMS:
          type: string
        sourceName:
          type: string
        tableName:
          type: string
        tieredStorage:
          $ref: '#/components/schemas/PayloadsKafkaTopicTieredStorage'
        topic:
          type: string
      required:
        - topic
        - retentionMS
        - partitionCount
        - artieManaged
        - tieredStorage
      type: object
    PayloadsKafkaTopicTieredStorage:
      properties:
        canTier:
          description: >-
            Whether tiered storage can be on for this topic. Kafka refuses it on
            compacted topics, and Artie keeps it off Kafka's and Cruise
            Control's own topics and topics whose retention can't be read.
          type: boolean
        state:
          $ref: '#/components/schemas/EnumsKafkaTopicTieredStorageState'
          description: >-
            off, on or paused, from the topic's remote.storage.enable and
            remote.log.copy.disable configs.
        switchOn:
          description: >-
            Whether the topic's tiered storage switch is on. On a Managed Kafka
            cluster it's the topic's own switch, else the cluster's
            tierAllTopics; elsewhere it's whether the topic is tiered (on or
            paused).
          type: boolean
      required:
        - state
        - canTier
        - switchOn
      type: object
    EnumsKafkaTopicTieredStorageState:
      enum:
        - 'off'
        - 'on'
        - paused
      type: string
  securitySchemes:
    ApiKey:
      description: API key passed as a Bearer token in the Authorization header.
      scheme: bearer
      type: http

````

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