API Reference

The Knock API enables you to add a complete notification engine to your product. This API provides programmatic access to integrating Knock via a REST-ful API.

Client libraries

Knock offers native SDKs in several popular programming languages:

API keys

Knock authenticates your API requests using your account's API keys. API requests made without authentication or using an incorrect key will return a 401 error. Requests using a valid key but with insufficient permissions will return a 403 error.

You can view and manage your API keys in the Developer Dashboard. There are two types of API keys:

  • Publishable keys are only meant to identify your account with Knock. They aren't secret, and can safely be made public in any of your client-side code. Publishable keys are prefixed with pk_*.

  • Secret keys can perform any API request to Knock, they should be kept secure and private! Be sure to prevent secret keys from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth. Secret keys are prefixed with sk_*.

Each Environment in your account has both a publishable and secret key pair. API requests will be scoped to the provided key's Environment.

Authentication

You must pass your API key to Knock as a Bearer token using the Authorization header.

Rate limits

Each endpoint in the Knock API is rate limited. Knock uses a tier system to determine the rate limit scale for each endpoint. When your request has been rate limited, the Knock API will return a 429 Too Many Requests error in response.

Knock's default behavior scopes rate limits based on the authorizing credential used in your requests. When you use a public or private API key to authorize a request, Knock will scope the rate limit for each endpoint by the environment associated with the key. If you use a signed user token as your authorizing credential, Knock will scope the rate limit by both the key's environment and the signing user. See our guide on enhanced security mode for more details on working with signed user tokens.

💡
Concerned about exceeding a Knock rate limit? Contact us and we can help figure out a usage rate that's right for your specific needs.
ScaleLimit
Tier 11 request / second
Tier 25 requests / second
Tier 360 requests / second
Tier 4200 requests / second
Tier 51,000 requests / second

Batch and bulk endpoint deduplication rate limits

Knock's batch and bulk endpoints may also have an additional layer of rate limiting applied. For these cases, Knock will also limit the number of times you can update a specific entity over a given scale. These limits are in place to prevent too many duplicate modifications applied to the same set of entities.

When you exceed a batch deduplication rate limit, Knock will still return a success (2xx) response if it is able to handle the request. For any entities not updated due to a rate limit hit, Knock will return the data as it exists at request time. Knock will also include an x-ratelimited-{param} header. The {param} value will be the name of the request param within which the rate limit was applied. The value will be a comma-delimited string of the param values that were rejected due to a rate limit hit.

Knock can apply batch deduplication rate limits to all or part of a request. If Knock rejects a subset of your batch, you can expect to see the full set of requested entities in the response body, and the IDs of those that were rejected in the x-ratelimited-{param} header.

ScaleLimit
Batch Tier 11 update / second / entity

Idempotent requests

Knock supports idempotency so that requests can be retried safely without unintended side effects.

To perform an idempotent request, set an Idempotency-Key header on your request. This idempotency key is a unique value that you generate for each request. It is used to identify and prevent the duplicate processing of requests. If you retry a request with the same idempotency key within 24 hours from the original request, Knock will return the same response as the original request. You may use any string up to 255 characters in length as an idempotency key.

Idempotency keys can be random UUIDs, or they can have some meaning in your application. For example, if you are sending a notification after a user has placed an order, you could use a key that is a combination of the reason for the notification, the user ID, and the order ID (e.g. order-placed:user-123:order-456). If your user then cancels the order, you could use an idempotency key like order-cancelled:user-123:order-456. This will ensure each type of notification is only sent once, even if your system retries the request multiple times.

If you are making calls to Knock from a job queue, the ID of the job can be a good choice for an idempotency key. If the job fails and is retried, the same idempotency key will be used.

💡
The default idempotency window for the Knock API is 24 hours. If you're interested in configuring a different idempotency window for your account, please contact us at support@knock.app.
Supported endpoints

Bulk endpoints

Knock exposes several endpoints that enqueue and return a BulkOperation. These endpoints perform their logic asynchronously, and you use the BulkOperation record to track progress.

In some cases, a bulk endpoint will accept a large set of entities to perform some action upon. In others, a bulk endpoint will accept a set of filter parameters and then execute an action across a large set of data on your account.

See the Bulk operations section for more information on parsing and polling bulk operation statuses.

Pagination

All top-level API resources expose support for bulk fetches via a list method. For instance, you can list users, list objects in a collection, and list subscriptions.

Resources that return multiple entities support the same cursor-based pagination to interact with the resources, using after, before, and page_size parameters as well as returning a common format for the metadata associated with the page.

Query parameters

afterstringThe pagination cursor to fetch items after. Usually derived from the after cursor in `PageInfo`.
beforestringThe pagination cursor to fetch items before. Usually derived from the before cursor in `PageInfo`.
page_sizenumber (optional)A number between 1 and 50 that represents the number of items to return in the response. Defaults to 50.

Response format

entriesmap[]A list of items contained in this response
page_infoPageInfoMetadata about the page of data returned

PageInfo response details

afterstringThe cursor to use to fetch items after the last item in the list. May be null when there are no other items to retrieve.
beforestringThe cursor to use to fetch items before the first item in the list. May be null when there are no other items to retrieve.
page_sizenumberThe maximum number of items requested in the page
total_countnumberThe total number of items in this resource (up-to 10,000)

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.

