Knock Docs

Management API reference

Complete reference documentation for the Knock Management API.

Overview

The Knock Management API enables you to manage your Knock resources programmatically. Use this API to automate configuration changes and integrate with your CI/CD pipelines.

Base URL

https://control.knock.app/v1

Environments

Knock uses the concept of environments to ensure logical separation of your data. Dashboard resources are created in your development environment and promoted to higher environments.

Endpoints
GET/v1/environments
GET/v1/environments/{environment_slug}

List environments

Returns a paginated list of environments. The environments will be returned in order of their index, with the development environment first.

Endpoint

GET/v1/environments

Query parameters

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedEnvironmentResponse

A paginated list of Environment. Contains a list of entries and page information.

Get an environment

Returns a single environment by the environment_slug.

Endpoint

GET/v1/environments/{environment_slug}

Path parameters

environment_slugstringrequired

The slug of the environment to retrieve.

Returns

Environment

An environment object.

Environment

An environment object.

Attributes

created_atstringrequired

The timestamp of when the environment was created.

deleted_atstringnullable

The timestamp of when the environment was deleted.

hide_pii_databoolean

Whether PII data is hidden from the environment. Read more in the [data obfuscation docs](https://docs.knock.app/manage-your-account/data-obfuscation).

Default: false

label_colorstringnullable

The color of the environment label to display in the dashboard.

last_commit_atstringnullable

The timestamp of the most-recent commit in the environment.

namestringrequired

A human-readable name for the environment. Cannot exceed 255 characters.

orderintegerrequired

The order of the environment. The lowest number is the first environment, the highest number is the last environment. The order will not always be sequential.

ownerstringrequired

The owner of the environment.

One of: "system", "user"

slugstringrequired

A unique slug for the environment. Cannot exceed 255 characters.

updated_atstringrequired

The timestamp of when the environment was last updated.

Channels

Channels are the delivery mechanisms for your notifications.

Endpoints
GET/v1/channels

List channels

Returns a paginated list of channels. Note: the list of channels is across the entire account, not scoped to an environment.

Endpoint

GET/v1/channels

Query parameters

idstring

A channel id to filter the results by.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedChannelResponse

A paginated list of Channel. Contains a list of entries and page information.

Channel

A configured channel, which is a way to route messages to a provider.

Attributes

archived_atstringnullable

The timestamp of when the channel was deleted.

created_atstringrequired

The timestamp of when the channel was created.

custom_icon_urlstringnullable

Optional URL to a custom icon for the channel. Only used for display purposes in the dashboard.

descriptionstringnullable

Optional description of the channel's purpose or usage.

idstringrequired

The unique identifier for the channel.

keystringrequired

Unique identifier for the channel within a project (immutable once created).

namestringrequired

The human-readable name of the channel.

providerstringrequired

The ID of the provider that this channel uses to deliver messages. Learn more about the providers available [in our documentation](https://docs.knock.app/integrations/overview).

typestringrequired

The type of channel, determining what kind of messages it can send.

One of: "email", "in_app", "in_app_feed", "in_app_guide", "sms", "push", "chat", "http"

updated_atstringrequired

The timestamp of when the channel was last updated.

ChatChannelSettings

Chat channel settings. Only used as configuration as part of a workflow channel step.

Attributes

email_based_user_id_resolutionboolean

Whether to resolve chat provider user IDs using a Knock user's email address. Only relevant for Slack channels for the time being.

link_trackingboolean

Whether to track link clicks on chat notifications.

EmailChannelSettings

Email channel settings. Only used as configuration as part of a workflow channel step.

Attributes

bcc_addressstringnullable

The BCC address on email notifications. Supports liquid.

cc_addressstringnullable

The CC address on email notifications. Supports liquid.

from_addressstringnullable

The email address from which this channel will send. Supports liquid.

from_namestringnullable

The name from which this channel will send. Supports liquid.

json_overridesstringnullable

A JSON template for any custom overrides to merge into the API payload that is sent to the email provider. Supports liquid.

link_trackingboolean

Whether to track link clicks on email notifications.

open_trackingboolean

Whether to track opens on email notifications.

reply_to_addressstringnullable

The Reply-to address on email notifications. Supports liquid.

to_addressstring

The email address to which this channel will send. Defaults to `recipient.email`. Supports liquid.

PushChannelSettings

Push channel settings. Only used as configuration as part of a workflow channel step.

Attributes

token_deregistrationboolean

Whether to deregister a push-token when a push send hard bounces. This is to prevent the same token from being used for future pushes.

SmsChannelSettings

SMS channel settings. Only used as configuration as part of a workflow channel step.

Attributes

link_trackingboolean

Whether to track link clicks on SMS notifications.

InAppFeedChannelSettings

In-app feed channel settings. Only used as configuration as part of a workflow channel step.

Attributes

link_trackingboolean

Whether to track link clicks on in-app feed notifications.

Workflows

To define a logical flow for your notifications, you create a workflow consisting of 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/v1/workflows
GET/v1/workflows/{workflow_key}
PUT/v1/workflows/{workflow_key}
PUT/v1/workflows/{workflow_key}/activate
PUT/v1/workflows/{workflow_key}/run
PUT/v1/workflows/{workflow_key}/validate

List workflows

Returns a paginated list of workflows available in a given environment. The workflows are returned alphabetically by key.

Endpoint

GET/v1/workflows

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

PaginatedWorkflowResponse

A paginated list of Workflow. Contains a list of entries and page information.

Get a workflow

Retrieve a workflow by its key in a given environment.

Endpoint

GET/v1/workflows/{workflow_key}

Path parameters

workflow_keystringrequired

The key of the workflow to retrieve.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

ShowWorkflowResponse

A workflow object.

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/v1/workflows/{workflow_key}

Path parameters

workflow_keystringrequired

The key of the workflow.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

commitboolean

Whether to commit the resource at the same time as modifying it.

commit_messagestring

The message to commit the resource with, only used if `commit` is `true`.

Request body

workflowWorkflowRequestrequired

A workflow request for upserting a workflow.

Returns

WrappedWorkflowResponse

Wraps the Workflow response under the `workflow` key.

Activate a workflow

Activates (or deactivates) a workflow in a given environment. Read more in the docs.

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

Endpoint

PUT/v1/workflows/{workflow_key}/activate

Path parameters

workflow_keystringrequired

The key of the workflow.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

statusbooleanrequired

Whether to activate or deactivate the workflow. Set to `true` by default, which will activate the workflow.

Returns

WrappedWorkflowResponse

Wraps the Workflow response under the `workflow` key.

Run a workflow

Runs the latest version of a committed workflow in a given environment using the params provided.

Endpoint

PUT/v1/workflows/{workflow_key}/run

Path parameters

workflow_keystringrequired

The key of the workflow.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

actorobject

The actor to reference in the the workflow run.

cancellation_keystringnullable

A key to cancel the workflow run.

dataobject

A map of data to be used in the workflow run. The structure should conform to the workflow's `trigger_data_json_schema` if one is defined. Available in templates as `{{ data.field_name }}`. See [trigger data validation docs](https://docs.knock.app/developer-tools/validating-trigger-data).

recipientsRecipientReference[]required

A list of recipients to run the workflow for.

tenantstring

The tenant to associate the workflow run with. Must not contain whitespace.

Returns

RunWorkflowResponse

A response to a run workflow request.

Validate a workflow

Validates a workflow payload without persisting it. Some read-only fields will be empty as they are generated by the system when persisted.

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

Endpoint

PUT/v1/workflows/{workflow_key}/validate

Path parameters

workflow_keystringrequired

The key of the workflow.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

workflowWorkflowRequestrequired

A workflow request for upserting a workflow.

Returns

WrappedWorkflowResponse

Wraps the Workflow response under the `workflow` key.

Steps

Methods that operate on the individual steps within a workflow. Steps are referenced by their ref, which is unique within a workflow.

Endpoints
POST/v1/workflows/{workflow_key}/steps/{step_ref}/preview_template

Preview a workflow template

Generates a rendered template for a given channel step in a workflow.

Endpoint

POST/v1/workflows/{workflow_key}/steps/{step_ref}/preview_template

Path parameters

workflow_keystringrequired

The key of the workflow.

step_refstringrequired

The reference key of the channel step in the workflow to preview.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

actorobject

The actor to reference in the the workflow run.

dataobject

The data to pass to the workflow template for rendering.

recipientRecipientReferencerequired

A recipient reference, used when referencing a recipient by either their ID (for a user), or by a reference for an object.

tenantstringnullable

The tenant to associate the workflow with. Must not contain whitespace.

Returns

PreviewWorkflowTemplateResponse

A response to a preview workflow template request.

Condition

A condition to be evaluated.

Attributes

argumentstringnullable

The argument to be evaluated. Arguments can be either static values or dynamic properties. Static values will always be JSON decoded so will support strings, lists, objects, numbers, and booleans. Dynamic values should be path expressions.

operatorstringrequired

The operator to use in the evaluation of the condition.

One of: "equal_to", "not_equal_to", "greater_than", "less_than", "greater_than_or_equal_to", "less_than_or_equal_to", "contains", "not_contains", "contains_all", "not_contains_all", "is_timestamp_before", "is_timestamp_after", "is_timestamp_before_date", "is_timestamp_after_date", "is_timestamp_between", "empty", "not_empty", "is_timestamp", "is_audience_member", "is_not_audience_member"

variablestringrequired

The variable to be evaluated. Variables can be either static values or dynamic properties. Static values will always be JSON decoded so will support strings, lists, objects, numbers, and booleans. Dynamic values should be path expressions.

ConditionGroup

A group of conditions to be evaluated.

Attributes

Duration

A duration of time, represented as a unit and a value.

Attributes

unitstringrequired

The unit of time.

One of: "minutes", "hours", "days", "weeks", "months"

valueintegerrequired

The value of the duration.

SendWindow

A send window time for a notification. Describes a single day.

Attributes

daystringrequired

The day of the week.

One of: "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"

fromstringnullable

The start time of the send window.

typestringrequired

The type of send window.

One of: "send", "do_not_send"

untilstringnullable

The end time of the send window.

Workflow

A workflow object. Read more in the docs.

Attributes

activebooleanrequired

Whether the workflow is [active](https://docs.knock.app/concepts/workflows#workflow-status) in the current environment. (read-only).

categoriesstring[]

A list of [categories](https://docs.knock.app/concepts/workflows#workflow-categories) that the workflow belongs to.

conditionsobject

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

created_atstringrequired

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

deleted_atstring

The timestamp of when the workflow was deleted. (read-only).

descriptionstring

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

environmentstringrequired

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

keystringrequired

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_-]+$.

namestringrequired

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

settingsobject

A map of workflow settings.

shastringrequired

The SHA hash of the workflow data. (read-only).

stepsWorkflowStep[]required

A list of workflow step objects in the workflow.

trigger_data_json_schemaobject

A JSON schema for the expected structure of the workflow trigger's `data` payload (available in templates as `{{ data.field_name }}`). Used to validate trigger requests. Read more in the [docs](https://docs.knock.app/developer-tools/validating-trigger-data).

trigger_frequencystring

The frequency at which the workflow should be triggered. One of: `once_per_recipient`, `once_per_recipient_per_tenant`, `every_trigger`. Defaults to `every_trigger`. Read more in [docs](https://docs.knock.app/send-notifications/triggering-workflows/overview#controlling-workflow-trigger-frequency).

One of: "every_trigger", "once_per_recipient", "once_per_recipient_per_tenant"

updated_atstringrequired

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

validbooleanrequired

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

WorkflowStep

A step within a workflow. Each workflow step, regardless of its type, share a common set of core attributes (type, ref, name, description, conditions).

Attributes

WorkflowBatchStep

A batch function step. Read more in the docs.

Attributes

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

settingsobjectrequired

The settings for the batch step.

typestringrequired

The type of the workflow step.

One of: "batch"

WorkflowBranchStep

A branch function step. Read more in the docs.

Attributes

branchesWorkflowBranchStepBranch[]required

A list of workflow branches to be evaluated.

descriptionstring

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

namestringnullable

A name for the workflow step.

refstringrequired

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

typestringrequired

The type of step.

One of: "branch"

WorkflowChatStep

A chat step within a workflow. Read more in the docs.

Attributes

channel_group_keystringnullable

The key of the channel group to which the channel step will be sending a notification. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_keystringnullable

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_overridesobject

A map of channel overrides for the channel step.

channel_typestring

The type of the channel step. Always `chat` for chat steps.

One of: "chat"

conditionsobject

A set of conditions to be evaluated for this channel step.

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

send_windowsSendWindow[]nullable

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

templateChatTemplaterequired

A chat template.

typestringrequired

The type of the workflow step.

One of: "channel"

WorkflowInAppFeedStep

An in-app feed step within a workflow. Read more in the docs.

Attributes

channel_group_keystringnullable

The key of the channel group to which the channel step will be sending a notification. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_keystringnullable

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_overridesobject

A map of channel overrides for the channel step.

channel_typestring

The type of the channel step. Always `in_app_feed` for in-app feed steps.

One of: "in_app_feed"

conditionsobject

A set of conditions to be evaluated for this channel step.

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

send_windowsSendWindow[]nullable

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

templateInAppFeedTemplaterequired

An in-app feed template.

typestringrequired

The type of the workflow step.

One of: "channel"

WorkflowEmailStep

An email step within a workflow. Read more in the docs.

Attributes

channel_group_keystringnullable

The key of the channel group to which the channel step will be sending a notification. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_keystringnullable

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_overridesobject

A map of channel overrides for the channel step.

channel_typestring

The category of channel for this step. Always `email` for email steps. This identifies the type of notification (email, sms, push, etc.) while `channel_key` specifies which configured provider instance to use.

One of: "email"

conditionsobject

A set of conditions to be evaluated for this channel step.

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

send_windowsSendWindow[]nullable

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

templateEmailTemplaterequired

An email message template.

typestringrequired

The type of the workflow step.

One of: "channel"

WorkflowPushStep

A push step within a workflow. Read more in the docs.

Attributes

channel_group_keystringnullable

The key of the channel group to which the channel step will be sending a notification. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_keystringnullable

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_overridesobject

A map of channel overrides for the channel step.

channel_typestring

The type of the channel step. Always `push` for push steps.

One of: "push"

conditionsobject

A set of conditions to be evaluated for this channel step.

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

send_windowsSendWindow[]nullable

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

templatePushTemplaterequired

A push notification template.

typestringrequired

The type of the workflow step.

One of: "channel"

WorkflowSmsStep

A SMS step within a workflow. Read more in the docs.

Attributes

channel_group_keystringnullable

The key of the channel group to which the channel step will be sending a notification. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_keystringnullable

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_overridesobject

A map of channel overrides for the channel step.

channel_typestring

The type of the channel step. Always `sms` for SMS steps.

One of: "sms"

conditionsobject

A set of conditions to be evaluated for this channel step.

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

send_windowsSendWindow[]nullable

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

templateSmsTemplaterequired

An SMS template.

typestringrequired

The type of the workflow step.

One of: "channel"

WorkflowWebhookStep

A webhook step within a workflow to send an HTTP request to a generic channel. Read more in the docs.

Attributes

channel_group_keystringnullable

The key of the channel group to which the channel step will be sending a notification. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_keystringnullable

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either `channel_key` or `channel_group_key` must be provided, but not both.

channel_typestring

The type of the channel step. Always `http` for webhook steps.

One of: "http"

conditionsobject

A set of conditions to be evaluated for this channel step.

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

send_windowsSendWindow[]nullable

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

templateWebhookTemplaterequired

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 per-step basis.

typestringrequired

The type of the workflow step.

One of: "channel"

WorkflowDelayStep

A delay function step. Read more in the docs.

Attributes

conditionsobject

A set of conditions to be evaluated for this delay step.

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

settingsobjectrequired

The settings for the delay step. Both fields can be set to compute a delay where `delay_for` is an offset from the `delay_until_field_path`.

typestringrequired

The type of the workflow step.

One of: "delay"

WorkflowFetchStep

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.

Attributes

conditionsobject

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

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

settingsRequestTemplaterequired

A request template for a fetch function step.

typestringrequired

The type of the workflow step.

One of: "http_fetch"

WorkflowThrottleStep

A throttle function step. Read more in the docs.

Attributes

conditionsobject

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

descriptionstringnullable

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

namestringnullable

A name for the workflow step.

refstringrequired

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

settingsobjectrequired

The settings for the throttle step.

typestringrequired

The type of the workflow step.

One of: "throttle"

WorkflowTriggerWorkflowStep

A workflow trigger function step. Read more in the docs.

Attributes

conditionsobject

A set of conditions to be evaluated for this trigger workflow step.

descriptionstringnullable

A description for the workflow step.

namestringnullable

A name for the workflow step.

refstringrequired

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

settingsobjectrequired

The settings for the workflow trigger workflow step.

typestringrequired

The type of the workflow step.

One of: "trigger_workflow"

Broadcasts

Broadcasts are a way to send one-time, cross-channel notifications to your users through Knock. They use the Knock workflow engine, but are configured in the Knock dashboard to run once.

Endpoints
PUT/v1/broadcasts/{broadcast_key}/send
PUT/v1/broadcasts/{broadcast_key}/validate
GET/v1/broadcasts
GET/v1/broadcasts/{broadcast_key}
PUT/v1/broadcasts/{broadcast_key}
PUT/v1/broadcasts/{broadcast_key}/cancel

Send a broadcast

Sends a broadcast immediately or schedules it to send at a future time.

Endpoint

PUT/v1/broadcasts/{broadcast_key}/send

Path parameters

broadcast_keystringrequired

The key of the broadcast.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

send_atstring

When to send the broadcast. If provided, the broadcast will be scheduled to send at this time. Must be in ISO 8601 UTC format. If not provided, the broadcast will be sent immediately.

Returns

WrappedBroadcastResponse

Wraps the Broadcast response under the `broadcast` key.

Validate a broadcast

Validates a broadcast payload without persisting it.

Endpoint

PUT/v1/broadcasts/{broadcast_key}/validate

Path parameters

broadcast_keystringrequired

The key of the broadcast.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

broadcastBroadcastRequestrequired

A broadcast request for upserting a broadcast.

Returns

WrappedBroadcastResponse

Wraps the Broadcast response under the `broadcast` key.

List broadcasts

Returns a paginated list of broadcasts available in a given environment. The broadcasts are returned ordered by creation time (newest first).

Endpoint

GET/v1/broadcasts

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

PaginatedBroadcastResponse

A paginated list of Broadcast. Contains a list of entries and page information.

Get a broadcast

Get a broadcast by its key in a given environment.

Endpoint

GET/v1/broadcasts/{broadcast_key}

Path parameters

broadcast_keystringrequired

The key of the broadcast to retrieve.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

Broadcast

A broadcast object.

Upsert a broadcast

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

Endpoint

PUT/v1/broadcasts/{broadcast_key}

Path parameters

broadcast_keystringrequired

The key of the broadcast.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

Request body

broadcastBroadcastRequestrequired

A broadcast request for upserting a broadcast.

Returns

WrappedBroadcastResponse

Wraps the Broadcast response under the `broadcast` key.

Cancel a scheduled broadcast

Cancels sending a scheduled broadcast. The broadcast will return to draft status.

Endpoint

PUT/v1/broadcasts/{broadcast_key}/cancel

Path parameters

broadcast_keystringrequired

The key of the broadcast.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Returns

WrappedBroadcastResponse

Wraps the Broadcast response under the `broadcast` key.

BroadcastRequest

A broadcast request for upserting a broadcast.

Attributes

categoriesstring[]

A list of categories that the broadcast belongs to.

descriptionstring

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

namestringrequired

A name for the broadcast. Must be at maximum 255 characters in length.

scheduled_atstringnullable

The timestamp of when the broadcast is scheduled to be sent.

settingsobject

A map of broadcast settings.

stepsobject[]required

A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.

target_audience_keystring

The key of the audience to target for this broadcast.

Broadcast

A broadcast object.

Attributes

archived_atstringnullable

The timestamp of when the broadcast was archived.

categoriesstring[]

A list of categories that the broadcast belongs to.

created_atstringrequired

The timestamp of when the broadcast was created. (read-only).

descriptionstring

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

environmentstringrequired

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

keystringrequired

The unique key string for the broadcast object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

namestringrequired

A name for the broadcast. Must be at maximum 255 characters in length.

scheduled_atstringnullable

The timestamp of when the broadcast is scheduled to be sent.

sent_atstringnullable

The timestamp of when the broadcast was sent. (read-only).

settingsobject

A map of broadcast settings.

shastringrequired

The SHA hash of the workflow data. (read-only).

statusstringrequired

The current status of the broadcast. One of: `draft`, `scheduled`, `sent`.

One of: "draft", "scheduled", "sent"

stepsobject[]required

A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.

target_audience_keystring

The key of the audience to target for this broadcast.

updated_atstringrequired

The timestamp of when the broadcast was last updated. (read-only).

validbooleanrequired

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

Email layouts

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

You can create and update email layouts in your development environment, as well as retrieve or list all layouts in a given environment.

Endpoints
GET/v1/email_layouts
GET/v1/email_layouts/{email_layout_key}
PUT/v1/email_layouts/{email_layout_key}
PUT/v1/email_layouts/{email_layout_key}/validate

List email layouts

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

Endpoint

GET/v1/email_layouts

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedEmailLayoutResponse

A paginated list of EmailLayout. Contains a list of entries and page information.

Get email layout

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

Endpoint

GET/v1/email_layouts/{email_layout_key}

Path parameters

email_layout_keystringrequired

The key of the email layout to show.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

EmailLayout

A versioned email layout used within an environment.

Upsert 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/v1/email_layouts/{email_layout_key}

Path parameters

email_layout_keystringrequired

The key of the email layout to upsert.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

commitboolean

Whether to commit the resource at the same time as modifying it.

commit_messagestring

The message to commit the resource with, only used if `commit` is `true`.

Request body

email_layoutEmailLayoutRequestrequired

A request to update or create an email layout.

Returns

WrappedEmailLayoutResponse

Wraps the EmailLayout response under the `email_layout` key.

Validate email layout

Validates an email layout payload without persisting it.

Note: this endpoint only operates in the "development" environment.

Endpoint

PUT/v1/email_layouts/{email_layout_key}/validate

Path parameters

email_layout_keystringrequired

The key of the email layout to validate.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

email_layoutEmailLayoutRequestrequired

A request to update or create an email layout.

Returns

WrappedEmailLayoutResponse

Wraps the EmailLayout response under the `email_layout` key.

EmailLayout

A versioned email layout used within an environment.

Attributes

created_atstringrequired

The timestamp of when the email layout was created.

environmentstring

The environment of the email layout.

footer_linksobject[]

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

html_layoutstringrequired

The complete HTML content of the email layout.

keystringrequired

The unique key for this email layout.

namestringrequired

The human-readable name of this email layout.

shastringrequired

The SHA of the email layout.

text_layoutstringrequired

The complete plaintext content of the email layout.

updated_atstring

The timestamp of when the email layout was last updated.

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 list all translations in a given environment. Translations are identified by their locale code + an optional namespace.

Endpoints
GET/v1/translations
GET/v1/translations/{locale_code}
PUT/v1/translations/{locale_code}
PUT/v1/translations/{locale_code}/validate

List translations

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

Endpoint

GET/v1/translations

Query parameters

locale_codestring

A specific locale code to filter translations for.

namespacestring

A specific namespace to filter translations for.

formatstring

Optionally specify the returned content format. Supports 'json' and 'po'. Defaults to 'json'.

One of: "json", "po"

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedTranslationResponse

A paginated list of Translation. Contains a list of entries and page information.

Get translation

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

Endpoint

GET/v1/translations/{locale_code}

Path parameters

locale_codestringrequired

A specific locale code to filter translations for.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

formatstring

Optionally specify the returned content format. Supports 'json' and 'po'. Defaults to 'json'.

One of: "json", "po"

namespacestring

A specific namespace to filter translations for.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

WrappedTranslationResponse

Wraps the Translation response under the `translation` key.

Upsert 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/v1/translations/{locale_code}

Path parameters

locale_codestringrequired

A locale code of the translation.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

namespacestringrequired

An optional namespace that identifies the translation.

formatstring

Optionally specify the returned content format. Supports 'json' and 'po'. Defaults to 'json'.

One of: "json", "po"

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

commitboolean

Whether to commit the resource at the same time as modifying it.

commit_messagestring

The message to commit the resource with, only used if `commit` is `true`.

Request body

translationTranslationRequestrequired

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

Returns

WrappedTranslationResponse

Wraps the Translation response under the `translation` key.

Validate translation

Validates a translation payload without persisting it.

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

Endpoint

PUT/v1/translations/{locale_code}/validate

Path parameters

locale_codestringrequired

The translation's locale code.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

translationTranslationRequestrequired

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

Returns

WrappedTranslationResponse

Wraps the Translation response under the `translation` key.

Translation

A translation object.

Attributes

contentstringrequired

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

formatstringrequired

Indicates whether content is a JSON encoded object string or a string in the PO format.

One of: "json", "po"

inserted_atstringrequired

The timestamp of when the translation was created.

locale_codestringrequired

The locale code for the translation object.

namespacestringrequired

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

updated_atstringrequired

The timestamp of when the translation was last updated.

Partials

Partials are reusable pieces of content you can use across your channel templates.

You can retrieve, update, and create partials as well as list all partials in a given environment. Partials are identified by their unique partial key.

Endpoints
GET/v1/partials
GET/v1/partials/{partial_key}
PUT/v1/partials/{partial_key}
PUT/v1/partials/{partial_key}/validate

List partials

List all partials for a given environment.

Endpoint

GET/v1/partials

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedPartialResponse

A paginated list of Partial. Contains a list of entries and page information.

Get a partial

Get a partial by its key.

Endpoint

GET/v1/partials/{partial_key}

Path parameters

partial_keystringrequired

The key of the partial to retrieve.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

Partial

A partial is a reusable piece of content that can be used in a template.

Upsert a partial

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

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

Endpoint

PUT/v1/partials/{partial_key}

Path parameters

partial_keystringrequired

The key of the partial to upsert.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

commitboolean

Whether to commit the resource at the same time as modifying it.

commit_messagestring

The message to commit the resource with, only used if `commit` is `true`.

Request body

partialPartialRequestrequired

A partial object with attributes to update or create a partial.

Returns

WrappedPartialResponse

Wraps the Partial response under the `partial` key.

Validate a partial

Validates a partial payload without persisting it.

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

Endpoint

PUT/v1/partials/{partial_key}/validate

Path parameters

partial_keystringrequired

The key of the partial to validate.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

partialPartialRequestrequired

A partial object with attributes to update or create a partial.

Returns

WrappedPartialResponse

Wraps the Partial response under the `partial` key.

Partial

A partial is a reusable piece of content that can be used in a template.

Attributes

contentstringrequired

The partial content.

descriptionstring

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

environmentstring

The slug of the environment in which the partial exists.

icon_namestring

The name of the icon to be used in the visual editor.

input_schemaobject[]

The field types available for the partial.

inserted_atstringrequired

The timestamp of when the partial was created.

keystringrequired

The unique key string for the partial object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

namestringrequired

A name for the partial. Must be at maximum 255 characters in length.

typestringrequired

The partial type. One of 'html', 'json', 'markdown', 'text'.

One of: "html", "text", "json", "markdown"

updated_atstringrequired

The timestamp of when the partial was last updated.

validbooleanrequired

Whether the partial and its content are in a valid state.

visual_block_enabledboolean

Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.

Commits

To version the changes you make in your environments, Knock uses a commit model. When you make changes to a workflow, a layout, or a translation, 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
GET/v1/commits
PUT/v1/commits
GET/v1/commits/{id}
PUT/v1/commits/promote
PUT/v1/commits/{id}/promote

List commits

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

Endpoint

GET/v1/commits

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

promotedboolean

Whether to show commits in the given environment that have not been promoted to the subsequent environment (false) or commits which have been promoted (true).

resource_typeunknown

Filter commits by resource type(s). Accepts a single type or array of types. Can be combined with resource_id to filter for specific resources.

resource_idstring

Filter commits by resource identifier. Must be used together with resource_type. For most resources, this will be the resource key. In the case of translations, this will be the locale code and namespace, separated by a `/`. For example, `en/courses` or `en`.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedCommitResponse

A paginated list of Commit. Contains a list of entries and page information.

Commit all changes

Commit all changes across all resources in the development environment.

Endpoint

PUT/v1/commits

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

commit_messagestring

An optional message to include in a commit.

resource_typeunknown

Filter changes to commit by resource type(s). Accepts a single type or array of types. Can be combined with resource_id to filter for specific resources.

resource_idstring

Filter changes to commit by resource identifier. Must be used together with resource_type.

Returns

CommitAllResponse

The response from committing all changes.

Get a commit

Retrieve a single commit by its ID.

Endpoint

GET/v1/commits/{id}

Path parameters

idstringrequired

The id of the commit to retrieve.

Returns

Commit

A commit is a change to a resource within an environment, made by an author.

Promote all changes

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

Endpoint

PUT/v1/commits/promote

Query parameters

to_environmentstringrequired

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 commits not currently in production from staging. When this param is set to `"development"`, the `"branch"` param must be provided.

branchstring

The slug of the branch to promote all changes from.

resource_typeunknown

Filter commits to promote by resource type(s). Accepts a single type or array of types. Can be combined with resource_id to filter for specific resources.

resource_idstring

Filter commits to promote by resource identifier. Must be used together with resource_type.

Returns

PromoteAllResponse

The response from promoting all changes.

Promote one commit

Promotes one change to the subsequent environment.

Endpoint

PUT/v1/commits/{id}/promote

Path parameters

idstringrequired

The target commit ID to promote to the subsequent environment.

Returns

WrappedCommitResponse

Wraps the Commit response under the `commit` key.

Commit

A commit is a change to a resource within an environment, made by an author.

Attributes

authorCommitAuthorrequired

The author of the commit.

commit_messagestring

The optional message about the commit.

created_atstringrequired

The timestamp of when the commit was created.

environmentstringrequired

The environment of the commit.

idstringrequired

The unique identifier for the commit.

resourceCommitResourcerequired

The resource object associated with the commit.

Variables

Variables are used to store shared attributes for your workflows and templates at the environment level.

Endpoints
GET/v1/variables

List variables

Returns a paginated list of variables for a given environment.

Endpoint

GET/v1/variables

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedVariableResponse

A paginated list of Variable. Contains a list of entries and page information.

Variable

An environment variable object.

Attributes

descriptionstringnullable

The description of the variable.

inserted_atstringrequired

The timestamp of when the variable was created.

keystringrequired

The key of the variable.

typestringrequired

The type of the variable.

One of: "public", "secret"

Default: "public"

updated_atstringrequired

The timestamp of when the variable was last updated.

valuestringrequired

The value of the variable.

Templates

Templates represent the templated contents of a message sent to an individual recipient on a specific channel.

There are no endpoints for working directly with templates, instead you must do so through modifying a workflow.

ChatTemplate

A chat template.

Attributes

json_bodystringnullable

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

markdown_bodystringrequired

The markdown body of the chat template.

summarystring

The summary of the chat template. Used by some chat apps in their push notifications.

EmailTemplate

An email message template.

Attributes

html_bodystringnullable

An HTML template for the email body. **Required** if `visual_blocks` is not provided. Only one of `html_body` or `visual_blocks` should be set. Supports Liquid templating with variables like `{{ recipient.name }}`, `{{ actor.name }}`, `{{ vars.app_name }}`, `{{ data.custom_field }}`, and `{{ tenant.name }}`. See the [template variables reference](https://docs.knock.app/designing-workflows/template-editor/variables) for available variables.

settingsEmailTemplateSettingsrequired

The [settings](https://docs.knock.app/integrations/email/settings) for the email template. Must be supplied with at least `layout_key`.

subjectstringrequired

The subject of the email. Supports Liquid templating with variables like `{{ recipient.name }}`, `{{ actor.name }}`, `{{ vars.app_name }}`, `{{ data.custom_field }}`, and `{{ tenant.name }}`. See the [template variables reference](https://docs.knock.app/designing-workflows/template-editor/variables) for available variables.

text_bodystringnullable

A text template for the email body. When omitted, the email template will be autogenerated from the `html_body` or `visual_blocks`.

visual_blocksobject

The visual blocks that make up the email template. **Required** if `html_body` is not provided. Only one of `html_body` or `visual_blocks` should be set.

PushTemplate

A push notification template.

Attributes

settingsobjectrequired

The [settings](https://docs.knock.app/integrations/sms/settings-and-overrides) for the push template.

text_bodystringrequired

The body of the push notification.

titlestringrequired

The title of the push notification.

SmsTemplate

An SMS template.

Attributes

settingsobject

The settings for the SMS template. Can be omitted.

text_bodystringrequired

The message of the SMS.

InAppFeedTemplate

An in-app feed template.

Attributes

action_buttonsobject[]

The action buttons of the in-app feed message.

action_urlstringnullable

The URL to navigate to when the in-app feed is tapped. Can be omitted for multi-action templates, where the action buttons will be used instead.

markdown_bodystringrequired

The markdown body of the in-app feed.

RequestTemplate

A request template for a fetch function step.

Attributes

bodystringnullable

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

headersobject

The headers of the request. Can be a template string or a list of key-value pairs.

methodstringrequired

The HTTP method of the request.

One of: "get", "post", "put", "delete", "patch"

query_paramsobject

The query params of the request. Can be a template string or a list of key-value pairs.

urlstringrequired

The URL of the request.

WebhookTemplate

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 per-step basis.

Attributes

bodystringnullable

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

headersobject[]

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

methodstringrequired

The HTTP method of the webhook.

One of: "get", "post", "put", "delete", "patch"

query_paramsobject[]

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

urlstringrequired

The URL of the webhook.

Message types

A message type is a schema for a message that maps to a UI component or element within your application.

Endpoints
GET/v1/message_types
GET/v1/message_types/{message_type_key}
PUT/v1/message_types/{message_type_key}
PUT/v1/message_types/{message_type_key}/validate

List message types

Returns a paginated list of message types available in a given environment.

Endpoint

GET/v1/message_types

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedMessageTypeResponse

A paginated list of MessageType. Contains a list of entries and page information.

Get message type

Retrieve a message type by its key, in a given environment.

Endpoint

GET/v1/message_types/{message_type_key}

Path parameters

message_type_keystringrequired

The key of the message type to retrieve.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

MessageType

A message type is a schema for a message that maps to a UI component or element within your application.

Upsert message type

Updates a message type, or creates a new one if it does not yet exist.

Note: this endpoint only operates in the development environment.

Endpoint

PUT/v1/message_types/{message_type_key}

Path parameters

message_type_keystringrequired

The key of the message type to upsert.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

commitboolean

Whether to commit the resource at the same time as modifying it.

commit_messagestring

The message to commit the resource with, only used if `commit` is `true`.

Request body

message_typeMessageTypeRequestrequired

A request to create a message type.

Returns

WrappedMessageTypeResponse

Wraps the MessageType response under the `message_type` key.

Validate message type

Validates a message type payload without persisting it.

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

Endpoint

PUT/v1/message_types/{message_type_key}/validate

Path parameters

message_type_keystringrequired

The key of the message type to validate.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

message_typeMessageTypeRequestrequired

A request to create a message type.

Returns

WrappedMessageTypeResponse

Wraps the MessageType response under the `message_type` key.

MessageType

A message type is a schema for a message that maps to a UI component or element within your application.

Attributes

archived_atstringnullable

The timestamp of when the message type was deleted.

created_atstringrequired

The timestamp of when the message type was created.

deleted_atstringnullable

The timestamp of when the message type was deleted.

descriptionstringnullable

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

environmentstringrequired

The environment of the message type.

icon_namestring

The icon name of the message type.

keystringrequired

The unique key string for the message type object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

namestringrequired

A name for the message type. Must be at maximum 255 characters in length.

ownerstringrequired

The owner of the message type.

One of: "system", "user"

previewstringrequired

An HTML/liquid template for the message type preview.

semverstringrequired

The semantic version of the message type.

shastringrequired

The SHA hash of the message type.

updated_atstringrequired

The timestamp of when the message type was last updated.

validbooleanrequired

Whether the message type is valid.

variantsMessageTypeVariant[]required

The variants of the message type.

MessageTypeVariant

A variant of a message type.

Attributes

fieldsobject[]required

The field types available for the variant.

keystringrequired

The unique key string for the variant. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

namestringrequired

A name for the variant. Must be at maximum 255 characters in length.

MessageTypeTextField

A text field used in a message type.

Attributes

keystringrequired

The unique key of the field.

labelstringrequirednullable

The label of the field.

settingsobject

Settings for the text field.

typestringrequired

The type of the field.

One of: "text"

Guides

Guides let you define in-app messaging for your users, powered by your own components.

Endpoints
GET/v1/guides
GET/v1/guides/{guide_key}
DELETE/v1/guides/{guide_key}
PUT/v1/guides/{guide_key}
PUT/v1/guides/{guide_key}/validate
PUT/v1/guides/{guide_key}/activate

List guides

Returns a paginated list of guides available in a given environment.

Endpoint

GET/v1/guides

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedGuideResponse

A paginated list of Guide. Contains a list of entries and page information.

Get a guide

Get a guide by its key.

Endpoint

GET/v1/guides/{guide_key}

Path parameters

guide_keystringrequired

The key of the guide to retrieve.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changesboolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

Guide

A guide defines an in-app guide that can be displayed to users based on priority and other conditions.

Archive a guide

Archives a given guide across all environments.

Endpoint

DELETE/v1/guides/{guide_key}

Path parameters

guide_keystringrequired

The key of the guide to archive.

Returns

ArchiveGuideResponse

The response from archiving a guide.

Upsert a guide

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

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

Endpoint

PUT/v1/guides/{guide_key}

Path parameters

guide_keystringrequired

The key of the guide to upsert.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

annotateboolean

Whether to annotate the resource. Only used in the Knock CLI.

commitboolean

Whether to commit the resource at the same time as modifying it.

commit_messagestring

The message to commit the resource with, only used if `commit` is `true`.

Request body

guideGuideRequestrequired

A request to create or update a guide.

Returns

WrappedGuideResponse

Wraps the Guide response under the `guide` key.

Validate a guide

Validates a guide payload without persisting it.

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

Endpoint

PUT/v1/guides/{guide_key}/validate

Path parameters

guide_keystringrequired

The key of the guide.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

guideGuideRequestrequired

A request to create or update a guide.

Returns

WrappedGuideResponse

Wraps the Guide response under the `guide` key.

Activate a guide

Activates (or deactivates) a guide in a given environment. You can either set the active status immediately or schedule it.

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

Endpoint

PUT/v1/guides/{guide_key}/activate

Path parameters

guide_keystringrequired

The key of the guide.

Query parameters

environmentstringrequired

The environment slug.

branchstring

The slug of a branch to use. This option can only be used when `environment` is `"development"`.

Request body

Returns

WrappedGuideResponse

Wraps the Guide response under the `guide` key.

Guide

A guide defines an in-app guide that can be displayed to users based on priority and other conditions.

Attributes

activation_url_patternsGuideActivationUrlPattern[]

A list of activation url patterns that describe when the guide should be shown.

activebooleanrequired

Whether the guide is active.

Default: false

archived_atstringnullable

The timestamp of when the guide was archived.

channel_keystring

The key of the channel in which the guide exists.

created_atstringrequired

The timestamp of when the guide was created.

deleted_atstringnullable

The timestamp of when the guide was deleted.

descriptionstringnullable

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

environmentstringrequired

The slug of the environment in which the guide exists.

keystringrequired

The unique key string for the guide object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

namestringrequired

A name for the guide. Must be at maximum 255 characters in length.

semverstring

The semver of the guide.

shastringrequired

The SHA hash of the guide.

stepsGuideStep[]

A list of guide step objects in the guide.

target_audience_idstringnullable

The ID of the target audience for the guide. When not set, will default to targeting all users.

target_property_conditionsobject

A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.

typestring

The type of the guide. This is derived from the message type of the guide steps.

updated_atstringrequired

The timestamp of when the guide was last updated.

validboolean

Whether the guide is valid.

GuideStep

A step in a guide that corresponds to a piece of UI and its content.

Attributes

namestring

A name for the step.

refstringrequired

The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

schema_keystringrequired

The key of the template schema to use for this step.

schema_semverstringrequired

The semantic version of the template schema to use.

schema_variant_keystringrequired

The key of the template schema variant to use.

valuesobject

A map of values that make up the step's content. Each value must conform to its respective template schema field settings.

GuideActivationUrlPattern

A rule that controls when a guide should be shown based on the user's location in the application.

Attributes

directivestringrequired

Whether to allow or block the guide at the specified pathname.

One of: "allow", "block"

Default: "allow"

pathnamestringrequired

The URL pathname pattern to match against. Must be a valid URI path.

API keys

API keys are used to authenticate requests to the Knock API.

Endpoints
POST/v1/api_keys/exchange

Exchange for API key

Given an authenticated service token and an environment, will exchange the service token for a secret API key that can be used to make requests to the public API.

Endpoint

POST/v1/api_keys/exchange

Query parameters

environmentstringrequired

The environment slug.

Returns

ExchangeForApiKeyResponse

Returns an API key that can be used to make requests to the public API.

Branches

Branches are a way to isolate changes to your Knock resources.

Endpoints
GET/v1/branches
DELETE/v1/branches/{branch_slug}
GET/v1/branches/{branch_slug}
POST/v1/branches/{branch_slug}

List branches

Returns a paginated list of branches. The branches will be returned in order of their last commit time (newest first).

Endpoint

GET/v1/branches

Query parameters

environmentstringrequired

The environment slug.

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

limitinteger

The number of entries to fetch per-page.

Returns

PaginatedBranchResponse

A paginated list of Branch. Contains a list of entries and page information.

Delete a branch

Deletes a branch by the branch_slug.

Endpoint

DELETE/v1/branches/{branch_slug}

Path parameters

branch_slugstringrequired

The slug of the branch to delete.

Query parameters

environmentstringrequired

The environment slug.

Returns

204 No Content

Get a branch

Returns a single branch by the branch_slug.

Endpoint

GET/v1/branches/{branch_slug}

Path parameters

branch_slugstringrequired

The slug of the branch to retrieve.

Query parameters

environmentstringrequired

The environment slug.

Returns

Branch

A branch object.

Create a branch

Creates a new branch off of the development environment with the given slug.

Endpoint

POST/v1/branches/{branch_slug}

Path parameters

branch_slugstringrequired

The slug for the new branch to create.

Query parameters

environmentstringrequired

The environment slug.

Returns

Branch

A branch object.

Branch

A branch object.

Attributes

created_atstringrequired

The timestamp of when the branch was created.

deleted_atstringnullable

The timestamp of when the branch was deleted.

last_commit_atstringnullable

The timestamp of the most-recent commit in the branch.

slugstringrequired

A unique slug for the branch. Cannot exceed 255 characters.

updated_atstringrequired

The timestamp of when the branch was last updated.

Shared

Resources that are shared across the API.

PageInfo

The information about a paginated result.

Attributes

afterstringnullable

The cursor to fetch entries after. Will only be present if there are more entries to fetch.

beforestringnullable

The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.

page_sizeintegerrequired

The number of entries to fetch per-page.