Objects
An [Object](/concepts/objects) represents a resource in your system that you've stored in Knock. It can be used to send out-of-app notifications to non-user recipients (such as a public channel in a chat app), or to trigger notifications to [subscribers](/concepts/subscriptions) of a non-user resource such as a shared document.
Objects
#An Object represents a resource in your system that you've stored in Knock. It can be used to send out-of-app notifications to non-user recipients (such as a public channel in a chat app), or to trigger notifications to subscribers of a non-user resource such as a shared document.
Set an object
#Creates a new object or updates an existing one in the specified collection. This operation is used to identify objects with their properties, as well as optional preferences and channel data.
Endpoint
Rate limit
Tier 3Path parameters
The collection this object belongs to.
Unique identifier for the object.
Request body
A request to set channel data for a type of channel inline.
The locale of the object. Used for message localization.
An optional name for the object.
Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.
The timezone of the object. Must be a valid tz database time zone string. Used for recurring schedules.
Any additional custom properties.
Returns
A custom Object entity which belongs to a collection.
The typename of the schema.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
The custom properties associated with the object.
The timestamp when the resource was last updated.
Get an object
#Retrieves a specific object by its ID from the specified collection. Returns the object with all its properties.
Endpoint
Rate limit
Tier 4Path parameters
The collection this object belongs to.
Unique identifier for the object.
Returns
A custom Object entity which belongs to a collection.
The typename of the schema.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
The custom properties associated with the object.
The timestamp when the resource was last updated.
List objects in a collection
#Returns a paginated list of objects from the specified collection. Optionally includes preference data for the objects.
Endpoint
Rate limit
Tier 4Path parameters
The collection this object belongs to.
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Includes preferences of the objects in the response.
Returns
A paginated list of objects in a collection.
A list of objects.
The typename of the schema.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
The custom properties associated with the object.
The timestamp when the resource was last updated.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Delete an object
#Permanently removes an object from the specified collection. This operation cannot be undone.
Endpoint
Rate limit
Tier 3Path parameters
The collection this object belongs to.
Unique identifier for the object.
Returns
List preference sets
#Returns a paginated list of preference sets for the specified object.
Endpoint
Rate limit
Tier 4Path parameters
Unique identifier for the object.
The collection this object belongs to.
Returns
A list of preference sets for the object
Get object preference set
#Returns the preference set for the specified object and preference set id.
Endpoint
Rate limit
Tier 4Path parameters
Unique identifier for the object.
The collection this object belongs to.
Unique identifier for the preference set.
Returns
A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the channel ID and the values are the preference settings for that channel ID.
Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
Unique identifier for the preference set.
An object where the key is the workflow key and the values are the preference settings for that workflow.
Update a preference set
#Sets preferences within the given preference set. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use '__persistence_strategy': 'merge' to merge with existing preferences instead. 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 limit
Tier 3Path parameters
Unique identifier for the object.
The collection this object belongs to.
Unique identifier for the preference set.
Request body
Controls how the preference set is persisted. 'replace' will completely replace the preference set, 'merge' will merge with existing preferences.
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the channel ID and the values are the preference settings for that channel ID.
Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
An object where the key is the workflow key and the values are the preference settings for that workflow.
Returns
A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.
An object where the key is the category and the values are the preference settings for that category.
An object where the key is the channel type and the values are the preference settings for that channel type.
An object where the key is the channel ID and the values are the preference settings for that channel ID.
Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
Unique identifier for the preference set.
An object where the key is the workflow key and the values are the preference settings for that workflow.
List object schedules
#Returns a paginated list of schedules for an object.
Endpoint
Rate limit
Tier 4Path parameters
The ID of the object to list schedules for.
The collection of the object to list schedules for.
Query parameters
Filter schedules by tenant id.
Filter schedules by workflow id.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Returns
A response containing a list of schedules.
A list of schedules.
The typename of the schema.
A map of properties describing a user or an object to identify in Knock and mark as who or what performed the action.
An optional map of data to pass into the workflow execution. There is a 10MB limit on the size of the full data payload. Any individual string value greater than 1024 bytes in length will be truncated in your logs.
Unique identifier for the schedule.
Timestamp when the resource was created.
The last occurrence of the schedule.
The next occurrence of the schedule.
A recipient of a notification, which is either a user or an object.
The repeat rule for the schedule.
The typename of the schema.
The day of the month to repeat the schedule.
The days of the week to repeat the schedule.
The frequency of the schedule.
The hour of the day to repeat the schedule.
The interval of the schedule.
The minute of the hour to repeat the schedule.
The tenant to trigger the workflow for. Triggering with a tenant will use any tenant-level overrides associated with the tenant object, and all messages produced from workflow runs will be tagged with the tenant.
The timestamp when the resource was last updated.
The workflow the schedule is applied to.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
List messages
#Returns a paginated list of messages for a specific object in the given collection. Allows filtering by message status and provides various sorting options.
Endpoint
Rate limit
Tier 4Path parameters
The collection this object belongs to.
Unique identifier for the object.
Query parameters
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Limits the results to items with the corresponding tenant.
Limits the results to items with the corresponding channel ID.
Limits the results to messages with the given delivery status.
Limits the results to messages with the given engagement status.
Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.
Limits the results to messages related to any of the provided categories.
Limits the results to messages triggered by the given workflow key.
Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.
Limits the results to messages for a specific recipient's workflow run.
Limits the results to only messages that were generated with the given data. See trigger data filtering for more information.
Limits the results to messages inserted after or on the given date.
Limits the results to messages inserted before or on the given date.
Limits the results to messages inserted after the given date.
Limits the results to messages inserted before the given date.
Returns
A paginated list of messages.
A list of messages.
The typename of the schema.
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.
Timestamp when the message was archived.
A configured channel, which is a way to route messages to a provider.
The timestamp of when the channel was created.
The unique identifier for the channel.
Unique identifier for the channel within a project (immutable once created).
The human-readable name of the channel.
The ID of the provider that this channel uses to deliver messages.
The type of channel, determining what kind of messages it can send.
The timestamp of when the channel was last updated.
Deprecated, use channel.id instead.
Timestamp when the message was clicked.
Data associated with the message’s workflow run. Includes the workflow trigger request’s data payload merged with any additional data returned by a fetch function. For messages produced after a batch step, includes the payload data from the most-recent trigger request (the final activity in the batch).
A list of engagement statuses.
The unique identifier for the message.
Timestamp when the resource was created.
Timestamp when the message was interacted with.
Timestamp when a link in the message was clicked.
The metadata associated with the message.
Timestamp when the message was read.
A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
Timestamp when the message was scheduled to be sent.
Timestamp when the message was seen.
The workflow or guide that triggered the message.
The categories associated with the message.
The key of the workflow or guide that triggered the message.
The step reference for the step in the workflow that generated the message.
Whether this message was generated from a workflow, broadcast, or guide.
The ID of the version of the workflow or guide that triggered the message.
The unique identifier for the workflow recipient run that generated this message. Only present for workflow/broadcast messages.
The unique identifier for the workflow run that generated this message. Only present for workflow/broadcast messages.
The message delivery status.
The ID of the tenant associated with the message. Only present when a tenant is provided on a workflow trigger request.
The timestamp when the resource was last updated.
The key of the workflow that generated the message.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Get channel data
#Returns the channel data for the specified object and channel.
Endpoint
Rate limit
Tier 4Path parameters
Unique identifier for the object.
The collection this object belongs to.
The unique identifier for the channel.
Returns
Channel data for a given channel type.
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
Set channel data
#Sets the channel data for the specified object and channel. 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 limit
Tier 3Path parameters
Unique identifier for the object.
The collection this object belongs to.
The unique identifier for the channel.
Request body
Channel data for a given channel type.
Returns
Channel data for a given channel type.
The typename of the schema.
The unique identifier for the channel.
Channel data for a given channel type.
The type of provider.
Unset channel data
#Unsets the channel data for the specified object and channel.
Endpoint
Rate limit
Tier 3Path parameters
Unique identifier for the object.
The collection this object belongs to.
The unique identifier for the channel.
Returns
List subscriptions
#List subscriptions for an object. Either list the recipients that subscribe to the provided object, or list the objects that the provided object is subscribed to. Determined by the mode query parameter.
Endpoint
Rate limit
Tier 4Path parameters
Unique identifier for the object.
The collection this object belongs to.
Query parameters
Mode of the request. recipient to list the objects that the provided object is subscribed to, object to list the recipients that subscribe to the provided object.
Additional fields to include in the response.
Objects to filter by (only used if mode is recipient).
The collection the recipient object belongs to.
An identifier for the recipient object.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Returns
A response containing a list of subscriptions.
A list of subscriptions.
The typename of the schema.
Timestamp when the resource was created.
A custom Object entity which belongs to a collection.
The typename of the schema.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
The custom properties associated with the object.
The timestamp when the resource was last updated.
The custom properties associated with the subscription relationship.
A recipient of a notification, which is either a user or an object.
The timestamp when the resource was last updated.
Pagination information for a list of resources.
The typename of the schema.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of items per page (defaults to 50).
Add subscriptions
#Add subscriptions for an object. If a subscription already exists, it will be updated. This endpoint also handles inline identifications for the recipient.
Endpoint
Rate limit
Tier 3Path parameters
Unique identifier for the object.
The collection this object belongs to.
Request body
The custom properties associated with the subscription relationship.
The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.
Returns
A response containing a list of subscriptions.
Delete subscriptions
#Delete subscriptions for the specified recipients from an object. Returns the list of deleted subscriptions.
Endpoint
Rate limit
Tier 3Path parameters
Unique identifier for the object.
The collection this object belongs to.
Request body
The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.
Returns
A response containing a list of subscriptions.
Bulk operations
#Bulk operations available for objects. These endpoints return a BulkOperation that executes the job asynchronously. Progress can be tracked via the Bulk operations API.
Bulk set objects
#Bulk sets up to 1,000 objects at a time in the specified collection.
Endpoint
Rate limit
Tier 1Path parameters
The collection this object belongs to.
Request body
A list of objects.
Timestamp when the resource was created.
Unique identifier for the object.
An optional name for the object.
Returns
A bulk operation entity.
The typename of the schema.
Timestamp when the bulk operation was completed.
The number of failed operations.
A list of items that failed to be processed.
The collection this object belongs to.
Unique identifier for the object.
The estimated total number of rows to process.
Timestamp when the bulk operation failed.
Unique identifier for the bulk operation.
Timestamp when the resource was created.
The name of the bulk operation.
The number of rows processed so far.
The URI to the bulk operation's progress.
Timestamp when the bulk operation was started.
The status of the bulk operation.
The number of successful operations.
The timestamp when the resource was last updated.
Bulk add subscriptions
#Add subscriptions for all objects in a single collection. If a subscription for an object in the collection already exists, it will be updated. This endpoint also handles inline identifications for the recipient field.
Endpoint
Rate limit
Tier 1Path parameters
The collection this object belongs to.
Request body
A nested list of subscriptions.
Unique identifier for the object.
The custom properties associated with the subscription relationship.
The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.
Returns
A bulk operation entity.
The typename of the schema.
Timestamp when the bulk operation was completed.
The number of failed operations.
A list of items that failed to be processed.
The collection this object belongs to.
Unique identifier for the object.
The estimated total number of rows to process.
Timestamp when the bulk operation failed.
Unique identifier for the bulk operation.
Timestamp when the resource was created.
The name of the bulk operation.
The number of rows processed so far.
The URI to the bulk operation's progress.
Timestamp when the bulk operation was started.
The status of the bulk operation.
The number of successful operations.
The timestamp when the resource was last updated.
Bulk delete objects
#Bulk deletes objects from the specified collection.
Endpoint
Rate limit
Tier 1Path parameters
The collection this object belongs to.
Request body
List of object IDs to delete.
Returns
A bulk operation entity.
The typename of the schema.
Timestamp when the bulk operation was completed.
The number of failed operations.
A list of items that failed to be processed.
The collection this object belongs to.
Unique identifier for the object.
The estimated total number of rows to process.
Timestamp when the bulk operation failed.
Unique identifier for the bulk operation.
Timestamp when the resource was created.
The name of the bulk operation.
The number of rows processed so far.
The URI to the bulk operation's progress.
Timestamp when the bulk operation was started.
The status of the bulk operation.
The number of successful operations.
The timestamp when the resource was last updated.
Bulk delete subscriptions
#Delete subscriptions for many objects in a single collection type. If a subscription for an object in the collection doesn't exist, it will be skipped.
Endpoint
Rate limit
Tier 1Path parameters
The collection this object belongs to.
Request body
A nested list of subscriptions.
Unique identifier for the object.
The recipients of the subscription. You can subscribe up to 100 recipients to an object at a time.
Returns
A bulk operation entity.
The typename of the schema.
Timestamp when the bulk operation was completed.
The number of failed operations.
A list of items that failed to be processed.
The collection this object belongs to.
Unique identifier for the object.
The estimated total number of rows to process.
Timestamp when the bulk operation failed.
Unique identifier for the bulk operation.
Timestamp when the resource was created.
The name of the bulk operation.
The number of rows processed so far.
The URI to the bulk operation's progress.
Timestamp when the bulk operation was started.
The status of the bulk operation.
The number of successful operations.
The timestamp when the resource was last updated.
Object
#A custom Object entity which belongs to a collection.
Attributes
The typename of the schema.
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
The custom properties associated with the object.
The timestamp when the resource was last updated.
InlineIdentifyObjectRequest
#A custom Object entity which belongs to a collection.
Attributes
The collection this object belongs to.
Timestamp when the resource was created.
Unique identifier for the object.
An optional name for the object.
Any additional custom properties.