Error codes

Here's a list of common

400

error codes you may encounter while working with the Knock API. We also provide additional context on how to resolve them.
actor_missingYou called a workflow with an actor that has not yet been identified in Knock. To resolve, identify the actor prior to passing their ID in a workflow trigger.
api_key_expiredYour API key has expired. You can regenerate one on the developers page of the Knock dashboard.
api_key_missingThe API key you provided is invalid.
authentication_requiredThis endpoint requires authentication. Check the Authentication section of this API reference for more information.
channel_invalidThe channel you supplied in this request is invalid.
incorrect_token_typeYou cannot call this endpoint with this token.
invalid_paramsThe parameters supplied in your request were invalid. Check the payload you're sending to Knock to make sure it's valid.
invalid_user_tokenThe user token supplied is invalid.
missing_jwt_signing_key

Your request needs a JWT signing key. You can learn more about JWT signing keys in our client authentication docs.

missing_user_token

This environment requires that you supply a `X-Knock-User-Token` header when using a public API key. You can learn more in our client authentication docs.

workflow_inactiveThe workflow you attempted to invoke is marked as inactive. To resolve this error, activate the workflow on its page in the dashboard.
workflow_missingThe workflow you attemped to invoke could not be found. To resolve this error, confirm that you're calling the correct environment and that your workflow has been committed to it.

Users

A user represents an individual who may need to receive a notification from Knock. They are always referenced by your internal identifier.

Attributes

idstringUnique identifier for the user
namestring (optional)The full name of the user
emailstring (optional)The email of the user
avatarstring (optional)A URL for the avatar of the user
phone_numberstring (optional)The phone number of the user to use with SMS channels
*key-value pairsAny custom properties

Identify a user

Identifying a user will create or update a user in Knock, merging the properties given with what we currently have set on the user (if any).

Endpoint

PUT/users/:user_id

Rate limit

Tier 3

Path parameters

idstringUnique identifier of the user

Body parameters

namestring (optional)The name of the user
emailstring (optional)The email of the user
avatarstring (optional)A URL for the avatar of the user
phone_numberstring (optional)The phone number of the user to use with SMS channels
localestring (optional)The locale of the user. Used for message localization.
timezonestring (optional)The timezone of the user. Must be a valid tz database time zone string. Used for recurring schedules.
*key-value pairsAny custom properties

Returns

A User.

List users

Lists all non-deleted users for the environment.

Endpoint

GET/users

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)

Returns

A paginated list of User records.

Get a user

Retrieve a user by their ID, including all properties previously set.

Endpoint

GET/users/:user_id

Rate limit

Tier 4

Path parameters

idstringUnique identifier of the user

Returns

A User.

User messages

Retrieve a paginated list of messages for a user. Will return most recent messages first.

Endpoint

GET/users/:id/messages

Rate limit

Tier 4

Path parameters

idstringThe ID of the user

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestring (optional)Limits the results to only items of the source workflow
tenantstring (optional)Limits the results to items with the corresponding tenant, or where the tenant is empty
statusstring[] (optional)One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `not_sent`. Limits results to messages with the given delivery status(es)
channel_idstring (optional)Limits the results to only items that belong to the channel
workflow_categoriesstring[] (optional)Limits the results to only items related to any of the provided categories
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data

Returns

A paginated list of Message records

Delete a user

Deletes a user by the id given.

Endpoint

DELETE/users/:user_id

Rate limit

Tier 2

Path parameters

idstringUnique identifier of the user

Returns

No response.

Merge users

Merges the two users together, merging the user specified in the from_user_id into the user_id.

Read more on how merging works →

Endpoint

POST/users/:user_id/merge

Rate limit

Tier 2

Path parameters

idstringUnique identifier of the user to merge into

Body parameters

from_user_idstringUnique identifier of the user to merge from

Returns

The merged User.

Bulk identify users

Identifies up to 1000 users at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/users/bulk/identify

Rate limit

Tier 1

Body parameters

usersUser[]A list of users to upsert

Returns

A BulkOperation.

Bulk delete users

Deletes up to 1000 users at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/users/bulk/delete

Rate limit

Tier 1

Body parameters

user_idsstring[]Unique identifiers of the users to delete

Returns

A BulkOperation.

Workflows

A Workflow orchestrates the delivery of messages to your end users. When you configure a workflow you'll determine which channels its messages should route to, what those messages should look like on each channel, as well as any functions—batch, throttle, digest—you want applied to the messages prior to delivery. A workflow is triggered by a trigger call, usually when something occurs in your product that you want your users to know about (e.g. a new comment.)

Endpoints
POST/workflows/:key/trigger
POST/workflows/:key/cancel

Triggering a workflow

A trigger calls a workflow created via the Knock dashboard.

Endpoint

POST/workflows/:key/trigger

Rate limit

Tier 5

Path parameters

keystringThe key of the workflow to call

Body parameters

recipientsRecipientIdentifier[]A list of user ids or object references to notify for this workflow
actorRecipientIdentifier (optional)An identifier of who or what performed this action
cancellation_keystring (optional)The key to use for canceling the workflow
tenantstring (optional)The id of the tenant that this workflow run should be associated with
datadictionaryA set of key value pairs to pass to the notify

Returns

workflow_run_idstringA unique UUID of this workflow run

