openapi: 3.1.0
info:
  title: Strimzi Kafka Bridge REST API
  description: >-
    The Strimzi Kafka Bridge provides an HTTP/REST interface to Apache Kafka.
    It allows HTTP clients to produce and consume messages, manage consumer
    group subscriptions, and query topic metadata without needing a native
    Kafka client library. The Bridge acts as a protocol translator between
    HTTP and the Kafka protocol. Deploy via the KafkaBridge custom resource.
  version: '0.28.0'
  contact:
    name: Strimzi Community
    url: https://strimzi.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: Strimzi Kafka Bridge Documentation
  url: https://strimzi.io/docs/bridge/latest/
servers:
  - url: http://localhost:8080
    description: Kafka Bridge (default local port)
tags:
  - name: Producer
    description: >-
      Endpoints for producing (sending) messages to Kafka topics via HTTP.
      Supports JSON and binary message formats.
  - name: Consumer
    description: >-
      Endpoints for managing consumer groups and consuming messages from
      Kafka topics via HTTP long-polling.
  - name: Topics
    description: >-
      Endpoints for querying Kafka topic metadata including partition counts,
      offsets, and configuration.
  - name: Seek
    description: >-
      Endpoints for seeking consumer positions within topic partitions.
paths:
  /topics/{topicname}:
    post:
      operationId: send
      summary: Send Messages to Topic
      description: >-
        Sends one or more messages to a Kafka topic. Messages can include
        a key, value, partition, headers, and timestamp. Supports JSON-encoded
        Kafka records.
      tags:
        - Producer
      parameters:
        - name: topicname
          in: path
          required: true
          description: The name of the Kafka topic to send messages to
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/vnd.kafka.json.v2+json:
            schema:
              $ref: '#/components/schemas/ProducerRecordList'
      responses:
        '200':
          description: Messages sent successfully
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/OffsetRecordSentList'
        '404':
          $ref: '#/components/responses/TopicNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /topics/{topicname}/partitions/{partitionid}:
    post:
      operationId: sendToPartition
      summary: Send Messages to Partition
      description: >-
        Sends one or more messages to a specific partition of a Kafka topic.
      tags:
        - Producer
      parameters:
        - name: topicname
          in: path
          required: true
          description: The name of the Kafka topic
          schema:
            type: string
        - name: partitionid
          in: path
          required: true
          description: The partition ID to send messages to
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/vnd.kafka.json.v2+json:
            schema:
              $ref: '#/components/schemas/ProducerRecordList'
      responses:
        '200':
          description: Messages sent successfully
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/OffsetRecordSentList'
        '404':
          $ref: '#/components/responses/TopicNotFound'
  /consumers/{groupid}:
    post:
      operationId: createConsumer
      summary: Create Consumer
      description: >-
        Creates a new Kafka consumer instance in the specified consumer group.
        Returns a base URI for subsequent consumer operations. Consumer
        instances are not thread-safe and must be used by a single client.
      tags:
        - Consumer
      parameters:
        - name: groupid
          in: path
          required: true
          description: The consumer group ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/Consumer'
      responses:
        '200':
          description: Consumer created successfully
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/CreatedConsumer'
        '409':
          $ref: '#/components/responses/Conflict'
  /consumers/{groupid}/instances/{name}:
    delete:
      operationId: deleteConsumer
      summary: Delete Consumer
      description: >-
        Destroys a consumer instance and removes it from the consumer group.
        Any subscriptions and assignments are also removed.
      tags:
        - Consumer
      parameters:
        - name: groupid
          in: path
          required: true
          description: The consumer group ID
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The unique name for the consumer instance
          schema:
            type: string
      responses:
        '204':
          description: Consumer deleted successfully
        '404':
          $ref: '#/components/responses/ConsumerNotFound'
  /consumers/{groupid}/instances/{name}/subscription:
    post:
      operationId: subscribe
      summary: Subscribe to Topics
      description: >-
        Subscribes a consumer to one or more Kafka topics. The consumer will
        receive messages from all partitions of the subscribed topics, with
        partitions assigned by the Kafka broker.
      tags:
        - Consumer
      parameters:
        - name: groupid
          in: path
          required: true
          description: The consumer group ID
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The unique name for the consumer instance
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/Topics'
      responses:
        '204':
          description: Consumer subscribed successfully
        '404':
          $ref: '#/components/responses/ConsumerNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    get:
      operationId: listSubscriptions
      summary: List Topic Subscriptions
      description: >-
        Returns the list of topics to which a consumer is subscribed.
      tags:
        - Consumer
      parameters:
        - name: groupid
          in: path
          required: true
          description: The consumer group ID
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The unique name for the consumer instance
          schema:
            type: string
      responses:
        '200':
          description: The subscriptions list
          content:
            application/vnd.kafka.v2+json:
              schema:
                $ref: '#/components/schemas/SubscribedTopicList'
        '404':
          $ref: '#/components/responses/ConsumerNotFound'
    delete:
      operationId: unsubscribe
      summary: Unsubscribe from Topics
      description: >-
        Removes the current subscription for a consumer, unsubscribing it
        from all topics.
      tags:
        - Consumer
      parameters:
        - name: groupid
          in: path
          required: true
          description: The consumer group ID
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The unique name for the consumer instance
          schema:
            type: string
      responses:
        '204':
          description: Consumer unsubscribed successfully
        '404':
          $ref: '#/components/responses/ConsumerNotFound'
  /consumers/{groupid}/instances/{name}/records:
    get:
      operationId: poll
      summary: Poll for Records
      description: >-
        Fetches records from the topics to which the consumer is subscribed.
        Returns an empty array if no records are available. Calls are
        long-polled — the server waits up to the timeout for records to
        become available.
      tags:
        - Consumer
      parameters:
        - name: groupid
          in: path
          required: true
          description: The consumer group ID
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The unique name for the consumer instance
          schema:
            type: string
        - name: timeout
          in: query
          description: Maximum time in milliseconds to wait for records
          schema:
            type: integer
            default: 1000
        - name: max_bytes
          in: query
          description: Maximum total bytes to return in the response
          schema:
            type: integer
      responses:
        '200':
          description: A list of consumed records
          content:
            application/vnd.kafka.json.v2+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerRecord'
        '404':
          $ref: '#/components/responses/ConsumerNotFound'
  /consumers/{groupid}/instances/{name}/offsets:
    post:
      operationId: commit
      summary: Commit Offsets
      description: >-
        Commits offsets for one or more topic partitions for the consumer.
        Committed offsets are used to resume consumption after a restart.
      tags:
        - Consumer
      parameters:
        - name: groupid
          in: path
          required: true
          description: The consumer group ID
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The unique name for the consumer instance
          schema:
            type: string
      requestBody:
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/OffsetCommitSeekList'
      responses:
        '204':
          description: Offsets committed successfully
        '404':
          $ref: '#/components/responses/ConsumerNotFound'
  /consumers/{groupid}/instances/{name}/positions:
    post:
      operationId: seek
      summary: Seek to Offset
      description: >-
        Overrides the fetch offset for one or more topic partitions, allowing
        the consumer to start reading from a specific position.
      tags:
        - Seek
      parameters:
        - name: groupid
          in: path
          required: true
          description: The consumer group ID
          schema:
            type: string
        - name: name
          in: path
          required: true
          description: The unique name for the consumer instance
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/vnd.kafka.v2+json:
            schema:
              $ref: '#/components/schemas/OffsetCommitSeekList'
      responses:
        '204':
          description: Seek successful
        '404':
          $ref: '#/components/responses/ConsumerNotFound'
  /topics:
    get:
      operationId: listTopics
      summary: List Topics
      description: >-
        Returns a list of all topic names available in the Kafka cluster.
      tags:
        - Topics
      responses:
        '200':
          description: A list of topic names
          content:
            application/vnd.kafka.v2+json:
              schema:
                type: array
                items:
                  type: string
  /topics/{topicname}/partitions:
    get:
      operationId: listPartitions
      summary: List Topic Partitions
      description: >-
        Returns partition metadata for all partitions of a topic, including
        leader, replicas, and in-sync replicas.
      tags:
        - Topics
      parameters:
        - name: topicname
          in: path
          required: true
          description: The name of the Kafka topic
          schema:
            type: string
      responses:
        '200':
          description: Partition metadata
          content:
            application/vnd.kafka.v2+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Partition'
        '404':
          $ref: '#/components/responses/TopicNotFound'
  /healthy:
    get:
      operationId: healthy
      summary: Check Bridge Health
      description: >-
        Returns HTTP 200 if the Bridge is healthy and connected to Kafka.
      tags:
        - Topics
      responses:
        '200':
          description: Bridge is healthy
        '503':
          description: Bridge is not healthy
  /ready:
    get:
      operationId: ready
      summary: Check Bridge Readiness
      description: >-
        Returns HTTP 200 if the Bridge is ready to accept requests.
      tags:
        - Topics
      responses:
        '200':
          description: Bridge is ready
        '503':
          description: Bridge is not ready
