Partials mAPI reference
Complete reference documentation for the Partials resource.
Partials
#Partials are reusable pieces of content you can use across your channel templates.
You can retrieve, update, and create partials as well as list all partials in a given environment. Partials are identified by their unique partial key.
List partials
#List all partials for a given environment.
Endpoint
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "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 Partial. Contains a list of entries and page information.
A list of entries.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the partial exists.
The name of the icon to be used in the visual editor.
The field types available for the partial.
The timestamp of when the partial was created.
The unique key string for the partial 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 partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
The timestamp of when the partial was last updated.
Whether the partial and its content are in a valid state.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
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 partial
#Get a partial by its key.
Endpoint
Path parameters
The key of the partial to retrieve.
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "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 partial is a reusable piece of content that can be used in a template.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the partial exists.
The name of the icon to be used in the visual editor.
The field types available for the partial.
The timestamp of when the partial was created.
The unique key string for the partial 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 partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
The timestamp of when the partial was last updated.
Whether the partial and its content are in a valid state.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
Upsert a partial
#Updates a partial of a given key, or creates a new one if it does not yet exist.
The write targets the environment in the request. Accounts that allow writes in every environment can create and update in that environment. Pass force to write outside the request's origin environment. When writes are limited to development, this endpoint accepts the development environment unless force is set.
Endpoint
Path parameters
The key of the partial to upsert.
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "development".
Whether to annotate the resource. Only used in the Knock CLI.
When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks.
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.
When used with commit, creates a new version with identical content and commits it if there are no unpublished changes.
Request body
A partial object with attributes to update or create a partial.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The name of the icon to be used in the visual editor.
The field types available for the partial.
A name for the partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
Returns
Wraps the Partial response under the partial key.
A partial is a reusable piece of content that can be used in a template.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the partial exists.
The name of the icon to be used in the visual editor.
The field types available for the partial.
The timestamp of when the partial was created.
The unique key string for the partial 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 partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
The timestamp of when the partial was last updated.
Whether the partial and its content are in a valid state.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
Validate a partial
#Validates a partial payload without persisting it.
Validation uses the environment in the request. Accounts that allow writes in every environment can validate in that environment. When writes are limited to development, this endpoint accepts the development environment.
Endpoint
Path parameters
The key of the partial to validate.
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "development".
Request body
A partial object with attributes to update or create a partial.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The name of the icon to be used in the visual editor.
The field types available for the partial.
A name for the partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
Returns
Wraps the Partial response under the partial key.
A partial is a reusable piece of content that can be used in a template.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the partial exists.
The name of the icon to be used in the visual editor.
The field types available for the partial.
The timestamp of when the partial was created.
The unique key string for the partial 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 partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
The timestamp of when the partial was last updated.
Whether the partial and its content are in a valid state.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
Preview a partial
#Renders a partial in isolation, without requiring the partial to be persisted in Knock.
Useful for iterating on a partial locally and seeing how it renders against sample data.
Endpoint
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "development".
Request body
The data to pass to the partial when rendering. Top-level keys are exposed as variables in the partial template.
Email layout configuration. Only applicable for html partials. When omitted, the rendered partial is returned unwrapped.
The key of an existing email layout to use.
A partial object with attributes to update or create a partial.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The name of the icon to be used in the visual editor.
The field types available for the partial.
A name for the partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
Returns
A response to a partial preview request.
The rendered partial content. Present when result is success.
A list of errors encountered during rendering. Present when result is error.
The partial field that caused the error, if available.
A human-readable description of the error.
The result of the preview.
The partial type that was rendered.
Archive a partial
#Archives a partial by key across all environments, not only the one in the request. The
token needs the partials:manage permission in every environment that holds a copy of the
partial.
Archiving renames the partial's key in every environment, so a new partial can use the key. Templates that reference the archived partial keep using it until their workflow is next committed, and it can't be added to new templates. Restore it with the unarchive endpoint, using its original key.
Returns a 422 with the code partial_in_use while a workflow or an unsent broadcast in any
environment uses the partial. Remove it from them first. Returns a 404 when no live partial
has the key, including when it's already archived.
Endpoint
Path parameters
The key of the partial to archive.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Returns
The response from archiving a partial.
The result of the archive operation.
Discard a partial's uncommitted changes
#Discards the uncommitted changes to a partial in a given environment, returning it to its last committed version. Other environments aren't changed.
Returns the partial unchanged when it has no uncommitted changes. Returns a 422 when the partial has never been committed, or can't be changed in the environment.
Endpoint
Path parameters
The key of the partial.
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "development".
Returns
Wraps the Partial response under the partial key.
A partial is a reusable piece of content that can be used in a template.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the partial exists.
The name of the icon to be used in the visual editor.
The field types available for the partial.
The timestamp of when the partial was created.
The unique key string for the partial 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 partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
The timestamp of when the partial was last updated.
Whether the partial and its content are in a valid state.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
Unarchive a partial
#Restores an archived partial by its original key, with every copy archived alongside it in
other environments. The token needs the partials:manage permission in every environment
that holds a copy of the archived partial.
When the key was archived more than once, the most recent archive in the environment is restored.
Returns a 404 when the key isn't archived in the environment, including when an earlier or
concurrent request already restored it. Returns a 422 with the code key_in_use when a live
partial uses the key.
Endpoint
Path parameters
The original key of the archived partial.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Returns
Wraps the Partial response under the partial key.
A partial is a reusable piece of content that can be used in a template.
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the partial exists.
The name of the icon to be used in the visual editor.
The field types available for the partial.
The timestamp of when the partial was created.
The unique key string for the partial 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 partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
The timestamp of when the partial was last updated.
Whether the partial and its content are in a valid state.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
Partial
#A partial is a reusable piece of content that can be used in a template.
Attributes
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the partial exists.
The name of the icon to be used in the visual editor.
The field types available for the partial.
The timestamp of when the partial was created.
The unique key string for the partial 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 partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
The timestamp of when the partial was last updated.
Whether the partial and its content are in a valid state.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.
PartialRequest
#A partial object with attributes to update or create a partial.
Attributes
The partial content.
An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.
The name of the icon to be used in the visual editor.
The field types available for the partial.
A name for the partial. Must be at maximum 255 characters in length.
The partial type. One of 'html', 'json', 'markdown', 'text'.
Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.