List asset versions

GET

assets

{id}

versions

curl --request GET \
  --url https://api.posta.co/assets/{id}/versions \
  --header 'X-Api-Key: <api-key>'

{
  "items": [
    {
      "id": "astv_2jyk1xYhW4n0vVfHirU5eJeXsbw",
      "status": "draft",
      "notes": "Minor changes to the footer.",
      "content": {
        "source": "inline",
        "type": "text/html",
        "content": "<html><body>Hello {{firstName}}</body></html>"
      },
      "variableDefinitions": [
        {
          "name": "name",
          "behavior": "required",
          "allowEmpty": false
        }
      ],
      "contentType": "text/html",
      "contentLength": 100,
      "contentUrl": "https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content",
      "publish": false,
      "createdAt": "2023-06-07T12:34:56Z",
      "modifiedAt": "2023-06-07T12:34:56Z"
    }
  ],
  "nextToken": "<string>"
}

Results are ordered from newest to oldest.

Authorizations

X-Api-Key

string

header

required

Path Parameters

string

required

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

Query Parameters

includeArchived

boolean

Include archived versions in the results. Default is false.

pageSize

integer

The number of items to return per page. The maximum pageSize is 100 items.

nextToken

string

A cursor for the next page of results.

Response

200

application/json

The request has succeeded.

items

object[]

required

Array of items for the current page.

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.

items.id

string

required

Unique identifier for the Asset Version. Format: 'astv_' followed by alphanumeric characters.

Required string length: 1 - 99999

Example:

"astv_2jyk1xYhW4n0vVfHirU5eJeXsbw"

items.status

enum<string>

required

Represents the status of an Asset Version.

draft: An Asset Version that is being worked on and can be modified. This is the initial state for new Asset Version and cloned Asset Versions.
published: An Asset Version that is finalized and available for use. Published Asset Versions cannot be edited.
archived: An Asset Version unavailable for new uses but may still be accessible for historical purposes. It can be republished if needed.
deleted: An Asset Version that has been deleted from the system. This is a terminal state.

State transitions:

Draft Asset Versions can be published, archived, or deleted.
Published Asset Versions can only be archived or deleted.
Archived Asset Versions can be republished (becoming published) or deleted.
Deleted is a terminal state with no further transitions.

Notes:

Only one Asset Version can be in the published state at a time for a given Asset.
Publishing a new Asset Versions will automatically archive the previously published one, if there was one.
Cloning any non-deleted Asset Versions will create a new one in draft state.
Deletion is permanent and should be used with caution.

Available options:

draft,

published,

archived,

deleted

Example:

"draft"

items.contentType

string

required

MIME type of the Asset Version content. Indicates the format of the content (e.g., 'text/html', 'image/jpeg', 'application/pdf').

Required string length: 1 - 99999

Example:

"text/html"

items.contentLength

integer

required

Length of the Asset Version content in bytes. Useful for content management and transfer considerations.

Required range: -1 <= x <= 999999999

Example:

100

items.contentUrl

string

required

URL where the rendered content of this asset version can be accessed. Available after publishing.

Required string length: 1 - 99999

Example:

"https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content"

items.createdAt

string

required

The timestamp the resource was created at (UTC).

items.modifiedAt

string

required

The timestamp the resource was last modified at (UTC).

items.notes

string

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

Maximum length: 255

Example:

"Initial version."

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

List of variables defined for this Asset Version. Used for content personalization in HTML templates. A maximum of 128 variable definitions can be specified per Asset Version. This limit helps maintain performance and readability of templates.

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

Example:

"firstName"

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

Example:

"value"

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

Example:

"optional"

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

Example:

true

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

Example:

"ast_2k1UXnFem92yBFKxtTkQQYhVWyr"

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

Example:

"Jane"

nextToken

string

A cursor for the next page of results.

Asset Version object Create asset version

curl --request GET \
  --url https://api.posta.co/assets/{id}/versions \
  --header 'X-Api-Key: <api-key>'

{
  "items": [
    {
      "id": "astv_2jyk1xYhW4n0vVfHirU5eJeXsbw",
      "status": "draft",
      "notes": "Minor changes to the footer.",
      "content": {
        "source": "inline",
        "type": "text/html",
        "content": "<html><body>Hello {{firstName}}</body></html>"
      },
      "variableDefinitions": [
        {
          "name": "name",
          "behavior": "required",
          "allowEmpty": false
        }
      ],
      "contentType": "text/html",
      "contentLength": 100,
      "contentUrl": "https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content",
      "publish": false,
      "createdAt": "2023-06-07T12:34:56Z",
      "modifiedAt": "2023-06-07T12:34:56Z"
    }
  ],
  "nextToken": "<string>"
}

Getting started

Assets

Postal

Authorizations

Path Parameters

Query Parameters

Response