API Reference
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 following header:
Errors
Knock uses standard HTTP response codes to indicate the success or failure of your API requests.
2xxsuccess status codes confirm that your request worked as expected.4xxerror status codes indicate an error caused by incorrect or missing request information (e.g. providing an incorrect API key).5xxerror 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.
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.
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
Path parameters
Body parameters
Returns
A User.
Get a user
Retrieve a user by their ID, including all properties previously set.
Endpoint
Path parameters
Returns
A User.
User messages
Retrieve a paginated list of messages for a user. Will return most recent messages first.
Endpoint
Path parameters
Query parameters
Returns
A paginated list of Message records
Delete a user
Deletes a user by the id given.
Endpoint
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
Path parameters
Body parameters
Returns
The merged User.
Bulk identify users
Identifies up to 100 users at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.
Endpoint
Body parameters
Returns
A BulkOperation.
Bulk delete users
Deletes up to 100 users at a time. Returns a BulkOperation that executes the job asynchronously. Progress can be tracked via the BulkOperation API.
Endpoint
Body parameters
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 notify call, usually when something occurs in your product that you want your users to know about (e.g. a new comment.)
Triggering a workflow (notify)
A notify calls a workflow created via the Knock dashboard.
Endpoint
Path parameters
Body parameters
Returns
Triggering a workflow with inline identifications
In the recipients and actor fields in a notify 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.
See our guides on inline identification for users and for objects for more details on this use case.
Endpoint
Path parameters
Body parameters
Returns
Canceling workflows
Cancel a delayed workflow for one or more recipients.
Endpoint
Path parameters
Body parameters
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.
Attributes
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
Path 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.
Endpoint
Path parameters
Body parameters
Response
Returns a PreferenceSet.
Bulk set preferences
Sets the preferences for the users indicated via an asynchronous BulkOperation. This is a destructive operation and
will replace any existing users' preferences with the preferences sent.
Endpoint
Body parameters
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
Path 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.
Endpoint
Path parameters
Body parameters
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
Getting user channel data
Retrieves the channel data for the provided user (or object) on the channel specified.
Endpoint
Path parameters
Returns
200with aChannelDataobject (when found)404when not found
Setting user channel data
Sets channel data for the user and the channel specified.
Endpoint
Path parameters
Body parameters
Returns
200with aChannelDataobject (when set)404when the channel specified cannot be found422with errors when the data is incorrectly shaped
Unsetting user channel data
Unsets (removes) channel data for the user and the channel specified.
Endpoint
Path parameters
Returns
204no content404when 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
Path parameters
Returns
200with aChannelData(when found)404when not found
Setting object channel data
Sets channel data for the object and the channel specified.
Endpoint
Path parameters
Body parameters
Returns
200with aChannelDataobject (when set)404when the channel specified cannot be found422with errors when the data is incorrectly shaped
Unsetting object channel data
Unsets (removes) channel data for the object and the channel specified.
Endpoint
Path parameters
Returns
204no content404when 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
Get feed for user
Retrieves a feed of items for a given user_id on the given feed_id.
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
Path parameters
Query parameters
Returns
A feed response.
Messages
A message is a notification delivered on a particular channel to a user.
Attributes
Listing messages
Returns a paginated list of messages.
Endpoint
Query parameters
Returns
A paginated list of Message records
Fetching a message
Retrieve a message by the id.
Endpoint
Path parameters
Returns
A Message
Events
Returns a paginated list of events for a message.
Endpoint
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
Path parameters
Query parameters
Returns
A paginated list of Activity records
Content
Retrieves the contents of a message, generated and sent to the end provider.
Endpoint
Path parameters
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).
Updating a message status
Marks the given message as the status, recording an event in the process.
Endpoint
Path parameters
Returns
A Message.
Undoing a message status change
Un-marks the given message as the status, recording an event in the process.
Endpoint
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
Path parameters
Body parameters
Returns
A list of Messages that were mutated during the call.
Bulk changing message statuses in a channel
The bulk change endpoint allows you to modify all, or a subset of messages for a given channel via an asynchronous job. The messages
to be modified can be filtered using the properties listed below, and this operation will always return a BulkOperation
which allows you to track the status of the job.
Endpoint
Path parameters
Body parameters
Returns
A BulkOperation
Bulk operations
A bulk operation represents a set of changes that are to be performed across 0 or more records. The bulk operation resource 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. If you wish to pin this job to a specific point in
time, you can initiate it with a date filter (like older_than).
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
Path 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
Get an object
Retrieve an object in a collection by the id.
Endpoint
Path parameters
Response
Returns an Object.
Object messages
Returns a paginated list of messages for an object. Will return newest messages first.
Endpoint
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
Path parameters
Body parameters
Response
Returns an Object.
Delete an object
Deletes an object from a collection by the id provided.
Endpoint
Path parameters
Response
No response.
Bulk set objects in a collection
Bulk sets up to 100 objects at a time within a collection, returning an asynchronous BulkOperation that can be used to monitor the progress of the operation.
Endpoint
Path parameters
Body parameters
Response
Returns a BulkOperation.
Bulk delete objects in a collection
Bulk deletes up to 100 objects at a time within a collection, returning an asynchronous BulkOperation that can be used to monitor the progress of the operation.
Endpoint
Path parameters
Body parameters
Response
Returns a BulkOperation.