Confluent | the Data Streaming Platform Partition (v3) API

openapi: 3.2.0
info:
  title: Confluent Cloud Partition (v3) API
  version: ''
  x-api-id: 46234552-5833-42eb-ba0f-883ad3f70d2b
  x-audience: external-public
  x-logo:
    url: https://assets.confluent.io/m/1661ef5e4ff82d3d/
  description: '# Introduction


    Note


    This documents the collection of Confluent Cloud APIs.'
servers:
- url: https://api.confluent.cloud
  description: Confluent Cloud API
tags:
- name: Partition (v3)
  description: '![Generally Available](#section/Versioning/API-Lifecycle-Policy)'
paths:
  /kafka/v3/clusters/{cluster_id}/topics/{topic_name}/partitions:
    servers:
    - url: https://pkc-00000.region.provider.confluent.cloud
      x-audience: business-unit-internal
      description: Confluent Cloud REST Endpoint. For example https://pkc-00000.region.provider.confluent.cloud
    parameters:
    - $ref: '#/components/parameters/ClusterId'
    - $ref: '#/components/parameters/TopicName'
    get:
      summary: List Partitions
      operationId: listKafkaPartitions
      description: '![Generally Available](#section/Versioning/API-Lifecycle-Policy)


        Return the list of partitions that belong to the specified topic.'
      tags:
      - Partition (v3)
      security:
      - resource-api-key: []
      - external-access-token: []
      responses:
        '200':
          $ref: '#/components/responses/ListPartitionsResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /kafka/v3/clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}:
    servers:
    - url: https://pkc-00000.region.provider.confluent.cloud
      x-audience: business-unit-internal
      description: Confluent Cloud REST Endpoint. For example https://pkc-00000.region.provider.confluent.cloud
    parameters:
    - $ref: '#/components/parameters/ClusterId'
    - $ref: '#/components/parameters/TopicName'
    - $ref: '#/components/parameters/PartitionId'
    get:
      summary: Get Partition
      operationId: getKafkaPartition
      description: '![Generally Available](#section/Versioning/API-Lifecycle-Policy)


        Return the partition with the given `partition_id`.'
      tags:
      - Partition (v3)
      security:
      - resource-api-key: []
      - external-access-token: []
      responses:
        '200':
          $ref: '#/components/responses/GetPartitionResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
