Management API reference

Management API Reference

🚨

Note: the Knock management API only provides access to the resources managed in the Knock dashboard, such as workflows, templates, translations and commits.

All other concepts within the Knock notification engine are accessed through the Knock API, which you use to trigger workflows, identify users, and manage preferences.

The Knock management API provides you with a programmatic way to interact with the resources you create and manage in your Knock dashboard, including workflows, templates, layouts, translations and commits. It's separate from the Knock API and only provides access to a limited subset of resources.

You can use the Knock management API to:

Create, update, and manage your Knock workflows and the notification templates within those workflows.
Create and manage the translations used by your notification templates.
Create, update and manage your email layouts.
Commit and promote changes between your Knock environments.

Authentication

The management API authenticates with a Bearer authentication mechanism using a service token generated on your account.

Note: environment-level API keys should never be used to authenticate with the management API. To authenticate with the management API, generate a service token.

Errors

Knock uses standard HTTP response codes to indicate the success or failure of your API requests.

2xx success status codes confirm that your request worked as expected.
4xx error status codes indicate an error caused by incorrect or missing request information (e.g. providing an incorrect API key).
5xx error status codes indicate a Knock server error.

Postman

You can use our Management API Postman collection to quickly get started testing our Management API.

Workflows

To define a logical flow of your notifications, you create a workflow consisting of workflow steps. Workflow steps can be functions or channels, and can have conditional logic that determines whether to execute that step when the workflow is triggered.

You can retrieve, update, or create a workflow as well as list all workflows in a given environment. Workflows are identified by their unique workflow key.

Endpoints

GET/workflows

GET/workflows/:workflow_key

PUT/workflows/:workflow_key

PUT/workflows/:workflow_key/validate

PUT/workflows/:workflow_key/activate

Workflow definition

Attributes

activeboolean (read-only)Whether the workflow is active in the current environment.

categoriesstring[]A list of categories that the workflow belongs to.

created_attimestamp (read-only)A timestamp of when the workflow was created.

descriptionstringAn arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

environmentstring (read-only)The slug of the environment in which the workflow exists.

keystring (mutable only at creation)The unique key string for the workflow object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

namestringA name for the workflow. Must be at maximum 255 characters in length.

settingsWorkflowSettingsA map of workflow settings.

stepsWorkflowStep[]A list of workflow step objects in the workflow, which may contain any of: channel step, delay step, batch step, fetch step.

updated_attimestamp (read-only)A timestamp of when the workflow was last updated.

validboolean (read-only)Whether the workflow and its steps are in a valid state.

WorkflowSettings definition

Optional settings for a workflow.

Attributes

override_preferencesbooleanWhether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

WorkflowStep definition

All workflow steps, regardless of its type, share a common set of core attributes.

Common attributes

typestringThe type of the workflow step. One of: ”channel”, “delay”, “batch”, or “http_fetch”.

refstringThe reference key of the workflow step. Must be unique per workflow.

namestringA name for the workflow step.

descriptionstringAn arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

conditionsobjectA conditions object that describes one or more conditions to be met in order for the step to be executed.

ChannelStep definition

Contains all properties of the WorkflowStep and additionally:

Attributes

channel_keystringThe key of the channel to which the channel step will be sending a notification. A channel step can have either a channel key or a channel group key, but not both.

channel_group_keystringThe key of the channel group to which the channel step will be sending a notification. A channel step can have either a channel key or a channel group key, but not both.

templateobjectThe message template set up with the channel step. The shape of the template depends on the type of the channel you'll be sending to. See below for definitions.

send_windowsSendWindow[]A list of send window objects. Must include one send window object per day of the week.

Email template attributes

subjectstringA text template for the email subject line.

html_bodystringAn HTML template for the email body.

text_bodystringA text template for the email body. Only present if opted out from autogenerating it from the HTML template.

visual_blocksobject[]A list of visual blocks for the email body. Only present if using the visual blocks template over the HTML template.

settings.layout_keystringThe key of the email layout which the step is using.

settings.pre_contentstringA liquid template that will be injected into the layout above the message template content.

settings.attachment_keystringThe object path in the data payload (of the workflow trigger call) to resolve attachments.

In-app template attributes

markdown_bodystringA markdown template for the in-app notification message.

action_urlstringA text template for the URL of the in-app notification message.

SMS template attributes

text_bodystringA text template for the SMS notification message.

Push template attributes

titlestringA text template for the push notification message title.

text_bodystringA text template for the push notification message body.

settings.delivery_typestringThe delivery type for the push notification. One of: “content” or “silent”.

settings.payload_overridesstringA JSON template for any custom overrides to apply to the push notification payload.

Chat template attributes