Triggering a workflow with inline identifications

In the recipients and actor fields in a trigger call, you can optionally include maps full of properties describing a user or an object. These can be properties describing a brand new user/object, or properties describing an update to an existing one. When this data is present in a notify call, Knock will persist it as part of processing the workflow. This is comparable to direct calls to the identify user or set object APIs.

Each recipient and actor must have an id field set in addition to other properties (e.g. email, name, or phone number).

See our guides on inline identification for users and for objects for more details on this use case.

Endpoint

POST/workflows/:key/trigger

Rate limit

Tier 5

Path parameters

keystringThe key of the workflow to call

Body parameters

recipientsRecipient[]A list of maps of properties describing a user or an object to identify in Knock and notify for this workflow
actorRecipient (optional)A map of properties describing a user or an object to identify in Knock and mark as who or what performed the notify action
cancellation_keystring (optional)The key to use for canceling the workflow
tenantstring (optional)The id of the tenant that this workflow run should be associated with
datadictionaryA set of key value pairs to pass to the notify call

Returns

workflow_run_idstringA unique UUID of this workflow run

Canceling workflows

Cancel a delayed workflow for one or more recipients.

Read more about canceling workflows.

Endpoint

POST/workflows/:key/cancel

Rate limit

Tier 5

Path parameters

keystringThe key of the workflow

Body parameters

cancellation_keystringThe cancellation key unique to the trigger call
recipientsRecipientIdentifier[]An optional list of user ids or object references to cancel the workflow for

Returns

204, with empty content.

Preferences

A preference determines whether a recipient should receive a particular type of notification. By default all preferences are opted in unless a preference explicitly opts the recipient out of the notification.

Read more about Preferences.

Attributes

idstringUnique identifier for the preference set
workflowsobjectA set of preferences for workflows, each can resolve to a boolean, to a set of channel types, or to a set of conditions
channel_typesobjectA set of preferences for channel types
categoriesobjectA set of preferences for workflow categories, each can resolve to a boolean, to a set of channel types, or to a set of conditions
Endpoints
GET/users/:user_id/preferences
GET/objects/:collection/:id/preferences
GET/users/:user_id/preferences/:id
GET/objects/:collection/:id/preferences/:id
PUT/users/:user_id/preferences/:id
PUT/objects/:collection/:id/preferences/:id
POST/users/bulk/preferences

Getting user preferences

Retrieve a user's preference set. Will always return an empty preference set object, even if it does not currently exist for the user.

Endpoint

GET/users/:user_id/preferences/:id

Rate limit

Tier 4

Path parameters

user_idstringUnique identifier for the user
idstringUnique identifier for the preference set

Query parameters

tenantstringAn optional tenant identifier to supply to return the user's preferences with any tenant defaults applied

Response

Returns a PreferenceSet.

Setting user preferences

Sets preferences within the given preference set. This is a destructive operation and will replace any existing preferences with the preferences given.

If no user exists in the current environment for the given :user_id, Knock will create the user entry as part of this request.

The preference set :id can be either "default" or a tenant.id. Learn more about per-tenant preference sets in our preferences guide.

Endpoint

PUT/users/:user_id/preferences/:id

Rate limit

Tier 3

Path parameters

user_idstringUnique identifier for the user
idstringUnique identifier for the preference set

Body parameters

channel_typesobjectA set of channel type preferences
workflowsobjectA set of workflow preferences, can be a boolean, an object containing channel type preferences, or a set of conditions
categoriesobjectA set of category preferences, can be a boolean, an object containing channel type preferences, or a set of conditions

Response

Returns a PreferenceSet.

Bulk set preferences

Bulk sets the preferences for up to 1000 users at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Please note: This is a destructive operation and will replace any existing users' preferences with the preferences sent.

Endpoint

POST/users/bulk/preferences

Rate limit

Tier 1

Body parameters

user_idsstring[]A list of user ids to set preferences for
preferences.idstringThe id of the preference set
preferences.channel_typesobjectA set of channel type preferences to set
preferences.workflowsobjectA set of workflow preferences, can be a boolean or an object containing channel type preferences
preferences.categoriesobjectA set of categories preferences, can be a boolean or an object containing channel type preferences

Response

Returns a BulkOperation.

Getting object preferences

Retrieve an object's preference set. Will always return an empty preference set object, even if it does not currently exist for the object.

Endpoint

GET/objects/:collection/:object_id/preferences/:id

Rate limit

Tier 4

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection of the object to lookup
idstringUnique identifier for the preference set

Query parameters

tenantstringAn optional tenant identifier to supply to return the user's preferences with any tenant defaults applied

Response

Returns a PreferenceSet.

Setting object preferences

Sets preferences within the given preference set. This is a destructive operation and will replace any existing preferences with the preferences given.

If no object exists in the current environment for the given :collection and :object_id, Knock will create the object as part of this request.

The preference set :id can be either "default" or a tenant.id. Learn more about per-tenant preference sets in our preferences guide.

Endpoint

PUT/objects/:collection/:object_id/preferences/:id

Rate limit

Tier 3

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection of the object to lookup
idstringUnique identifier for the preference set

Body parameters

channel_typesobjectA set of channel type preferences
workflowsobjectA set of workflow preferences, can be a boolean, an object containing channel type preferences, or a set of conditions
categoriesobjectA set of category preferences, can be a boolean, an object containing channel type preferences, or a set of conditions

