API Reference

REST API operations for managing and interacting with Azure SRE Agent programmatically.

---

TL;DR

• Two API planes: control plane (ARM) for resource lifecycle, data plane for runtime operations
• Control plane: https://management.azure.com/.../Microsoft.App/agents/{name} + ?api-version=2025-05-01-preview
• Data plane: https://{agentEndpoint}/api/... — get the endpoint from an ARM GET call
• Auth: ARM uses standard Azure credentials; data plane requires a token with audience https://azuresre.dev

---

Overview

Azure SRE Agent provides REST APIs at two layers. Use the control plane (ARM) to create, configure, and delete agents and their sub-resources. Use the data plane for runtime operations like chat, repo management, and knowledge uploads.

Plane	Base URL	Auth	Use for
Control plane	management.azure.com	Standard Azure RBAC	Create, update, delete agents and config
Data plane	Per-agent endpoint	azuresre.dev audience	Chat, repos, hooks, knowledge, triggers

---

Authentication

Control plane (ARM)

Standard Azure authentication — Azure CLI, service principal, or managed identity:

# Interactive login
az login

# Service principal
az login --service-principal -u $APP_ID -p $SECRET --tenant $TENANT_ID

# Managed identity (from Azure VM or Container App)
az login --identity

Data plane

The data plane requires a separate token with audience https://azuresre.dev:

