OpenMetadata Notification Templates API

openapi: 3.0.1
info:
  title: OpenMetadata APIs Agent Executions Notification Templates API
  description: Common types and API definition for OpenMetadata
  contact:
    name: OpenMetadata
    url: https://open-metadata.org
    email: openmetadata-dev@googlegroups.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '1.13'
servers:
- url: /api
  description: Current Host
- url: http://localhost:8585/api
  description: Endpoint URL
security:
- BearerAuth: []
tags:
- name: Notification Templates
  description: Notification templates for customizing event notifications
paths:
  /v1/notificationTemplates:
    get:
      tags:
      - Notification Templates
      summary: List notification templates
      description: Get a list of notification templates
      operationId: listNotificationTemplates
      parameters:
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
      - name: provider
        in: query
        description: Filter templates by provider type (SYSTEM or USER)
        schema:
          type: string
          enum:
          - system
          - user
          - automation
      - name: limit
        in: query
        description: Limit the number of results. (1 to 1000000, default = 10)
        schema:
          maximum: 1000000
          minimum: 0
          type: integer
          format: int32
          default: 10
      - name: before
        in: query
        description: Returns list of entities before this cursor
        schema:
          type: string
      - name: after
        in: query
        description: Returns list of entities after this cursor
        schema:
          type: string
      - name: include
        in: query
        description: Include all, deleted, or non-deleted entities.
        schema:
          type: string
          default: non-deleted
          enum:
          - all
          - deleted
          - non-deleted
      responses:
        '200':
          description: List of notification templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplateList'
    put:
      tags:
      - Notification Templates
      summary: Create or update a notification template
      description: Create a notification template, if it does not exist or update an existing notification template.
      operationId: createOrUpdateNotificationTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNotificationTemplate'
      responses:
        '200':
          description: The notification template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
        '400':
          description: Bad request
        '403':
          description: Forbidden - Requires appropriate permissions for USER or SYSTEM templates
    post:
      tags:
      - Notification Templates
      summary: Create a notification template
      description: Create a new notification template
      operationId: createNotificationTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNotificationTemplate'
      responses:
        '200':
          description: The notification template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
        '400':
          description: Bad request
  /v1/notificationTemplates/name/{fqn}:
    get:
      tags:
      - Notification Templates
      summary: Get a notification template by fully qualified name
      description: Get a notification template by `fullyQualifiedName`.
      operationId: getNotificationTemplateByFQN
      parameters:
      - name: fqn
        in: path
        description: Fully qualified name of the notification template
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
      - name: include
        in: query
        description: Include all, deleted, or non-deleted entities.
        schema:
          type: string
          default: non-deleted
          enum:
          - all
          - deleted
          - non-deleted
      - name: includeRelations
        in: query
        description: 'Per-relation include control. Format: field:value,field2:value2. Example: owners:non-deleted,followers:all. Valid values: all, deleted, non-deleted. If not specified for a field, uses the entity''s include value.'
        schema:
          type: string
          example: owners:non-deleted,followers:all
      responses:
        '200':
          description: The notification template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
        '404':
          description: Notification template for instance {fqn} is not found
    delete:
      tags:
      - Notification Templates
      summary: Delete a notification template by fully qualified name
      description: Delete a notification template by `fullyQualifiedName`. System templates cannot be deleted.
      operationId: deleteNotificationTemplateByFQN
      parameters:
      - name: fqn
        in: path
        description: Fully qualified name of the notification template
        required: true
        schema:
          type: string
      - name: recursive
        in: query
        description: Recursively delete this entity and it's children. (Default `false`)
        schema:
          type: boolean
          default: false
      - name: hardDelete
        in: query
        description: Hard delete the entity. (Default = `false`)
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
        '400':
          description: Bad request - System templates cannot be deleted
        '404':
          description: Notification template for instance {fqn} is not found
    patch:
      tags:
      - Notification Templates
      summary: Update a notification template by name
      description: Update an existing notification template using JsonPatch.
      operationId: patchNotificationTemplateByFQN
      parameters:
      - name: fqn
        in: path
        description: Fully qualified name of the notification template
        required: true
        schema:
          type: string
      requestBody:
        description: JsonPatch with array of operations
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/JsonPatch'
            example:
            - op: replace
              path: /description
              value: new description
      responses:
        '200':
          description: Successfully updated the notification template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
        '400':
          description: Bad request
        '403':
          description: Forbidden - Requires appropriate permissions for USER or SYSTEM templates
        '404':
          description: Notification template not found
  /v1/notificationTemplates/{id}:
    get:
      tags:
      - Notification Templates
      summary: Get a notification template by Id
      description: Get a notification template by `Id`.
      operationId: getNotificationTemplateById
      parameters:
      - name: id
        in: path
        description: Id of the notification template
        required: true
        schema:
          type: string
          format: uuid
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
      - name: include
        in: query
        description: Include all, deleted, or non-deleted entities.
        schema:
          type: string
          default: non-deleted
          enum:
          - all
          - deleted
          - non-deleted
      - name: includeRelations
        in: query
        description: 'Per-relation include control. Format: field:value,field2:value2. Example: owners:non-deleted,followers:all. Valid values: all, deleted, non-deleted. If not specified for a field, uses the entity''s include value.'
        schema:
          type: string
          example: owners:non-deleted,followers:all
      responses:
        '200':
          description: The notification template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
        '404':
          description: Notification template for instance {id} is not found
    delete:
      tags:
      - Notification Templates
      summary: Delete a notification template by Id
      description: Delete a notification template by `Id`. System templates cannot be deleted.
      operationId: deleteNotificationTemplate
      parameters:
      - name: id
        in: path
        description: Id of the notification template
        required: true
        schema:
          type: string
          format: uuid
      - name: recursive
        in: query
        description: Recursively delete this entity and it's children. (Default `false`)
        schema:
          type: boolean
          default: false
      - name: hardDelete
        in: query
        description: Hard delete the entity. (Default = `false`)
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
        '400':
          description: Bad request - System templates cannot be deleted
        '404':
          description: Notification template for instance {id} is not found
    patch:
      tags:
      - Notification Templates
      summary: Update a notification template
      description: Update an existing notification template using JsonPatch.
      operationId: patchNotificationTemplate
      parameters:
      - name: id
        in: path
        description: Id of the notification template
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: JsonPatch with array of operations
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/JsonPatch'
            example:
            - op: replace
              path: /description
              value: new description
      responses:
        '200':
          description: Successfully updated the notification template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
        '400':
          description: Bad request
        '403':
          description: Forbidden - Requires appropriate permissions for USER or SYSTEM templates
        '404':
          description: Notification template not found
  /v1/notificationTemplates/async/{id}:
    delete:
      tags:
      - Notification Templates
      summary: Asynchronously delete a notification template by Id
      description: Asynchronously delete a notification template by `Id`.
      operationId: deleteNotificationTemplateAsync
      parameters:
      - name: hardDelete
        in: query
        description: Hard delete the entity. (Default = `false`)
        schema:
          type: boolean
          default: false
      - name: recursive
        in: query
        description: Recursively delete this entity and it's children. (Default `false`)
        schema:
          type: boolean
          default: false
      - name: id
        in: path
        description: Id of the notification template
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
        '404':
          description: Notification template for instance {id} is not found
  /v1/notificationTemplates/helpers:
    get:
      tags:
      - Notification Templates
      summary: Get available Handlebars helpers
      description: Returns a list of all available Handlebars helpers with their usage information. Requires VIEW_BASIC permission for notification templates.
      operationId: getHandlebarsHelpers
      responses:
        '200':
          description: List of Handlebars helpers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlebarsHelperMetadata'
  /v1/notificationTemplates/{id}/versions/{version}:
    get:
      tags:
      - Notification Templates
      summary: Get a version of the notification template
      description: Get a version of the notification template by given `Id`
      operationId: getSpecificNotificationTemplateVersion
      parameters:
      - name: id
        in: path
        description: Id of the notification template
        required: true
        schema:
          type: string
          format: uuid
      - name: version
        in: path
        description: Notification template version number in the form `major`.`minor`
        required: true
        schema:
          type: string
          example: 0.1 or 1.1
      responses:
        '200':
          description: notification template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
        '404':
          description: Notification template for instance {id} and version {version} is not found
  /v1/notificationTemplates/history:
    get:
      tags:
      - Notification Templates
      summary: List all entity versions within a time range
      description: 'Get a paginated list of all entity versions within a given time range specified by `startTs` and `endTs` in milliseconds since epoch. '
      operationId: listAllEntityVersionsByTimestamp_28
      parameters:
      - name: startTs
        in: query
        description: Start timestamp in milliseconds since epoch
        required: true
        schema:
          type: integer
          format: int64
      - name: endTs
        in: query
        description: End timestamp in milliseconds since epoch
        required: true
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: Limit the number of entity returned (1 to 1000000, default = 10)
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
          default: 10
      - name: before
        in: query
        description: Returns list of entity versions before this cursor
        schema:
          type: string
      - name: after
        in: query
        description: Returns list of entity versions after this cursor
        schema:
          type: string
      responses:
        '200':
          description: List of all versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultList'
  /v1/notificationTemplates/{id}/versions:
    get:
      tags:
      - Notification Templates
      summary: List notification template versions
      description: Get a list of all the versions of a notification template identified by `Id`
      operationId: listAllNotificationTemplateVersions
      parameters:
      - name: id
        in: path
        description: Id of the notification template
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of notification template versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityHistory'
  /v1/notificationTemplates/render:
    post:
      tags:
      - Notification Templates
      summary: Render notification template with mock data
      description: 'Generates mock ChangeEvent data for the specified resource and eventType, then renders the template. Returns the rendered subject and body for preview. Does not send to any destination. Requires any of: CREATE, EDIT_ALL, EDIT_USER_NOTIFICATION_TEMPLATE.'
      operationId: renderNotificationTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationTemplateRenderRequest'
      responses:
        '200':
          description: Rendering result with validation and render outputs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplateRenderResponse'
        '400':
          description: Bad request
  /v1/notificationTemplates/name/{fqn}/reset:
    put:
      tags:
      - Notification Templates
      summary: Reset a notification template to its default state by fully qualified name
      description: Reset a SYSTEM notification template to its original default state from seed data. Only SYSTEM templates can be reset. This operation requires EDIT permissions.
      operationId: resetNotificationTemplateByFQN
      parameters:
      - name: fqn
        in: path
        description: Fully qualified name of the notification template to reset
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Template successfully reset to default
        '400':
          description: Bad request - Template cannot be reset (not a SYSTEM template)
        '403':
          description: Forbidden - proper EDIT permission required
        '404':
          description: Notification template for instance {fqn} is not found
  /v1/notificationTemplates/{id}/reset:
    put:
      tags:
      - Notification Templates
      summary: Reset a notification template to its default state by Id
      description: Reset a SYSTEM notification template to its original default state from seed data. Only SYSTEM templates can be reset. This operation requires EDIT permissions.
      operationId: resetNotificationTemplateById
      parameters:
      - name: id
        in: path
        description: Id of the notification template
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Template successfully reset to default
        '400':
          description: Bad request - Template cannot be reset (not a SYSTEM template)
        '403':
          description: Forbidden - proper EDIT permission required
        '404':
          description: Notification template for instance {id} is not found
  /v1/notificationTemplates/restore:
    put:
      tags:
      - Notification Templates
      summary: Restore a soft deleted notification template
      description: Restore a soft deleted notification template.
      operationId: restore_20
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreEntity'
      responses:
        '200':
          description: Successfully restored the notification template
  /v1/notificationTemplates/send:
    post:
      tags:
      - Notification Templates
      summary: Validate and send notification template to external destinations
      description: 'Validates template syntax, generates mock ChangeEvent data, and sends to specified external destinations. Returns validation status only. Delivery errors are logged server-side. Only external destinations (Email, Slack, Teams, GChat, Webhook) are supported. Requires any of: CREATE, EDIT_ALL, EDIT_USER_NOTIFICATION_TEMPLATE.'
      operationId: sendNotificationTemplateTest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationTemplateSendRequest'
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplateValidationResponse'
        '400':
          description: Bad request or validation failure
  /v1/notificationTemplates/validate:
    post:
      tags:
      - Notification Templates
      summary: Validate notification template syntax
      description: 'Validates only the Handlebars syntax of template subject and body without generating mock data or sending. Requires any of: CREATE, EDIT_ALL, EDIT_USER_NOTIFICATION_TEMPLATE.'
      operationId: validateNotificationTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationTemplateValidationRequest'
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplateValidationResponse'
        '400':
          description: Bad request
