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
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.
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.
Scale | Limit |
---|---|
Batch Tier 1 | 1 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.
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
Response format
PageInfo response details
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
400
error codes you may encounter while working with the Knock API. We also provide additional context on how to resolve them.Your request needs a JWT signing key. You can learn more about JWT signing keys in our client authentication docs.
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.
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.)
Triggering a workflow
Invokes the workflow with the given key for the given set of recipients. Each recipient will have a workflow run triggered for them against the latest committed version of the workflow in the environment.
Read more about triggering a workflow.
This endpoint will return errors in the following cases:
- The workflow does not exist, or has not been committed to the environment
- The workflow is inactive
- The trigger data does not match the schema defined for the workflow (learn more)
Endpoint
Rate limitTier 5
Payload size limit
The workflow trigger endpoint enforces the following payload size limits:
- The
data
payload must be no more than10MB
- The
recipients
list must not exceed 1000 entries
Path parameters
Body parameters
Returns
Triggering a workflow with inline identifications
In the recipients
and actor
fields in a trigger call, you can optionally include maps 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 workflow trigger, 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
Rate limitTier 5
Payload size limit
The workflow trigger endpoint enforces the following payload size limits:
- The
data
payload must be no more than10MB
- The
recipients
list must not exceed 1000 entries
Path parameters
Body parameters
Returns
Canceling workflows
Cancel a delayed workflow for one or more recipients.
Read more about canceling workflows.
Endpoint
Rate limitTier 5
Payload size limit
The workflow cancelation endpoint enforces the following payload size limits:
- The
recipients
list must not exceed 1000 entries
Path parameters
Body parameters
Returns
204
, with empty content.
Messages
A message is a notification delivered on a particular channel to a user.
Attributes
Listing messages
Returns a paginated list of messages.
Endpoint
Rate limitTier 4
Query parameters
Returns
A paginated list of Message records
Fetching a message
Retrieve a message by the id.
Endpoint
Rate limitTier 4
Path parameters
Returns
A Message
Events
Returns a paginated list of events for a message.
Endpoint
Rate limitTier 4
Path parameters
Query parameters
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
Rate limitTier 4
Path parameters
Query parameters
Returns
A paginated list of Activity records
Message content
Retrieves the contents of a message, as generated and sent to the end provider.
Endpoint
Rate limitTier 3
Path parameters
Returns
A MessageContent
object.
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).
Batch message content
Retrieves the contents of a list of messages, as generated and sent to the end provider.
Endpoint
Rate limitTier 4
Query parameters
Returns
A list of MessageContent
objects for the provided message IDs.
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
Rate limitTier 4
Path parameters
Query parameters
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. Note that message engagement statuses are mutually inclusive; a message can have zero, one, or multiple statuses.
Endpoint
Rate limitTier 2
Path parameters
Returns
A Message.
Undoing a message status change
Un-marks the given status
on a message, recording an event in the process. Note that message engagement statuses are mutually inclusive; a message can have zero, one, or multiple statuses.
Endpoint
Rate limitTier 2
Path parameters
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
Rate limitTier 3
Batch rate limitBatch Tier 1
message_ids
and status
. This allows for 1 update per second per message per status.Path parameters
Body parameters
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
Rate limitTier 2
Path parameters
Body parameters
Returns
A BulkOperation
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
Get a feed for user
Retrieves a feed of items in reverse chronological order for a given user_id
on the given feed_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
Rate limitTier 2
Path parameters
Query parameters
Returns
A feed response.
Users
A user represents an individual who may need to receive a notification from Knock. They are always referenced by your internal identifier.
Attributes
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
Rate limitTier 3
Path parameters
Body parameters
Returns
A User.
List users
Lists all non-deleted users for the environment. You can optionally request all preferences associated with a user while listing by passing include[]=preferences
.
Endpoint
Rate limitTier 4
Query parameters
Returns
A paginated list of User
records.
Get a user
Retrieve a user by their ID, including all properties previously set.
Endpoint
Rate limitTier 4
Path parameters
Returns
A User.
User messages
Retrieve a paginated list of messages for a user. Will return most recent messages first.
Endpoint
Rate limitTier 4
Path parameters
Query parameters
Returns
A paginated list of Message records
Delete a user
Deletes a user by the id given.
Endpoint
Rate limitTier 2
Path parameters
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
Rate limitTier 2
Path parameters
Body parameters
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
Rate limitTier 1
Body parameters
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
Rate limitTier 1
Body parameters
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
List objects
Lists all objects under a collection. Note: does not validate that the collection exists and contains objects. You can optionally request all preferences associated with an object while listing by passing include[]=preferences
.
Endpoint
Rate limitTier 4
Path parameters
Query parameters
Response
Returns a paginated list of Object
records.
Get an object
Retrieve an object in a collection by the id.
Endpoint
Rate limitTier 4
Path parameters
Response
Returns an Object
.
Object messages
Returns a paginated list of messages for an object. Will return newest messages first.
Endpoint
Rate limitTier 4
Path parameters
Query parameters
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
Rate limitTier 3
Path parameters
Body parameters
Response
Returns an Object
.
Delete an object
Deletes an object from a collection by the id provided.
Endpoint
Rate limitTier 2
Path parameters
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
Rate limitTier 1
Path parameters
Body parameters
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
Rate limitTier 1
Path parameters
Body parameters
Response
Returns a BulkOperation
.
Subscriptions
List subscriptions
Lists all subscriptions to an object (the subscribers) or all of the current subscriptions for which the specified object is a recipient, depending on the mode
given. Defaults to returning subscriber information.
Will return the underlying recipient attached. Note: the object must exist.
Endpoint
Rate limitTier 4
Path parameters
Query parameters
Response
A paginated list response
User subscriptions
Returns a paginated list of subscriptions for a single user, in descending order.
Endpoint
Rate limitTier 4
Path parameters
Query parameters
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
Rate limitTier 3
Path parameters
Body parameters
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
Rate limitTier 1
Path parameters
Body parameters
Response
A BulkOperation
.
Delete subscriptons
Removes one or more recipients as subscribers to the object.
Endpoint
Rate limitTier 3
Path parameters
Body parameters
Response
A list of deleted ObjectSubscription
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.
The preference set :id
can be either "default"
or a tenant.id
. Learn more about per-tenant preferences.
Attributes
Listing user preferences
Retrieve all preference sets for a user. This endpoint returns a list of preference sets associated with the user.
Endpoint
Rate limitTier 4
Path parameters
Response
Returns a list of PreferenceSet
objects.
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
Rate limitTier 4
Path parameters
Query parameters
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 preferences.
Endpoint
Rate limitTier 3
Path parameters
Body parameters
Response
Returns a PreferenceSet
.
Listing object preferences
Retrieve all preference sets for an object. This endpoint returns a list of preference sets associated with the object.
Endpoint
Rate limitTier 4
Path parameters
Response
Returns a list of PreferenceSet
objects.
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
Rate limitTier 4
Path parameters
Query parameters
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 preferences.
Endpoint
Rate limitTier 3
Path parameters
Body parameters
Response
Returns a PreferenceSet
.
Bulk set user 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.
The preference set :id
can be either "default"
or a tenant.id
. Learn more about per-tenant preferences.
Please note: This is a destructive operation and will replace any existing users' preferences with the preferences sent.
Endpoint
Rate limitTier 1
Body parameters
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
List tenants for environment
Lists tenants for the environment of the API key
Endpoint
Rate limitTier 4
Response
Returns a list of Tenant
objects.
Get a tenant
Retrieve a tenant by its id.
Endpoint
Rate limitTier 4
Path parameters
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
Rate limitTier 3
Path parameters
Body parameters
Response
Returns a Tenant
.
Delete a tenant
Deletes a tenant by the id provided.
Endpoint
Rate limitTier 2
Path parameters
Response
No response.
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.
Attributes
List schedules
Returns a paginated list of schedules in descending order.
Endpoint
Rate limitTier 4
Query parameters
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
Rate limitTier 4
Query parameters
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
Rate limitTier 4
Query parameters
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
Rate limitTier 3
Body parameters
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
Rate limitTier 3
Body parameters
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
Rate limitTier 3
Body parameters
Response
The list of deleted Schedule
entities.
Channel data
ChannelData
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.
The shape of the data
payload varies depending on the channel type; you can learn more about channel data schemas here.
Attributes
Getting user channel data
Retrieves the channel data for the provided user (or object) on the channel specified.
Endpoint
Rate limitTier 4
Path parameters
Returns
200
with aChannelData
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
Rate limitTier 3
Path parameters
Body parameters
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 aChannelData
object (when set)404
when the channel specified cannot be found422
with errors when the data is incorrectly shaped
Unsetting user channel data
Unsets (removes) channel data for the user and the channel specified.
Endpoint
Rate limitTier 3
Path parameters
Returns
204
no content404
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
Rate limitTier 4
Path parameters
Returns
200
with aChannelData
(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
Rate limitTier 3
Path parameters
Body parameters
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 aChannelData
object (when set)404
when the channel specified cannot be found422
with errors when the data is incorrectly shaped
Unsetting object channel data
Unsets (removes) channel data for the object and the channel specified.
Endpoint
Rate limitTier 3
Path parameters
Returns
204
no content404
when the channel specified cannot be found
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
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
Rate limitTier 4
Path parameters
Returns
A BulkOperation
Slack
These endpoints handle communication with the Slack API to streamline authentication and data gathering. They are used by SlackKit components and hooks.
Slack auth check
Get the status of Slack authentication.
Endpoint
Rate limitTier 3
Path parameters
Body parameters
AccessTokenObject
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
Rate limitTier 3
Path parameters
Body parameters
AccessTokenObject
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.