# Step 1: Get the agent's data plane endpoint
ENDPOINT=$(az rest -m GET \
  --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.App/agents/{agentName}?api-version=2025-05-01-preview" \
  --query properties.agentEndpoint -o tsv)

# Step 2: Get a data plane token
TOKEN=$(az account get-access-token \
  --resource https://azuresre.dev \
  --query accessToken -o tsv)

# Step 3: Call the data plane
curl -H "Authorization: Bearer $TOKEN" "$ENDPOINT/api/v1/threads"

info

The agent endpoint is unique per agent. It follows the pattern https://{name}--{id}.{hash}.{region}.azuresre.ai and is visible under Settings in the agent portal, or returned by the ARM GET operation in properties.agentEndpoint.

---

RBAC roles

Role	Description	Scope
SRE Agent Administrator	Full control over agent configuration and operations	Agent resource
SRE Agent Author	Create custom agents, upload knowledge, author response plans, manage connectors	Agent resource
SRE Agent Standard User	Chat, run diagnostics, request actions, manage scheduled tasks	Agent resource
SRE Agent Reader	Read-only access to agent configuration and threads	Agent resource

Assign roles using the Azure portal, CLI, or ARM API:

az role assignment create \
  --assignee {userOrServicePrincipalId} \
  --role "SRE Agent Administrator" \
  --scope "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.App/agents/{name}"

---

Control plane (ARM) operations

API version

2025-05-01-preview

note

Both the control plane and data plane APIs are currently in preview. Endpoint paths, request/response schemas, and behavior may change before general availability. Pin your integrations to this API version and test after upgrades.

Base URL

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.App/agents/{agentName}

Append the path suffix from the operations table, then add ?api-version=2025-05-01-preview as a query parameter. For example: .../agents/{agentName}/start?api-version=2025-05-01-preview.

Agent resource operations

Operation	Method	Path suffix
Create or update	PUT	—
Get	GET	—
Delete	DELETE	—
Start	POST	/start
Stop	POST	/stop
Get usages	GET	/usages
Get daily usages	GET	/dailyusages
Get daily usage details (per thread)	GET	/dailyUsageDetails

Get daily usage details

GET /dailyUsageDetails is the only programmatic surface that breaks AAU consumption down per thread. It is the same data that backs the Consumption by thread table on the Agent consumption page, so use it when you need per-thread or per-incident cost in a report, dashboard, or chargeback pipeline rather than in the portal. Use GET /dailyusages when whole-agent daily totals are enough; this endpoint is for per-thread and per-source attribution.

Query parameters

Parameter	Type	Default	Description
startTime	date	60 days ago	Start of the range (inclusive). Binned to whole UTC days.
endTime	date	now	End of the range (inclusive). Binned to whole UTC days.

The range cannot exceed 60 days; a longer range returns 400 Bad Request. Requests are also capped at roughly 5,000 records per response — when a range exceeds that, the response carries a nextLink you must follow to page through the remainder.

Response

An ARM-style envelope: a top-level value array plus a nextLink that is present only when more records remain. Deserialize the body as this envelope, not as a bare array:

{
  "value": [
    {
      "date": "2026-08-29",
      "threadId": "3f2a9d3e-8c1b-4f6a-9e2d-5b7c1a0d4e88",
      "source": "Thread",
      "value": 12.5,
      "name": { "value": "AgentUnits", "localizedValue": "Agent Units" }
    }
  ],
  "nextLink": "https://management.azure.com/..."
}

Each value[] item is one record per (date, threadId, source) - a thread produces multiple records for the same day when its consumption comes from more than one source, so sum across source (and across days) for a thread total:

Field	Type	Description
date	string	Usage day, yyyy-MM-dd (UTC)
threadId	string	Thread the consumption is attributed to
source	string	What drove the work — for example Thread, or Other when unclassified
value	number	AAUs consumed
name	object	Unit descriptor (AgentUnits)

curl -H "Authorization: Bearer $TOKEN" \
  "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.App/agents/{agentName}/dailyUsageDetails?api-version=2025-05-01-preview&startTime=2026-08-01&endTime=2026-08-30"

note

Things to account for before you build a cost model on this endpoint:

• AAU only. Raw input/output token counts are not returned.
• Day-binned and source-split. A thread that spans midnight UTC appears on both days, and each day can carry one record per source; sum records by threadId (across date and source) to get a thread total.
• Up to ~30 minutes stale. Usage is refreshed on a background timer, so a thread that just finished may not be fully reflected yet.
• Active flow only. Always-on (time-based) AAU is billed on the same meter but is not attributed to any thread, so per-thread sums are lower than your total agent cost. See Pricing & Billing.
• Non-billable internal work is excluded, so totals here reconcile with your bill rather than with raw model telemetry.

Agent properties

Property	Type	Description
provisioningState	string	Succeeded, Failed, InProgress, Canceled, Deleting (read-only)
agentEndpoint	string	Data plane URL (read-only)
powerState	string	Running or Stopped (read-only)
outboundIpAddresses	string[]	Outbound IPs for allowlisting (read-only)
actionConfiguration.mode	string	Review, Automatic, or ReadOnly
actionConfiguration.accessLevel	string	Low or High
defaultModel.provider	string	Anthropic or MicrosoftFoundry
defaultModel.name	string	Model name (e.g., Automatic)
upgradeChannel	string	Stable or Preview
monthlyAgentUnitLimit	number	Monthly active flow AAU cap (does not include always-on flow)
knowledgeGraphConfiguration.identity	string	Managed identity resource ID
knowledgeGraphConfiguration.managedResources	string[]	Resource group IDs the agent can access
logConfiguration	object	Application Insights configuration
incidentManagementConfiguration.type	string	PagerDuty, AzMonitor, ServiceNow, or None
mcpServers	string[]	MCP server URLs
vnetConfiguration.subnetResourceId	string	VNet injection subnet. Must be /27 or larger, delegated to Microsoft.App/environments, and in the same region as the agent.
experimentalSettings	object	Feature flag overrides

Sub-resources

Sub-resource	ARM type	Path
Connectors	Microsoft.App/agents/DataConnectors	/DataConnectors/{name}
Skills	Microsoft.App/agents/skills	/skills/{name}
Subagents	Microsoft.App/agents/subagents	/subagents/{name}
Tools	Microsoft.App/agents/tools	/tools/{name}
Scheduled tasks	Microsoft.App/agents/scheduledTasks	/scheduledTasks/{name}
Incident filters	Microsoft.App/agents/incidentFilters	/incidentFilters/{name}
Hooks	Microsoft.App/agents/hooks	/hooks/{name}
Common prompts	Microsoft.App/agents/commonPrompts	/commonPrompts/{name}

All sub-resources support PUT (create/update), GET, and DELETE operations.

Sub-resource body formats

Connectors use direct properties:

az rest -m PUT \
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.App/agents/{agent}/DataConnectors/my-kusto?api-version=2025-05-01-preview" \
  --body '{
    "properties": {
      "name": "my-kusto",
      "dataConnectorType": "Kusto",
      "dataSource": "https://mycluster.eastus2.kusto.windows.net",
      "identity": "system"
    }
  }'

