Knock Workflows API
A workflow is a structured set of steps that is triggered to produce notifications sent over channels.
OpenAPI Specification
openapi: 3.0.0
info:
title: Knock Audiences Workflows API
version: '1.0'
description: An Audience is a segment of users.
servers:
- url: https://api.knock.app
variables: {}
security:
- BearerAuth: []
tags:
- description: A workflow is a structured set of steps that is triggered to produce notifications sent over channels.
name: Workflows
paths:
/v1/workflows/{key}/trigger:
post:
callbacks: {}
description: Trigger a workflow (specified by the key) to run for the given recipients, using the parameters provided. Returns an identifier for the workflow run request. All workflow runs are executed asynchronously. This endpoint also handles [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients) for the `actor`, `recipient`, and `tenant` fields.
operationId: triggerWorkflow (2)
parameters:
- description: Key of the workflow to trigger.
in: path
name: key
required: true
schema:
type: string
x-struct: null
x-validate: null
requestBody:
content:
application/json:
example:
actor: mr_dna
cancellation_key: isla_nublar_incident_1993
data:
affected_areas:
- visitor_center
- raptor_pen
- trex_paddock
attraction_id: paddock_rex_01
evacuation_protocol: active
message: Life finds a way
severity: critical
system_status: fences_failing
recipients:
- dr_grant
- dr_sattler
- dr_malcolm
tenant: ingen_isla_nublar
schema:
$ref: '#/components/schemas/TriggerWorkflowRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerWorkflowResponse'
description: OK
summary: Trigger workflow
tags:
- Workflows
x-idempotent: true
x-ratelimit-tier: 5
/v1/workflows/{key}/cancel:
post:
callbacks: {}
description: When invoked for a workflow using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optionally be provided one or more recipients to scope the request to.
operationId: cancelWorkflow
parameters:
- description: The key of the workflow to cancel.
in: path
name: key
required: true
schema:
type: string
x-struct: null
x-validate: null
requestBody:
content:
application/json:
example:
cancellation_key: cancel-workflow-123
recipients:
- jhammond
schema:
$ref: '#/components/schemas/CancelWorkflowRequest'
description: Params
required: true
responses:
'204':
description: No Content
summary: Cancel workflow
tags:
- Workflows
x-ratelimit-tier: 5
components:
schemas:
DiscordIncomingWebhookConnection:
description: Discord incoming webhook connection.
example:
incoming_webhook:
url: https://example.com/webhook
properties:
incoming_webhook:
description: Discord incoming webhook object.
properties:
url:
description: Incoming webhook URL.
example: https://example.com/webhook
type: string
x-struct: null
x-validate: null
required:
- url
type: object
x-struct: null
x-validate: null
required:
- incoming_webhook
title: DiscordIncomingWebhookConnection
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData.IncomingWebhookConnection
x-validate: null
TenantRequest:
additionalProperties: true
description: A tenant to be set in the system. You can supply any additional properties on the tenant object.
example:
id: tenant_123
name: ACME Corp, Inc.
settings:
branding:
icon_url: https://example.com/icon.png
logo_url: https://example.com/logo.png
primary_color: '#000000'
primary_color_contrast: '#FFFFFF'
properties:
channel_data:
description: The channel data for the tenant.
oneOf:
- nullable: true
x-struct: null
x-validate: null
- $ref: '#/components/schemas/InlineChannelDataRequest'
x-struct: null
x-validate: null
id:
description: The unique identifier for the tenant.
type: string
x-struct: null
x-validate: null
name:
description: An optional name for the tenant.
nullable: true
type: string
x-struct: null
x-validate: null
preferences:
description: The preferences for the tenant.
oneOf:
- nullable: true
x-struct: null
x-validate: null
- $ref: '#/components/schemas/InlinePreferenceSetRequest'
x-struct: null
x-validate: null
settings:
description: The settings for the tenant. Includes branding and preference set.
properties:
branding:
description: The branding for the tenant.
properties:
icon_url:
description: The icon URL for the tenant. Must point to a valid image with an image MIME type.
nullable: true
type: string
x-struct: null
x-validate: null
logo_url:
description: The logo URL for the tenant. Must point to a valid image with an image MIME type.
nullable: true
type: string
x-struct: null
x-validate: null
primary_color:
description: The primary color for the tenant, provided as a hex value.
nullable: true
type: string
x-struct: null
x-validate: null
primary_color_contrast:
description: The primary color contrast for the tenant, provided as a hex value.
nullable: true
type: string
x-struct: null
x-validate: null
type: object
x-struct: null
x-validate: null
preference_set:
description: The preference set for the tenant. Used to override the default preference set.
oneOf:
- nullable: true
x-struct: null
x-validate: null
- $ref: '#/components/schemas/PreferenceSetRequest'
x-struct: null
x-validate: null
type: object
x-struct: null
x-validate: null
required:
- id
title: TenantRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.TenantRequest
x-validate: null
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
nullable: false
title: UserReference
type: string
x-struct: null
x-validate: null
- 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
nullable: false
type: string
x-struct: null
x-validate: null
id:
description: An identifier for the recipient object.
example: project_123
nullable: false
type: string
x-struct: null
x-validate: null
title: ObjectReference
type: object
x-struct: null
x-validate: null
title: RecipientReference
x-struct: Elixir.SwitchboardWeb.V1.Specs.RecipientReference
x-validate: null
InlinePreferenceSetRequest:
additionalProperties:
$ref: '#/components/schemas/PreferenceSetRequest'
description: Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
example:
default:
categories:
transactional:
channel_types:
email: false
channel_types:
email: true
title: InlinePreferenceSetRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.InlinePreferenceSetRequest
x-validate: null
InlineTenantRequest:
description: An request to set a tenant inline.
example:
id: tenant_1
name: Acme Corp, Inc.
oneOf:
- description: The unique identifier for the tenant.
type: string
x-struct: null
x-validate: null
- $ref: '#/components/schemas/TenantRequest'
title: InlineTenantRequest
x-struct: Elixir.SwitchboardWeb.V1.Specs.InlineTenantRequest
x-validate: null
MsTeamsChannelData:
description: Microsoft Teams channel data.
example:
connections:
- ms_teams_channel_id: 123e4567-e89b-12d3-a456-426614174000
ms_teams_team_id: 123e4567-e89b-12d3-a456-426614174000
ms_teams_tenant_id: null
ms_teams_user_id: null
ms_teams_tenant_id: null
properties:
connections:
description: List of Microsoft Teams connections.
items:
oneOf:
- $ref: '#/components/schemas/MsTeamsTokenConnection'
- $ref: '#/components/schemas/MsTeamsIncomingWebhookConnection'
type: object
x-struct: null
x-validate: null
nullable: false
type: array
x-struct: null
x-validate: null
ms_teams_tenant_id:
description: Microsoft Teams tenant ID.
example: 123e4567-e89b-12d3-a456-426614174000
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
required:
- connections
title: MsTeamsChannelData
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.MsTeamsChannelData
x-validate: null
MsTeamsTokenConnection:
description: Microsoft Teams token connection.
example:
ms_teams_channel_id: 123e4567-e89b-12d3-a456-426614174000
ms_teams_team_id: 123e4567-e89b-12d3-a456-426614174000
ms_teams_tenant_id: null
ms_teams_user_id: null
properties:
ms_teams_channel_id:
description: Microsoft Teams channel ID.
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
ms_teams_team_id:
description: Microsoft Teams team ID.
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
ms_teams_tenant_id:
description: Microsoft Teams tenant ID.
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
ms_teams_user_id:
description: Microsoft Teams user ID.
format: uuid
nullable: true
type: string
x-struct: null
x-validate: null
title: MsTeamsTokenConnection
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.MsTeamsChannelData.TokenConnection
x-validate: null
TriggerWorkflowResponse:
description: The response from triggering a workflow.
example:
workflow_run_id: 123e4567-e89b-12d3-a456-426614174000
properties:
workflow_run_id:
description: This value allows you to track individual messages associated with this trigger request.
example: 123e4567-e89b-12d3-a456-426614174000
format: uuid
type: string
x-struct: null
x-validate: null
required:
- workflow_run_id
title: TriggerWorkflowResponse
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.TriggerWorkflowResponse
x-validate: null
MsTeamsIncomingWebhookConnection:
description: Microsoft Teams incoming webhook connection.
example:
incoming_webhook:
url: https://example.com/webhook
properties:
incoming_webhook:
description: Microsoft Teams incoming webhook.
properties:
url:
description: Microsoft Teams incoming webhook URL.
example: https://example.com/webhook
type: string
x-struct: null
x-validate: null
required:
- url
type: object
x-struct: null
x-validate: null
required:
- incoming_webhook
title: MsTeamsIncomingWebhookConnection
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.MsTeamsChannelData.IncomingWebhookConnection
x-validate: null
OneSignalChannelDataPlayerIdsOnly:
description: OneSignal channel data.
example:
player_ids:
- 123e4567-e89b-12d3-a456-426614174000
properties:
player_ids:
description: A list of OneSignal player IDs.
example:
- 123e4567-e89b-12d3-a456-426614174000
items:
description: OneSignal player ID.
format: uuid
nullable: false
type: string
x-struct: null
x-validate: null
nullable: false
type: array
x-struct: null
x-validate: null
required:
- player_ids
title: OneSignalChannelDataPlayerIdsOnly
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.OneSignalChannelDataPlayerIdsOnly
x-validate: null
InlineIdentifyObjectRequest:
additionalProperties: true
description: A custom [Object](/concepts/objects) entity which belongs to a collection.
example:
collection: projects
id: project_1
name: My project
properties:
channel_data:
description: An optional set of [channel data](/managing-recipients/setting-channel-data) for the object. This is a list of `ChannelData` objects.
oneOf:
- $ref: '#/components/schemas/InlineChannelDataRequest'
- nullable: true
x-struct: null
x-validate: null
x-struct: null
x-validate: null
collection:
description: The collection this object belongs to.
nullable: false
type: string
x-struct: null
x-validate: null
created_at:
description: Timestamp when the resource was created.
format: date-time
nullable: true
type: string
x-struct: null
x-validate: null
id:
description: Unique identifier for the object.
nullable: false
type: string
x-struct: null
x-validate: null
name:
description: An optional name for the object.
nullable: true
type: string
x-struct: null
x-validate: null
preferences:
description: An optional set of [preferences](/concepts/preferences) for the object.
oneOf:
- $ref: '#/components/schemas/InlinePreferenceSetRequest'
- nullable: true
x-struct: null
x-validate: null
x-struct: null
x-validate: null
required:
- id
- collection
title: InlineIdentifyObjectRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.InlineIdentifyObjectRequest
x-validate: null
PreferenceSetWorkflowCategorySetting:
description: Workflow or category preferences within a preference set
example:
channel_types:
email: false
channels:
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
oneOf:
- example: false
type: boolean
x-struct: null
x-validate: null
- description: The settings object for a workflow or category, where you can specify channel types or conditions.
example:
channel_types:
email: false
channels:
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
conditions: null
properties:
channel_types:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannelTypes'
- nullable: true
x-struct: null
x-validate: null
description: An object where the key is the channel type and the values are the preference settings for that channel type.
x-struct: null
x-validate: null
channels:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannels'
- nullable: true
x-struct: null
x-validate: null
description: An object where the key is the channel ID and the values are the preference settings for that channel ID.
x-struct: null
x-validate: null
conditions:
description: A list of conditions to apply to a channel type.
items:
$ref: '#/components/schemas/Condition'
nullable: true
type: array
x-struct: null
x-validate: null
title: PreferenceSetWorkflowCategorySettingObject
type: object
x-struct: null
x-validate: null
title: PreferenceSetWorkflowCategorySetting
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSetWorkflowCategorySetting
x-validate: null
PreferenceSetChannelTypes:
description: Channel type preferences.
example:
email: true
sms:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
properties:
chat:
description: Whether the channel type is enabled for the preference set.
oneOf:
- type: boolean
x-struct: null
x-validate: null
- $ref: '#/components/schemas/PreferenceSetChannelTypeSetting'
x-struct: null
x-validate: null
email:
description: Whether the channel type is enabled for the preference set.
oneOf:
- type: boolean
x-struct: null
x-validate: null
- $ref: '#/components/schemas/PreferenceSetChannelTypeSetting'
x-struct: null
x-validate: null
http:
description: Whether the channel type is enabled for the preference set.
oneOf:
- type: boolean
x-struct: null
x-validate: null
- $ref: '#/components/schemas/PreferenceSetChannelTypeSetting'
x-struct: null
x-validate: null
in_app_feed:
description: Whether the channel type is enabled for the preference set.
oneOf:
- type: boolean
x-struct: null
x-validate: null
- $ref: '#/components/schemas/PreferenceSetChannelTypeSetting'
x-struct: null
x-validate: null
push:
description: Whether the channel type is enabled for the preference set.
oneOf:
- type: boolean
x-struct: null
x-validate: null
- $ref: '#/components/schemas/PreferenceSetChannelTypeSetting'
x-struct: null
x-validate: null
sms:
description: Whether the channel type is enabled for the preference set.
oneOf:
- type: boolean
x-struct: null
x-validate: null
- $ref: '#/components/schemas/PreferenceSetChannelTypeSetting'
x-struct: null
x-validate: null
title: PreferenceSetChannelTypes
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSetChannelTypes
x-validate: null
PreferenceSetChannelTypeSetting:
description: A set of settings for a channel type. Currently, this can only be a list of conditions to apply.
example:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
properties:
conditions:
description: A list of conditions to apply to a channel type.
items:
$ref: '#/components/schemas/Condition'
type: array
x-struct: null
x-validate: null
required:
- conditions
title: PreferenceSetChannelTypeSetting
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSetChannelTypes.PreferenceSetChannelTypeSetting
x-validate: null
CancelWorkflowRequest:
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: cancel-workflow-123
recipients:
- jhammond
properties:
cancellation_key:
description: An optional 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
x-struct: null
x-validate: null
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'
nullable: true
type: array
x-struct: null
x-validate: null
required:
- cancellation_key
title: CancelWorkflowRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.CancelWorkflowRequest
x-validate: null
PreferenceSetRequest:
description: A request to set a preference set for a recipient.
example:
__persistence_strategy__: merge
categories:
marketing: false
transactional:
channel_types:
email: false
channel_types:
email: true
channels:
2f641633-95d3-4555-9222-9f1eb7888a80:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
commercial_subscribed: true
workflows:
dinosaurs-loose:
channel_types:
email: false
properties:
__persistence_strategy__:
description: Controls how the preference set is persisted. 'replace' will completely replace the preference set, 'merge' will merge with existing preferences.
enum:
- merge
- replace
type: string
x-struct: null
x-validate: null
categories:
anyOf:
- additionalProperties:
$ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
description: An object where the key is the category and the values are the preference settings for that category.
example:
marketing:
channel_types:
email: false
transactional: true
title: PreferenceSetRequestCategories
type: object
x-struct: null
x-validate: null
- nullable: true
x-struct: null
x-validate: null
description: An object where the key is the category and the values are the preference settings for that category.
x-struct: null
x-validate: null
channel_types:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannelTypes'
- nullable: true
x-struct: null
x-validate: null
description: An object where the key is the channel type and the values are the preference settings for that channel type.
x-struct: null
x-validate: null
channels:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannels'
- nullable: true
x-struct: null
x-validate: null
description: An object where the key is the channel ID and the values are the preference settings for that channel ID.
x-struct: null
x-validate: null
commercial_subscribed:
description: Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
nullable: true
type: boolean
x-struct: null
x-validate: null
workflows:
anyOf:
- additionalProperties:
$ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
description: An object where the key is the workflow key and the values are the preference settings for that workflow.
example:
dinosaurs-loose:
channel_types:
email: false
sms: true
welcome-sequence: true
title: PreferenceSetRequestWorkflows
type: object
x-struct: null
x-validate: null
- nullable: true
x-struct: null
x-validate: null
description: An object where the key is the workflow key and the values are the preference settings for that workflow.
x-struct: null
x-validate: null
title: PreferenceSetRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSetRequest
x-validate: null
AWSSNSPushChannelDataTargetARNsOnly:
description: AWS SNS push channel data.
example:
target_arns:
- arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3
properties:
target_arns:
description: A list of platform endpoint ARNs. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).
example:
- arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3
items:
description: The ARN of a platform endpoint associated with a platform application and a device token. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).
nullable: false
type: string
x-struct: null
x-validate: null
nullable: false
type: array
x-struct: null
x-validate: null
required:
- target_arns
title: AWSSNSPushChannelDataTargetARNsOnly
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.AWSSNSPushChannelDataTargetARNsOnly
x-validate: null
DiscordChannelConnection:
description: Discord channel connection.
example:
channel_id: '123456789012345678'
properties:
channel_id:
description: Discord channel ID.
example: '123456789012345678'
type: string
x-struct: null
x-validate: null
required:
- channel_id
title: DiscordChannelConnection
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData.ChannelConnection
x-validate: null
AWSSNSPushChannelDataDevicesOnly:
description: AWS SNS push channel data.
example:
devices:
- locale: en-US
target_arn: arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3
timezone: America/Los_Angeles
properties:
devices:
description: A list of devices. Each device contains a target_arn, and optionally a locale and timezone.
items:
properties:
locale:
description: The locale of the object. Used for [message localization](/concepts/translations).
nullable: true
type: string
x-struct: null
x-validate: null
target_arn:
description: The ARN of a platform endpoint associated with a platform application and a device token. See [Setting up an Amazon SNS platform endpoint for mobile notifications](https://docs.aws.amazon.com/sns/latest/dg/mobile-platform-endpoint.html).
type: string
x-struct: null
x-validate: null
timezone:
description: The timezone of the object. Must be a valid [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Used for [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
nullable: true
type: string
x-struct: null
x-validate: null
required:
- target_arn
type: object
x-struct: null
x-validate: null
nullable: false
type: array
x-struct: null
x-validate: null
required:
- devices
title: AWSSNSPushChannelDataDevicesOnly
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.AWSSNSPushChannelDataDevicesOnly
x-validate: null
InlineIdentifyUserRequest:
additionalProperties: true
description: A set of parameters to inline-identify a user with. Inline identifying the user will ensure that the user is available before the request is executed in Knock. It will perform an upsert for the user you're supplying, replacing any properties specified.
example:
channel_data:
97c5837d-c65c-4d54-aa39-080eeb81c69d:
tokens:
- push_token_123
email: jane@ingen.net
id: user_1
name: Jane Doe
preferences:
default:
channel_types:
email: true
workflows:
dinosaurs-loose:
channel_types:
email: true
timezone: America/New_York
properties:
avatar:
description: A URL for the avatar of the user.
nullable: true
type: string
x-struct: null
x-validate: null
channel_data:
allOf:
- $ref: '#/components/schemas/InlineChannelDataRequest'
description: Channel-specific information that's needed to deliver a notification to an end provider.
nullable: true
x-struct: null
x-validate: null
created_at:
description: The creation date of the user from your system.
format: date-time
nullable: true
type: string
x-struct: null
x-validate: null
email:
description: The primary email address for the user.
nullable: true
type: string
x-struct: null
x-validate: null
id:
description: The unique identifier of the user.
nullable: false
type: string
x-struct: null
x-validate: null
locale:
descriptio
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock/refs/heads/main/openapi/knock-workflows-api-openapi.yml