summarystringA text template for the chat notification message summary.

markdown_bodystringA markdown template for the chat notification message body.

json_bodystringA JSON template for the chat notification message payload. Only present if not using the markdown body.

Webhook template attributes

By default, a webhoook step will use the request settings you configured in your webhook channel. You can override this as you see fit on a per-step basis in the template field.

template.methodstringAn HTTP method of the request. One of: “get”, “post”, “put”.

template.urlstringA URL of the request.

template.bodystringA body of the request. Only used for POST or PUT requests.

template.headersobject[]A list of key-value pairs for the request headers. Each object should contain key and value fields with string values.

template.query_paramsobject[]A list of key-value pairs for the request query params. Each object should contain key and value fields with string values.

SendWindow definition

Attributes

daystringDay of the week. One of: ”monday”, ”tuesday”, ”wednesday”, ”thursday”, ”friday”, ”saturday”, ”sunday”.

typestringWhether notifications should be sent or not sent for this send window. One of: ”send”, ”do_not_send”.

fromstringAn optional ISO-8601 time-only format string specifying the start of the window (defaults to 00:00:00). Only supported if type is set to ”send”.

untilstringAn optional ISO-8601 time-only format string specifying the end of the window (defaults to end of day). Only supported if type is set to ”send”.

Delay step definition

Contains all properties of the WorkflowStep and additionally:

Attributes

Must set either settings.delay_for or settings.delay_until_field_path.

settings.delay_forobjectA duration object that describes how long to wait before proceeding to the next step.

settings.delay_for.unitstringOne of: “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”.

settings.delay_for.valuenumberA non-negative integer.

settings.delay_until_field_pathstringThe data path to resolve the delay window. The resolved value must be an ISO-8601 timestamp.

Batch step definition

Contains all properties of the WorkflowStep and additionally:

Attributes

Must set either settings.batch_window or settings.batch_until_field_path.

batch_keystringThe data property to use to batch notifications per recipient.

settings.batch_windowobjectA duration object that describes how long the batch window should be open for.

settings.batch_window.unitstringOne of: “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”.

settings.batch_window.valuenumberA non-negative integer.

settings.batch_window_typestringThe type of the batch window used. One of: “fixed” or “sliding”.

settings.batch_window_extension_limitobjectA duration object that describes the maximum duration a batch window can be extended to from opening when using a sliding batch window.

settings.batch_window_extension_limit.unitstringOne of: “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”.

settings.batch_window_extension_limit.valuenumberA non-negative integer.

settings.batch_items_max_limitnumberThe maximum number of batch items allowed in a batch. Between: 2 and 1000.

settings.batch_until_field_pathstringThe data path to resolve the batch window. The resolved value must be an ISO-8601 timestamp.

settings.batch_orderstringThe order describing whether to return the first or last ten batch items in the activities variable. One of: “asc” or “desc”.

Branch step definition

Contains all properties of the WorkflowStep, but cannot have conditions and additionally:

Attributes

branchesWorkflowBranch[]A list of workflow branches to be evaluated.

WorkflowBranch definition

stepsWorkflowStep[]A list of steps that will be executed if the branch is chosen.

namestringThe name of the branch.

terminatesbooleanIf the workflow should halt at the end of the branch.

conditionsobjectA set of conditions to be evaluated for this branch.

Fetch step definition

Contains all properties of the WorkflowStep and additionally:

Attributes

settings.methodstringAn HTTP method of the request. One of: “get”, “post”, “put”.

settings.urlstringA URL of the request.

settings.bodystringA body of the request. Only used for POST or PUT requests.

settings.headersobject[]A list of key-value pairs for the request headers. Each object should contain key and value fields with string values.

settings.query_paramsobject[]A list of key-value pairs for the request query params. Each object should contain key and value fields with string values.

List all workflows

Returns a paginated list of workflows available in a given environment. The workflows are returned in alpha sorted order by its key.

Endpoint

GET/workflows

Query parameters

environmentstringA slug of the environment from which to query workflows.

hide_uncommitted_changesbooleanWhether to hide saved but uncommitted changes. Only relevant for “development” environment.

afterstringThe cursor to retrieve items after.

beforestringThe cursor to retrieve items before.

limitnumberThe total number to retrieve per page (defaults to 50, maximum of 100).

Returns

A paginated list of workflows

Get a workflow

Retrieve a workflow by its key and namespace, in a given environment.

Endpoint

GET/workflows/:workflow_key

Path parameters

workflow_keystringThe key of the workflow.

Query parameters

environmentstringA slug of the environment from which to query workflows.

hide_uncommitted_changesbooleanWhether to hide saved but uncommitted changes. Only relevant for “development” environment.

Returns

A complete workflow

