openapi: 3.0.1
info:
  title: Conduktor API
  description: >-
    Unified specification of the Conduktor REST API surface, covering the Conduktor
    Console API (clusters, certificates, users, groups, RBAC permissions, and
    declarative Self-Service resources) and the Conduktor Gateway API
    (interceptors, virtual clusters, service accounts, and tokens). Console
    endpoints authenticate with an admin-generated Bearer API key; Gateway admin
    endpoints authenticate with Basic auth. Host names are deployment-specific.
  termsOfService: https://www.conduktor.io/terms-and-conditions/
  contact:
    name: Conduktor Support
    url: https://www.conduktor.io/contact/
  version: '1.0'
servers:
  - url: https://{consoleHost}
    description: Conduktor Console deployment host
    variables:
      consoleHost:
        default: localhost:8080
        description: Host and port of your Conduktor Console deployment
  - url: https://{gatewayAdminHost}:8888
    description: Conduktor Gateway admin API host
    variables:
      gatewayAdminHost:
        default: localhost
        description: Host of your Conduktor Gateway admin endpoint
tags:
  - name: Clusters
    description: Manage Kafka cluster registrations in Console
  - name: Certificates
    description: Manage cluster certificates in Console
  - name: Users
    description: Manage organization users in Console
  - name: Groups
    description: Manage groups and RBAC permissions in Console
  - name: Self-Service
    description: Declarative Application, ApplicationInstance, and TopicPolicy resources
  - name: Interceptors
    description: Gateway interceptors for data security, quality, and governance
  - name: Virtual Clusters
    description: Gateway virtual clusters, service accounts, and tokens
