Docs
/
/

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

GET/v1/partials

Query parameters

environment
string

The environment slug. When omitted, the account's default environment is used.

branch
string

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".

annotate
boolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changes
boolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

after
string

The cursor to fetch entries after.

before
string

The cursor to fetch entries before.

limit
integer

The number of entries to fetch per-page.

Returns

PaginatedPartialResponse

A paginated list of Partial. Contains a list of entries and page information.

entries

A list of entries.

content
string
Required

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the partial exists.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

inserted_at
string(date-time)
Required

The timestamp of when the partial was created.

key
string
Required

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_-]+$.

name
string
Required

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)
Required

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
updated_at
string(date-time)
Required

The timestamp of when the partial was last updated.

valid
boolean
Required

Whether the partial and its content are in a valid state.

visual_block_enabled
boolean

Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.

page_info

The information about a paginated result.

after
string

The cursor to fetch entries after. Will only be present if there are more entries to fetch.

before
string

The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.

page_size
integer

The number of entries to fetch per-page.

Get a partial

#

Get a partial by its key.

Endpoint

GET/v1/partials/{partial_key}

Path parameters

partial_key
string

The key of the partial to retrieve.

Query parameters

environment
string

The environment slug. When omitted, the account's default environment is used.

branch
string

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".

annotate
boolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changes
boolean

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.

content
string

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the partial exists.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

inserted_at
string(date-time)

The timestamp of when the partial was created.

key
string

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_-]+$.

name
string

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
updated_at
string(date-time)

The timestamp of when the partial was last updated.

valid
boolean

Whether the partial and its content are in a valid state.

visual_block_enabled
boolean

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

PUT/v1/partials/{partial_key}

Path parameters

partial_key
string

The key of the partial to upsert.

Query parameters

environment
string

The environment slug. When omitted, the account's default environment is used.

branch
string

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".

annotate
boolean

Whether to annotate the resource. Only used in the Knock CLI.

force
boolean

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.

commit
boolean

Whether to commit the resource at the same time as modifying it.

commit_message
string

The message to commit the resource with, only used if commit is true.

allow_empty
boolean

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.

content
string
Required

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

name
string
Required

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)
Required

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
visual_block_enabled
boolean

Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.

Returns

WrappedPartialResponse

Wraps the Partial response under the partial key.

partial

A partial is a reusable piece of content that can be used in a template.

content
string

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the partial exists.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

inserted_at
string(date-time)

The timestamp of when the partial was created.

key
string

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_-]+$.

name
string

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
updated_at
string(date-time)

The timestamp of when the partial was last updated.

valid
boolean

Whether the partial and its content are in a valid state.

visual_block_enabled
boolean

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

PUT/v1/partials/{partial_key}/validate

Path parameters

partial_key
string

The key of the partial to validate.

Query parameters

environment
string

The environment slug. When omitted, the account's default environment is used.

branch
string

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.

content
string
Required

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

name
string
Required

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)
Required

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
visual_block_enabled
boolean

Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.

Returns

WrappedPartialResponse

Wraps the Partial response under the partial key.

partial

A partial is a reusable piece of content that can be used in a template.

content
string

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the partial exists.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

inserted_at
string(date-time)

The timestamp of when the partial was created.

key
string

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_-]+$.

name
string

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
updated_at
string(date-time)

The timestamp of when the partial was last updated.

valid
boolean

Whether the partial and its content are in a valid state.

visual_block_enabled
boolean

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

POST/v1/partials/preview

Query parameters

environment
string

The environment slug. When omitted, the account's default environment is used.

branch
string

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

data
object(any)

The data to pass to the partial when rendering. Top-level keys are exposed as variables in the partial template.

layout
object

Email layout configuration. Only applicable for html partials. When omitted, the rendered partial is returned unwrapped.

key
string

The key of an existing email layout to use.

A partial object with attributes to update or create a partial.

content
string
Required

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

name
string
Required

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)
Required

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
visual_block_enabled
boolean

Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.

Returns

PreviewPartialResponse

A response to a partial preview request.

content
string

The rendered partial content. Present when result is success.

errors
object[]

A list of errors encountered during rendering. Present when result is error.

field
string

The partial field that caused the error, if available.

message
string
Required

A human-readable description of the error.

result
enum(string)

The result of the preview.

successerror
type
enum(string)

The partial type that was rendered.

htmltextjsonmarkdown

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

DELETE/v1/partials/{partial_key}

Path parameters

partial_key
string

The key of the partial to archive.

Query parameters

environment
string

The environment slug. When omitted, the account's default environment is used.

Returns

ArchivePartialResponse

The response from archiving a partial.

result
string

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

PUT/v1/partials/{partial_key}/discard

Path parameters

partial_key
string

The key of the partial.

Query parameters

environment
string

The environment slug. When omitted, the account's default environment is used.

branch
string

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

WrappedPartialResponse

Wraps the Partial response under the partial key.

partial

A partial is a reusable piece of content that can be used in a template.

content
string

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the partial exists.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

inserted_at
string(date-time)

The timestamp of when the partial was created.

key
string

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_-]+$.

name
string

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
updated_at
string(date-time)

The timestamp of when the partial was last updated.

valid
boolean

Whether the partial and its content are in a valid state.

visual_block_enabled
boolean

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

PUT/v1/partials/{partial_key}/unarchive

Path parameters

partial_key
string

The original key of the archived partial.

Query parameters

environment
string

The environment slug. When omitted, the account's default environment is used.

Returns

WrappedPartialResponse

Wraps the Partial response under the partial key.

partial

A partial is a reusable piece of content that can be used in a template.

content
string

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the partial exists.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

inserted_at
string(date-time)

The timestamp of when the partial was created.

key
string

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_-]+$.

name
string

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
updated_at
string(date-time)

The timestamp of when the partial was last updated.

valid
boolean

Whether the partial and its content are in a valid state.

visual_block_enabled
boolean

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

content
string

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the partial exists.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

inserted_at
string(date-time)

The timestamp of when the partial was created.

key
string

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_-]+$.

name
string

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
updated_at
string(date-time)

The timestamp of when the partial was last updated.

valid
boolean

Whether the partial and its content are in a valid state.

visual_block_enabled
boolean

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

content
string

The partial content.

description
string

An arbitrary string attached to a partial object. Useful for adding notes about the partial for internal purposes. Maximum of 280 characters allowed.

icon_name
string

The name of the icon to be used in the visual editor.

input_schema
object[]

The field types available for the partial.

name
string

A name for the partial. Must be at maximum 255 characters in length.

type
enum(string)

The partial type. One of 'html', 'json', 'markdown', 'text'.

htmltextjsonmarkdown
visual_block_enabled
boolean

Indicates whether the partial can be used in the visual editor. Only applies to HTML partials.

New chat