Response

Returns a PreferenceSet.

Channel data

Channel data is channel-specific information stored on a Knock user or object that's needed to deliver a notification to an end provider.

For a push channel, this includes device-specific tokens that map the recipient to the device they use. For chat apps, such as Slack, this includes the access token used to send notifications to a customer's Slack channel.

Attributes

channel_idstringThe UUID of the channel this data belongs to
dataobjectThe provider specific channel data
Endpoints
GET/users/:user_id/channel_data/:channel_id
PUT/users/:user_id/channel_data/:channel_id
DELETE/users/:user_id/channel_data/:channel_id
GET/objects/:collection/:object_id/channel_data/:channel_id
PUT/objects/:collection/:object_id/channel_data/:channel_id
DELETE/objects/:collection/:object_id/channel_data/:channel_id

Getting user channel data

Retrieves the channel data for the provided user (or object) on the channel specified.

Endpoint

GET/users/:user_id/channel_data/:channel_id

Rate limit

Tier 4

Path parameters

user_idstringThe id of the user to lookup
channel_idstringThe id of the Knock channel to lookup

Returns

  • 200 with a ChannelData object (when found)
  • 404 when not found

Setting user channel data

Sets channel data for the user and the channel specified.

If no user exists in the current environment for the given :user_id, Knock will create the user entry as part of this request.

Endpoint

PUT/users/:user_id/channel_data/:channel_id

Rate limit

Tier 3

Path parameters

user_idstringThe id of the user to lookup
channel_idstringThe id of the Knock channel to lookup

Body parameters

dataobject

The data to set for the specified channel_id. The shape of the payload varies depending on the channel. You can learn more about channel data schemas here.

Returns

  • 200 with a ChannelData object (when set)
  • 404 when the channel specified cannot be found
  • 422 with errors when the data is incorrectly shaped

Unsetting user channel data

Unsets (removes) channel data for the user and the channel specified.

Endpoint

DELETE/users/:user_id/channel_data/:channel_id

Rate limit

Tier 3

Path parameters

user_idstringThe id of the user to lookup
channel_idstringThe id of the Knock channel to lookup

Returns

  • 204 no content
  • 404 when the channel specified cannot be found

Getting object channel data

Retrieves the channel data for the provided user (or object) on the channel specified.

Endpoint

GET/objects/:collection/:object_id/channel_data/:channel_id

Rate limit

Tier 4

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection of the object to lookup
channel_idstringThe id of the Knock channel to lookup

Returns

  • 200 with a ChannelData (when found)
  • 404 when not found

Setting object channel data

Sets channel data for the object and the channel specified.

If no object exists in the current environment for the given :collection and :object_id, Knock will create the object as part of this request.

Endpoint

PUT/objects/:collection/:object_id/channel_data/:channel_id

Rate limit

Tier 3

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection of the object to lookup
channel_idstringThe id of the Knock channel to lookup

Body parameters

dataobject

The data to set for the specified channel_id. The shape of the payload varies depending on the channel. You can learn more about channel data schemas here.

Returns

  • 200 with a ChannelData object (when set)
  • 404 when the channel specified cannot be found
  • 422 with errors when the data is incorrectly shaped

Unsetting object channel data

Unsets (removes) channel data for the object and the channel specified.

Endpoint

DELETE/objects/:collection/:object_id/channel_data/:channel_id

Rate limit

Tier 3

Path parameters

object_idstringThe id of the object to lookup
collectionstringThe parent collection of the object to lookup
channel_idstringThe id of the Knock channel to lookup

Returns

  • 204 no content
  • 404 when the channel specified cannot be found

Feeds

A feed exposes the messages delivered to an in-app feed channel, formatted specially to be consumed in a notification feed.

A feed will always return a list of FeedItems, which are pointers to a message delivered and contain all of the information needed in order to render an item within a notification feed.

Note: feeds are a specialized form of messages that are designed purely for in-app rendering, and as such return information that is required on the client to do so

Attributes

entriesFeedItem[]An ordered list of feed items (most recent first)
page_infoPageInfoPagination information for the items returned
varsobjectEnvironment specific account variables
metaFeedMetadataInformation about the total unread and unseen items
Endpoints
GET/users/:user_id/feeds/:feed_id
GET/users/:user_id/feeds/:feed_id/settings

Get a feed for user

Retrieves a feed of items in reverse chronological order for a given user_id on the given in_app_feed_channel_id. In the case where the user has not yet been identified within Knock, this endpoint will return an empty feed.

You can customize the response for this endpoint by using response filters to exclude or only include certain properties on your resources.

Note: if you're making this call from a client-side environment you should be using your publishable key along with a user token to make this request

Endpoint

GET/users/:user_id/feeds/:in_app_feed_channel_id

Rate limit

Tier 2
⚠️
This endpoint's rate limit is always scoped per-user and per-environment. This is true even for requests made without a signed user token.

Path parameters

user_idstringThe ID of the user
feed_idstringThe ID of the feed (the channel ID)

Query parameters

