---
title: "Perform actions with a workflow version"
method: POST
path: "/v1/workflow-templates/{id}/versions/{versionId}/actions"
tags: ["Workflows"]
---

# Perform actions with a workflow version

`POST /v1/workflow-templates/{id}/versions/{versionId}/actions`

## Request

- Base URL: `https://api.emma.ms/external`
- URL: `https://api.emma.ms/external/v1/workflow-templates/{id}/versions/{versionId}/actions`
- Auth: HTTP bearer

Executes "Restore" action on the specified workflow version.

Restoring creates a new active version from the selected version's snapshot. The new version receives an auto-generated name; use `PATCH` to assign a custom name.

A workflow template can contain up to 20 versions. If the limit is reached, retry the request with `forceDeleteOldest = true` to delete the oldest non-active version as part of the same operation. The restore is rejected if the oldest non-active version is the one being restored.

## Path parameters

- `id` integer, required
- `versionId` integer, required

## Request body

- WorkflowTemplateVersionRestore
  - `action` 'restore', required: `restore` — creates a new active version from this version's snapshot. The new version gets a server-generated name and is not a byte-for-byte duplicate: secret parameters come back with `hasDefaultValue = false` (secret values are never restored) and Vault-backed parameters get a fresh `vaultVersion`. The previous active version remains in history with `isActive = false`.
  - `forceDeleteOldest` boolean, nullable: Indicates whether the oldest version may be deleted if the 20-version limit is reached. By default - false

## Response `200`

Workflow version restored successfully

- WorkflowTemplateVersion
  - `id` integer, required: ID of the workflow template version
  - `name` string, required: Name of the workflow version
  - `createdAt` string, required: Date and time of the version creation.
  - `createdById` integer, required: ID of the user or service application that initiated creation of the version.
  - `createdByName` string, required: Name of the user or service application that initiated creation of the version.
  - `isActive` boolean, required: Indicates whether the workflow version is active
  - `secretsChanged` boolean, required: Indicates whether the secrets were changed in this version.
  - `tagsRestorable` boolean, nullable: Indicates whether all tags in the snapshot can be restored. `true` if every tag still exists in the company, `false` if at least one has been deleted and cannot be restored. `null` when restorability was not determined — the snapshot holds no tags at all, or the check could not be completed. Treat `null` as "unknown", not as `false`.
  - `sequenceNumber` integer, required: A sequential number assigned to each version in creation order.
  - `restoredFrom` integer, nullable: ID of the source version. Present only if this version was created by restoring another version; null otherwise.
  - `restoredFromName` string, nullable: Name of the source version. Present only if this version was created by restoring another version; null otherwise.
  - `snapshot` WorkflowTemplateSnapshot, required
    - `name` string, required: Name of the workflow template as captured in this version's snapshot.
    - `description` string, nullable: Description of the workflow template as captured in this version's snapshot.
    - `status` 'PUBLISHED' | 'UNPUBLISHED', required: Status of the workflow template at the time this version was saved.
    - `resourceTypes` string[], required: Types of the resources, as captured in this version's snapshot.
    - `resourceParams` object[]: Resource limitation parameters as captured in this version's snapshot.
      - `name` string: Name of the resource parameter.
      - `value` string: Value of the resource parameter.
    - `tags` object[]: Tags as captured in this version's snapshot.
      - `tagId` string
      - `key` string
      - `value` string
    - `contentType` 'Shell', required: Format of the content field.
    - `content` string, required: Shell script content as captured in this version's snapshot.
    - `isContentValid` boolean: Indicates whether the content of this version was valid at save time.
    - `contentParams` ContentParam[]: Content parameters as captured in this version's snapshot. Default values for secret parameters are not stored.
      - `id` integer, nullable: Stable server-assigned parameter id. Returned on read; echo it back on create/update so the backend matches params by id (preserves the stored value across a rename). Null for a newly added param.
      - `name` string, required: Name of the content parameter, e.g. command1, command2.
      - `defaultValue` string, nullable: Value of the content parameter. On request: actual value submitted by user (plaintext). On response: for isSecret=false — the current value; inside a version snapshot, the value as of that version (resolved by the pinned `vaultVersion`). For isSecret=true — always null (write-only, the secret is never returned). The internal Vault path is never returned.
      - `mandatory` boolean, required: Indicates whether the content parameter is mandatory to fill in when creating
      - `description` string, nullable: Human-readable description of the content parameter.
      - `isSecret` boolean, nullable: If true, the parameter value is treated as a secret: stored in Vault, never returned in responses (defaultValue is always null on read), write-only on update. If false or null — regular parameter, value is visible on read. Transitions on update: - false → true (without new defaultValue): the existing plaintext value is preserved and becomes secret-protected on subsequent reads (defaultValue returned as null, hasDefaultValue=true). - false → true (with new defaultValue): the new value is stored in Vault and protected. - true → false (without new defaultValue): the stored secret is cleared (soft-deleted from Vault); defaultValue returns null and hasDefaultValue=false. The previous secret is NEVER exposed on read. - true → false (with new defaultValue): the new value replaces the stored secret and is returned as a regular value going forward.
      - `hasDefaultValue` boolean, nullable: Response-only. True if a stored default value exists for this parameter. For secrets (defaultValue is always null on read) use this flag to detect a stored value — e.g. to show a masked placeholder in UI or to allow deploy of a mandatory secret-parameter without re-entering the value. Ignored on request.
      - `defaultValueChanged` boolean, nullable: Request-only. Set true if the user edited defaultValue in this request. For isSecret=true: false/null means "keep stored value" (Vault is not touched); true means apply the submitted defaultValue (null clears, value writes). For isSecret=false: the flag has no effect; defaultValue is applied directly (null clears the stored value, a value replaces it). Not returned in responses.
      - `vaultVersion` integer, nullable: Vault version the parameter's value is pinned to. For internal use only, ignored on write. Returned only inside a version snapshot (`WorkflowTemplateVersion.snapshot.contentParams`), where it is always present but may be `null` for a parameter with no pinned version. The live workflow template endpoints never return this field.
    - `contentExecutionTimeout` integer: Maximum script execution time in minutes (1–30), as captured in this version's snapshot.
    - `isDefault` boolean: Indicates whether this is a built-in default (system-provided) workflow template, as captured in this version's snapshot.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden - Access is denied
- `404`: Not found
- `409`: Conflict. Returned in four distinct situations: - the version is already the active one, so restoring it would change nothing; - the template has reached the limit of 20 versions and `forceDeleteOldest` was not set — retry with `forceDeleteOldest = true`; - `forceDeleteOldest = true` was sent, but the oldest non-active version is the very version being restored, so no room can be freed — delete another version manually first, then retry; - the template name captured in the snapshot is already used by another non-deleted template of the company — rename that template and retry.
- `500`: Internal server error
- `503`: InternalError
- `504`: Timeout

---

[API](https://skmtc.dev/emma/apis/public-emma-api.md) - [All operations](https://skmtc.dev/emma/apis/public-emma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/emma/apis/public-emma-api/revisions/9e55f0920078?raw)