Upsert a workflow

Updates a workflow of a given key, or creates a new one if it does not yet exist.

Note: this endpoint only operates on workflows in the development environment.

Endpoint

PUT/workflows/:workflow_key

Path parameters

workflow_keystringThe key of the workflow.

Query parameters

commitbooleanWhether to commit the upserted workflow changes in the “development” environment. Set to “false” by default.

commit_messagebooleanAn optional message to include in a commit.

Body parameters

workflowWorkflowA workflow object with attributes to update or create a workflow.

Returns

An upserted workflow

Run a workflow

Runs the latest version of a saved workflow.

Endpoint

PUT/workflows/:workflow_key/run

Rate limit

Tier 2

Path parameters

workflow_keystringThe key of the workflow.

Body parameters

environmentstringThe slug of the environment in which to run this workflow. Defaults to development.

recipientsstring[]One or more recipient ids for this workflow run, maximum limit 5.

datastringA JSON string of the data with which this workflow will run.

actorstringAn optional actor id for this workflow run.

tenantstringAn optional tenant id for this workflow run.

Returns

A workflow run ID

Validate a workflow

Validates a workflow payload without persisting it.

Note: Validating a workflow is only done in the development environment context.

Endpoint

PUT/workflows/:workflow_key/validate

Path parameters

workflow_keystringThe key of the workflow.

Body parameters

workflowWorkflowA workflow object with attributes to update or create a workflow.

Returns

A validated workflow object, if valid. Note: some read-only fields will be empty as they are generated by the system when persisted.

Activate a workflow

Activates (or deactivates) a workflow in a given environment.

Note: This immediately enables or disables a workflow in a given environment without needing to go through environment promotion.

Endpoint

PUT/workflows/:workflow_key/activate

Path parameters

workflow_keystringThe key of the workflow.

environmentstringThe environment slug. (Defaults to "development".)

Body parameters

statusbooleanWhether to activate or deactivate the upserted workflow changes in the “development” environment. Set to “true” by default, which is to activate. Setting to “false” will deactivate.

Returns

workflow A workflow object.

Email layouts

Email layouts wrap email message templates to share consistent design components between the email notifications that your recipients receive.

You can retrieve, update, and create email layouts as well as listing all in a given environment. Email layouts are identified by their unique key.

Endpoints

GET/email_layouts

GET/email_layouts/:key

PUT/email_layouts/:key

PUT/email_layouts/:key/validate

Email layout definition

Attributes

keystringThe unique key for this email layout

namestringThe friendly name of this email layout

html_layoutstringThe complete HTML content of the email

text_layoutstringThe complete plain text content of the email layout

footer_linksEmailLayoutFooterLink[]A list of one or more items to show in the footer of the email layout.

EmailLayoutFooterLink Attributes

textstringThe text to display as the link

urlstringThe URL to link to

List all email layouts

Returns a paginated list of email layouts available in a given environment.

Endpoint

GET/email_layouts

Query parameters

environmentstringA slug of the environment from which to query.

hide_uncommitted_changesbooleanWhether to hide saved but uncommitted changes. Only relevant for “development” environment.

afterstringThe cursor to retrieve items after.

beforestringThe cursor to retrieve items before.

limitnumberThe total number to retrieve per page (defaults to 50, maximum of 100).

Returns

A paginated list of email layouts

Get an email layout

Retrieve an email layout by its key, in a given environment.

Endpoint

GET/email_layouts/:key

Path parameters

keystringThe key of the email layout.

Query parameters

environmentstringA slug of the environment from which to query translations.

hide_uncommitted_changesbooleanWhether to hide saved but uncommitted changes. Only relevant for “development” environment.

Returns

An email layout object

Upsert an email layout

Updates an email layout, or creates a new one if it does not yet exist.

Note: this endpoint only operates in the “development” environment.

Endpoint

PUT/email_layouts/:key

Path parameters

keystringThe email layout key.

Query parameters

commitbooleanWhether to commit the upserted email layout changes in the “development” environment.

commit_messagestringAn optional message to include in a commit.

Body parameters

email_layoutobjectAn email layout object with a content attribute used to update or create an email layout.

Returns

An email layout.

Validate an email layout

Validates an email layout payload without persisting it.

Note: this endpoint only operates in the “development” environment.

Endpoint

PUT/email_layouts/:key/validate

Path parameters

keystringThe email layout key.

Body parameters

email_layoutobjectAn email layout object to validate.

Returns

An email layout

Translations

Translations support localization in Knock. They hold the translated content for a given locale, which you can reference in your message templates with the t Liquid function filter.

You can retrieve, update, and create translations as well as listing all in a given environment. Translations are identified by their locale code + an optional namespace.

