Update asset version

PUT

assets

{id}

versions

{versionId}

object

notes

string

content

Inline · object

source

enum<string>

type

string

content

string

variableDefinitions

array

publish

boolean

Only draft or published Asset Versions can be updated. On a published Asset Version only notes can be updated.

Authorizations

X-Api-Key

string

headerrequired

Headers

Idempotency-Key

string

Unique idempotency key for each request (e.g., V4 UUID).

Path Parameters

string

required

The unique identifier of the asset. Format: 'ast_' followed by alphanumeric characters.

versionId

string

required

The unique identifier of the asset version to update. Format: 'astv_' followed by alphanumeric characters.

Body

application/json

Represents a specific version of an Asset, containing the actual content and metadata. Asset Versions are the core entities for version control, compliance tracking, and content management in Posta.

Key aspects:

Content: Can be HTML templates (with variable support), images, fonts, or documents (e.g., PDFs).
Status: Determines the overall status of the parent Asset (draft, published, archived, or deleted).
Version Control: Allows tracking changes and maintaining multiple iterations of an Asset.
Compliance: Facilitates auditing and regulatory compliance through versioning.

HTML templates can use variables for dynamic content. Images and fonts can be referenced as variables within HTML templates. Documents (like PDFs) are static and used for rendering documents without dynamic components.

notes

string

Optional notes or comments about this specific Asset Version. Useful for tracking changes or providing context.

Maximum length: 255

content

object

Defines the content of an Asset Version, supporting multiple content sources. The source property determines how the content is provided and managed.

inline: Content is stored directly in Posta. It can be provided upon creation or added/edited later, used primarily for HTML templates. Maximum 102,400 bytes.
import: A convenience feature for initial content creation. Accepts a publicly available URL, downloads the content, and stores it in Posta. After import, it doesn't retain its external reference.
externalUrl: Content remains externally hosted and is fetched every time it's needed. Posta does not store this content but maintains a reference to the external URL.

Choose the appropriate type based on your content management needs, update frequency, and integration requirements. inline and import are recommended over externalUrl for security, compliance, and performance reasons.

variableDefinitions

object[]

List of variables defined for this Asset Version. Used for content personalization in HTML templates. Note: When using Assets with Variables with our Letter API, always review the variableHandling option on the Letter. If validationScope is set to none in the request, the defined variables and their behavior will not be evaluated at all. See further information on the Letter object.

variableDefinitions.name

string

required

Name of the Variable. Used as the key for content personalization. Must be unique within the Asset Version. Example: firstName

Required string length: 1 - 64

variableDefinitions.type

enum<string>

default: value

Specifies the type of the Variable:

value: A string value (default Variable type when not specified)
asset: References another Asset by its Id
externalUrl: References content at an external URL (must be publicly available)

Note: We recommend using asset type Variables instead of externalUrl for better consistency, security, compliance, and availability. External URLs might change without version control, may be subject to throttling, or could become unavailable.

Available options:

value,

asset,

externalUrl

variableDefinitions.behavior

enum<string>

default: optional

Specifies how the Variable should be handled during rendering.

optional: The Variable is optional and may or may not be provided in a request (such as create letter). If allowEmpty is true you can pass an empty string as its value.
required: The Variable must be provided in a request (such as create letter). If allowEmpty is true you can pass an empty string as its value.
preset: The preset value will be used and the variable should not be included in the request (such as create letter). The presetValue must be defined when this behavior is used. allowEmpty is not applicable to this behavior.
overridablePreset: The preset value will be used, unless a value is explicitly passed in a request to override the preset value. The presetValue must be set when this behavior is used, and the variable can be included in a request if an override is necessary, otherwise the presetValue will be used. If allowEmpty is true you can pass an empty string as its value.

Note: When using Assets with Variables with our Letter API, always review the variableHandling option on the Letter. If validationScope is set to none in the request, the defined variables and their behavior will not be evaluated at all. See further information on the Letter object.

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

Available options:

optional,

required,

preset,

overridablePreset

variableDefinitions.allowEmpty

boolean

Determines whether an empty value is acceptable for this Variable.

Example empty string: { "name": "firstName", "value": "" }

Note: null is considered as no value, not an empty one.

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

variableDefinitions.presetValue

string

Specifies a preset value for the Variable. This value may be used when:

the Variable is not provided
a value is provided but the behavior is set to presetValue

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

Example: "ast_2k1UXnFem92yBFKxtTkQQYhVWyr"

Maximum length: 512

variableDefinitions.exampleValue

string

Provides a sample value for the Variable, useful for documentation and UI purposes. This value is not used in the actual rendering process. It's primarily for demonstrating expected input in user interfaces or documentation.

Example: "Jane"

Maximum length: 512

publish

boolean

If set to true, this Asset Version will be published immediately after creation. Default is false.

Get asset version Publish asset version

Getting started

Assets

Postal

Authorizations

Headers

Path Parameters

Body