Azure Event Hubs Messaging API

asyncapi: 2.6.0
info:
  title: Azure Event Hubs Messaging API
  version: 1.0.0
  description: >-
    Azure Event Hubs is a big data streaming platform and event ingestion
    service that can receive and process millions of events per second. This
    AsyncAPI specification describes the event-driven messaging capabilities
    of Azure Event Hubs, including publishing events to event hubs and
    consuming events from partitions via consumer groups. Event Hubs supports
    AMQP 1.0, Kafka, and HTTPS protocols for both producing and consuming
    events. Events are organized into partitions for parallel processing, and
    consumer groups provide independent views of the event stream.
  contact:
    name: Microsoft Azure Support
    url: https://azure.microsoft.com/en-us/support/
  license:
    name: Microsoft Azure Terms of Service
    url: https://azure.microsoft.com/en-us/support/legal/
  x-logo:
    url: https://azure.microsoft.com/svghandler/event-hubs/
servers:
  amqp:
    url: '{namespaceName}.servicebus.windows.net'
    protocol: amqp
    protocolVersion: '1.0'
    description: >-
      Azure Event Hubs AMQP 1.0 endpoint. AMQP is the primary protocol for
      high-throughput event streaming. Connections use TLS on port 5671.
    variables:
      namespaceName:
        description: The Event Hubs namespace name.
        default: my-namespace
    security:
      - sasToken: []
      - azureAd: []
  kafka:
    url: '{namespaceName}.servicebus.windows.net:9093'
    protocol: kafka
    protocolVersion: '2.0'
    description: >-
      Azure Event Hubs Kafka endpoint. Event Hubs provides a Kafka-compatible
      endpoint that allows existing Kafka applications to connect without code
      changes. Requires SASL/PLAIN authentication over TLS.
    variables:
      namespaceName:
        description: The Event Hubs namespace name.
        default: my-namespace
    security:
      - kafkaSasl: []
  https:
    url: '{namespaceName}.servicebus.windows.net'
    protocol: https
    description: >-
      Azure Event Hubs HTTPS endpoint for sending events via REST API. This
      endpoint supports sending single events, batch events, and
      partition-targeted events.
    variables:
      namespaceName:
        description: The Event Hubs namespace name.
        default: my-namespace
    security:
      - sasToken: []
      - azureAd: []
