Skip to main content

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.

PlaneBase URLAuthUse for
Control planemanagement.azure.comStandard Azure RBACCreate, update, delete agents and config
Data planePer-agent endpointazuresre.dev audienceChat, 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​

RoleDescriptionScope
SRE Agent AdministratorFull control over agent configuration and operationsAgent resource
SRE Agent AuthorCreate custom agents, upload knowledge, author response plans, manage connectorsAgent resource
SRE Agent Standard UserChat, run diagnostics, request actions, manage scheduled tasksAgent resource
SRE Agent ReaderRead-only access to agent configuration and threadsAgent 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​

OperationMethodPath suffix
Create or updatePUT—
GetGET—
DeleteDELETE—
StartPOST/start
StopPOST/stop
Get usagesGET/usages
Get daily usagesGET/dailyusages

Agent properties​

PropertyTypeDescription
provisioningStatestringSucceeded, Failed, InProgress, Canceled, Deleting (read-only)
agentEndpointstringData plane URL (read-only)
powerStatestringRunning or Stopped (read-only)
outboundIpAddressesstring[]Outbound IPs for allowlisting (read-only)
actionConfiguration.modestringReview, Automatic, or ReadOnly
actionConfiguration.accessLevelstringLow or High
defaultModel.providerstringAnthropic or MicrosoftFoundry
defaultModel.namestringModel name (e.g., Automatic)
upgradeChannelstringStable or Preview
monthlyAgentUnitLimitnumberMonthly active flow AAU cap (does not include always-on flow)
knowledgeGraphConfiguration.identitystringManaged identity resource ID
knowledgeGraphConfiguration.managedResourcesstring[]Resource group IDs the agent can access
logConfigurationobjectApplication Insights configuration
incidentManagementConfiguration.typestringPagerDuty, AzMonitor, ServiceNow, or None
mcpServersstring[]MCP server URLs
vnetConfiguration.subnetResourceIdstringVNet injection subnet. Must be /27 or larger, delegated to Microsoft.App/environments, and in the same region as the agent.
experimentalSettingsobjectFeature flag overrides

Sub-resources​

Sub-resourceARM typePath
ConnectorsMicrosoft.App/agents/DataConnectors/DataConnectors/{name}
SkillsMicrosoft.App/agents/skills/skills/{name}
SubagentsMicrosoft.App/agents/subagents/subagents/{name}
ToolsMicrosoft.App/agents/tools/tools/{name}
Scheduled tasksMicrosoft.App/agents/scheduledTasks/scheduledTasks/{name}
Incident filtersMicrosoft.App/agents/incidentFilters/incidentFilters/{name}
HooksMicrosoft.App/agents/hooks/hooks/{name}
Common promptsMicrosoft.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​

TypeValueUse case
Azure Data ExplorerKustoQuery ADX clusters
Application InsightsKustoQuery App Insights
Log AnalyticsKustoQuery Log Analytics
MCPMcpMCP-compatible connectors (Datadog, Splunk, etc.)
PagerDutyMcpPagerDuty incidents
ServiceNowMcpServiceNow incidents
OutlookOutlookEmail notifications
TeamsTeamsTeams 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​

MethodPathDescription
GET/api/v1/threadsList conversation threads
GET/api/v1/threads/{threadId}Get a specific thread
POST/api/v1/threads/{threadId}/messagesSend a message (start a conversation)
GET/api/v1/threads/{threadId}/messagesGet messages in a thread

Approvals​

MethodPathDescription
GET/api/v1/approvals/{threadId}List pending approvals
POST/api/v1/approvals/{threadId}/{id}/decisionApprove or reject an action

Code repos​

MethodPathDescription
PUT/api/v2/repos/{repoName}Add a code repository
GET/api/v2/reposList repositories
GET/api/v2/repos/{repoName}Get repo details
DELETE/api/v2/repos/{repoName}Remove a repository
POST/api/v2/repos/{repoName}/testTest 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).

MethodPathDescription
GET/api/v2/github/domainsList 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}/reposList accessible repositories for a domain
GET/api/v2/github/oauth/configGet OAuth login URL (github.com only)

PUT request body:

FieldTypeRequiredDescription
authTypestringYesPat or GitHubApp (OAuth uses the /oauth/complete callback)
patstringFor PATPersonal access token (github.com only — GHE requires GitHubApp)
clientIdstringFor GitHubAppGitHub App client ID
privateKeySecretUristringFor GitHubAppKey Vault secret URI for the App's PEM private key
keyVaultManagedIdentityIdstringNoUser-assigned managed identity resource ID for Key Vault access (empty = system-assigned)

Knowledge (agent memory)​

MethodPathDescription
POST/api/v1/agentmemory/uploadUpload documents (multipart, max 100 MB total, 16 MB per file)
GET/api/v1/agentmemory/statusCheck memory status
DELETE/api/v1/agentmemory/document/{fileName}Delete a document
DELETE/api/v1/agentmemory/documentsBulk delete documents
GET/api/v1/agentmemory/indexer-statusCheck indexer progress

HTTP triggers​

MethodPathDescription
POST/api/v1/httptriggers/createCreate an HTTP trigger
GET/api/v1/httptriggersList triggers
POST/api/v1/httptriggers/{triggerId}/executeExecute 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​

MethodPathDescription
PUT/api/v2/extendedAgent/hooks/{hookName}Create or update a hook
GET/api/v2/extendedAgent/hooksList 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:

ResourcePath 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:

HubPathPurpose
AgentHub/agentHubReal-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​

Last updated on
Was this page helpful?
Report an issue with this page