Knock Workflows API
Workflows let you express your cross-channel notification logic.
Knock Workflows API is one of 35 APIs that Knock publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 2 JSON Schema definitions.
Tagged areas include Workflows. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and 2 JSON Schemas.
This API exposes 9 operations across 8 paths, and defines 88 schemas. It is described by OpenAPI 3.0.3, at version 1.0.
Requests are made against a single base URL, https://api.knock.app.
9 operations
8 paths
88 schemas
2 GET3 POST4 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
Knock Workflows API declares
1 security scheme
for authenticating requests.
It accepts HTTP bearer tokens (BearerAuth).
By default, every request must be authenticated.
BearerAuth— Knock API key as a Bearer token. Use a public key (pk...) for client-side requests or a secret key (sk...) for server-side.
Paths & Operations 9
Across 8 paths, the API surfaces 9 operations — 2 GET, 3 POST, 4 PUT. Each is listed below with its method, path, parameters, and response codes.
Workflows 9
Workflows let you express your cross-channel notification logic.
PUT
/v1/workflows/{workflow_key}/validate
Validate a workflow
PUT
/v1/workflows/{workflow_key}/run
Run a workflow
POST
/v1/workflows/{workflow_key}/steps/{step_ref}/preview_template
Preview a workflow template
GET
/v1/workflows
List workflows
PUT
/v1/workflows/{workflow_key}/activate
Activate a workflow
GET
/v1/workflows/{workflow_key}
Get a workflow
PUT
/v1/workflows/{workflow_key}
Upsert a workflow
POST
/v1/workflows/{key}/trigger
Trigger workflow
POST
/v1/workflows/{key}/cancel
Cancel workflow
Schemas 88
The contract defines 88 schemas that model the data the API accepts and returns. The most detailed are ShowWorkflowResponse (18 properties), Workflow (16 properties), WorkflowEmailStep (11 properties), WorkflowInAppFeedStep (11 properties). Each schema is shown below with its type and property counts.
PushChannelDataTokensOnly
object
Push channel data.
1 property
1 required
TriggerWorkflowResponse
object
The response from triggering a workflow.
1 property
1 required
RecipientReference_2
A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
WebhookTemplate
object
A webhook template. By default, a webhook step will use the request settings you configured in your webhook channel. You can override this as you see fit on a…
5 properties
2 required
WorkflowInAppFeedStep
object
An in-app feed step within a workflow. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
11 properties
3 required
PreferenceSetChannels
object
Channel preferences.
WorkflowWebhookStep
object
A webhook step within a workflow to send an HTTP request to a generic channel. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
10 properties
3 required
Condition_2
object
A condition to be evaluated.
3 properties
3 required
InlineChannelDataRequest
object
A request to set channel data for a type of channel inline.
CancelWorkflowRequest
object
When invoked using a specific workflow key and cancellation key, will cancel any queued workflow runs associated with that key/cancellation key pair. Can optio…
2 properties
1 required
ConditionGroupAnyMatch
object
A group of conditions that any must be met. Can contain nested alls.
1 property
EmailPartialBlock
object
A partial block in an email template, used to render a reusable partial component.
7 properties
4 required
InAppFeedChannelSettings
object
In-app feed channel settings. Only used as configuration as part of a workflow channel step.
1 property
PreviewWorkflowTemplateResponse
object
A response to a preview workflow template request.
3 properties
3 required
AWSSNSPushChannelDataTargetARNsOnly
object
AWS SNS push channel data.
1 property
1 required
Duration
object
A duration of time, represented as a unit and a value.
2 properties
2 required
InAppFeedTemplate
object
An in-app feed template.
3 properties
1 required
ChatTemplate
object
A chat template.
3 properties
1 required
EmailDividerBlock
object
A divider block in an email template.
4 properties
1 required
InlineIdentifyUserRequest
object
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.…
10 properties
1 required
WorkflowUpdateDataStep
object
An update data function step. Merges data into the workflow's data scope for use in subsequent steps.
6 properties
3 required
AWSSNSPushChannelDataDevicesOnly
object
AWS SNS push channel data.
1 property
1 required
EmailButtonSetBlock
object
A button set block in an email template.
5 properties
2 required
EmailMarkdownBlock
object
A markdown block in an email template.
6 properties
2 required
MsTeamsIncomingWebhookConnection
object
Microsoft Teams incoming webhook connection.
1 property
1 required
PreferenceSetRequest
object
A request to set a preference set for a recipient.
6 properties
ConditionGroup
object
A group of conditions to be evaluated.
EmailChannelSettings
object
Email channel settings. Only used as configuration as part of a workflow channel step.
9 properties
WorkflowUpdateUserStep
object
An update user step. Updates properties of a specific user referenced in the workflow.
6 properties
3 required
InlineIdentifyObjectRequest
object
A custom [Object](/concepts/objects) entity which belongs to a collection.
6 properties
2 required
Workflow
object
A workflow object. Read more in the [docs](https://docs.knock.app/concepts/workflows).
16 properties
9 required
SlackIncomingWebhookConnection
object
A Slack connection incoming webhook.
1 property
1 required
PushChannelDataDevicesOnly
object
Push channel data.
1 property
1 required
WorkflowUpdateTenantStep
object
An update tenant step. Updates properties of a specific tenant referenced in the workflow.
6 properties
3 required
WorkflowAIAgentStep
object
An AI agent function step. Fetches data from an AI model and merges it into the workflow's data scope for use in later steps. Supports Liquid templating in the…
6 properties
3 required
Condition
object
A condition to be evaluated.
3 properties
2 required
PreferenceSetChannelTypes
object
Channel type preferences.
6 properties
RunWorkflowRequest
object
A request to run (test) a workflow.
5 properties
1 required
TriggerWorkflowRequest
object
A request to trigger a notification workflow.
5 properties
1 required
RecipientRequest
Specifies a recipient in a request. This can either be a user identifier (string), an inline user request (object), or an inline object request, which is deter…
WorkflowRequest
object
A workflow request for upserting a workflow.
8 properties
2 required
MemberUser
object
Information about a user within the Knock dashboard. Not to be confused with an external user (recipient) of a workflow.
6 properties
4 required
DiscordChannelConnection
object
Discord channel connection.
1 property
1 required
InlineTenantRequest
An request to set a tenant inline.
PreviewWorkflowTemplateRequest
object
A request to preview a workflow template.
4 properties
1 required
PreferenceSetWorkflowCategorySetting
object
Workflow or category preferences within a preference set
RunWorkflowResponse
object
A response to a run workflow request.
1 property
1 required
WorkflowRandomCohortStepBranch
object
A cohort branch in an experiment step.
4 properties
1 required
WorkflowChatStep
object
A chat step within a workflow. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
11 properties
3 required
InlinePreferenceSetRequest
object
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 ra…
ChatChannelSettings
object
Chat channel settings. Only used as configuration as part of a workflow channel step.
2 properties
WorkflowFetchStep
object
A fetch function step. Retrieves data from an external source and merges it into the workflow's data scope for use in later steps. Read more in the [docs](http…
6 properties
3 required
ShowWorkflowResponse
object
A workflow object.
18 properties
9 required
WorkflowBatchStep
object
A batch function step. Read more in the [docs](https://docs.knock.app/designing-workflows/batch-function).
5 properties
3 required
SmsTemplate
object
An SMS template.
2 properties
1 required
SlackChannelData
object
Slack channel data.
2 properties
1 required
PreferenceSetChannelTypeSetting
object
A set of settings for a channel type. Currently, this can only be a list of conditions to apply.
1 property
1 required
ConditionGroupAllMatch
object
A group of conditions that must all be met.
1 property
WorkflowUpdateObjectStep
object
An update object step. Updates properties of a specific object referenced in the workflow.
6 properties
3 required
WorkflowTriggerWorkflowStep
object
A workflow trigger function step. Read more in the [docs](https://docs.knock.app/designing-workflows/trigger-workflow-function).
6 properties
3 required
DiscordIncomingWebhookConnection
object
Discord incoming webhook connection.
1 property
1 required
EmailHtmlBlock
object
An HTML block in an email template.
5 properties
2 required
EmailVisualBlocks
array
The visual blocks that make up the email template.
EmailTemplate
object
An email message template.
6 properties
2 required
OneSignalChannelDataPlayerIdsOnly
object
OneSignal channel data.
1 property
1 required
WorkflowEmailStep
object
An email step within a workflow. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
11 properties
3 required
RecipientReference
object
A recipient reference, used when referencing a recipient by either their ID (for a user), or by a reference for an object.
SlackTokenConnection
object
A Slack connection token.
3 properties
PushChannelSettings
object
Push channel settings. Only used as configuration as part of a workflow channel step.
1 property
TenantRequest
object
A tenant to be set in the system. You can supply any additional properties on the tenant object.
5 properties
1 required
EmailButtonSetBlockButton
object
A button in a button set block.
5 properties
3 required
WorkflowStep
object
A step within a workflow. Each workflow step, regardless of its type, share a common set of core attributes (type, ref, name, description, conditions).
SmsChannelSettings
object
SMS channel settings. Only used as configuration as part of a workflow channel step.
1 property
DiscordChannelData
object
Discord channel data.
1 property
1 required
MsTeamsChannelData
object
Microsoft Teams channel data.
2 properties
1 required
WorkflowSmsStep
object
A SMS step within a workflow. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
11 properties
3 required
PageInfo
object
The information about a paginated result.
3 properties
1 required
WorkflowBranchStep
object
A branch function step. Read more in the [docs](https://docs.knock.app/designing-workflows/branch-function).
5 properties
3 required
PreferenceSetChannelSetting
object
A set of settings for a specific channel. Currently, this can only be a list of conditions to apply.
1 property
1 required
WorkflowDelayStep
object
A delay function step. Read more in the [docs](https://docs.knock.app/designing-workflows/delay-function).
6 properties
3 required
SendWindow
object
A send window time for a notification. Describes a single day.
4 properties
2 required
WorkflowRandomCohortStep
object
An experiment step. Deterministically assigns recipients to percentage-based cohorts for A/B testing and experimentation.
6 properties
3 required
WorkflowPushStep
object
A push step within a workflow. Read more in the [docs](https://docs.knock.app/designing-workflows/channel-step).
11 properties
3 required
PushTemplate
object
A push notification template.
3 properties
3 required
RequestTemplate
object
A request template for a fetch function step.
5 properties
2 required
EmailImageBlock
object
An image block in an email template.
8 properties
2 required
WorkflowThrottleStep
object
A throttle function step. Read more in the [docs](https://docs.knock.app/designing-workflows/throttle-function).
6 properties
3 required
MsTeamsTokenConnection
object
Microsoft Teams token connection.
4 properties
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Knock 12
Other APIs Knock publishes across the network.
Knock Outbound Webhooks
Knock Accounts API
Knock API keys API
Knock Audiences API
Knock Branches API
Knock Broadcasts API
Knock Bulk operations API
Knock Channel data API
Knock Channel Groups API
Knock Channels API
Knock Commits API
Knock Email layouts API
#Workflows