defaultContentType: application/json
channels:
  '{eventHubName}':
    description: >-
      An event hub channel for publishing and subscribing to events. Events
      sent to this channel are distributed across partitions based on the
      partition key or round-robin if no partition key is specified. Each
      event hub can have up to 32 partitions (configurable at creation time)
      and supports multiple consumer groups for independent consumption.
    parameters:
      eventHubName:
        description: >-
          The name of the event hub. Event hub names must be between 1 and
          256 characters long.
        schema:
          type: string
          minLength: 1
          maxLength: 256
    publish:
      operationId: publishEvent
      summary: Publish event to event hub
      description: >-
        Publishes an event to the specified event hub. The event is
        distributed to a partition based on the partition key if provided, or
        using round-robin distribution. Events are appended to the event
        stream and assigned a sequence number and offset within the partition.
      tags:
        - name: Event Publishing
      bindings:
        amqp:
          is: queue
          exchange:
            type: topic
            vhost: /
          bindingVersion: 0.3.0
        kafka:
          groupId:
            type: string
          bindingVersion: 0.5.0
        http:
          type: request
          method: POST
          bindingVersion: 0.3.0
      message:
        oneOf:
          - $ref: '#/components/messages/EventMessage'
          - $ref: '#/components/messages/BatchEventMessage'
    subscribe:
      operationId: consumeEvent
      summary: Consume events from event hub
      description: >-
        Consumes events from the specified event hub. Events are read from
        partitions via consumer groups. Each consumer group maintains its
        own offset position in each partition. The default consumer group
        $Default is created automatically. Consumers can read from a specific
        offset, from the beginning, or from the latest event.
      tags:
        - name: Event Consumption
      bindings:
        amqp:
          is: queue
          exchange:
            type: topic
            vhost: /
          bindingVersion: 0.3.0
        kafka:
          groupId:
            type: string
          bindingVersion: 0.5.0
      message:
        $ref: '#/components/messages/ReceivedEventMessage'
  '{eventHubName}/partitions/{partitionId}':
    description: >-
      A partition-specific channel for publishing events to a specific
      partition of an event hub. Using partition-targeted publishing gives
      you direct control over which partition receives the event but bypasses
      the load balancing that Event Hubs provides.
    parameters:
      eventHubName:
        description: The name of the event hub.
        schema:
          type: string
          minLength: 1
          maxLength: 256
      partitionId:
        description: >-
          The partition identifier. Partition IDs are zero-based integers
          (e.g., 0, 1, 2, ..., N-1 where N is the partition count).
        schema:
          type: string
    publish:
      operationId: publishPartitionEvent
      summary: Publish event to specific partition
      description: >-
        Publishes an event directly to a specific partition of the event hub.
        This is useful when you need deterministic partition placement but
        should be used carefully as it bypasses partition load balancing.
      tags:
        - name: Event Publishing
      message:
        $ref: '#/components/messages/EventMessage'
    subscribe:
      operationId: consumePartitionEvent
      summary: Consume events from specific partition
      description: >-
        Consumes events from a specific partition of the event hub. The
        consumer can specify the starting position using an offset, sequence
        number, or enqueued time. This is the lowest-level consumption model
        and is typically wrapped by higher-level abstractions like the Event
        Processor.
      tags:
        - name: Event Consumption
      message:
        $ref: '#/components/messages/ReceivedEventMessage'
  '{eventHubName}/publishers/{publisherId}':
    description: >-
      A publisher-specific channel for sending events with a publisher
      identity. Publisher policies enable you to track which publisher sent
      each event and to revoke publishing access for misbehaving publishers.
    parameters:
      eventHubName:
        description: The name of the event hub.
        schema:
          type: string
          minLength: 1
          maxLength: 256
      publisherId:
        description: >-
          The publisher identifier. This is a unique string that identifies
          the event source, often a device ID or application instance ID.
        schema:
          type: string
    publish:
      operationId: publishEventWithPublisherId
      summary: Publish event with publisher identity
      description: >-
        Publishes an event to the event hub with a specified publisher
        identity. This enables per-publisher access control and tracking
        through publisher policies.
      tags:
        - name: Event Publishing
      message:
        $ref: '#/components/messages/EventMessage'
