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.

Knock offers native SDKs in several popular programming languages:

• Node.js
• Python
• Ruby
• Go
• PHP
• Java
• C# (dotnet)
• Elixir

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 dashboard. You can create any number of API keys per environment, and there are two types of keys:

• Public 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 and 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 can have any number of publishable and secret keys. API requests will be scoped to the provided key's environment. You can create and revoke keys at any time from the API keys page in your dashboard.

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

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 documentation on enhanced security mode for more details on working with signed user tokens.

If you're concerned about exceeding a Knock rate limit, please contact us and we can help figure out a usage rate that's right for your specific needs.

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.

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 string of up to 255 characters 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. Idempotent requests are expected to be identical. To prevent accidental misuse, Knock returns an error when incoming parameters don't match those from the original request.

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.

Several V1 API endpoints return data that is subject to deletion according to the data retention policy associated with your account. These endpoints are tagged with the Retention policy applied badge.

For more information, see the data retention docs.

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.

Some V1 API endpoints that return lists of message data accept a trigger_data parameter. Knock uses this parameter to scope results it returns down to messages generated with the trigger data you provide.

The trigger data that Knock filters against is the combined and truncated data from the time the message was generated.

If a batch step preceded the creation of your message, the trigger data available for filtering will be the combined data for all the workflow triggers bundled into your batch. If a fetch step preceded, then the filterable data will include any data pulled in via the fetch step request.

Knock truncates trigger data for filtering to ensure it can efficiently process your request. The current data truncation rules are:

• Nested data structures (objects and arrays) are removed. Trigger data for filtering will be a JSON object with a single level of key-value pairs.
• Supported values are the JSON scalars string, number, boolean, and null.
• String values are limited to 256 characters in length. Strings that exceed this limit are truncated to the maximum.

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

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.