page_sizenumberThe total number to retrieve per page. Defaults to 50 and the max limit is 200.
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestring (optional)Limits the feed to only items of the source workflow
tenantstring (optional)Limits the feed to only display items with the corresponding tenant, or where the tenant is empty
has_tenantboolean (optional)Scope the feed to display items with or without any tenancy
statusstring (optional)One of `unread`,`read`, `unseen`,`seen`, `all`
workflow_categoriesstring[] (optional)Limits the feed to only display items related to any of the provided categories
archivedstring (optional)One of `include`, `exclude`, `only` (defaults to `exclude`)
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data

Returns

A feed response.

Messages

A message is a notification delivered on a particular channel to a user.

Attributes

idstringThe unique ID of this message
channel_idstringThe ID of the channel through which this message was delivered
recipientRecipientIdentifierThe ID of the user who received the message. If the recipient is an object, the result will be an object containing its id and collection
actorsRecipientIdentifier[]One or more actors that are associated with this message. Note: this is a list that can contain up to 10 actors if the message is produced from a batch.
workflowstringThe key of the workflow that this message was generated from
tenantstringThe ID of the tenant that this message belongs to
statusstringThe delivery status for the message. One of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `seen`, `unseen`.
engagement_statusesstring[]One or more engagement statuses for the message. Each engagement status can be one of `seen`, `read`, `interacted`, `link_clicked`, or `archived`.
seen_atstring (optional)When the message was last seen
read_atstring (optional)When the message was last read
interacted_atstring (optional)When the message was last interacted with
link_clicked_atstring (optional)When a message link was last clicked
archived_atstring (optional)When the message was archived
inserted_atstringWhen the message was created
updated_atstringWhen the message was last updated
sourceobjectThe workflow which is the message source
dataobjectData from the activities linked to the message
Endpoints
GET/messages
GET/messages/:id
GET/messages/:id/activities
GET/messages/:id/events
GET/messages/:id/content
GET/messages/:id/delivery_logs
PUT/messages/:id/:status
DELETE/messages/:id/:status
POST/messages/batch/:status
POST/channels/:id/messages/bulk/:status

Listing messages

Returns a paginated list of messages.

Endpoint

GET/messages

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestring (optional)Limits the results to only items of the source workflow
tenantstring (optional)Limits the results to items with the corresponding tenant, or where the tenant is empty
statusstring[] (optional)One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `not_sent`. Limits results to messages with the given delivery status(es).
channel_idstring (optional)Limits the results to only items that belong to the channel
workflow_categoriesstring[] (optional)Limits the results to only items related to any of the provided categories
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data

Returns

A paginated list of Message records

Fetching a message

Retrieve a message by the id.

Endpoint

GET/messages/:id

Rate limit

Tier 4

Path parameters

idstringThe ID of the message

Returns

A Message

Events

Returns a paginated list of events for a message.

Endpoint

GET/messages/:id/events

Rate limit

Tier 4

Path parameters

idstringThe ID of the message

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)

Returns

A paginated list of MessageEvent records

Activities

Returns a paginated list of activities associated with the message. Note: for non batched messages this will always return a single activity. For messages produced after a batch step, this will contain one or more activities.

Endpoint

GET/messages/:id/activities

Rate limit

Tier 4

Path parameters

idstringThe ID of the message

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data

Returns

A paginated list of Activity records

Content

Retrieves the contents of a message, generated and sent to the end provider.

Endpoint

GET/messages/:id/content

Rate limit

Tier 3

Path parameters

idstringThe ID of the message

Returns

A MessageContent.

Note: the data attribute of the MessageContent payload will vary based on the type of message being sent (email, chat, in-app feed, sms and push).

Delivery logs

Retrieves the delivery logs of a message, generated while sending and checking the delivery status of the message sent to an end provider. Note: for in-app channels, the delivery logs will always be an empty list.

Endpoint

GET/messages/:id/delivery_logs

Rate limit

Tier 4

Path parameters

idstringThe ID of the message

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after
beforestringThe cursor to retrieve items before

Returns

A paginated list of MessageDeliveryLog.

Note: the request and response attributes of the MessageDeliveryLog payload will vary depending on the provider.

Updating a message status

Marks the given message with the provided status, recording an event in the process.

Endpoint

PUT/messages/:id/:status

Rate limit

Tier 2

Path parameters

idstringThe ID of the message
statusenumOne of `seen`, `read`, `interacted`, `archived`

Returns

A Message.

Undoing a message status change

Un-marks the given status on a message, recording an event in the process.

Endpoint

DELETE/messages/:id/:status

Rate limit

Tier 2

Path parameters

idstringThe ID of the message
statusenumOne of `seen`, `read`, `interacted`, `archived`

Returns

A Message.

Batch changing message statuses

Multiple messages can be changed at once using the batch API, where all message ids given in will have their statuses changed.

Endpoint

POST/messages/batch/:status

Rate limit

Tier 3

Batch rate limit

Batch Tier 1
⚠️
Knock scopes this batch rate limit by message_ids and status. This allows for 1 update per second per message per status.

Path parameters

statusenumOne of `seen`, `read`, `interacted`, `archived` or `unseen`, `unread`, `unarchived`

Body parameters

message_idsstring[]A list of one or more message IDs

Returns

A list of Messages that were mutated during the call.

Bulk changing message statuses in a channel

Apply the given status to a set of messages for the given channel. Will modify all valid messages, or a subset based on the filters provided.

Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/channels/:id/messages/bulk/:status

