canonical: https://jentic.com/apis/azure.com/healthcareapisclient

# Microsoft Azure HealthcareApisClient

Jentic publishes the only available OpenAPI specification for HealthcareApisClient, keeping it validated and agent-ready. The Azure Healthcare APIs Management API provisions and manages Microsoft Healthcare APIs services through Azure Resource Manager. These services host FHIR-compliant clinical data stores in Azure, and this control-plane API handles their lifecycle: name availability, create or update, get, list, update, and delete. The data plane (actual FHIR resource access) is reached through each provisioned service's hostname; this API governs the service resource itself. Authentication is Azure AD OAuth2 against management.azure.com.

## For AI agents

Provision Microsoft Healthcare APIs (FHIR) service instances on Azure, list services across a subscription, and manage their lifecycle.

## Scope

Does not read or write FHIR resources, run FHIR queries, or manage clinical data - use for provisioning and managing Healthcare APIs service instances only.

## Capabilities

- Provision a new Microsoft Healthcare APIs service instance with a FHIR data store
- Check whether a proposed service name is available before creation
- List all Healthcare APIs services in a subscription or filter by resource group
- Retrieve the configuration of a specific service including its FHIR endpoint
- Patch tags or properties on an existing Healthcare APIs service
- Delete a service when the FHIR data store is no longer needed
- Poll long-running provisioning operations via the operationresults endpoint

## Use cases

### Stand up a FHIR data store on Azure

Provision a Microsoft Healthcare APIs service via PUT on /subscriptions/.../services/{resourceName} with the desired location, kind (fhir-R4 or fhir-Stu3), and authentication configuration. Once Succeeded, the service exposes a FHIR endpoint that applications can use for clinical data exchange. Suitable for healthcare ISVs needing a managed FHIR server.

Example prompt: Create a Healthcare APIs service named 'patient-records-prod' in resource group 'clinical-rg' with kind 'fhir-R4' and the agreed Azure AD authority configured.

### Pre-flight name availability check

Validate a candidate service name with POST /subscriptions/{subscriptionId}/providers/Microsoft.HealthcareApis/checkNameAvailability before attempting a PUT. This avoids a failed provision if the name is taken across the subscription scope. Useful in self-service portals that surface name validation to users.

Example prompt: POST /subscriptions/{sub}/providers/Microsoft.HealthcareApis/checkNameAvailability with the proposed name 'patient-records-prod' and report whether it is available.

### Subscription-wide FHIR service inventory

List all Healthcare APIs services across a subscription via GET /subscriptions/.../providers/Microsoft.HealthcareApis/services. The response gives each service's FHIR kind, endpoint hostname, and current provisioning state. Useful for compliance teams that need a snapshot of every clinical data store under management.

Example prompt: GET all Healthcare APIs services in subscription 'sub-clinical' and return each service's resource ID, kind, and FHIR endpoint.

### AI agent FHIR provisioning via Jentic

A clinical platform agent uses Jentic to spin up FHIR data stores on demand for new tenants. Jentic finds Services_CreateOrUpdate, loads the input schema, and executes against ARM with a scoped bearer token. The agent never sees the raw Azure credentials.

Example prompt: Use Jentic to search for 'create azure healthcare apis service', load Services_CreateOrUpdate, and execute it for a new tenant with kind 'fhir-R4' in the agreed region.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.HealthcareApis/services/{resourceName} | Create or update a Healthcare APIs service |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.HealthcareApis/services | List services in a subscription |
| GET | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.HealthcareApis/services/{resourceName} | Get a specific service |
| POST | /subscriptions/{subscriptionId}/providers/Microsoft.HealthcareApis/checkNameAvailability | Check if a service name is available |
| PATCH | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.HealthcareApis/services/{resourceName} | Patch tags or properties |
| DELETE | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.HealthcareApis/services/{resourceName} | Delete a service |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.HealthcareApis/locations/{locationName}/operationresults/{operationResultId} | Get an operation result |

## Key resources

- **Services** — Provision, list, get, update, delete, and check name availability for Healthcare APIs service instances.
- **OperationResults** — Poll the result of a long-running Healthcare APIs operation by operation result ID.
- **Operations** — Enumerate the operations supported by the Microsoft.HealthcareApis provider.

## Why Jentic

- **Setup:** Wiring the Healthcare APIs control plane by hand means setting up an Azure AD service principal, minting bearer tokens against management.azure.com, running name-availability checks, and polling the operationresults endpoint while a FHIR service provisions. Through Jentic you install once, import Healthcare APIs Management from the API Directory, store the service principal credentials once, and your agent calls it.
- **Permission scoping:** The service name travels in the URL path (/services/{resourceName}), so a rule can pin your agent to reading and checking named services. You choose the operations it may call, so deleting a Healthcare APIs service is not included unless you add it.
- **Credential handling:** Your Azure service principal credentials are stored once, encrypted, by your own Jentic One instance and exchanged for a scoped Azure AD bearer token at execution time. The client secret never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an azure healthcare apis fhir service' or 'check a fhir service name availability', and Jentic returns the matching Services operation with its full input schema so the agent calls the right ARM endpoint without reading Microsoft Learn.

## Related APIs

- **Azure Bot Service** — Manages Azure Bot Service resources used in clinical chatbot scenarios.
- **Azure API Management** — Front the FHIR endpoint with API Management for rate limiting, auth, and audit.
- **Azure Key Vault** — Store secrets and certificates used by client apps that talk to the FHIR endpoint.

## FAQ

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

Microsoft Azure does not publish a stand-alone OpenAPI specification for the 2019-09-16 Healthcare APIs management surface. Jentic generates and maintains this spec from the Microsoft.HealthcareApis ARM surface so that AI agents and developers can call HealthcareApisClient 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 this API use?

The control-plane API uses Azure AD OAuth2 against management.azure.com, declared as the azure_auth security scheme. The data plane (FHIR access on each provisioned service) uses a separate Azure AD authority configured per service. Through Jentic, your service principal credentials sit encrypted in the vault and are exchanged for a scoped bearer token at execution.

### Does this API let me read or write FHIR resources?

No. This is the management/control-plane API for Healthcare APIs services. It provisions and configures service instances. To read or write FHIR resources (Patient, Observation, Encounter, etc.) you call the FHIR endpoint of a provisioned service, which speaks the FHIR REST standard, not this ARM API.

### What are the rate limits?

Standard ARM throttles apply at the subscription level - about 12,000 reads and 1,200 writes per hour per subscription. Provisioning is long-running, so PUT calls return 202 and callers should poll the operationresults endpoint rather than retry.

### How do I provision a FHIR service through Jentic?

Run jentic.search('create azure healthcare apis service'), load the Services_CreateOrUpdate schema, and execute it with the subscription, resource group, service name, location, kind (such as 'fhir-R4'), and the Azure AD auth configuration. Once the operationresults endpoint reports Succeeded, the FHIR endpoint hostname is available on the resource.

### Can I limit what my agent is allowed to do with the Azure Healthcare APIs Management API?

Yes. Because you run Jentic One yourself, your own rules decide which of this API's operations the agent may call, so you can allow the read and check-name-availability operations while withholding create, patch, and delete on a Healthcare APIs service. Since the service name travels in the URL path under /services/{resourceName}, a rule can pin the agent to reading and checking specific named services rather than acting across the whole subscription. Deleting a Healthcare APIs service stays off the table unless you explicitly grant it, and the Azure service principal credentials never enter the agent's prompt or context.