Knock Workflows API
Trigger and orchestrate notification workflows with batch, throttle and delay logic.
OpenAPI Specification
{
"components": {
"responses": {},
"schemas": {
"ListUsersResponse": {
"description": "A paginated list of users.",
"example": {
"entries": [
{
"__typename": "User",
"created_at": null,
"email": "[email protected]",
"id": "user_id",
"name": "Dr. Ian Malcolm",
"updated_at": "2024-05-22T12:00:00Z"
}
],
"page_info": {
"__typename": "PageInfo",
"after": null,
"before": null,
"page_size": 25
}
},
"properties": {
"entries": {
"description": "A list of users.",
"items": {
"$ref": "#/components/schemas/User"
},
"type": "array",
"x-struct": null,
"x-validate": null
},
"page_info": {
"$ref": "#/components/schemas/PageInfo"
}
},
"title": "ListUsersResponse",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListUsersResponse",
"x-validate": null
},
"ChannelData": {
"description": "Channel data for a given channel type.",
"example": {
"__typename": "ChannelData",
"channel_id": "123e4567-e89b-12d3-a456-426614174000",
"data": {
"devices": [
{
"locale": null,
"timezone": null,
"token": "device_1"
}
],
"tokens": [
"push_token_1"
]
}
},
"properties": {
"__typename": {
"description": "The typename of the schema.",
"example": "ChannelData",
"type": "string",
"x-struct": null,
"x-validate": null
},
"channel_id": {
"description": "The unique identifier for the channel.",
"format": "uuid",
"type": "string",
"x-struct": null,
"x-validate": null
},
"data": {
"description": "Channel data for a given channel type.",
"oneOf": [
{
"$ref": "#/components/schemas/PushChannelDataFull"
},
{
"$ref": "#/components/schemas/AWSSNSPushChannelDataFull"
},
{
"$ref": "#/components/schemas/OneSignalChannelDataPlayerIdsOnly"
},
{
"$ref": "#/components/schemas/SlackChannelData"
},
{
"$ref": "#/components/schemas/MsTeamsChannelData"
},
{
"$ref": "#/components/schemas/DiscordChannelData"
}
],
"type": "object",
"x-struct": null,
"x-validate": null
},
"provider": {
"description": "The type of provider.",
"enum": [
"push_fcm",
"push_apns",
"push_aws_sns",
"push_expo",
"push_one_signal",
"chat_slack",
"chat_ms_teams",
"chat_discord",
"http_knock_webhook"
],
"example": "push_fcm",
"type": "string",
"x-struct": null,
"x-validate": null
}
},
"required": [
"channel_id",
"data",
"__typename"
],
"title": "ChannelData",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.ChannelData",
"x-validate": null
},
"AddAudienceMembersRequest": {
"description": "A request to add a list of audience members.",
"example": {
"members": [
{
"tenant": "ingen_isla_nublar",
"user": {
"email": "[email protected]",
"id": "dr_sattler",
"name": "Dr. Ellie Sattler"
}
}
]
},
"properties": {
"members": {
"description": "A list of audience members to add. You can add up to 1,000 members per request.",
"items": {
"$ref": "#/components/schemas/AudienceMemberRequest"
},
"nullable": false,
"type": "array",
"x-struct": null,
"x-validate": null
}
},
"required": [
"members"
],
"title": "AddAudienceMembersRequest",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.AddAudienceMembersRequest",
"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
},
"Subscription": {
"description": "A subscription object.",
"example": {
"__typename": "Subscription",
"inserted_at": "2021-01-01T00:00:00Z",
"object": {
"__typename": "Object",
"collection": "assets",
"created_at": null,
"id": "specimen_25",
"properties": {
"classification": "Theropod",
"config": {
"biz": "baz",
"foo": "bar"
},
"name": "Velociraptor",
"status": "contained"
},
"updated_at": "2024-05-22T12:00:00Z"
},
"recipient": {
"__typename": "User",
"avatar": null,
"created_at": null,
"email": "[email protected]",
"id": "jane",
"name": "Jane Doe",
"phone_number": null,
"timezone": null,
"updated_at": "2024-05-22T12:00:00Z"
},
"updated_at": "2021-01-01T00:00:00Z"
},
"properties": {
"__typename": {
"description": "The typename of the schema.",
"example": "Subscription",
"type": "string",
"x-struct": null,
"x-validate": null
},
"inserted_at": {
"description": "Timestamp when the resource was created.",
"example": "2021-01-01T00:00:00Z",
"format": "date-time",
"type": "string",
"x-struct": null,
"x-validate": null
},
"object": {
"$ref": "#/components/schemas/Object"
},
"properties": {
"additionalProperties": true,
"description": "The custom properties associated with the subscription relationship.",
"nullable": true,
"type": "object",
"x-struct": null,
"x-validate": null
},
"recipient": {
"$ref": "#/components/schemas/Recipient"
},
"updated_at": {
"description": "The timestamp when the resource was last updated.",
"example": "2021-01-01T00:00:00Z",
"format": "date-time",
"type": "string",
"x-struct": null,
"x-validate": null
}
},
"required": [
"__typename",
"recipient",
"object",
"inserted_at",
"updated_at"
],
"title": "Subscription",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.Subscription",
"x-validate": null
},
"ListUserPreferenceSetsResponse": {
"description": "A list of preference sets for the user.",
"example": [
{
"categories": {
"marketing": false,
"transactional": {
"channel_types": {
"email": false
}
}
},
"channel_types": {
"email": true,
"push": false,
"sms": {
"conditions": [
{
"argument": "US",
"operator": "equal_to",
"variable": "recipient.country_code"
}
]
}
},
"commercial_subscribed": true,
"id": "default",
"workflows": null
}
],
"items": {
"$ref": "#/components/schemas/PreferenceSet"
},
"title": "ListUserPreferenceSetsResponse",
"type": "array",
"x-struct": null,
"x-validate": null
},
"ListWorkflowRecipientRunsResponse": {
"description": "A paginated list of workflow recipient runs.",
"example": {
"items": [
{
"__typename": "WorkflowRecipientRun",
"actor": "user_456",
"error_count": 0,
"id": "550e8400-e29b-41d4-a716-446655440000",
"inserted_at": "2025-01-01T00:00:00Z",
"recipient": "user_123",
"status": "completed",
"tenant": "tenant_abc",
"trigger_source": {
"cancellation_key": "comment-123-user-456",
"type": "api"
},
"updated_at": "2025-01-01T00:05:00Z",
"workflow": "comment-created",
"workflow_run_id": "660e8400-e29b-41d4-a716-446655440000"
}
],
"page_info": {
"__typename": "PageInfo",
"after": null,
"before": null,
"page_size": 25
}
},
"properties": {
"items": {
"description": "A list of workflow recipient runs.",
"items": {
"$ref": "#/components/schemas/WorkflowRecipientRun"
},
"type": "array",
"x-struct": null,
"x-validate": null
},
"page_info": {
"$ref": "#/components/schemas/PageInfo"
}
},
"required": [
"items",
"page_info"
],
"title": "ListWorkflowRecipientRunsResponse",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListWorkflowRecipientRunsResponse",
"x-validate": null
},
"PreferenceSetWorkflowCategorySettingObject": {
"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
},
"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
},
"TriggerWorkflowRequest": {
"description": "A request to trigger a notification workflow.",
"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"
},
"properties": {
"actor": {
"anyOf": [
{
"$ref": "#/components/schemas/RecipientRequest"
},
{
"nullable": true,
"x-struct": null,
"x-validate": null
}
],
"description": "A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.",
"x-struct": null,
"x-validate": null
},
"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.",
"nullable": true,
"type": "string",
"x-struct": null,
"x-validate": 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.",
"nullable": true,
"type": "object",
"x-struct": null,
"x-validate": null
},
"recipients": {
"description": "The recipients to trigger the workflow for. Can inline identify users, objects, or use a list of user IDs. Limited to 1,000 recipients.",
"items": {
"$ref": "#/components/schemas/RecipientRequest"
},
"type": "array",
"x-struct": null,
"x-validate": null
},
"tenant": {
"anyOf": [
{
"$ref": "#/components/schemas/InlineTenantRequest"
},
{
"nullable": true,
"x-struct": null,
"x-validate": null
}
],
"description": "The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.",
"x-struct": null,
"x-validate": null
}
},
"required": [
"recipients"
],
"title": "TriggerWorkflowRequest",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.TriggerWorkflowRequest",
"x-validate": null
},
"BulkIdentifyUsersRequest": {
"description": "A request to identify a list of users.",
"example": {
"users": [
{
"email": "[email protected]",
"id": "user_1",
"name": "Jane Doe",
"timezone": "America/New_York"
}
]
},
"properties": {
"users": {
"description": "A list of users.",
"items": {
"$ref": "#/components/schemas/InlineIdentifyUserRequest"
},
"type": "array",
"x-struct": null,
"x-validate": null
}
},
"required": [
"users"
],
"title": "BulkIdentifyUsersRequest",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkIdentifyUsersRequest",
"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
},
"MessageContents": {
"description": "The content of a message.",
"example": {
"__typename": "MessageContent",
"data": {
"__typename": "MessageSmsContent",
"body": "URGENT: Power failure detected in perimeter fencing. Backup generators failed to engage. Technical team dispatched. Maintain lockdown protocols.",
"to": "+15553982647"
},
"inserted_at": "1993-06-11T20:30:00Z",
"message_id": "2w3YUpTTOxuDvZFji8OMsKrG176"
},
"properties": {
"__typename": {
"description": "The typename of the schema.",
"example": "MessageContent",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
},
"data": {
"description": "Content data specific to the channel type.",
"nullable": false,
"oneOf": [
{
"$ref": "#/components/schemas/MessageEmailContent"
},
{
"$ref": "#/components/schemas/MessageSmsContent"
},
{
"$ref": "#/components/schemas/MessagePushContent"
},
{
"$ref": "#/components/schemas/MessageChatContent"
},
{
"$ref": "#/components/schemas/MessageInAppFeedContent"
}
],
"type": "object",
"x-struct": null,
"x-validate": null
},
"inserted_at": {
"description": "Timestamp when the message content was created.",
"example": "2021-01-01T00:00:00Z",
"format": "date-time",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
},
"message_id": {
"description": "The unique identifier for the message content.",
"example": "1jNaXzB2RZX3LY8wVQnfCKyPnv7",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
}
},
"required": [
"__typename",
"message_id",
"data",
"inserted_at"
],
"title": "MessageContents",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageContents",
"x-validate": null
},
"ListAudienceMembersResponse": {
"description": "A paginated list of audience members.",
"example": {
"entries": [
{
"__typename": "AudienceMember",
"added_at": "1993-06-10T14:30:00Z",
"tenant": "ingen_isla_nublar",
"user": {
"__typename": "User",
"created_at": null,
"email": "[email protected]",
"id": "dr_grant",
"name": "Dr. Alan Grant",
"updated_at": "1993-06-09T08:15:00Z"
},
"user_id": "dr_grant"
}
],
"page_info": {
"__typename": "PageInfo",
"after": null,
"before": null,
"page_size": 25
}
},
"properties": {
"entries": {
"description": "A list of audience members.",
"items": {
"$ref": "#/components/schemas/AudienceMember"
},
"type": "array",
"x-struct": null,
"x-validate": null
},
"page_info": {
"$ref": "#/components/schemas/PageInfo"
}
},
"required": [
"entries",
"page_info"
],
"title": "ListAudienceMembersResponse",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.ListAudienceMembersResponse",
"x-validate": null
},
"BulkDeleteSubscriptionsRequest": {
"description": "A request to delete subscriptions for many groups of 1 subscribed-to object, N subscriber recipients.",
"example": {
"subscriptions": [
{
"id": "subscribed-to-object-1",
"recipients": [
{
"collection": "projects",
"id": "subscriber-project-1"
},
"subscriber-user-1"
]
},
{
"id": "subscribed-to-object-2",
"recipients": [
"subscriber-user-2"
]
}
]
},
"properties": {
"subscriptions": {
"description": "A nested list of subscriptions.",
"items": {
"description": "A list of subscriptions. 1 subscribed-to id, and N subscriber recipients.",
"properties": {
"id": {
"description": "Unique identifier for the object.",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
},
"recipients": {
"description": "The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.",
"items": {
"$ref": "#/components/schemas/RecipientReference"
},
"nullable": false,
"type": "array",
"x-struct": null,
"x-validate": null
}
},
"required": [
"id",
"recipients"
],
"type": "object",
"x-struct": null,
"x-validate": null
},
"type": "array",
"x-struct": null,
"x-validate": null
}
},
"required": [
"subscriptions"
],
"title": "BulkDeleteSubscriptionsRequest",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.BulkDeleteSubscriptionsRequest",
"x-validate": null
},
"InlineChannelDataRequest": {
"additionalProperties": {
"description": "Channel data for a given channel type.",
"nullable": false,
"oneOf": [
{
"$ref": "#/components/schemas/PushChannelDataTokensOnly"
},
{
"$ref": "#/components/schemas/PushChannelDataDevicesOnly"
},
{
"$ref": "#/components/schemas/AWSSNSPushChannelDataTargetARNsOnly"
},
{
"$ref": "#/components/schemas/AWSSNSPushChannelDataDevicesOnly"
},
{
"$ref": "#/components/schemas/OneSignalChannelDataPlayerIdsOnly"
},
{
"$ref": "#/components/schemas/SlackChannelData"
},
{
"$ref": "#/components/schemas/MsTeamsChannelData"
},
{
"$ref": "#/components/schemas/DiscordChannelData"
}
],
"x-struct": null,
"x-validate": null
},
"description": "A request to set channel data for a type of channel inline.",
"example": {
"97c5837d-c65c-4d54-aa39-080eeb81c69d": {
"tokens": [
"push_token_xxx"
]
}
},
"title": "InlineChannelDataRequest",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.InlineChannelDataRequest",
"x-validate": null
},
"MessageEmailContent": {
"description": "The content of an email message.",
"example": {
"__typename": "MessageEmailContent",
"bcc": "[email protected]",
"cc": "[email protected]",
"from": "[email protected]",
"html_body": "<h1>Welcome to Isla Nublar</h1><p>Dear visitor,</p><p>We're excited to confirm your upcoming tour of our biological preserve. Your safety is our primary concern.</p><p>Please review the <a href='https://example.com/safety'>safety protocols</a> before arrival.</p><p><strong>Remember:</strong> All specimens are accounted for and contained.</p>",
"reply_to": "[email protected]",
"subject_line": "Tour Confirmation: Isla Nublar Biological Preserve",
"text_body": "Welcome to Isla Nublar\n\nDear visitor,\n\nWe're excited to confirm your upcoming tour of our biological preserve. Your safety is our primary concern.\n\nPlease review the safety protocols before arrival: https://example.com/safety\n\nRemember: All specimens are accounted for and contained.",
"to": "[email protected]"
},
"properties": {
"__typename": {
"description": "The typename of the schema.",
"example": "MessageEmailContent",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
},
"bcc": {
"description": "The BCC email addresses.",
"nullable": true,
"type": "string",
"x-struct": null,
"x-validate": null
},
"cc": {
"description": "The CC email addresses.",
"nullable": true,
"type": "string",
"x-struct": null,
"x-validate": null
},
"from": {
"description": "The sender's email address.",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
},
"html_body": {
"description": "The HTML body of the email message.",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
},
"reply_to": {
"description": "The reply-to email address.",
"nullable": true,
"type": "string",
"x-struct": null,
"x-validate": null
},
"subject_line": {
"description": "The subject line of the email message.",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
},
"text_body": {
"description": "The text body of the email message.",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
},
"to": {
"description": "The recipient's email address.",
"nullable": false,
"type": "string",
"x-struct": null,
"x-validate": null
}
},
"required": [
"__typename",
"html_body",
"text_body",
"subject_line",
"from",
"to"
],
"title": "MessageEmailContent",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.V1.Specs.MessageEmailContent",
"x-validate": null
},
"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",
"x-struct": null,
"x-validate": null
}
},
"required": [
"result_id"
],
"title": "Notify Response",
"type": "object",
"x-struct": "Elixir.SwitchboardWeb.Specs.Notify.Responses.NotifyResponse",
"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
},
"PreferenceSetChannelTypes": {
"description": "Channel type preferences.",
# --- truncated at 32 KB (580 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock/refs/heads/main/openapi/knock-openapi.json