canonical: https://jentic.com/apis/azure.com/azure-digital-twins-management

# Microsoft Azure AzureDigitalTwinsManagementClient

Jentic publishes the only available OpenAPI specification for AzureDigitalTwinsManagementClient, keeping it validated and agent-ready. The Azure Digital Twins management API provisions DigitalTwinsInstance resources, attaches event endpoints (Event Grid, Event Hubs, Service Bus), and links integration resources such as IoT Hubs to a twin graph. It is the control plane for setting up the modelling environment in which a digital twin of a physical environment lives, distinct from the data plane that runs queries against twins.

## For AI agents

Provision Azure Digital Twins instances, configure their event endpoints, and link IoT Hub integration resources for twin graph telemetry.

## Scope

Does not run twin queries, upload twin models, or ingest device telemetry - use for DigitalTwinsInstance provisioning and endpoint wiring only.

## Capabilities

- Provision and delete DigitalTwinsInstance resources scoped to a resource group
- Check name availability for a new DigitalTwinsInstance in a region before creating it
- Attach Event Grid, Event Hubs, or Service Bus endpoints to a twin instance for change notifications
- List, link, and unlink IoT Hub integration resources against a digital twin
- Update tags and properties on an existing DigitalTwinsInstance
- List DigitalTwinsInstance resources by subscription or by resource group

## Use cases

### Stand up a new Digital Twins environment

Solution architects use this API to bootstrap a Digital Twins instance for a smart-building or factory project. They call CheckNameAvailability, then PUT on /digitalTwinsInstances/{resourceName} to create the instance, and finally attach an Event Grid endpoint so downstream services receive twin change events. This is faster and more reproducible than clicking through the Azure portal.

Example prompt: Call DigitalTwins_CheckNameAvailability for 'factory-twin-eu', then DigitalTwins_CreateOrUpdate in resource group iot-rg, then DigitalTwinsEndpoint_CreateOrUpdate to attach an Event Grid endpoint

### Wire IoT Hubs into a twin graph

Operations engineers connect existing IoT Hubs to a Digital Twins instance so device telemetry flows into the twin model. The API exposes IoTHub_CreateOrUpdate under the integrationResources path, letting agents declare the IoT Hub by ARM ID and receive a managed integration resource that the twin uses to ingest events.

Example prompt: Use IoTHub_CreateOrUpdate to attach a specific IoT Hub ARM resource ID to a DigitalTwinsInstance

### Lifecycle management at scale

Platform teams that run many short-lived twin environments use this API to enumerate, tag, and tear down DigitalTwinsInstance resources by subscription. DigitalTwins_List walks every twin in a subscription, DigitalTwins_Update changes tags, and DigitalTwins_Delete removes the instance plus its endpoints in a single asynchronous operation.

Example prompt: Enumerate every DigitalTwinsInstance in a subscription, filter by tag environment=dev, and call DigitalTwins_Delete on each match

### AI agent integration via Jentic

An IoT operations agent uses Jentic to provision and tear down twin environments without learning ARM. The agent searches Jentic for 'create an Azure Digital Twins instance', loads the DigitalTwins_CreateOrUpdate schema, and executes with structured input. Jentic mints the AAD token in the background, so the agent never holds a Microsoft Graph or ARM bearer token.

Example prompt: Through Jentic, search 'provision a digital twins instance', load the schema, and execute DigitalTwins_CreateOrUpdate for a new factory environment

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DigitalTwins/digitalTwinsInstances/{resourceName} | Create or update a Digital Twins instance |
| DELETE | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DigitalTwins/digitalTwinsInstances/{resourceName} | Delete a Digital Twins instance |
| POST | /subscriptions/{subscriptionId}/providers/Microsoft.DigitalTwins/locations/{location}/checkNameAvailability | Check whether a Digital Twins instance name is available |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DigitalTwins/digitalTwinsInstances/{resourceName}/endpoints/{endpointName} | Create or update an event endpoint on a twin |
| PUT | /{scope}/providers/Microsoft.DigitalTwins/integrationResources/{integrationResourceName} | Attach or update an IoT Hub integration resource |

## Key resources

- **DigitalTwinsInstance** — The top-level twin environment - supports list, get, create, update, delete and name availability checks.
- **DigitalTwinsEndpoint** — Event Grid, Event Hubs, or Service Bus endpoints attached to a DigitalTwinsInstance.
- **IntegrationResources / IoTHub** — IoT Hub bindings that bring device telemetry into a twin graph.
- **Operations** — Lists the operations available under the Microsoft.DigitalTwins resource provider.

## Why Jentic

- **Setup:** Wiring the AzureDigitalTwinsManagementClient API by hand means registering an Azure AD app for OAuth2 bearer auth against management.azure.com, building the Microsoft.DigitalTwins instance and endpoint paths, and polling ARM while a twin instance or endpoint provisions. Through Jentic you install once, import AzureDigitalTwinsManagementClient from the API Directory, store the Azure AD credential once, and your agent calls it.
- **Permission scoping:** The instance sits in the URL path (/digitalTwinsInstances/{resourceName}, with /endpoints/{endpointName} children), so a rule can pin your agent to one Digital Twins instance and its endpoints. You choose the operations it may call, so the DELETE that tears down an instance and its endpoints is not included unless you add it.
- **Credential handling:** Your Azure AD credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'provision an azure digital twins instance' or 'attach an event grid endpoint to a twin', and Jentic returns the matching Microsoft.DigitalTwins operation, for example DigitalTwins_CreateOrUpdate, with its input schema so the agent calls the right endpoint without browsing the ARM reference.

## Related APIs

- **Azure IoT Hub Client** — IoT Hub provides the device-side telemetry that integration resources route into a twin.
- **Azure Maps Resource Provider** — Provisions Azure Maps accounts often used to layer geospatial context onto a twin.
- **Azure Blockchain Management** — Different IoT-adjacent control plane focused on consortium ledgers rather than twin graphs.

## FAQ

### Why is there no official OpenAPI spec for AzureDigitalTwinsManagementClient?

Microsoft Azure does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AzureDigitalTwinsManagementClient via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the AzureDigitalTwinsManagementClient API use?

The API uses Azure Active Directory OAuth 2.0 declared as azure_auth with the implicit flow. Tokens are presented as Bearer tokens against management.azure.com. Jentic stores the AAD client secret in its vault and mints scoped tokens for each call so the agent never sees the raw credential.

### Can I run twin queries with this API?

No. This is the management plane only - it provisions DigitalTwinsInstance resources and configures their endpoints and integrations. Twin model uploads, twin queries, and relationship traversal happen on the data plane API of each instance.

### What are the rate limits for the AzureDigitalTwinsManagementClient API?

Azure Resource Manager applies subscription-level throttling - typically 12,000 read and 1,200 write requests per hour, surfaced via x-ms-ratelimit-remaining headers. The Digital Twins management API does not document additional limits beyond ARM.

### How do I provision a Digital Twins instance through Jentic?

Run pip install jentic, then use the async client to search 'provision an Azure Digital Twins instance', load the DigitalTwins_CreateOrUpdate operation, and execute with subscriptionId, resourceGroupName, and a body specifying location and tags. Jentic returns the resource details once the deployment completes.

### Can I attach multiple endpoints to a single DigitalTwinsInstance?

Yes. Each endpoint is a child resource at /digitalTwinsInstances/{resourceName}/endpoints/{endpointName}. List existing endpoints with DigitalTwinsEndpoint_List and create more with DigitalTwinsEndpoint_CreateOrUpdate, choosing Event Grid, Event Hubs, or Service Bus per endpoint.