Audiences mAPI reference
Complete reference documentation for the Audiences resource.
Audiences
#Audiences are user segments that you can use to target users for workflows, guides, and broadcasts.
Archive an audience
#Archives a given audience across all environments.
Endpoint
Path parameters
The key of the audience to archive.
Query parameters
The environment slug.
Returns
The response from archiving an audience.
The result of the archive operation.
Get an audience
#Retrieve an audience by its key in a given environment.
Endpoint
Path parameters
The key of the audience 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
An audience defines a set of users that can be targeted for notifications. Can be either a StaticAudience (members explicitly added/removed) or a DynamicAudience (members determined by segment conditions).
Upsert an audience
#Updates an audience of a given key, or creates a new one if it does not yet exist.
Endpoint
Path parameters
The key of the audience 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
An audience object with attributes to create or update an audience. Use type: static for audiences with explicitly managed members, or type: dynamic for audiences with segment-based membership.
Returns
Wraps the Audience response under the audience key.
An audience defines a set of users that can be targeted for notifications. Can be either a StaticAudience (members explicitly added/removed) or a DynamicAudience (members determined by segment conditions).
Validate an audience
#Validates an audience payload without persisting it.
Endpoint
Path parameters
The key of the audience to validate.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Request body
An audience object with attributes to create or update an audience. Use type: static for audiences with explicitly managed members, or type: dynamic for audiences with segment-based membership.
Returns
Wraps the Audience response under the audience key.
An audience defines a set of users that can be targeted for notifications. Can be either a StaticAudience (members explicitly added/removed) or a DynamicAudience (members determined by segment conditions).
List audiences
#Returns a paginated list of audiences for the 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".
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of entries to fetch per-page.
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 paginated list of Audience. Contains a list of entries and page information.
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.
Audience
#An audience defines a set of users that can be targeted for notifications. Can be either a StaticAudience (members explicitly added/removed) or a DynamicAudience (members determined by segment conditions).
Attributes
An audience defines a set of users that can be targeted for notifications. Can be either a StaticAudience (members explicitly added/removed) or a DynamicAudience (members determined by segment conditions).
DynamicAudience
#A dynamic audience where membership is determined by segment conditions evaluated at runtime.
Attributes
The timestamp of when the audience was created.
A description of the audience.
The slug of the environment in which the audience exists.
The unique key of the audience.
The name of the audience.
A list of segments that define the dynamic audience membership criteria. Each segment contains one or more conditions joined by AND. Multiple segments are joined by OR.
A list of conditions within this segment, joined by AND.
The argument to compare against. Can be a static value (string, number, boolean) or a dynamic path expression.
The operator to use when evaluating the condition.
The property to be evaluated. Properties are dynamic values using path expressions like recipient.plan or recipient.created_at.
The SHA hash of the audience data.
The type of audience. Always dynamic for dynamic audiences.
The timestamp of when the audience was last updated.
StaticAudience
#A static audience where members are explicitly added or removed via the API.
Attributes
The timestamp of when the audience was created.
A description of the audience.
The slug of the environment in which the audience exists.
The unique key of the audience.
The name of the audience.
The SHA hash of the audience data.
The type of audience. Always static for static audiences.
The timestamp of when the audience was last updated.
AudienceCondition
#A condition to evaluate for audience membership.
Attributes
The argument to compare against. Can be a static value (string, number, boolean) or a dynamic path expression.
The operator to use when evaluating the condition.
The property to be evaluated. Properties are dynamic values using path expressions like recipient.plan or recipient.created_at.