Rate limit

Tier 2

Path parameters

idstringThe ID of a channel that you wish to modify messages under
statusenumOne of `seen`, `read`, `interacted`, `archived` or `unseen`, `unread`, `unarchived`

Body parameters

user_idsstring[] (optional)Scope the bulk update to one or more users
tenantsstring[] (optional)A list of one or more tenants to match
has_tenantboolean (optional)When set to false, will only return messages that do not have a tenant associated
workflowsstring[] (optional)A list of one or more workflow keys to match
older_thanstring (optional)An ISO-8601 timestamp to find messages created before
newer_thanstring (optional)An ISO-8601 timestamp to find messages created after
delivery_statusenum (optional)Limit messages to one of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `not_sent`
engagement_statusenum (optional)Limit messages to one of `seen`, `unseen`, `read`, `unread`, `archived`, `unarchived`, `interacted`

Returns

A BulkOperation

Bulk operations

A bulk operation is a set of changes applied across 0 or more records triggered via a call to the Knock API and performed asynchronously. The BulkOperation record represents the state of the operation, including recording the number of rows that have been modified during the operation.

Please note here: the estimated_total_rows field may have a different value to the processed_rows field due to the asynchronous nature of the operation.

Attributes

idstringThe unique ID of this bulk operation
namestringThe type of operation being performed
estimated_total_rowsintegerAn approximation of the number of rows that will be mutated in this operation
processed_rowsintegerThe number of the rows that have been handled in this operation, either successfully or in error
success_countintegerThe number of the rows that have been modified successfully in this operation
error_countintegerThe number of the rows that errored in this operation
error_itemsmap[]A list of items that errored in this operation, if available
statusenumOne of `queued`, `processing`, `completed`, `failed`
started_atstringAn ISO-8601 datetime string for when the operation started processing
completed_atstringAn ISO-8601 datetime string for when the operation completed processing
failed_atstringAn ISO-8601 datetime string for when the operation failed processing
Endpoints
GET/bulk_operations/:id

Retrieve a bulk operation

Retrieve the bulk operation, revealing the current status and the number of rows processed. You can poll this endpoint to understand when a bulk operation has finished executing (either completed, or failed).

Endpoint

GET/bulk_operations/:id

Rate limit

Tier 4

Path parameters

idstringThe ID of a bulk operation to retrieve

Returns

A BulkOperation

Objects

An Object represents a resource in your system that you've stored in Knock.

The most common use case for objects is as a store for non-user channel data when sending Slack notifications.

Attributes

collectionstringThe type of object you are storing in Knock.
idstringA unique identifier for the object within the collection.
propertiesobjectAn object of key-value pairs for attributes you want to associate with the object. Each collection has its own schema in Knock as defined by these properties.

List objects

Lists all objects under a collection. Note: does not validate that the collection exists and contains objects.

Endpoint

GET/objects/:collection

Rate limit

Tier 4

Path parameters

collectionstringThe type of object you are storing in Knock.

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)

Response

Returns a paginated list of Object records.

Get an object

Retrieve an object in a collection by the id.

Endpoint

GET/objects/:collection/:id

Rate limit

Tier 4

Path parameters

collectionstringThe type of object you are storing in Knock.
idstringA unique identifier for the object within the collection.

Response

Returns an Object.

Object messages

Returns a paginated list of messages for an object. Will return newest messages first.

Endpoint

GET/objects/:collection/:id/messages

Rate limit

Tier 4

Path parameters

collectionstringThe collection of the object
idstringThe ID of the object

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestring (optional)Limits the results to only items of the source workflow
tenantstring (optional)Limits the results to items with the corresponding tenant, or where the tenant is empty
statusstring[] (optional)One or more of `queued`, `sent`, `delivered`, `delivery_attempted`, `undelivered`, `not_sent`. Limits results to messages with the given status(es)
channel_idstring (optional)Limits the results to only items that belong to the channel
workflow_categoriesstring[] (optional)Limits the results to only items related to any of the provided categories
trigger_dataJSON string (optional)Limits the results to only items that were generated with the given data

Returns

A paginated list of Message records

Set an object

Sets an object within a collection, performing an upsert operation. Any existing properties will be merged with the incoming properties.

Endpoint

PUT/objects/:collection/:id

Rate limit

Tier 3

Path parameters

collectionstringThe type of object you are storing in Knock.
idstringA unique identifier for the object within the collection.

Body parameters

*anyA collection of key value pairs to set as properties for this object.

Response

Returns an Object.

Delete an object

Deletes an object from a collection by the id provided.

Endpoint

DELETE/objects/:collection/:id

Rate limit

Tier 2

Path parameters

collectionstringThe type of object you are storing in Knock.
idstringA unique identifier for the object within the collection.

Response

No response.

Bulk set objects in a collection

Bulk sets up to 1000 objects at a time within a collection. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/objects/:collection/bulk/set

Rate limit

Tier 1

Path parameters

collectionstringThe type of object you are storing in Knock.

Body parameters

objects[].idstringThe id of the object to set.
objects[].*anyKey value pairs to set as properties on this object.

Response

Returns a BulkOperation.

Bulk delete objects in a collection

Bulk deletes up to 1000 objects at a time within a collection. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/objects/:collection/bulk/delete

Rate limit

Tier 1