Other sub-resources (skills, subagents, tools, etc.) use a base64-encoded envelope:

# The spec is base64-encoded inside properties.value
SPEC='{"name":"my-tool","description":"Query Azure Resource Graph"}'
ENCODED=$(echo -n "$SPEC" | base64)

az rest -m PUT \
  --url "...Microsoft.App/agents/{agent}/tools/my-tool?api-version=2025-05-01-preview" \
  --body "{\"properties\":{\"value\":\"$ENCODED\"}}"

Connector types

Type	Value	Use case
Azure Data Explorer	Kusto	Query ADX clusters
Application Insights	Kusto	Query App Insights
Log Analytics	Kusto	Query Log Analytics
MCP	Mcp	MCP-compatible connectors (Datadog, Splunk, etc.)
PagerDuty	Mcp	PagerDuty incidents
ServiceNow	Mcp	ServiceNow incidents
Outlook	Outlook	Email notifications
Teams	Teams	Teams channel notifications

---

Data plane operations

Base URL

Get from ARM:

ENDPOINT=$(az rest -m GET \
  --url "...Microsoft.App/agents/{name}?api-version=2025-05-01-preview" \
  --query properties.agentEndpoint -o tsv)

All data plane paths start with $ENDPOINT/api/....

Threads and chat

Method	Path	Description
POST	/api/v1/threads	Start a conversation. Creates a new thread and posts the first message. Body: {"startMessage": {"text": "..."}}. Returns 201 with the server-generated thread object (the id is also in the Location header)
GET	/api/v1/threads	List conversation threads
GET	/api/v1/threads/{threadId}	Get a specific thread
POST	/api/v1/threads/{threadId}/messages	Append a follow-up message to an existing thread. Body: {"text": "..."}
GET	/api/v1/threads/{threadId}/messages	Get messages in a thread. The response also carries a state field (Processing, Waiting, PendingApproval, Idle, Completed, Failed) — poll this to tell whether the agent is still working

Thread IDs are server-generated

There is no create-with-client-ID route. POST /api/v1/threads/{threadId}/messages only appends to a thread that already exists, so calling it with a client-minted GUID always returns 404. Always create the thread with POST /api/v1/threads first and use the id it returns.