components:
  schemas:
    TagLabelRecognizerMetadata:
      required:
      - recognizerId
      - recognizerName
      - score
      type: object
      properties:
        recognizerId:
          type: string
          format: uuid
        recognizerName:
          type: string
        score:
          type: number
          format: double
        target:
          type: string
          enum:
          - content
          - column_name
        patterns:
          type: array
          items:
            $ref: '#/components/schemas/PatternMatch'
    TemplateRenderResult:
      required:
      - body
      - subject
      type: object
      properties:
        subject:
          type: string
        body:
          type: string
    NotificationTemplateValidationResponse:
      required:
      - isValid
      type: object
      properties:
        isValid:
          type: boolean
        subjectError:
          type: string
        bodyError:
          type: string
    NotificationTemplateList:
      required:
      - data
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NotificationTemplate'
        paging:
          $ref: '#/components/schemas/Paging'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/EntityError'
        warningsCount:
          type: integer
          format: int32
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/EntityError'
    CreateNotificationTemplate:
      required:
      - name
      - templateBody
      - templateSubject
      type: object
      properties:
        name:
          maxLength: 256
          minLength: 1
          pattern: ^((?!::).)*$
          type: string
        displayName:
          type: string
        description:
          type: string
        templateSubject:
          maxLength: 255
          minLength: 1
          type: string
        templateBody:
          maxLength: 65536
          minLength: 1
          type: string
        owners:
          type: array
          items:
            $ref: '#/components/schemas/EntityReference'
        domains:
          type: array
          items:
            type: string
        extension:
          type: object
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagLabel'
        reviewers:
          type: array
          items:
            $ref: '#/components/schemas/EntityReference'
        dataProducts:
          type: array
          items:
            type: string
        lifeCycle:
          $ref: '#/components/schemas/LifeCycle'
    ChangeSummaryMap:
      type: object
    AccessDetails:
      required:
      - timestamp
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
        accessedBy:
          $ref: '#/components/schemas/EntityReference'
        accessedByAProcess:
          type: string
    RestoreEntity:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          format: uuid
    CoverImage:
      type: object
      properties:
        url:
          type: string
        position:
          type: string
    FieldChange:
      type: object
      properties:
        name:
          type: string
        oldValue:
          type: object
        newValue:
          type: object
    LifeCycle:
      type: object
      properties:
        created:
          $ref: '#/components/schemas/AccessDetails'
        updated:
          $ref: '#/components/schemas/AccessDetails'
        accessed:
          $ref: '#/components/schemas/AccessDetails'
    EntityHistory:
      required:
      - entityType
      - versions
      type: object
      properties:
        entityType:
          type: string
        versions:
          type: array
          items:
            type: object
    AssetCertification:
      required:
      - appliedDate
      - expiryDate
      - tagLabel
      type: object
      properties:
        tagLabel:
          $ref: '#/components/schemas/TagLabel'
        appliedDate:
          type: integer
          format: int64
        expiryDate:
          type: integer
          format: int64
    ResultList:
      required:
      - data
      type: object
      properties:
        data:
          type: array
          items:
            type: object
        paging:
          $ref: '#/components/schemas/Paging'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/EntityError'
        warningsCount:
          type: integer
          format: int32
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/EntityError'
    Paging:
      required:
      - total
      type: object
      properties:
        before:
          type: string
        after:
          type: string
        offset:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
    HandlebarsHelperMetadata:
      required:
      - description
      - name
      - usages
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        cursorOffset:
          type: integer
          format: int32
        usages:
          type: array
          items:
            $ref: '#/components/schemas/HandlebarsHelperUsage'
    JsonPatch:
      type: object
    ChangeDescription:
      type: object
      properties:
        fieldsAdded:
          type: array
          items:
            $ref: '#/components/schemas/FieldChange'
        fieldsUpdated:
          type: array
          items:
            $ref: '#/components/schemas/FieldChange'
        fieldsDeleted:
          type: array
          items:
            $ref: '#/components/schemas/FieldChange'
        previousVersion:
          type: number
          format: double
        changeSummary:
          $ref: '#/components/schemas/ChangeSummaryMap'
    NotificationTemplateValidationRequest:
      required:
      - templateBody
      - templateSubject
      type: object
      properties:
        templateBody:
          maxLength: 65536
          minLength: 1
          type: string
        templateSubject:
          maxLength: 256
          minLength: 1
          type: string
    NotificationTemplateSendRequest:
      required:
      - destinations
      - renderRequest
      type: object
      properties:
        renderRequest:
          $ref: '#/components/schemas/NotificationTemplateRenderRequest'
        destinations:
          maxItems: 2147483647
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionDestination'
    UsageStats:
      required:
      - count
      type: object
      properties:
        count:
          minimum: 0
          exclusiveMinimum: false
          type: integer
          format: int32
        percentileRank:
          type: number
          format: double
    SubscriptionDestination:
      required:
      - category
      - type
      type: object
      properties:
        id:
          type: string
          format: uuid
        category:
          type: string
          enum:
          - Users
          - Teams
          - Admins
          - Assignees
          - Owners
          - Mentions
          - Followers
          - External
        type:
          type: string
          enum:
          - Webhook
          - Slack
          - MsTeams
          - GChat
          - Email
          - ActivityFeed
          - GovernanceWorkflowChangeEvent
        statusDetails:
          type: object
        timeout:
          type: integer
          format: int32
        readTimeout:
          type: integer
          format: int32
        enabled:
          type: boolean
        config:
          type: object
        notifyDownstream:
          type: boolean
        downstreamDepth:
          minimum: 1
          exclusiveMinimum: false
          type: integer
          format: int32
    Style:
      type: object
      properties:
        color:
          type: string
        iconURL:
          type: string
        coverImage:
          $ref: '#/components/schemas/CoverImage'
    Votes:
      type: object
      properties:
        upVotes:
          type: integer
          format: int32
        downVotes:
          type: integer
          format: int32
        upVoters:
          type: array
          items:
            $ref: '#/components/schemas/EntityReference'
        downVoters:
          type: array
          items:
            $ref: '#/components/schemas/EntityReference'
    TagLabel:
      required:
      - labelType
      - source
      - state
      - tagFQN
      type: object
      properties:
        tagFQN:
          type: string
        name:
          type: string
        displayName:
          type: string
        description:
          type: string
        style:
          $ref: '#/components/schemas/Style'
        source:
          type: string
          enum:
          - Classification
          - Glossary
        labelType:
          type: string
          enum:
          - Manual
          - Propagated
          - Automated
          - Derived
          - Generated
        state:
          type: string
          enum:
          - Suggested
          - Confirmed
        href:
          type: string
          format: uri
        reason:
          type: string
        appliedAt:
          type: string
          format: date-time
        appliedBy:
          type: string
        metadata:
          $ref: '#/components/schemas/TagLabelMetadata'
    PatternMatch:
      required:
      - name
      - score
      type: object
      properties:
        name:
          type: string
        regex:
          type: string
        score:
          type: number
          format: double
    NotificationTemplateRenderRequest:
      required:
      - resource
      - templateBody
      - templateSubject
      type: object
      properties:
        templateSubject:
          maxLength: 255
          minLength: 1
          type: string
        templateBody:
          maxLength: 65536
          minLength: 1
          type: string
        resource:
          maxLength: 128
          minLength: 1
          type: string
        eventType:
          type: string
          enum:
          - entityCreated
          - entityUpdated
          - entityFieldsChanged
          - entityNoChange
          - entitySoftDeleted
          - entityDeleted
          - entityRestored
          - threadCreated
          - threadUpdated
          - postCreated
          - postUpdated
          - taskResolved
          - taskClosed
          - logicalTestCaseAdded
          - suggestionCreated
          - suggestionUpdated
          - suggestionAccepted
          - suggestionRejected
          - suggestionDeleted
          - userLogin
          - userLogout
    HandlebarsHelperUsage:
      required:
      - example
      - syntax
      type: object
      properties:
        syntax:
          type: string
        example:
          type: string
    TagLabelMetadata:
      type: object
      properties:
        recognizer:
          $ref: '#/components/schemas/TagLabelRecognizerMetadata'
        expiryDate:
          type: i

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openmetadata/refs/heads/main/openapi/openmetadata-notification-templates-api-openapi.yml