Azure Event Hubs API Reference

Introduction

This document provides a comprehensive reference for the Azure Event Hubs API. Event Hubs is a highly scalable data streaming platform and event ingestion service. It can be used for real-time analytics, event-driven applications, and data warehousing.

The API is divided into two main categories:

Management Plane API: Used for creating, deleting, and managing Event Hubs namespaces, event hubs, and related resources.
Data Plane API: Used for sending events to and receiving events from Event Hubs.

Authentication

All API requests must be authenticated. Azure Event Hubs supports two primary authentication mechanisms:

Shared Access Signatures (SAS): Generate SAS tokens with specific permissions for your Event Hubs namespace or entity.
Azure Active Directory (Azure AD): Authenticate using service principals or managed identities for a more robust security model.

Authentication credentials should be passed in the Authorization header of your requests.

Management Operations

Create Namespace

POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}

Creates a new Azure Event Hubs namespace.

Parameters

Name	Type	Description	Required
`subscriptionId`	string	Your Azure Subscription ID.	Yes
`resourceGroupName`	string	The name of the resource group.	Yes
`namespaceName`	string	The desired name for the Event Hubs namespace.	Yes
`location`	string	The Azure region where the namespace will be created.	Yes
`sku`	object	Defines the SKU and capacity for the namespace.	Yes
`sku.name`	string	The SKU name (e.g., Basic, Standard, Premium).	Yes
`sku.capacity`	integer	The throughput units for Standard/Premium, or 1 for Basic.	No

Request Body Example:


{
    "location": "West US",
    "sku": {
        "name": "Standard",
        "capacity": 2
    }
}

Returns: 201 Created with the created namespace resource.

List Namespaces

GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces

Lists all Event Hubs namespaces within a specified resource group.

Parameters

Name	Type	Description	Required
`subscriptionId`	string	Your Azure Subscription ID.	Yes
`resourceGroupName`	string	The name of the resource group.	Yes

Returns: 200 OK with a JSON array of namespace resources.

Delete Namespace

DELETE /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}

Deletes an existing Azure Event Hubs namespace.

Parameters

Name	Type	Description	Required
`subscriptionId`	string	Your Azure Subscription ID.	Yes
`resourceGroupName`	string	The name of the resource group.	Yes
`namespaceName`	string	The name of the namespace to delete.	Yes

Returns: 204 No Content on successful deletion.

Create Event Hub

PUT /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}/eventhubs/{eventHubName}

Creates a new event hub within a specified namespace.

Parameters

Name	Type	Description	Required
`subscriptionId`	string	Your Azure Subscription ID.	Yes
`resourceGroupName`	string	The name of the resource group.	Yes
`namespaceName`	string	The name of the parent namespace.	Yes
`eventHubName`	string	The desired name for the event hub.	Yes
`partitionCount`	integer	The number of partitions for the event hub.	No
`messageRetentionInDays`	integer	The retention period for events in days.	No

Request Body Example:


{
    "properties": {
        "partitionCount": 4,
        "messageRetentionInDays": 7
    }
}

Returns: 201 Created with the created event hub resource.

List Event Hubs

GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}/eventhubs

Lists all event hubs within a specified namespace.

Parameters

Name	Type	Description	Required
`subscriptionId`	string	Your Azure Subscription ID.	Yes
`resourceGroupName`	string	The name of the resource group.	Yes
`namespaceName`	string	The name of the parent namespace.	Yes

Returns: 200 OK with a JSON array of event hub resources.

Delete Event Hub

DELETE /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}/eventhubs/{eventHubName}

Deletes an existing event hub.

Parameters

Name	Type	Description	Required
`subscriptionId`	string	Your Azure Subscription ID.	Yes
`resourceGroupName`	string	The name of the resource group.	Yes
`namespaceName`	string	The name of the parent namespace.	Yes
`eventHubName`	string	The name of the event hub to delete.	Yes

Returns: 204 No Content on successful deletion.

Data Plane Operations

Data plane operations typically use the Event Hubs protocol (AMQP or HTTPS) and often interact with specific endpoints within your namespace.

Send Message

POST https://{namespaceName}.servicebus.windows.net/{eventHubName}/messages?timeout=60

Sends events to an event hub. This is typically done over HTTPS or AMQP. The HTTPS endpoint is shown here for simplicity.

Headers

Name	Description
`Authorization`	SAS token or Azure AD token.
`Content-Type`	`application/vnd.microsoft.eventhub.json` or your custom content type.

Request Body: A JSON array of event objects.


[
    {
        "body": "Hello, Event Hubs!",
        "properties": {
            "customProperty": "customValue"
        }
    },
    {
        "body": { "data": "complex event object" },
        "partitionKey": "user123"
    }
]

Returns: 200 OK if successful. Specific status codes may indicate partial success or errors.

Receive Messages

GET https://{namespaceName}.servicebus.windows.net/{eventHubName}/consumergroups/{consumerGroupName}/messages/latest?timeout=60&api-version=2014-01

Receives events from an event hub using a specific consumer group. This is typically done over AMQP for efficiency. The HTTPS endpoint is an alternative.

Note: For production scenarios, using the AMQP protocol with a dedicated client library (e.g., Azure SDKs) is highly recommended for receiving messages.

Query Parameters

Name	Type	Description	Required
`consumerGroupName`	string	The name of the consumer group to use.	Yes
`timeout`	integer	Timeout in seconds for the request.	No
`api-version`	string	The API version.	Yes

Headers:

Name	Description
`Authorization`	SAS token or Azure AD token.

Returns: 200 OK with a JSON array of received events. An empty array indicates no new messages.