components:
  schemas:
    ProducerRecordList:
      type: object
      properties:
        records:
          type: array
          description: List of records to produce
          items:
            $ref: '#/components/schemas/ProducerRecord'
    ProducerRecord:
      type: object
      properties:
        key:
          description: The message key (optional)
        value:
          description: The message value (required)
        partition:
          type: integer
          description: The target partition (optional — if not set, uses partitioner)
        headers:
          type: object
          additionalProperties:
            type: string
          description: Optional message headers
        timestamp:
          type: integer
          description: Message timestamp in milliseconds since epoch
    OffsetRecordSentList:
      type: object
      properties:
        offsets:
          type: array
          items:
            $ref: '#/components/schemas/OffsetRecordSent'
    OffsetRecordSent:
      type: object
      properties:
        partition:
          type: integer
          description: The partition the message was sent to
        offset:
          type: integer
          description: The offset of the produced message
        error_code:
          type: integer
          nullable: true
          description: Error code if the record failed
        error:
          type: string
          nullable: true
          description: Error message if the record failed
    Consumer:
      type: object
      properties:
        name:
          type: string
          description: A unique name for the consumer instance
        auto.offset.reset:
          type: string
          enum: [latest, earliest, none]
          default: latest
          description: What to do when there is no initial offset
        format:
          type: string
          enum: [json, binary]
          default: json
          description: The message format for consuming records
        enable.auto.commit:
          type: boolean
          default: true
          description: If true, offsets are committed automatically
        fetch.min.bytes:
          type: integer
          description: Minimum bytes to return per poll
        consumer.request.timeout.ms:
          type: integer
          description: Maximum time for consumer requests in milliseconds
        isolation.level:
          type: string
          enum: [read_uncommitted, read_committed]
          default: read_uncommitted
    CreatedConsumer:
      type: object
      properties:
        instance_id:
          type: string
          description: The ID of the created consumer instance
        base_uri:
          type: string
          description: The base URI for subsequent requests for this consumer
    Topics:
      type: object
      properties:
        topics:
          type: array
          items:
            type: string
          description: List of topic names to subscribe to
    SubscribedTopicList:
      type: object
      properties:
        topics:
          type: array
          items:
            type: string
    ConsumerRecord:
      type: object
      properties:
        topic:
          type: string
          description: The topic the record was consumed from
        key:
          description: The message key
        value:
          description: The message value
        partition:
          type: integer
          description: The partition the record came from
        offset:
          type: integer
          description: The offset of the record
        headers:
          type: object
          additionalProperties:
            type: string
          description: Message headers
        timestamp:
          type: integer
          description: Message timestamp in milliseconds since epoch
    OffsetCommitSeekList:
      type: object
      properties:
        offsets:
          type: array
          items:
            $ref: '#/components/schemas/OffsetCommitSeek'
    OffsetCommitSeek:
      type: object
      properties:
        topic:
          type: string
          description: The topic name
        partition:
          type: integer
          description: The partition number
        offset:
          type: integer
          description: The offset to commit or seek to
        metadata:
          type: string
          description: Optional metadata string to store with the committed offset
    Partition:
      type: object
      properties:
        partition:
          type: integer
          description: The partition ID
        leader:
          type: integer
          description: The broker ID of the partition leader
        replicas:
          type: array
          items:
            type: object
            properties:
              broker:
                type: integer
              leader:
                type: boolean
              in_sync:
                type: boolean
    Error:
      type: object
      properties:
        error_code:
          type: integer
          description: The error code
        message:
          type: string
          description: A human-readable error message
  responses:
    TopicNotFound:
      description: Topic not found
      content:
        application/vnd.kafka.v2+json:
          schema:
            $ref: '#/components/schemas/Error'
    ConsumerNotFound:
      description: Consumer not found
      content:
        application/vnd.kafka.v2+json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/vnd.kafka.v2+json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict — consumer with the same name already exists
      content:
        application/vnd.kafka.v2+json:
          schema:
            $ref: '#/components/schemas/Error'