---
title: "PUT /gateway/v2/topic-view"
method: PUT
path: "/gateway/v2/topic-view"
tags: ["cli_topic-view_gateway_v2_13"]
---

# PUT /gateway/v2/topic-view

`PUT /gateway/v2/topic-view`

## Request

- Base URL: `https://developers.conduktor.io` (the document declares no server; this is the origin it was published from)
- URL: `https://developers.conduktor.io/gateway/v2/topic-view`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/conduktor/apis/conduktor-gateway-api/docs/gateway/v2/topic-view/put.ts> (a function with typed inputs; its response is checked against the schema)

[![Generally Available](https://img.shields.io/badge/Lifecycle-Generally%20Available-blue)](#tag/Versioning)

Upsert a topic view in a virtual cluster.

## Query parameters

- `dryMode` boolean

## Request body

- TopicView
  - `kind` string, required: The kind of the topic view
  - `apiVersion` string, required: The api version of the topic view
  - `metadata` TopicViewMetadata, required: The metadata of the topic view
    - `name` string, ^[a-zA-Z0-9._-]+$, required: The name of the topic view (virtual topic name that clients will use)
    - `vCluster` string, ^[a-zA-Z0-9._-]+$: The virtual cluster of the topic view (default: `passthrough`)
  - `spec` TopicViewSpec, required: The specification of the topic view
    - `transformation` Transformation, required
      - `type` string, required: The type of transformation
      - `statement` string, required: The SQL SELECT statement defining the topic filter. The FROM clause specifies the physical topic, and the WHERE clause defines the filter predicate.
    - `onError` OnErrorStrategy, required: The error-handling strategy for records that fail the filter. Required. `type` must be `DROP` (drop failing records) or `FAIL_FETCH` (fail the whole fetch).
      - `type` 'DROP' | 'FAIL_FETCH', required: The error-handling strategy type. Must be DROP or FAIL_FETCH.
    - `physicalCluster` string: The physical kafka cluster hosting the source topic referenced by the SQL `FROM` clause. Optional: when omitted, the source resolves to the main cluster.
    - `schemaRegistryConnectionName` string: Schema-registry connection (an externalConnections entry) used to decode Avro/Protobuf/JSON-Schema records for this view. Omit for raw-JSON views.

## Response `200`

- ApplyResultTopicView
  - `resource` TopicView, required
    - `kind` string, required: The kind of the topic view
    - `apiVersion` string, required: The api version of the topic view
    - `metadata` TopicViewMetadata, required: The metadata of the topic view
      - `name` string, ^[a-zA-Z0-9._-]+$, required: The name of the topic view (virtual topic name that clients will use)
      - `vCluster` string, ^[a-zA-Z0-9._-]+$: The virtual cluster of the topic view (default: `passthrough`)
    - `spec` TopicViewSpec, required: The specification of the topic view
      - `transformation` Transformation, required
        - `type` string, required: The type of transformation
        - `statement` string, required: The SQL SELECT statement defining the topic filter. The FROM clause specifies the physical topic, and the WHERE clause defines the filter predicate.
      - `onError` OnErrorStrategy, required: The error-handling strategy for records that fail the filter. Required. `type` must be `DROP` (drop failing records) or `FAIL_FETCH` (fail the whole fetch).
        - `type` 'DROP' | 'FAIL_FETCH', required: The error-handling strategy type. Must be DROP or FAIL_FETCH.
      - `physicalCluster` string: The physical kafka cluster hosting the source topic referenced by the SQL `FROM` clause. Optional: when omitted, the source resolves to the main cluster.
      - `schemaRegistryConnectionName` string: Schema-registry connection (an externalConnections entry) used to decode Avro/Protobuf/JSON-Schema records for this view. Omit for raw-JSON views.
  - `upsertResult` 'Created' | 'NotChanged' | 'Updated', required: The result of the upsert operation (created, updated, not changed)

## Other responses

- `400`: The request is not valid
- `401`: The given credentials are not valid
- `403`: The required feature is not included in the current license
- `404`: The topic view feature is disabled, or the given virtual cluster or physical topic does not exist
- `409`: Business rule violation
- `500`: An unexpected error occurred in the server

---

[API](https://skmtc.dev/conduktor/apis/conduktor-gateway-api.md) - [All operations](https://skmtc.dev/conduktor/apis/conduktor-gateway-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conduktor/apis/conduktor-gateway-api/revisions/73ad742aa630?raw)