Knock Workflow Triggers API

openapi: 3.2.0
info:
  title: Knock Workflow Triggers API
  version: '1.0'
  description: Operations for triggering and canceling workflow executions.
servers:
- url: https://api.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- description: Operations for triggering and canceling workflow executions.
  name: Workflow Triggers
paths:
  /v1/notify:
    post:
      callbacks: {}
      description: Triggers a workflow with the given key, actor, recipients, and optional data.
      operationId: triggerWorkflow(2)
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notify_Request'
        description: Notify Payload
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notify_Response'
          description: OK
      summary: Trigger workflow
      tags:
      - Workflow Triggers
      x-ratelimit-tier: 3
      x-operation-id-source: normalized
      x-operation-id-original: triggerWorkflow (2)
  /v1/notify/cancel:
    post:
      callbacks: {}
      description: Cancels a previously triggered workflow using the provided cancellation key.
      operationId: cancelWorkflow
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Cancel_Request'
        description: Cancel Payload
        required: true
      responses:
        '204':
          description: No Content
      summary: Cancel workflow
      tags:
      - Workflow Triggers
      x-ratelimit-tier: 3
components:
  schemas:
    Notify_Request:
      description: A request to trigger a notification workflow.
      example:
        actor: user_123
        cancellation_key: comment_123
        data:
          comment: Great work on this feature!
          url: https://example.com/projects/123/comments/456
        name: new-comment
        recipients:
        - user_456
        - collection: projects
          id: project_789
      properties:
        actor:
          $ref: '#/components/schemas/RecipientReference'
        cancellation_key:
          description: A key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.
          type:
          - string
          - 'null'
        data:
          additionalProperties: true
          description: An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full `data` payload. Any individual string value greater than 1024 bytes in length will be [truncated](/developer-tools/api-logs#log-truncation) in your logs.
          type:
          - object
          - 'null'
        name:
          description: The key of the workflow to trigger.
          type: string
        recipients:
          description: A list of recipients.
          items:
            $ref: '#/components/schemas/RecipientReference'
          type: array
      required:
      - name
      - actor
      - recipients
      title: Notify Request
      type: object
    Notify_Response:
      description: The response from triggering a workflow.
      example:
        result_id: wf_1234567890abcdef
      properties:
        result_id:
          description: This value allows you to track individual messages associated with this trigger request.
          type: string
      required:
      - result_id
      title: Notify Response
      type: object
    Cancel_Request:
      description: When invoked using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optionally provide one or more recipients to scope the request to.
      example:
        cancellation_key: comment_123
        name: new-comment
        recipients:
        - user_456
      properties:
        cancellation_key:
          description: A key that is used to reference a specific workflow trigger request when issuing a [workflow cancellation](/send-notifications/canceling-workflows) request. Must be provided while triggering a workflow in order to enable subsequent cancellation. Should be unique across trigger requests to avoid unintentional cancellations.
          type: string
        name:
          description: The key of the workflow to cancel.
          type: string
        recipients:
          description: A list of recipients to cancel the notification for. If omitted, cancels for all recipients associated with the cancellation key.
          items:
            $ref: '#/components/schemas/RecipientReference'
          type: array
      required:
      - name
      - cancellation_key
      title: Cancel Request
      type: object
    RecipientReference:
      description: A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
      example: user_123
      oneOf:
      - description: The ID of the user which is used as the reference for the recipient.
        example: user_123
        title: UserReference
        type: string
      - description: A reference to a recipient object.
        example:
          collection: projects
          id: project_123
        properties:
          collection:
            description: The collection the recipient object belongs to.
            example: projects
            type: string
          id:
            description: An identifier for the recipient object.
            example: project_123
            type: string
        title: ObjectReference
        type: object
      title: RecipientReference
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
x-provenance:
  method: harvested
  publisher: Knock
  source: https://knock.app/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)