Path parameters

collectionstringThe type of object you are storing in Knock.

Body parameters

object_idsstring[]The ids of the objects to delete within the collection

Response

Returns a BulkOperation.

Tenants

A Tenant represents a grouping with configurable settings that can be applied to a workflow when it's triggered in order to override account-level settings such as branding.

Use tenants when sending a notification to user(s) that you want to configure specific brand elements for, such as a separate organization logo.

Attributes

idstringA unique identifier for the tenant.
propertiesobjectAn object of key-value pairs for attributes you want to associate with the tenant. Currently only name is accepted as an attribute for tenants.
settingsobjectAn object of key-value pairs for configurable settings on a tenant. Currently settings only contain a branding key which points to the following configurable values: primary_color, primary_color_contrast, icon_url, and logo_url.
Endpoints
GET/tenants
GET/tenants/:id
PUT/tenants/:id
DELETE/tenants/:id

List tenants for environment

Lists tenants for the environment of the API key

Endpoint

GET/tenants

Rate limit

Tier 4

Response

Returns a list of Tenant objects.

Get a tenant

Retrieve a tenant by its id.

Endpoint

GET/tenants/:id

Rate limit

Tier 4

Path parameters

idstringA unique identifier for the tenant.

Response

Returns a Tenant.

Set a tenant

Sets a tenant within an environment, performing an upsert operation. Any existing properties will be merged with the incoming properties.

Endpoint

PUT/tenants/:id

Rate limit

Tier 3

Path parameters

idstringA unique identifier for the tenant.

Body parameters

namestringThe name to set on the tenant's name property.
settingsobjectAn object of key-value pairs for configurable settings on a tenant. See example for possible key-value pairs.

Response

Returns a Tenant.

Delete a tenant

Deletes a tenant by the id provided.

Endpoint

DELETE/tenants/:id

Rate limit

Tier 2

Path parameters

idstringA unique identifier for the tenant within the collection.

Response

No response.

Subscriptions

A subscription represents the relationship between a recipient (the subscriber) and an object.

Attributes

propertiesobjectAn object of key-value pairs for attributes you want to associate with the subscription.
recipientobjectA user or an object associated with this subscription
Endpoints
GET/objects/:collection/:id/subscriptions
GET/users/:id/subscriptions
POST/objects/:collection/:id/subscriptions
POST/objects/:collection/bulk/subscriptions/add
DELETE/objects/:collection/:id/subscriptions

List subscriptions

Lists all subscriptions for an object (the subscribers) or all of the current subscriptions for the object, depending on the mode given. Defaults to returning subscriber information.

Will return the underlying recipient attached. Note: the object must exist.

Endpoint

GET/objects/:collection/:id/subscriptions

Rate limit

Tier 4

Path parameters

collectionstringA collection that the object belongs to
idstringThe unique identifier of the object in the collection

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after
beforestringThe cursor to retrieve items before
modestringWhen set to `recipient` will return all of the active subscriptions for the object, not the subscribers of the object.
recipientsstring[]A list of recipient identifiers to filter subscribers of the object. Filtering by recipients will only be enabled when mode is not set.

Response

A paginated list response

User subscriptions

Returns a paginated list of subscriptions for a single user, in descending order.

Endpoint

GET/users/:id/subscriptions

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)

Response

A paginated response containing a list of Subscription entities.

Add subscriptions

Adds one or more recipients as subscribers to the object by creating subscriptions.

Endpoint

POST/objects/:collection/:id/subscriptions

Rate limit

Tier 3

Path parameters

collectionstringA collection that the object belongs to
idstringThe unique identifier of the object in the collection

Body parameters

recipientsRecipientIdentifier[]A list of recipient identifers
propertiesmap (optional)An optional set of key-value pairs to associate with the subscriptions

Response

A list of created ObjectSubscription

Bulk add subscriptions

Creates subscriptions for one or more recipients to one or more objects within the specified collection. You can create up to 50 recipient subscriptions per object at a time and you can modify up to 100 objects per request, totaling up to 5,000 operations per request.

Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.

Endpoint

POST/objects/:collection/bulk/subscriptions/add

Rate limit

Tier 1

Path parameters

collectionstringThe type of object you are storing in Knock.

Body parameters

subscriptionsAddSubscriptionsOp[]A list of subscriptions to create. Each entry represents a set of Recipients to subscribe to an Object.

Response

A BulkOperation.

Delete subscriptons

Removes one or more recipients as subscribers to the object.

Endpoint

DELETE/objects/:collection/:id/subscriptions

Rate limit

Tier 3

Path parameters

collectionstringA collection that the object belongs to
idstringThe unique identifier of the object in the collection

Body parameters

recipientsRecipientIdentifier[]A list of recipient identifers

Response

A list of deleted ObjectSubscription

Schedules

A schedule allows you to automatically trigger a workflow at a given time for one or more recipients. You can think of a schedule as a managed, recipient-timezone-aware cron job that Knock will run on your behalf.

Learn more about schedules

Attributes

