Confluent Records (v3) API

openapi: 3.2.0
info:
  title: Confluent Cloud Records (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: Records (v3)
  description: '![Generally Available](#section/Versioning/API-Lifecycle-Policy)'
paths:
  /kafka/v3/clusters/{cluster_id}/topics/{topic_name}/records:
    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'
    post:
      summary: Produce Records
      operationId: produceRecord
      description: '![Generally Available](#section/Versioning/API-Lifecycle-Policy)


        Produce records to the given topic, returning delivery reports for each

        record produced. This API can be used in streaming mode by setting

        "Transfer-Encoding: chunked" header. For as long as the connection is

        kept open, the server will keep accepting records. Records are streamed

        to and from the server as Concatenated JSON. For each record sent to the

        server, the server will asynchronously send back a delivery report, in

        the same order, each with its own error_code. An error_code of 200

        indicates success. The HTTP status code will be HTTP 200 OK as long as

        the connection is successfully established. To identify records that

        have encountered an error, check the error_code of each delivery report.


        Note that the cluster_id is validated only when running in Confluent Cloud.


        This API currently does not support Schema Registry integration. Sending

        schemas is not supported. Only BINARY, JSON, and STRING formats are

        supported.'
      tags:
      - Records (v3)
      security:
      - resource-api-key: []
      - external-access-token: []
      requestBody:
        $ref: '#/components/requestBodies/ProduceRequest'
      responses:
        '200':
          $ref: '#/components/responses/ProduceResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse_ProduceRecords'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '413':
          $ref: '#/components/responses/RequestEntityTooLargeErrorResponse'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeErrorResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntity_ProduceRecord'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
components:
  schemas:
    AnyValue: {}
    ProduceRequest:
      type: object
      properties:
        partition_id:
          type:
          - integer
          - 'null'
          format: int32
        headers:
          type: array
          items:
            $ref: '#/components/schemas/ProduceRequestHeader'
        key:
          $ref: '#/components/schemas/ProduceRequestData'
        value:
          $ref: '#/components/schemas/ProduceRequestData'
        timestamp:
          type:
          - string
          - 'null'
          format: date-time
    ProduceRequestData:
      type:
      - object
      - 'null'
      properties:
        type:
          type: string
          x-extensible-enum:
          - BINARY
          - JSON
          - STRING
        data:
          $ref: '#/components/schemas/AnyValue'
    ProduceRequestHeader:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        value:
          type:
          - string
          - 'null'
          format: byte
    ProduceResponseData:
      type:
      - object
      - 'null'
      required:
      - size
      - type
      properties:
        size:
          type: integer
        type:
          type: string
          x-extensible-enum:
          - BINARY
          - JSON
          - STRING
    ProduceResponse:
      type: object
      required:
      - error_code
      properties:
        error_code:
          type: integer
          format: int32
        message:
          type: string
        cluster_id:
          type: string
        topic_name:
          type: string
        partition_id:
          type: integer
          format: int32
        offset:
          type: integer
          format: int64
        timestamp:
          type:
          - string
          - 'null'
          format: date-time
        key:
          $ref: '#/components/schemas/ProduceResponseData'
        value:
          $ref: '#/components/schemas/ProduceResponseData'
    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
  parameters:
    ClusterId:
      name: cluster_id
      description: The Kafka cluster ID.
      in: path
      required: true
      schema:
        type: string
      example: cluster-1
    TopicName:
      name: topic_name
      description: The topic name.
      in: path
      required: true
      schema:
        type: string
      example: topic-1
  responses:
    UnsupportedMediaTypeErrorResponse:
      description: This implies the client is sending the request payload format in an unsupported format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            produce_records_expects_json:
              description: Thrown by /records API if payload format content-type doesn't match expected application/json
              value:
                error_code: 415
                message: HTTP 415 Unsupported Media Type
    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.
    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
    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
    ProduceResponse:
      description: 'The response containing a delivery report for a record produced to a topic. In streaming mode,

        for each record sent, a separate delivery report will be returned, in the same order,

        each with its own error_code.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProduceResponse'
          examples:
            produce_record_success:
              description: The record was successfully produced to the topic.
              value:
                error_code: 200
                cluster_id: cluster-1
                topic_name: topic-1
                partition_id: 1
                offset: 0
                timestamp: '2021-02-05T19:14:42Z'
                key:
                  type: BINARY
                  size: 7
                value:
                  type: JSON
                  size: 15
            produce_record_bad_binary_data:
              description: Thrown when sending a BINARY value which is not a base64-encoded string.
              value:
                error_code: 400
                message: 'Bad Request: data=1 is not a base64 string.'
    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>
    UnprocessableEntity_ProduceRecord:
      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:
            produce_record_empty_request_body:
              description: Thrown when the request body is empty.
              value:
                error_code: 422
                message: Payload error. Request body is empty. Data is required.
    RequestEntityTooLargeErrorResponse:
      description: This implies the client is sending a request payload that is larger than the maximum message size the server can accept.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            produce_records_expects_json:
              description: Thrown by /records API if payload size exceeds the message max size
              value:
                error_code: 413
                message: The request included a message larger than the maximum message size the server can accept.
    BadRequestErrorResponse_ProduceRecords:
      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:
            header_not_base64_encoded:
              description: Thrown when headers in the produce-record are not base64 encoded.
              value:
                error_code: 400
                message: 'Cannot deserialize value of type `byte[]` from String "": Unexpected end of base64-encoded String: base64 variant ''MIME-NO-LINEFEEDS'' expects padding (one or more ''='' characters) at the end. This Base64Variant might have been incorrectly configured'
  requestBodies:
    ProduceRequest:
      description: A single record to be produced to Kafka. To produce multiple records in the same request, simply concatenate the records. The delivery reports are concatenated in the same order as the records are sent.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProduceRequest'
          examples:
            binary_and_json:
              description: If using type, one of "BINARY", "JSON" or "STRING" is required.
              value:
                partition_id: 1
                headers:
                - name: Header-1
                  value: SGVhZGVyLTE=
                - name: Header-2
                  value: SGVhZGVyLTI=
                key:
                  type: BINARY
                  data: Zm9vYmFy
                value:
                  type: JSON
                  data:
                    foo: bar
                timestamp: '2021-02-05T19:14:42Z'
            string:
              description: If using type, one of "BINARY", "JSON" or "STRING" is required.
              value:
                value:
                  type: STRING
                  data: My message
            empty_value:
              description: key or value can be omitted entirely.
              value:
                key:
                  data: 1000
  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)