Built-in HTTP APIs exposed by the Durable Functions extension for starting orchestrations, querying instance status, raising events, terminating, suspending, resuming, rewinding, signaling entities, and purging history.
openapi: 3.1.0
info:
title: Azure Durable Functions HTTP API
description: >-
The Azure Durable Functions extension exposes built-in HTTP APIs for
managing orchestrations, entities, and task hubs. These HTTP APIs are
extensibility webhooks authorized by the Azure Functions host and
handled by the Durable Functions extension. Use them to start
orchestrations, query status, raise events, terminate, suspend, resume,
rewind, signal entities, and purge history.
version: 'v2'
contact:
name: Microsoft Azure
url: https://learn.microsoft.com/en-us/azure/azure-functions/durable/
externalDocs:
description: Durable Functions HTTP API documentation
url: https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-http-api
servers:
- url: https://{appName}.azurewebsites.net
description: Function App in Azure
variables:
appName:
default: myfuncapp
- url: http://localhost:7071
description: Local development with Azure Functions Core Tools
tags:
- name: Orchestrations
description: Orchestration instance management
- name: Entities
description: Durable entity management
security:
- systemKey: []
paths:
/runtime/webhooks/durabletask/orchestrators/{functionName}:
post:
operationId: startOrchestration
summary: Start orchestration
description: Starts a new instance of the specified orchestrator function.
tags:
- Orchestrations
parameters:
- name: functionName
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
requestBody:
required: false
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'202':
description: Orchestrator scheduled
content:
application/json:
schema:
$ref: '#/components/schemas/StartResponse'
'400':
description: Bad request
/runtime/webhooks/durabletask/orchestrators/{functionName}/{instanceId}:
post:
operationId: startOrchestrationWithId
summary: Start orchestration with explicit instance ID
tags:
- Orchestrations
parameters:
- name: functionName
in: path
required: true
schema:
type: string
- name: instanceId
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
requestBody:
required: false
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'202':
description: Orchestrator scheduled
content:
application/json:
schema:
$ref: '#/components/schemas/StartResponse'
'400':
description: Bad request
/runtime/webhooks/durabletask/instances:
get:
operationId: listInstances
summary: List instances
description: Queries the status of multiple orchestration instances.
tags:
- Orchestrations
parameters:
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
- name: createdTimeFrom
in: query
schema:
type: string
format: date-time
- name: createdTimeTo
in: query
schema:
type: string
format: date-time
- name: runtimeStatus
in: query
schema:
type: string
- name: instanceIdPrefix
in: query
schema:
type: string
- name: showInput
in: query
schema:
type: boolean
- name: top
in: query
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InstanceStatus'
delete:
operationId: purgeInstances
summary: Purge multiple instance histories
tags:
- Orchestrations
parameters:
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
- name: createdTimeFrom
in: query
schema:
type: string
format: date-time
- name: createdTimeTo
in: query
schema:
type: string
format: date-time
- name: runtimeStatus
in: query
schema:
type: string
responses:
'200':
description: Purge result
content:
application/json:
schema:
$ref: '#/components/schemas/PurgeResult'
'404':
description: No instances matched
/runtime/webhooks/durabletask/instances/{instanceId}:
parameters:
- name: instanceId
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
get:
operationId: getInstanceStatus
summary: Get instance status
tags:
- Orchestrations
parameters:
- name: showHistory
in: query
schema:
type: boolean
- name: showHistoryOutput
in: query
schema:
type: boolean
- name: showInput
in: query
schema:
type: boolean
- name: returnInternalServerErrorOnFailure
in: query
schema:
type: boolean
responses:
'200':
description: Instance completed or failed
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceStatus'
'202':
description: Instance running
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceStatus'
'404':
description: Instance not found
delete:
operationId: purgeInstance
summary: Purge single instance history
tags:
- Orchestrations
responses:
'200':
description: Purge result
content:
application/json:
schema:
$ref: '#/components/schemas/PurgeResult'
'404':
description: Instance not found
/runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName}:
post:
operationId: raiseEvent
summary: Raise event
description: Sends an event notification to a running orchestration instance.
tags:
- Orchestrations
parameters:
- name: instanceId
in: path
required: true
schema:
type: string
- name: eventName
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
requestBody:
required: true
content:
application/json:
schema: {}
responses:
'202':
description: Event accepted
'400':
description: Bad request
'404':
description: Instance not found
'410':
description: Instance no longer accepting events
/runtime/webhooks/durabletask/instances/{instanceId}/terminate:
post:
operationId: terminateInstance
summary: Terminate instance
tags:
- Orchestrations
parameters:
- name: instanceId
in: path
required: true
schema:
type: string
- name: reason
in: query
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
responses:
'202':
description: Termination accepted
'404':
description: Instance not found
'410':
description: Instance already completed or failed
/runtime/webhooks/durabletask/instances/{instanceId}/suspend:
post:
operationId: suspendInstance
summary: Suspend instance
tags:
- Orchestrations
parameters:
- name: instanceId
in: path
required: true
schema:
type: string
- name: reason
in: query
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
responses:
'202':
description: Suspension accepted
'404':
description: Instance not found
'410':
description: Instance cannot be suspended
/runtime/webhooks/durabletask/instances/{instanceId}/resume:
post:
operationId: resumeInstance
summary: Resume instance
tags:
- Orchestrations
parameters:
- name: instanceId
in: path
required: true
schema:
type: string
- name: reason
in: query
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
responses:
'202':
description: Resume accepted
'404':
description: Instance not found
'410':
description: Instance cannot be resumed
/runtime/webhooks/durabletask/instances/{instanceId}/rewind:
post:
operationId: rewindInstance
summary: Rewind instance (preview)
tags:
- Orchestrations
parameters:
- name: instanceId
in: path
required: true
schema:
type: string
- name: reason
in: query
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
responses:
'202':
description: Rewind accepted
'404':
description: Instance not found
'410':
description: Instance cannot be rewound
/runtime/webhooks/durabletask/entities/{entityName}/{entityKey}:
parameters:
- name: entityName
in: path
required: true
schema:
type: string
- name: entityKey
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
get:
operationId: getEntity
summary: Get entity
tags:
- Entities
responses:
'200':
description: Entity state
content:
application/json:
schema: {}
'404':
description: Entity not found
post:
operationId: signalEntity
summary: Signal entity
description: Sends a one-way operation message to a Durable Entity.
tags:
- Entities
parameters:
- name: op
in: query
schema:
type: string
requestBody:
required: false
content:
application/json:
schema: {}
responses:
'202':
description: Signal accepted
'400':
description: Bad request
'404':
description: Entity name not found
/runtime/webhooks/durabletask/entities/{entityName}:
get:
operationId: listEntities
summary: List entities
tags:
- Entities
parameters:
- name: entityName
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/TaskHub'
- $ref: '#/components/parameters/Connection'
- $ref: '#/components/parameters/Code'
- name: lastOperationTimeFrom
in: query
schema:
type: string
format: date-time
- name: lastOperationTimeTo
in: query
schema:
type: string
format: date-time
- name: fetchState
in: query
schema:
type: boolean
- name: top
in: query
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Entity'
components:
parameters:
TaskHub:
name: taskHub
in: query
schema:
type: string
Connection:
name: connection
in: query
schema:
type: string
Code:
name: code
in: query
schema:
type: string
securitySchemes:
systemKey:
type: apiKey
in: query
name: code
schemas:
StartResponse:
type: object
properties:
id:
type: string
statusQueryGetUri:
type: string
sendEventPostUri:
type: string
terminatePostUri:
type: string
purgeHistoryDeleteUri:
type: string
rewindPostUri:
type: string
suspendPostUri:
type: string
resumePostUri:
type: string
InstanceStatus:
type: object
properties:
instanceId:
type: string
runtimeStatus:
type: string
enum:
- Running
- Pending
- Failed
- Canceled
- Terminated
- Completed
- Suspended
input: {}
customStatus: {}
output: {}
createdTime:
type: string
format: date-time
lastUpdatedTime:
type: string
format: date-time
historyEvents:
type: array
items:
type: object
additionalProperties: true
PurgeResult:
type: object
properties:
instancesDeleted:
type: integer
Entity:
type: object
properties:
entityId:
type: object
properties:
key:
type: string
name:
type: string
lastOperationTime:
type: string
format: date-time
state:
type: object
additionalProperties: true