Other status codes worth handling: 401 = wrong token audience (an ARM token instead of https://azuresre.dev), 400 = malformed GUID, 422 = the thread is mid-run ("agent is currently busy") — back off and retry.

Approvals

Method	Path	Description
GET	/api/v1/approvals/{threadId}	List pending approvals
POST	/api/v1/approvals/{threadId}/{id}/decision	Approve or reject an action

Code repos

Method	Path	Description
PUT	/api/v2/repos/{repoName}	Add a code repository
GET	/api/v2/repos	List repositories
GET	/api/v2/repos/{repoName}	Get repo details
DELETE	/api/v2/repos/{repoName}	Remove a repository
POST	/api/v2/repos/{repoName}/test	Test repo connectivity

GitHub authentication

Manage GitHub authentication credentials per domain (github.com or <tenant>.ghe.com). The {domain} path segment uses underscores instead of dots (e.g., github_com or tenant_ghe_com).

Method	Path	Description
GET	/api/v2/github/domains	List all authenticated GitHub domains
GET	/api/v2/github/domains/{domain}	Get auth details for a domain
PUT	/api/v2/github/domains/{domain}	Add or update domain credentials (PAT or BYO GitHub App)
DELETE	/api/v2/github/domains/{domain}	Remove domain credentials
GET	/api/v2/github/domains/{domain}/repos	List accessible repositories for a domain
GET	/api/v2/github/oauth/config	Get OAuth login URL (github.com only)

PUT request body:

Field	Type	Required	Description
authType	string	Yes	Pat or GitHubApp (OAuth uses the /oauth/complete callback)
pat	string	For PAT	Personal access token (github.com only — GHE requires GitHubApp)
clientId	string	For GitHubApp	GitHub App client ID
privateKeySecretUri	string	For GitHubApp	Key Vault secret URI for the App's PEM private key
keyVaultManagedIdentityId	string	No	User-assigned managed identity resource ID for Key Vault access (empty = system-assigned)

Knowledge (agent memory)

Method	Path	Description
POST	/api/v1/agentmemory/upload	Upload documents (multipart, max 100 MB total, 16 MB per file)
GET	/api/v1/agentmemory/status	Check memory status
DELETE	/api/v1/agentmemory/document/{fileName}	Delete a document
DELETE	/api/v1/agentmemory/documents	Bulk delete documents
GET	/api/v1/agentmemory/indexer-status	Check indexer progress

HTTP triggers

Method	Path	Description
POST	/api/v1/httptriggers/create	Create an HTTP trigger
GET	/api/v1/httptriggers	List triggers
POST	/api/v1/httptriggers/{triggerId}/execute	Execute a trigger
POST	/api/v1/httptriggers/trigger/{triggerId}	External webhook endpoint. Requires a data plane bearer token (audience https://azuresre.dev); the caller must have AgentThreadWrite permission on the agent resource

Hooks

Method	Path	Description
PUT	/api/v2/extendedAgent/hooks/{hookName}	Create or update a hook
GET	/api/v2/extendedAgent/hooks	List hooks
DELETE	/api/v2/extendedAgent/hooks/{hookName}	Delete a hook

Extended agent configuration

Manage subagents, tools, connectors, skills, prompts, and plugins via the data plane:

Resource	Path pattern
Subagents	/api/v2/extendedAgent/agents/{name}
Tools	/api/v2/extendedAgent/tools/{name}
Connectors	/api/v2/extendedAgent/connectors/{name}
Skills	/api/v2/extendedAgent/skills/{name}
Common prompts	/api/v2/extendedAgent/commonprompts/{name}
Scheduled tasks	/api/v2/extendedAgent/scheduledtasks/{name}
Plugins	/api/v2/extendedAgent/plugins/{name}

All support PUT, GET, PATCH, and DELETE.

Real-time streaming

The agent uses SignalR for real-time chat streaming:

Hub	Path	Purpose
AgentHub	/agentHub	Real-time message streaming and thread updates

Connect using the SignalR client library with the same bearer token.

---

Examples

Get agent properties

az rest -m GET \
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.App/agents/{name}?api-version=2025-05-01-preview" \
  -o json

List all connectors

az rest -m GET \
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.App/agents/{name}/DataConnectors?api-version=2025-05-01-preview" \
  -o json

List threads via data plane

TOKEN=$(az account get-access-token --resource https://azuresre.dev --query accessToken -o tsv)
ENDPOINT="https://{agentEndpoint}"

curl -s -H "Authorization: Bearer $TOKEN" "$ENDPOINT/api/v1/threads"

Add a code repo via data plane

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$ENDPOINT/api/v2/repos/my-repo" \
  -d '{
    "properties": {
      "url": "https://github.com/myorg/myrepo",
      "type": "GitHub"
    }
  }'  

Store BYO GitHub App credentials via data plane

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$ENDPOINT/api/v2/github/domains/github_com" \
  -d '{
    "authType": "GitHubApp",
    "clientId": "Iv23li...",
    "privateKeySecretUri": "https://my-vault.vault.azure.net/secrets/gh-app-key/abc123"
  }'

For GitHub Enterprise Cloud, replace the domain segment with underscored notation:

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$ENDPOINT/api/v2/github/domains/contoso_ghe_com" \
  -d '{
    "authType": "GitHubApp",
    "clientId": "Iv23li...",
    "privateKeySecretUri": "https://my-vault.vault.azure.net/secrets/ghe-key/abc123",
    "keyVaultManagedIdentityId": "/subscriptions/.../providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity"
  }'

---

See also

• ARM template reference — full property schema on Microsoft Learn
• Deploy with Infrastructure as Code — automate agent deployment using Bicep, Terraform, or PowerShell
• Network requirements — firewall allowlist for API endpoints
• Pricing and billing — costs for API-driven operations