openapi: 3.1.0
info:
  title: Azure Durable Functions HTTP Entities Orchestrations 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/
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
security:
- systemKey: []
tags:
- name: Orchestrations
  description: Orchestration instance management
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
components:
  parameters:
    Code:
      name: code
      in: query
      schema:
        type: string
    TaskHub:
      name: taskHub
      in: query
      schema:
        type: string
    Connection:
      name: connection
      in: query
      schema:
        type: string
  schemas:
    PurgeResult:
      type: object
      properties:
        instancesDeleted:
          type: integer
    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
  securitySchemes:
    systemKey:
      type: apiKey
      in: query
      name: code
externalDocs:
  description: Durable Functions HTTP API documentation
  url: https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-http-api