> ## Documentation Index > Fetch the complete documentation index at: https://docs.posta.co/llms.txt > Use this file to discover all available pages before exploring further. # Create asset version > Create a new asset version for an existing asset. The new version will be in 'draft' status by default. ## OpenAPI ````yaml POST /assets/{id}/versions openapi: 3.0.0 info: title: Posta API description: Posta API version: '2024-07-30' servers: - url: https://api.posta.co description: Posta API endpoint variables: {} security: [] tags: - name: Letters - name: Assets - name: Asset Versions paths: /assets/{id}/versions: post: tags: - Asset Versions summary: Create asset version description: Create a new asset version for an existing asset. operationId: createAssetVersion parameters: - name: id in: path required: true description: >- The unique identifier of the asset to create a new version for. Format: 'ast_' followed by alphanumeric characters. schema: type: string - $ref: '#/components/parameters/IdempotencySupport' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssetVersionCreate' responses: '201': description: >- The request has succeeded and a new resource has been created as a result headers: location: required: true description: >- The Location header contains the URL where the status of the long running operation can be checked. schema: type: string content: application/json: schema: $ref: '#/components/schemas/AssetVersion' '400': description: The server could not understand the request due to invalid syntax. content: application/problem+json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Access is unauthorized. '403': description: Access is forbidden. '429': description: Client error headers: P-RateLimit-Limit: required: false schema: type: integer P-RateLimit-Remaining: required: false schema: type: integer P-RateLimit-Reset: required: false schema: type: string format: date-time '500': description: Server error security: - ApiKeyAuth: [] components: parameters: IdempotencySupport: name: Idempotency-Key in: header required: false description: Unique idempotency key for each request (e.g., V4 UUID). schema: type: string schemas: AssetVersionCreate: type: object properties: notes: type: string example: Initial version. minLength: 0 maxLength: 255 description: >- Optional notes or comments about this specific Asset Version. Useful for tracking changes or providing context. content: $ref: '#/components/schemas/AssetVersionContent' variableDefinitions: type: array items: $ref: '#/components/schemas/VariableDefinitionEntry' maxItems: 128 description: >- 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. publish: type: boolean example: false description: >- If set to `true`, this Asset Version will be published immediately after creation. Default is `false`. example: id: astv_2jyk1xYhW4n0vVfHirU5eJeXsbw status: draft notes: Minor changes to the footer. content: source: inline type: text/html content: Hello {{firstName}} 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' description: >- 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. AssetVersion: type: object required: - id - status - contentType - contentLength - contentUrl - createdAt - modifiedAt properties: id: type: string example: astv_2jyk1xYhW4n0vVfHirU5eJeXsbw minLength: 1 maxLength: 99999 description: >- Unique identifier for the Asset Version. Format: 'astv_' followed by alphanumeric characters. readOnly: true status: allOf: - $ref: '#/components/schemas/AssetVersionStatus' example: draft readOnly: true notes: type: string example: Initial version. minLength: 0 maxLength: 255 description: >- Optional notes or comments about this specific Asset Version. Useful for tracking changes or providing context. variableDefinitions: type: array items: $ref: '#/components/schemas/VariableDefinitionEntry' maxItems: 128 description: >- 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. contentType: type: string example: text/html minLength: 1 maxLength: 99999 description: >- MIME type of the Asset Version content. Indicates the format of the content (e.g., 'text/html', 'image/jpeg', 'application/pdf'). readOnly: true contentLength: type: integer format: int32 example: 100 minimum: -1 maximum: 999999999 description: >- Length of the Asset Version content in bytes. Useful for content management and transfer considerations. readOnly: true contentUrl: type: string example: https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content minLength: 1 maxLength: 99999 format: uri description: >- URL where the rendered content of this asset version can be accessed. Available after publishing. readOnly: true createdAt: type: string format: date-time description: The timestamp the resource was created at (UTC). readOnly: true modifiedAt: type: string format: date-time description: The timestamp the resource was last modified at (UTC). readOnly: true example: id: astv_2jyk1xYhW4n0vVfHirU5eJeXsbw status: draft notes: Minor changes to the footer. content: source: inline type: text/html content: Hello {{firstName}} 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' description: >- 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. ValidationError: type: object properties: errors: type: object description: Errors object is representing the request field validation errors allOf: - type: object required: - type - title - detail - status properties: type: type: string description: The type of the error title: type: string description: A brief summary of the error detail: type: string description: A detailed description of the error status: type: number enum: - 400 description: The HTTP status code description: RFC 7807 problem details object description: Request validation error response AssetVersionContent: oneOf: - $ref: '#/components/schemas/InlineAssetVersionContent' - $ref: '#/components/schemas/ImportAssetVersionContent' - $ref: '#/components/schemas/ExternalUrlAssetVersionContent' discriminator: propertyName: source mapping: inline: $ref: '#/components/schemas/InlineAssetVersionContent' import: $ref: '#/components/schemas/ImportAssetVersionContent' externalUrl: $ref: '#/components/schemas/ExternalUrlAssetVersionContent' description: >- 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. VariableDefinitionEntry: type: object required: - name properties: name: type: string example: firstName minLength: 1 maxLength: 64 description: |- Name of the Variable. Used as the key for content personalization. Must be unique within the Asset Version. Example: `firstName` type: allOf: - $ref: '#/components/schemas/VariableDefinitionEntryType' example: value description: >- 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. default: value behavior: allOf: - $ref: '#/components/schemas/VariableDefinitionEntryBehavior' example: optional description: >- 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. default: optional allowEmpty: type: boolean example: true description: >- 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. presetValue: type: string example: ast_2k1UXnFem92yBFKxtTkQQYhVWyr minLength: 0 maxLength: 512 description: >- 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"` exampleValue: type: string example: Jane minLength: 0 maxLength: 512 description: >- 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"` example: name: firstName type: value behavior: required allowEmpty: false exampleValue: John description: >- 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. AssetVersionStatus: type: string enum: - draft - published - archived - deleted description: >- 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. InlineAssetVersionContent: type: object required: - source - content properties: source: type: string enum: - inline example: inline description: >- Specifies that the content is provided inline and stored directly in Posta. Maximum size is 102,400 bytes. type: type: string example: text/html minLength: 0 maxLength: 99999 description: >- MIME type of the asset content (e.g., 'text/html' for HTML, 'image/png' for PNG images). `text/html` is the default value, unless specified otherwise. content: type: string example: Hello {{firstName}} minLength: 1 maxLength: 102400 description: >- The actual content of the asset as a string. For HTML templates, this can include variables in handlebars format for personalization. Maximum size is 102,400 bytes. example: source: inline type: text/html content: Hello {{firstName}} title: Inline ImportAssetVersionContent: type: object required: - source - url properties: source: type: string enum: - import example: import description: >- Indicates that the content will be imported from an external source and stored in Posta. type: type: string example: text/html minLength: 0 maxLength: 99999 description: >- MIME type of the asset content imported. If not provided, the service will use the content type of the resource. If no content type is sent by the server, we will default it to `binary/octet-stream`. url: type: string example: https://yourS3Bucket.com/yourAssetPublicUrl.html minLength: 0 maxLength: 99999 format: uri description: >- URL from which the asset content will be retrieved and imported. Must be a valid, publicly accessible URL. example: source: import type: text/html url: https://yourS3Bucket.com/yourAssetPublicUrl.html description: Content of the asset, referenced from an external URL. title: Import ExternalUrlAssetVersionContent: type: object required: - source - url properties: source: type: string enum: - externalUrl example: externalUrl description: >- Indicates that the content is referenced from an external URL and will be fetched when needed. type: type: string example: text/html minLength: 0 maxLength: 99999 description: >- MIME type of the external asset content. If not provided, the service will use the content type of the resource. If no content type is sent by the server, we will default it to `binary/octet-stream`. url: type: string example: https://yourS3Bucket.com/yourAssetPublicUrl.html minLength: 1 maxLength: 99999 format: uri description: >- The URL where the external asset content can be accessed. Must be a valid, publicly accessible URL. example: source: externalUrl type: text/html url: https://yourS3Bucket.com/yourAssetPublicUrl.html description: >- Represents asset content referenced by an external URL. This allows for dynamic content retrieval from external sources. title: External URL VariableDefinitionEntryType: type: string enum: - value - asset - externalUrl description: Defines the type of Variable and how its value should be interpreted. VariableDefinitionEntryBehavior: type: string enum: - optional - required - preset - overridablePreset description: Specifies the behavior of a Variable during rendering. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key ````