Guides Management API reference
Complete reference documentation for the Guides resource.
Guides
#Guides let you define in-app messaging for your users, powered by your own components.
List guides
#Returns a paginated list of guides available in a given environment.
Endpoint
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Whether to annotate the resource. Only used in the Knock CLI.
Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of entries to fetch per-page.
Returns
A paginated list of Guide. Contains a list of entries and page information.
A list of entries.
A list of activation url patterns that describe when the guide should be shown.
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.
Whether the guide is active.
The timestamp of when the guide was archived.
The key of the channel in which the guide exists.
The timestamp of when the guide was created.
The timestamp of when the guide was deleted.
An arbitrary string attached to a guide object. Useful for adding notes about the guide for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the guide exists.
The unique key string for the guide object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the guide. Must be at maximum 255 characters in length.
The semver of the guide.
The SHA hash of the guide.
A list of guide step objects in the guide.
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
The ID of the target audience for the guide. When not set, will default to targeting all users.
A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.
The type of the guide. This is derived from the message type of the guide steps.
The timestamp of when the guide was last updated.
Whether the guide is valid.
The information about a paginated result.
The cursor to fetch entries after. Will only be present if there are more entries to fetch.
The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
The number of entries to fetch per-page.
Get a guide
#Get a guide by its key.
Endpoint
Path parameters
The key of the guide to retrieve.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Whether to annotate the resource. Only used in the Knock CLI.
Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
Returns
A guide defines an in-app guide that can be displayed to users based on priority and other conditions.
A list of activation url patterns that describe when the guide should be shown.
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.
Whether the guide is active.
The timestamp of when the guide was archived.
The key of the channel in which the guide exists.
The timestamp of when the guide was created.
The timestamp of when the guide was deleted.
An arbitrary string attached to a guide object. Useful for adding notes about the guide for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the guide exists.
The unique key string for the guide object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the guide. Must be at maximum 255 characters in length.
The semver of the guide.
The SHA hash of the guide.
A list of guide step objects in the guide.
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
The ID of the target audience for the guide. When not set, will default to targeting all users.
A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.
The type of the guide. This is derived from the message type of the guide steps.
The timestamp of when the guide was last updated.
Whether the guide is valid.
Archive a guide
#Archives a given guide across all environments.
Endpoint
Path parameters
The key of the guide to archive.
Returns
The response from archiving a guide.
The result of the promote operation.
Upsert a guide
#Updates a guide of a given key, or creates a new one if it does not yet exist.
Note: this endpoint only operates on guides in the "development" environment.
Endpoint
Path parameters
The key of the guide to upsert.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Whether to annotate the resource. Only used in the Knock CLI.
Whether to commit the resource at the same time as modifying it.
The message to commit the resource with, only used if commit is true.
Request body
A request to create or update a guide.
A list of activation url patterns that describe when the guide should be shown.
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.
The timestamp of when the guide was archived.
The key of the channel in which the guide exists.
The timestamp of when the guide was deleted.
An arbitrary string attached to a guide object. Useful for adding notes about the guide for internal purposes. Maximum of 280 characters allowed.
A name for the guide. Must be at maximum 255 characters in length.
A list of guide step objects in the guide.
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
The ID of the target audience for the guide. When not set, will default to targeting all users.
A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.
Returns
Wraps the Guide response under the guide key.
A guide defines an in-app guide that can be displayed to users based on priority and other conditions.
A list of activation url patterns that describe when the guide should be shown.
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.
Whether the guide is active.
The timestamp of when the guide was archived.
The key of the channel in which the guide exists.
The timestamp of when the guide was created.
The timestamp of when the guide was deleted.
An arbitrary string attached to a guide object. Useful for adding notes about the guide for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the guide exists.
The unique key string for the guide object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the guide. Must be at maximum 255 characters in length.
The semver of the guide.
The SHA hash of the guide.
A list of guide step objects in the guide.
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
The ID of the target audience for the guide. When not set, will default to targeting all users.
A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.
The type of the guide. This is derived from the message type of the guide steps.
The timestamp of when the guide was last updated.
Whether the guide is valid.
Validate a guide
#Validates a guide payload without persisting it.
Note: Validating a guide is only done in the development environment context.
Endpoint
Path parameters
The key of the guide.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Request body
A request to create or update a guide.
A list of activation url patterns that describe when the guide should be shown.
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.
The timestamp of when the guide was archived.
The key of the channel in which the guide exists.
The timestamp of when the guide was deleted.
An arbitrary string attached to a guide object. Useful for adding notes about the guide for internal purposes. Maximum of 280 characters allowed.
A name for the guide. Must be at maximum 255 characters in length.
A list of guide step objects in the guide.
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
The ID of the target audience for the guide. When not set, will default to targeting all users.
A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.
Returns
Wraps the Guide response under the guide key.
A guide defines an in-app guide that can be displayed to users based on priority and other conditions.
A list of activation url patterns that describe when the guide should be shown.
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.
Whether the guide is active.
The timestamp of when the guide was archived.
The key of the channel in which the guide exists.
The timestamp of when the guide was created.
The timestamp of when the guide was deleted.
An arbitrary string attached to a guide object. Useful for adding notes about the guide for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the guide exists.
The unique key string for the guide object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the guide. Must be at maximum 255 characters in length.
The semver of the guide.
The SHA hash of the guide.
A list of guide step objects in the guide.
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
The ID of the target audience for the guide. When not set, will default to targeting all users.
A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.
The type of the guide. This is derived from the message type of the guide steps.
The timestamp of when the guide was last updated.
Whether the guide is valid.
Activate a guide
#Activates (or deactivates) a guide in a given environment. You can either set the active status immediately or schedule it.
Note: This immediately enables or disables a guide in a given environment without needing to go through environment promotion.
Endpoint
Path parameters
The key of the guide.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Request body
A request to activate or schedule the activation of a guide.
Returns
Wraps the Guide response under the guide key.
A guide defines an in-app guide that can be displayed to users based on priority and other conditions.
A list of activation url patterns that describe when the guide should be shown.
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.
Whether the guide is active.
The timestamp of when the guide was archived.
The key of the channel in which the guide exists.
The timestamp of when the guide was created.
The timestamp of when the guide was deleted.
An arbitrary string attached to a guide object. Useful for adding notes about the guide for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the guide exists.
The unique key string for the guide object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the guide. Must be at maximum 255 characters in length.
The semver of the guide.
The SHA hash of the guide.
A list of guide step objects in the guide.
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
The ID of the target audience for the guide. When not set, will default to targeting all users.
A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.
The type of the guide. This is derived from the message type of the guide steps.
The timestamp of when the guide was last updated.
Whether the guide is valid.
Guide
#A guide defines an in-app guide that can be displayed to users based on priority and other conditions.
Attributes
A list of activation url patterns that describe when the guide should be shown.
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.
Whether the guide is active.
The timestamp of when the guide was archived.
The key of the channel in which the guide exists.
The timestamp of when the guide was created.
The timestamp of when the guide was deleted.
An arbitrary string attached to a guide object. Useful for adding notes about the guide for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the guide exists.
The unique key string for the guide object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the guide. Must be at maximum 255 characters in length.
The semver of the guide.
The SHA hash of the guide.
A list of guide step objects in the guide.
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
The ID of the target audience for the guide. When not set, will default to targeting all users.
A conditions object that describes one or more conditions to be met for the guide to be shown to an audience member.
The type of the guide. This is derived from the message type of the guide steps.
The timestamp of when the guide was last updated.
Whether the guide is valid.
GuideStep
#A step in a guide that corresponds to a piece of UI and its content.
Attributes
A name for the step.
The unique reference string for the step. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
The key of the template schema to use for this step.
The semantic version of the template schema to use.
The key of the template schema variant to use.
A map of values that make up the step's content. Each value must conform to its respective template schema field settings.
GuideActivationUrlPattern
#A rule that controls when a guide should be shown based on the user's location in the application.
Attributes
Whether to allow or block the guide at the specified pathname.
The URL pathname pattern to match against. Must be a valid URI path.