Endpoints

GET/translations

GET/translations/:locale_code

PUT/translations/:locale_code

PUT/translations/:local_code/validate

Translation definition

Attributes

locale_codestringThe locale code for the translation object.

namespacestringAn optional namespace for the translation to help categorize your translations.

contentstringA JSON encoded object string containing the key-value pairs of translation references and translation strings.

inserted_attimestampA timestamp of when the translation was created.

updated_attimestampA timestamp of when the translation was updated.

List all translations

Returns a paginated list of translations available in a given environment. The translations are returned in alpha-sorted order by locale code.

Endpoint

GET/translations

Query parameters

environmentstringA slug of the environment from which to query translations.

hide_uncommitted_changesbooleanWhether to hide saved but uncommitted changes. Only relevant for “development” environment.

locale_codestringA specific locale code to filter translations for.

namespacestringA specific namespace to filter translations for.

afterstringThe cursor to retrieve items after.

beforestringThe cursor to retrieve items before.

limitnumberThe total number to retrieve per page (defaults to 50, maximum of 100).

Returns

A paginated list of translations

Get a translation

Retrieve a translation by its locale and namespace, in a given environment.

Endpoint

GET/translations/:locale_code

Path parameters

locale_codestringA locale code to retrieve translations for.

Query parameters

environmentstringA slug of the environment from which to query translations.

hide_uncommitted_changesbooleanWhether to hide saved but uncommitted changes. Only relevant for “development” environment.

namespacestringA specific namespace to filter translations for.

Returns

A translation object

Upsert a translation

Updates a translation of a given locale code + namespace, or creates a new one if it does not yet exist.

Note: this endpoint only operates on translations in the “development” environment.

Endpoint

PUT/translations/:locale_code

Path parameters

locale_codestringA locale code for the translation.

Query parameters

namespacestringAn optional namespace that identifies the translation.

commitbooleanWhether to commit the upserted translation’s changes in the “development” environment.

commit_messagestringAn optional message to include in a commit.

Body parameters

translationobjectA translation object with a content attribute used to update or create a translation.

Returns

A translation object

Validate a translation

Validates a translation payload without persisting it.

Note: this endpoint only operates on translations in the “development” environment.

Endpoint

PUT/translations/:locale_code/validate

Path parameters

locale_codestringA locale code of the translation.

Body parameters

translationobjectA translation object to validate.

Returns

A translation object

Commits

To version the changes you make in your environments, Knock uses a commit model. When you make changes to a workflow, a layout, a translation or an event action mapping, you will need to commit them in your development environment, then promote to subsequent environments before those changes will appear in the respective environments.

You can retrieve all commits in a given environment, or show the details of one single commit based on the target commit id.

Endpoints

PUT/commits/:id/promote

Commit definition

Attributes

idstringThe unique id for this commit.

resourceCommitResourceThe resource object associated with the commit.

authorCommitAuthorThe author responsible for the commit.

commit_messagestringThe optional message about the commit.

environmentstringThe environment where the commit was made.

created_attimestampA timestamp of when the commit was created.

CommitResource attributes

identifierstringThe unique identifier for the resource.

typestringThe type of the resource object.

CommitAuthor attributes

emailstringThe email address of the commit author.

namestringThe name of the commit author.

List all commits

Returns a paginated list of commits in a given environment. The commits are ordered from most recent first.

Endpoint

GET/commits

Query parameters

environmentstringA slug of the environment from which to query commits.

promotedbooleanWhether to show only promoted or unpromoted changes between the given environment and the subsequent environment.

afterstringThe cursor to retrieve items after.

beforestringThe cursor to retrieve items before.

limitnumberThe total number to retrieve per page (defaults to 50, maximum of 100).

Returns

A paginated list of commits

Get commit

Retrieve a single commit by its id.

Endpoint

GET/commits/:id

Path parameters

idstringThe id of the commit.

Returns

A complete commit.

Commit all changes

Commit all changes across all resources in the development environment.

Endpoint

PUT/commits

Query parameters

commit_messagestringAn optional message to include in a commit.

Returns

result A "success" message.

Promote all changes

Promote all changes across all resources to the target environment from its preceding environment.

Endpoint

PUT/commits/promote

Query parameters

to_environmentstring

A slug of the target environment to which you want to promote all changes from its directly preceding environment.

For example, if you have three environments “development”, “staging”, and “production” (in that order), setting this param to “production” will promote all new changes from the staging environment.

Note: This must be a non-development environment.

Returns

result A "success" message.

Promote one change

Promotes one change to the subsequent environment.

Endpoint

PUT/commits/:id/promote

Query parameters

idstringThe target commit id to promote to the subsequent environment.

Returns

A promoted commit.