components:
  parameters:
    TopicName:
      name: topic_name
      description: The topic name.
      in: path
      required: true
      schema:
        type: string
      example: topic-1
    PartitionId:
      name: partition_id
      description: The partition ID.
      in: path
      required: true
      schema:
        type: integer
      example: 0
    ClusterId:
      name: cluster_id
      description: The Kafka cluster ID.
      in: path
      required: true
      schema:
        type: string
      example: cluster-1
  responses:
    GetPartitionResponse:
      description: The partition
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PartitionData'
          example:
            kind: KafkaPartition
            metadata:
              self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1
              resource_name: crn:///kafka=cluster-1/topic=topic-1/partition=1
            cluster_id: cluster-1
            topic_name: topic-1
            partition_id: 1
            leader:
              related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas/1
            replicas:
              related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas
            reassignment:
              related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/reassignment
    ServerErrorResponse:
      description: A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            generic_internal_server_error:
              description: Thrown for generic HTTP 500 errors.
              value:
                error_code: 500
                message: Internal Server Error
    TooManyRequestsErrorResponse:
      description: Indicates that a rate limit threshold has been reached, and the client should retry again later.
      content:
        text/html:
          schema:
            type: string
          example:
            description: A sample response from Jetty's DoSFilter.
            value: <html> <head> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>
    ForbiddenErrorResponse:
      description: Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            kafka_authorization_failed:
              description: Thrown when the caller is not authorized to perform the underlying operation.
              value:
                error_code: 40301
                message: Request is not authorized
    UnauthorizedErrorResponse:
      description: Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            kafka_authentication_failed:
              description: Thrown when using Basic authentication with wrong Kafka credentials.
              value:
                error_code: 40101
                message: Authentication failed
    NotFoundErrorResponse:
      description: Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            endpoint_not_found:
              description: Thrown for generic HTTP 404 errors.
              value:
                error_code: 404
                message: HTTP 404 Not Found
            cluster_not_found:
              description: Thrown when using a non-existing cluster ID.
              value:
                error_code: 404
                message: Cluster my-cluster cannot be found.
            unknown_topic_or_partition:
              description: Thrown when using a non-existing topic name or partition ID.
              value:
                error_code: 40403
                message: This server does not host this topic-partition.
    BadRequestErrorResponse:
      description: Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            bad_request_cannot_deserialize:
              description: Thrown when trying to deserialize an integer from non-integer data.
              value:
                error_code: 400
                message: 'Cannot deserialize value of type `java.lang.Integer` from String "A": not a valid `java.lang.Integer` value'
            unsupported_version_exception:
              description: Thrown when the version of this API is not supported in the underlying Kafka cluster.
              value:
                error_code: 40035
                message: The version of this API is not supported in the underlying Kafka cluster.
    ListPartitionsResponse:
      description: The list of partitions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PartitionDataList'
          example:
            kind: KafkaPartitionList
            metadata:
              self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions
              next: null
            data:
            - kind: KafkaPartition
              metadata:
                self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1
                resource_name: crn:///kafka=cluster-1/topic=topic-1/partition=1
              cluster_id: cluster-1
              topic_name: topic-1
              partition_id: 1
              leader:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas/1
              replicas:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas
              reassignment:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/reassignment
            - kind: KafkaPartition
              metadata:
                self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2
                resource_name: crn:///kafka=cluster-1/topic=topic-1/partition=2
              cluster_id: cluster-1
              topic_name: topic-1
              partition_id: 2
              leader:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/replicas/2
              replicas:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/replicas
              reassignment:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/reassignment
            - kind: KafkaPartition
              metadata:
                self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3
                resource_name: crn:///kafka=cluster-1/topic=topic-1/partition=3
              cluster_id: cluster-1
              topic_name: topic-1
              partition_id: 3
              leader:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3/replicas/3
              replicas:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3/replicas
              reassignment:
                related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3/reassignment
  schemas:
    ResourceCollection:
      type: object
      required:
      - kind
      - metadata
      properties:
        kind:
          type: string
        metadata:
          $ref: '#/components/schemas/ResourceCollectionMetadata'
    PartitionData:
      allOf:
      - $ref: '#/components/schemas/Resource'
      - type: object
        required:
        - cluster_id
        - topic_name
        - partition_id
        - replicas
        - reassignment
        properties:
          cluster_id:
            type: string
          topic_name:
            type: string
          partition_id:
            type: integer
          leader:
            $ref: '#/components/schemas/Relationship'
          replicas:
            $ref: '#/components/schemas/Relationship'
          reassignment:
            $ref: '#/components/schemas/Relationship'
    PartitionDataList:
      allOf:
      - $ref: '#/components/schemas/ResourceCollection'
      - type: object
        required:
        - data
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/PartitionData'
    Error:
      type: object
      description: Describes a particular error encountered while performing an operation.
      properties:
        id:
          description: A unique identifier for this particular occurrence of the problem.
          type: string
          maxLength: 255
        status:
          description: The HTTP status code applicable to this problem, expressed as a string value.
          type: string
        code:
          description: An application-specific error code, expressed as a string value.
          type: string
        title:
          description: A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        source:
          type: object
          description: If this error was caused by a particular part of the API request, the source will point to the query string parameter or request body property that caused it.
          properties:
            pointer:
              description: A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
              type: string
            parameter:
              description: A string indicating which query parameter caused the error.
              type: string
        error_code:
          type: integer
          format: int32
        message:
          type:
          - string
          - 'null'
      additionalProperties: false
    Relationship:
      type: object
      required:
      - related
      properties:
        related:
          type: string
    ResourceCollectionMetadata:
      type: object
      required:
      - self
      properties:
        self:
          type: string
        next:
          type:
          - string
          - 'null'
    Resource:
      type: object
      required:
      - kind
      - metadata
      properties:
        kind:
          type: string
        metadata:
          $ref: '#/components/schemas/ResourceMetadata'
    ResourceMetadata:
      type: object
      required:
      - self
      properties:
        self:
          type: string
        resource_name:
          type:
          - string
          - 'null'
  securitySchemes:
    cloud-api-key:
      type: http
      scheme: basic
      description: Authenticate with Cloud API Keys using HTTP Basic Auth. Treat the Cloud API Key ID as the username and Cloud API Key Secret as the password.
    confluent-sts-access-token:
      type: oauth2
      description: Authenticate with Confluent API using this credentials (JSON Web Tokens) following OAuth 2.0.
      flows:
        clientCredentials:
          tokenUrl: https://api.confluent.cloud/sts/v1/oauth2/token
          scopes: {}
    global-api-key:
      type: http
      scheme: basic
      description: Authenticate with Global API Keys using HTTP Basic Auth. Treat the Global API Key ID as the username and Global API Key Secret as the password.
    resource-api-key:
      type: http
      scheme: basic
      description: Authenticate with resource-specific API Keys using HTTP Basic Auth. Treat the resource-specific API Key ID as the username and resource-specific API Key Secret as the password.
    external-access-token:
      type: oauth2
      description: Authenticate with Confluent API using this credentials (JSON Web Tokens) following OAuth 2.0.
      flows:
        clientCredentials:
          tokenUrl: https://api.confluent.cloud/sts/v1/oauth2/token
          scopes: {}
    oauth:
      type: oauth2
      description: Authenticate with OAuth 2.0. Currently this is only supported for partner APIs.
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes:
            partner:alter: enables partners to alter entitlements
            partner:create: enables partners to create entitlements and signup on behalf of customers
            partner:delete: enables partners to delete entitlements and organizations
            partner:describe: enables partners to read and list entitlements and organizations