components:
  messages:
    EventMessage:
      name: EventMessage
      title: Event Hub Event
      summary: An event published to Azure Event Hubs.
      description: >-
        Represents an event that is sent to an Azure Event Hub. The event
        body can contain any data format (JSON, Avro, binary, text). Events
        can include custom user properties as metadata and broker properties
        such as partition key for routing.
      contentType: application/json
      headers:
        type: object
        properties:
          Authorization:
            type: string
            description: >-
              SAS token or Azure AD bearer token for authentication.
          Content-Type:
            type: string
            description: The content type of the event body.
            default: application/json
          x-ms-retrypolicy:
            type: string
            description: Set to NoRetry to disable automatic retry.
            enum:
              - NoRetry
        additionalProperties:
          type: string
          description: >-
            Custom user properties as additional headers. These are
            key-value pairs attached to the event as metadata.
      payload:
        $ref: '#/components/schemas/EventData'
      traits:
        - $ref: '#/components/messageTraits/CommonEventProperties'
    BatchEventMessage:
      name: BatchEventMessage
      title: Batch Event Hub Events
      summary: A batch of events published to Azure Event Hubs.
      description: >-
        Represents a batch of events sent to an Azure Event Hub in a single
        request. Batching reduces network overhead by combining multiple
        events into one transmission. Each event in the batch can have its
        own user properties.
      contentType: application/vnd.microsoft.servicebus.json
      payload:
        $ref: '#/components/schemas/BatchEventData'
      traits:
        - $ref: '#/components/messageTraits/CommonEventProperties'
    ReceivedEventMessage:
      name: ReceivedEventMessage
      title: Received Event Hub Event
      summary: An event received from Azure Event Hubs.
      description: >-
        Represents an event consumed from an Azure Event Hub partition. In
        addition to the event body and user properties, received events
        include system properties such as the sequence number, offset, and
        enqueued timestamp assigned by the Event Hubs service.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ReceivedEventData'
      traits:
        - $ref: '#/components/messageTraits/CommonEventProperties'
  schemas:
    EventData:
      type: object
      description: >-
        The event data payload sent to Azure Event Hubs. The body can contain
        any serialized data.
      properties:
        body:
          description: >-
            The body of the event. Can be any valid data format including
            JSON objects, strings, or binary data.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
            - type: array
              items: {}
        properties:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined properties associated with the event.
            These are custom key-value pairs that serve as metadata.
        systemProperties:
          type: object
          description: System-assigned properties for the event.
          properties:
            partitionKey:
              type: string
              description: >-
                The partition key used to route the event to a specific
                partition. Events with the same partition key are guaranteed
                to be sent to the same partition.
            messageId:
              type: string
              description: >-
                A unique identifier for the message set by the producer.
            correlationId:
              type: string
              description: >-
                A correlation identifier for relating events.
            contentType:
              type: string
              description: >-
                The content type of the event body, such as
                application/json.
    BatchEventData:
      type: array
      description: >-
        An array of event messages for batch transmission. Each item
        represents a single event within the batch.
      items:
        type: object
        required:
          - Body
        properties:
          Body:
            description: The body content of the event message.
            oneOf:
              - type: string
              - type: object
                additionalProperties: true
          UserProperties:
            type: object
            additionalProperties:
              type: string
            description: >-
              Custom user properties for this specific event in the batch.
          BrokerProperties:
            type: object
            properties:
              PartitionKey:
                type: string
                description: Partition key for routing.
              MessageId:
                type: string
                description: Message identifier.
              CorrelationId:
                type: string
                description: Correlation identifier.
    ReceivedEventData:
      type: object
      description: >-
        The event data received from an Azure Event Hub partition. Includes
        the original event body, user properties, and system-assigned
        properties.
      properties:
        body:
          description: The body of the received event.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
            - type: array
              items: {}
        properties:
          type: object
          additionalProperties:
            type: string
          description: Application-defined properties from the event producer.
        systemProperties:
          type: object
          description: >-
            System properties assigned by the Event Hubs service when the
            event was enqueued.
          properties:
            sequenceNumber:
              type: integer
              format: int64
              description: >-
                The logical sequence number of the event within the
                partition stream. This is a monotonically increasing number
                assigned when the event is accepted.
            offset:
              type: string
              description: >-
                The offset of the event within the partition. This is a
                string representation of the byte offset in the partition
                log. It can be used to seek to a specific position.
            enqueuedTimeUtc:
              type: string
              format: date-time
              description: >-
                The UTC timestamp when the event was accepted and stored
                in the partition.
            partitionKey:
              type: string
              description: >-
                The partition key used by the producer when sending the
                event.
            x-opt-sequence-number:
              type: integer
              format: int64
              description: >-
                AMQP annotation for the sequence number.
            x-opt-offset:
              type: string
              description: >-
                AMQP annotation for the offset.
            x-opt-enqueued-time:
              type: string
              format: date-time
              description: >-
                AMQP annotation for the enqueued time.
  messageTraits:
    CommonEventProperties:
      headers:
        type: object
        properties:
          x-opt-partition-key:
            type: string
            description: >-
              The partition key for the event. Events with the same
              partition key are sent to the same partition.
          x-opt-sequence-number:
            type: integer
            format: int64
            description: The sequence number assigned by Event Hubs.
          x-opt-offset:
            type: string
            description: The offset of the event within the partition.
          x-opt-enqueued-time:
            type: string
            format: date-time
            description: The time the event was enqueued in the partition.
  securitySchemes:
    sasToken:
      type: httpApiKey
      name: Authorization
      in: header
      description: >-
        Shared Access Signature (SAS) token for authentication. Format:
        SharedAccessSignature sr={namespace}.servicebus.windows.net&sig={signature}&se={expiry}&skn={keyName}
    azureAd:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Azure Active Directory (Azure AD) bearer token (JWT) for
        authentication. The token must be issued for the Event Hubs
        resource.
    kafkaSasl:
      type: plain
      description: >-
        Kafka SASL/PLAIN authentication using the Event Hubs connection
        string. The username is $ConnectionString and the password is the
        Event Hubs connection string.
tags:
  - name: Event Publishing
    description: >-
      Operations for publishing events to Azure Event Hubs, including
      single events, batch events, and partition-targeted events.
  - name: Event Consumption
    description: >-
      Operations for consuming events from Azure Event Hubs partitions
      through consumer groups with configurable offset tracking.