paths:
  /public/v1/configs/{cluster}/clusters:
    get:
      operationId: listClusters
      tags:
        - Clusters
      summary: List configured Kafka clusters
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A list of cluster configurations.
          content:
            application/yaml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KafkaCluster'
  /public/v1/clusters:
    get:
      operationId: getClusters
      tags:
        - Clusters
      summary: List registered Kafka clusters
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Registered clusters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KafkaCluster'
    post:
      operationId: upsertCluster
      tags:
        - Clusters
      summary: Create or update a Kafka cluster registration
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KafkaCluster'
      responses:
        '200':
          description: Cluster created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KafkaCluster'
  /public/v1/clusters/{cluster}:
    delete:
      operationId: deleteCluster
      tags:
        - Clusters
      summary: Delete a Kafka cluster registration
      security:
        - bearerAuth: []
      parameters:
        - name: cluster
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Cluster deleted.
  /public/v1/certificates:
    get:
      operationId: listCertificates
      tags:
        - Certificates
      summary: List trusted certificates
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Certificates.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Certificate'
    post:
      operationId: upsertCertificate
      tags:
        - Certificates
      summary: Create or update a trusted certificate
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Certificate'
      responses:
        '200':
          description: Certificate created or updated.
  /public/iam/v2/user:
    get:
      operationId: listUsers
      tags:
        - Users
      summary: List organization users
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /public/iam/v2/user/{userEmail}:
    put:
      operationId: upsertUser
      tags:
        - Users
      summary: Create or update a user and their group membership
      security:
        - bearerAuth: []
      parameters:
        - name: userEmail
          in: path
          required: true
          schema:
            type: string
            format: email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User created or updated.
    delete:
      operationId: deleteUser
      tags:
        - Users
      summary: Delete a user
      security:
        - bearerAuth: []
      parameters:
        - name: userEmail
          in: path
          required: true
          schema:
            type: string
            format: email
      responses:
        '204':
          description: User deleted.
  /public/iam/v2/group:
    get:
      operationId: listGroups
      tags:
        - Groups
      summary: List groups
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Groups.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
  /public/iam/v2/group/{groupName}:
    get:
      operationId: getGroup
      tags:
        - Groups
      summary: Get a group and its permissions
      description: >-
        Retrieves a group with its members and the granular RBAC permissions
        attached to it. Permissions can be scoped to a single cluster or all
        clusters and reference topic patterns and Kafka resource types.
      security:
        - bearerAuth: []
      parameters:
        - name: groupName
          in: path
          required: true
          schema:
            type: string
          example: project-a
      responses:
        '200':
          description: The group and its permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
    put:
      operationId: upsertGroup
      tags:
        - Groups
      summary: Create or update a group and its permissions
      security:
        - bearerAuth: []
      parameters:
        - name: groupName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        '200':
          description: Group created or updated.
    delete:
      operationId: deleteGroup
      tags:
        - Groups
      summary: Delete a group
      security:
        - bearerAuth: []
      parameters:
        - name: groupName
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Group deleted.
  /public/self-serve/v1/application:
    get:
      operationId: listApplications
      tags:
        - Self-Service
      summary: List Self-Service applications
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Applications.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
    put:
      operationId: upsertApplication
      tags:
        - Self-Service
      summary: Create or update a Self-Service Application resource
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
      responses:
        '200':
          description: Application created or updated.
  /public/self-serve/v1/topic-policy:
    put:
      operationId: upsertTopicPolicy
      tags:
        - Self-Service
      summary: Create or update a TopicPolicy resource
      description: >-
        Defines constraints on topic metadata labels and configuration values
        (for example retention.ms or replicationFactor) using OneOf, Range, or
        Match constraints. A TopicPolicy applies once it is referenced from an
        ApplicationInstance via spec.topicPolicyRef.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopicPolicy'
      responses:
        '200':
          description: Topic policy created or updated.
  /gateway/v2/interceptor:
    get:
      operationId: listInterceptors
      tags:
        - Interceptors
      summary: List Gateway interceptors
      security:
        - basicAuth: []
      responses:
        '200':
          description: Interceptors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Interceptor'
    put:
      operationId: upsertInterceptor
      tags:
        - Interceptors
      summary: Create or update a Gateway interceptor
      description: >-
        Creates or updates an interceptor that applies a plugin (for example
        data quality, encryption, safeguard, or chargeback) to Kafka traffic
        flowing through the Gateway, optionally scoped to a virtual cluster,
        group, or username.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Interceptor'
      responses:
        '200':
          description: Interceptor created or updated.
  /gateway/v2/virtual-cluster:
    put:
      operationId: upsertVirtualCluster
      tags:
        - Virtual Clusters
      summary: Create or update a Gateway virtual cluster
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualCluster'
      responses:
        '200':
          description: Virtual cluster created or updated.
  /gateway/v2/virtual-cluster/{name}:
    get:
      operationId: getVirtualCluster
      tags:
        - Virtual Clusters
      summary: Get a virtual cluster
      description: >-
        Returns the virtual cluster definition including its bootstrap address
        and recommended client properties.
      security:
        - basicAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The virtual cluster.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualCluster'
  /gateway/v2/service-account:
    put:
      operationId: upsertServiceAccount
      tags:
        - Virtual Clusters
      summary: Create or update a Gateway service account
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceAccount'
      responses:
        '200':
          description: Service account created or updated.
  /gateway/v2/token:
    post:
      operationId: createToken
      tags:
        - Virtual Clusters
      summary: Generate an authentication token for a service account
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Generated token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Console API key generated by an admin in Settings > API Keys, passed as
        Authorization: Bearer $ADMIN_API_KEY.
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Gateway admin credentials (GATEWAY_ADMIN_API_USERS), passed as HTTP
        Basic authentication to the Gateway admin API.
  schemas:
    KafkaCluster:
      type: object
      properties:
        apiVersion:
          type: string
          example: v1
        kind:
          type: string
          example: KafkaCluster
        metadata:
          type: object
          properties:
            name:
              type: string
        spec:
          type: object
          properties:
            displayName:
              type: string
            bootstrapServers:
              type: string
            color:
              type: string
            ignoreUntrustedCertificate:
              type: boolean
            properties:
              type: object
              additionalProperties:
                type: string
            schemaRegistry:
              type: object
    Certificate:
      type: object
      properties:
        name:
          type: string
        certificate:
          type: string
          description: PEM-encoded certificate chain.
    User:
      type: object
      properties:
        apiVersion:
          type: string
          example: iam/v2
        kind:
          type: string
          example: User
        metadata:
          type: object
          properties:
            name:
              type: string
              format: email
        spec:
          type: object
          properties:
            firstName:
              type: string
            lastName:
              type: string
            permissions:
              type: array
              items:
                $ref: '#/components/schemas/Permission'
    Group:
      type: object
      properties:
        apiVersion:
          type: string
          example: iam/v2
        kind:
          type: string
          example: Group
        metadata:
          type: object
          properties:
            name:
              type: string
        spec:
          type: object
          properties:
            displayName:
              type: string
            description:
              type: string
            externalGroups:
              type: array
              items:
                type: string
            members:
              type: array
              items:
                type: string
            permissions:
              type: array
              items:
                $ref: '#/components/schemas/Permission'
    Permission:
      type: object
      properties:
        resourceType:
          type: string
          description: Kafka resource type the permission applies to.
          example: TOPIC
        name:
          type: string
          description: Topic or resource name or pattern.
          example: project-a-*
        patternType:
          type: string
          enum:
            - LITERAL
            - PREFIXED
        cluster:
          type: string
          description: Cluster id, or omitted/'*' for all clusters.
        permissions:
          type: array
          items:
            type: string
          example:
            - topicViewConfig
            - topicConsume
            - topicProduce
    Application:
      type: object
      properties:
        apiVersion:
          type: string
          example: self-serve/v1
        kind:
          type: string
          example: Application
        metadata:
          type: object
          properties:
            name:
              type: string
        spec:
          type: object
          properties:
            title:
              type: string
            description:
              type: string
            owner:
              type: string
    TopicPolicy:
      type: object
      properties:
        apiVersion:
          type: string
          example: self-serve/v1
        kind:
          type: string
          example: TopicPolicy
        metadata:
          type: object
          properties:
            name:
              type: string
        spec:
          type: object
          properties:
            policies:
              type: object
              description: >-
                Map of metadata labels and topic configuration keys to
                constraints (OneOf, Range, Match, etc.).
              additionalProperties: true
    Interceptor:
      type: object
      properties:
        apiVersion:
          type: string
          example: gateway/v2
        kind:
          type: string
          example: Interceptor
        metadata:
          type: object
          properties:
            name:
              type: string
            scope:
              type: object
              properties:
                vCluster:
                  type: string
                group:
                  type: string
                username:
                  type: string
        spec:
          type: object
          properties:
            comment:
              type: string
            pluginClass:
              type: string
              example: io.conduktor.gateway.interceptor.safeguard.ProduceRateLimitingPolicyPlugin
            priority:
              type: integer
            config:
              type: object
              additionalProperties: true
    VirtualCluster:
      type: object
      properties:
        apiVersion:
          type: string
          example: gateway/v2
        kind:
          type: string
          example: VirtualCluster
        metadata:
          type: object
          properties:
            name:
              type: string
        spec:
          type: object
          properties:
            aclEnabled:
              type: boolean
            superUsers:
              type: array
              items:
                type: string
            bootstrapServers:
              type: string
    ServiceAccount:
      type: object
      properties:
        apiVersion:
          type: string
          example: gateway/v2
        kind:
          type: string
          example: GatewayServiceAccount
        metadata:
          type: object
          properties:
            name:
              type: string
            vCluster:
              type: string
        spec:
          type: object
          properties:
            type:
              type: string
              enum:
                - LOCAL
                - EXTERNAL
            externalNames:
              type: array
              items:
                type: string
    TokenRequest:
      type: object
      properties:
        username:
          type: string
        vCluster:
          type: string
        lifeTimeSeconds:
          type: integer
    TokenResponse:
      type: object
      properties:
        token:
          type: string