idstringA unique, Knock generated identifier for the schedule.
actorRecipient | nullThe actor to be referenced on the workflow trigger.
recipientRecipientThe recipient of the scheduled workflow.
dataobject | nullStatic data to be passed to the workflow trigger.
workflowstringThe key of the workflow that will be triggered in this schedule.
tenantstring | nullThe tenant to be passed to the workflow trigger.
repeatsScheduleRepeat[]A list of one or more repeat definitions that determine when this schedule should run.
last_occurrence_at | nulldatetimeA datetime string in UTC that indicates when the last run for the schedule happened.
next_occurrence_at | nulldatetimeA datetime string in the recipient's timezone that indicates when the schedule will next run, generated from the repeat rules.
Endpoints
GET/schedules
GET/users/:id/schedules
GET/objects/:collection/:id/schedules
POST/schedules
PUT/schedules
DELETE/schedules

List schedules

Returns a paginated list of schedules in descending order.

Endpoint

GET/schedules

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
workflowstring (required)The workflow key to filter schedules for.
recipientsstring[]A list of recipient identifiers to filter schedules for.
tenantstringA tenant identifier to filter schedules for.

Response

A paginated response containing a list of Schedule entities.

User schedules

Returns a paginated list of schedules for a single user, in descending order.

Endpoint

GET/users/:id/schedules

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
workflowstring (required)The workflow key to filter schedules for.
tenantstringA tenant identifier to filter schedules for.

Response

A paginated response containing a list of Schedule entities.

Object schedules

Returns a paginated list of schedules for a single object, in descending order.

Endpoint

GET/objects/:collection/:id/schedules

Rate limit

Tier 4

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
workflowstring (required)The workflow key to filter schedules for.
tenantstringA tenant identifier to filter schedules for.

Response

A paginated response containing a list of Schedule entities.

Create schedules

Creates new schedules for the recipients given using. Up to 100 recipients may be specified in a single schedule creation call. Recipients may be inline-identified during this call.

Endpoint

POST/schedules

Rate limit

Tier 3

Body parameters

recipientsRecipientIdentifier[]A list of recipient identifers
actorRecipient | nullThe actor to be referenced on the workflow trigger for this schedule.
dataobject | nullStatic data to be passed to the workflow trigger or this schedule.
workflowstringThe key of the workflow that will be triggered in this schedule.
tenantstring | nullThe tenant to be passed to the workflow trigger for this schedule.
repeatsScheduleRepeat[]A list of one or more repeat definitions that determine when this schedule should run.

Response

The list of created Schedule entities.

Update schedules

Updates the schedules for the schedule_ids given. Can update up to 100 schedules at a time.

Endpoint

PUT/schedules

Rate limit

Tier 3

Body parameters

schedule_idsstring[]A list of schedule ids of the schedules to mutate.
actorRecipient | nullThe actor to be referenced on the workflow trigger for this schedule.
dataobject | nullStatic data to be passed to the workflow trigger or this schedule.
tenantstring | nullThe tenant to be passed to the workflow trigger for this schedule.
repeatsScheduleRepeat[]A list of one or more repeat definitions that determine when this schedule should run.

Response

The list of updated Schedule entities.

Delete schedules

Deletes the schedules for the schedule_ids given. Can delete up to 100 schedules at a time. Deleting a schedule will cancel its next occurrence immediately. Any running scheduled workflows will not be affected.

Endpoint

DELETE/schedules

Rate limit

Tier 3

Body parameters

schedule_idsstring[]A list of schedule ids of the schedules to mutate.

Response

The list of deleted Schedule entities.

Slack

Handles communication with the Slack API to streamline authentication and data gathering.

Endpoints
GET/providers/slack/:channel_id/auth_check
GET/providers/slack/:channel_id/channels
PUT/providers/slack/:channel_id/revoke_access

Slack auth check

Get the status of Slack authentication.

Endpoint

GET/providers/slack/:channel_id/auth_check

Rate limit

Tier 3

Path parameters

channel_idstringThe Knock Slack channel ID

Body parameters

access_token_objectAccessTokenObjectAn object containing the `object_id` and `collection` of the Object or Tenant that contains the access token for Slack.

AccessTokenObject

objectIdstringID of the Object or Tenant.
collectionstringCollection of the Object or Tenant. If Tenant, should be `$tenants`.

Response

Connection data from the Slack API.

Slack channels

Get a list of the Slack channels for the access token stored in the given access token object.

Endpoint

GET/providers/slack/:channel_id/channels

Rate limit

Tier 3

Path parameters

channel_idstringThe Knock Slack channel ID

Body parameters

access_token_objectAccessTokenObjectAn object containing the `object_id` and `collection` of the Object or Tenant that contains the access token for Slack.
query_optionsobjectAn optional object containing the query options passed to Slack. See Slack documentation for options: https://api.slack.com/methods/conversations.list#arg_cursor

AccessTokenObject

objectIdstringID of the Object or Tenant.
collectionstringCollection of the Object or Tenant. If Tenant, should be `$tenants`.

Response

List of partial data about the Slack channels requested.

Slack revoke access

Revoke an access token from Slack and remove it from the access token object.

Endpoint

GET/providers/slack/:channel_id/revoke_access

Rate limit

Tier 3

Path parameters

channel_idstringThe Knock Slack channel ID

Body parameters

access_token_objectAccessTokenObjectAn object containing the `object_id` and `collection` of the Object or Tenant that contains the access token for Slack.

AccessTokenObject

objectIdstringID of the Object or Tenant.
collectionstringCollection of the Object or Tenant. If Tenant, should be `$tenants`.