x-tagGroups:
- name: Identity Access Management (v2)
  tags:
  - API Keys (iam/v2)
  - Users (iam/v2)
  - Service Accounts (iam/v2)
  - Invitations (iam/v2)
  - IP Groups (iam/v2)
  - IP Filters (iam/v2)
  - IP Filter Summaries (iam/v2)
  - Role Bindings (iam/v2)
  - Identity Providers (iam/v2)
  - Jwks (iam/v2)
  - Identity Pools (iam/v2)
  - Group Mappings (iam/v2/sso)
  - Certificate Authorities (iam/v2)
  - Certificate Identity Pools (iam/v2)
- name: Org API (v2)
  tags:
  - Environments (org/v2)
  - Organizations (org/v2)
- name: Notifications API (v1)
  tags:
  - Subscriptions (notifications/v1)
  - Integrations (notifications/v1)
  - Notification Types (notifications/v1)
  - Resource Preferences (notifications/v1)
  - Resource Subscriptions (notifications/v1)
  - User Notifications (notifications/v1)
- name: Cluster Mgmt for Kafka (v2)
  tags:
  - Clusters (cmk/v2)
- name: Cluster Mgmt for ksqlDB (v2)
  tags:
  - Clusters (ksqldbcm/v2)
- name: Connect API (v1)
  tags:
  - Connectors (connect/v1)
  - Lifecycle (connect/v1)
  - Status (connect/v1)
  - Managed Connector Plugins (connect/v1)
  - Offsets (connect/v1)
  - Custom Connector Plugins (connect/v1)
  - Presigned Urls (connect/v1)
  - Custom Connector Runtimes (connect/v1)
- name: Connect Artifact Management (v1)
  tags:
  - Connect Artifacts (cam/v1)
  - Presigned Urls (cam/v1)
- name: Kafka API (v3)
  tags:
  - Cluster (v3)
  - Configs (v3)
  - ACL (v3)
  - Consumer Group (v3)
  - Partition (v3)
  - Topic (v3)
  - Records (v3)
  - Cluster Linking (v3)
  - Share Group (v3)
  - Streams Group (v3)
- name: Service Quota API (v1)
  tags:
  - Applied Quotas (service-quota/v1)
  - Scopes (service-quota/v1)
