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