- name: Partner API (v2)
  tags:
  - Entitlements (partner/v2)
  - Organizations (partner/v2)
  - Signup (partner/v2)
- name: Cluster Mgmt for Schema Registry (v2)
  tags:
  - Regions (srcm/v2)
  - Clusters (srcm/v2)
- name: Cluster Mgmt for Schema Registry (v3)
  tags:
  - Clusters (srcm/v3)
- name: Schema Registry API (v1)
  tags:
  - Compatibility (v1)
  - Config (v1)
  - Contexts (v1)
  - Exporters (v1)
  - Modes (v1)
  - Schemas (v1)
  - Subjects (v1)
  - Key Encryption Keys (v1)
  - Data Encryption Keys (v1)
- name: Catalog API (v1)
  tags:
  - Entity (v1)
  - Search (v1)
  - Types (v1)
- name: Stream Sharing API (v1)
  tags:
  - Provider Shared Resources (cdx/v1)
  - Provider Shares (cdx/v1)
  - Consumer Shared Resources (cdx/v1)
  - Consumer Shares (cdx/v1)
  - Shared Tokens (cdx/v1)
  - Opt Ins (cdx/v1)
- name: Networking (v1)
  tags:
  - Networks (networking/v1)
  - Peerings (networking/v1)
  - Transit Gateway Attachments (networking/v1)
  - Private Link Accesses (networking/v1)
  - Network Link Services (networking/v1)
  - Network Link Endpoints (networking/v1)
  - Network Link Service Associations (networking/v1)
  - IP Addresses (networking/v1)
  - Private Link Attachments (networking/v1)
  - Private Link Attachment Connections (networking/v1)
  - DNS Forwarders (networking/v1)
  - Access Points (networking/v1)
  - DNS Records (networking/v1)
  - Gateways (networking/v1)
- name: Security Token Service (v1)
  tags:
  - OAuth Tokens (sts/v1)
- name: Kafka Quota (v1)
  tags:
  - Client Quotas (kafka-quotas/v1)
- name: Bring Your Own Key (BYOK) Management (v1)
  tags:
  - Keys (byok/v1)
- name: Billing API (v1)
  tags:
  - Costs (billing/v1)
- name: Compute Pool Mgmt for Flink (v2)
  tags:
  - Compute Pools (fcpm/v2)
  - Regions (fcpm/v2)
  - Org Compute Pool Configs (fcpm/v2)
- name: SQL API (v1)
  tags:
  - Statements (sql/v1)
  - Statement Results (sql/v1)
  - Statement Exceptions (sql/v1)
  - Connections (sql/v1)
  - Agents (sql/v1)
  - Tools (sql/v1)
  - Materialized Tables (sql/v1)
  - Materialized Table Versions (sql/v1)
- name: Provider Integration Management (v1)
  tags:
  - Integrations (pim/v1)
- name: Provider Integration Management (v2)
  tags:
  - Integrations (pim/v2)
- name: Artifact API (v1)
  tags:
  - Flink Artifacts (artifact/v1)
  - Presigned Urls (artifact/v1)
  - Flink Artifact Versions (artifact/v1)
- name: Custom Code Logging API (v1)
  tags:
  - Custom Code Loggings (ccl/v1)
- name: Tableflow (v1)
  tags:
  - Regions (tableflow/v1)
  - Tableflow Topics (tableflow/v1)
  - Catalog Integrations (tableflow/v1)
- name: Custom Connect Plugin Management (v1)
  tags:
  - Custom Connect Plugins (ccpm/v1)
  - Presigned Urls (ccpm/v1)
  - Custom Connect Plugin Versions (ccpm/v1)
- name: Unified Stream Manager (v1)
  tags:
  - Kafka Clusters (usm/v1)
  - Connect Clusters (usm/v1)
- name: Endpoint (v1)
  tags:
  - Endpoints (endpoint/v1)
- name: Real Time Context Engine (v1)
  tags:
  - Rtce Topics (rtce/v1)
  - Regions (rtce/v1)
- name: Analytics (v1alpha1)
  tags:
  - Statements (query/v1alpha1)