---
title: "Update a workflow template"
method: PUT
path: "/v1/workflow-templates/{id}"
tags: ["Workflows"]
---

# Update a workflow template

`PUT /v1/workflow-templates/{id}`

## Request

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

This method updates an existing workflow template. A workflow template is a predefined blueprint for a workflow that includes a set of tasks and their dependencies. It serves as a starting point for creating workflows, allowing users to quickly set up and execute common processes without having to define each task from scratch.

The name must be unique among the company's non-deleted workflow templates. Renaming to a name held by another template returns `409`; submitting the template's own name is allowed. Names of deleted templates become available for reuse. The comparison is exact and case-sensitive.

## Path parameters

- `id` integer, required

## Request body

- WorkflowTemplateCreate
  - `name` string, required: Name of the workflow template
  - `description` string, nullable: Description of the workflow template
  - `contentType` 'Shell', required: Format of the content field, only Shell is supported for now
  - `content` string, required: Content of the workflow template. For Shell contentType, it includes shell commands to execute.
  - `status` 'PUBLISHED' | 'UNPUBLISHED', required: Status of the workflow template. Can be PUBLISHED or UNPUBLISHED
  - `resourceTypes` string[]: Types of the resource. Use this instead of the deprecated resourceType. At least one of resourceTypes or resourceType is required.
  - `resourceType` 'COMPUTE' | 'SPOT_COMPUTE': Deprecated — use resourceTypes. At least one of resourceTypes or resourceType is required.
  - `resourceParams` ResourceParamCreate[], required: Parameters of the resource limitation. The parameters depend on the resource type and include parameters for compute instance.
    - `name` 'minCpuCores' | 'maxCpuCores' | 'minRamSizeGb' | 'maxRamSizeGb' | 'minVolumeSizeGb' | 'maxVolumeSizeGb', required: Name of the resource parameter, e.g. minCpuCores, minRamSizeGb, minVolumeSizeGb (and their max* counterparts).
    - `value` string, required: Value of the resource parameter
  - `tags` TagCreate[], required: List of tags assigned to the workflow template
    - `tagId` string, nullable: Existing tag id — echo it back on update to match/preserve the stored tag. Omit (or null) for a newly added tag; the backend assigns the id.
    - `key` string, required: tag key
    - `value` string, nullable: tag key value
  - `contentParams` ContentParam[], required: List of parameters extracted from the content. These parameters can be used to fill in the blanks in the content when creating a workflow from the template.
    - `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.
  - `isContentValid` boolean: Whether the content passed validation. Optional on write; defaults to true when omitted. Must be true when status is PUBLISHED.
  - `contentExecutionTimeout` integer: Maximum script execution time in minutes (1–30). Defaults to 10 when omitted.
  - `forceDeleteOldest` boolean, nullable: PUT only, ignored on POST. When `true` and the workflow template has reached the 20-version limit, the server soft-deletes the oldest non-active version as part of the save. Otherwise, the request fails with 409 CONFLICT. Ignored on POST

## Response `200`

Workflow template updated successfully

- WorkflowTemplate
  - `id` integer, required: ID of the workflow template
  - `name` string, required: Name of the workflow template
  - `description` string, nullable: Description of the workflow template
  - `createdAt` string, required: Date and time of the workflow template creation (ISO-8601, UTC, with milliseconds)
  - `createdByName` string, required: Name of the user who created the workflow template
  - `createdById` integer, required: ID of the user who created the workflow template
  - `modifiedAt` string, required: Date and time when the workflow template was last edited (ISO-8601, UTC, with milliseconds)
  - `modifiedByName` string, required: Name of the user who last edited the workflow template
  - `modifiedById` integer, required: ID of the user who last edited the workflow template
  - `isDeleted` boolean, required: Indicates whether the workflow template is deleted
  - `status` 'PUBLISHED' | 'UNPUBLISHED', required: Status of the workflow template. Can be PUBLISHED or UNPUBLISHED
  - `resourceTypes` string[], required: Types of the resource.
  - `resourceType` 'COMPUTE' | 'SPOT_COMPUTE', nullable: Deprecated — use resourceTypes. Mirrors the first resource type; present for backward compatibility. Null when no resource type is set.
  - `activeVersionId` integer, nullable: ID of the active workflow version. `null` when the template has no versions — permanently so for built-in default templates (`isDefault = true`), which are excluded from versioning, and until the one-off backfill covers templates created before versioning was enabled.
  - `activeVersionName` string, nullable: Name of the active workflow version. `null` under the same conditions as `activeVersionId`.
  - `resourceParams` ResourceParam[], required: Parameters of the resource limitation. The parameters depend on the resource type and include parameters for compute instance.
    - `name` string, required: Name of the resource parameter, e.g. minCpuCores, minRamSizeGb, minVolumeSizeGb (and their max* counterparts).
    - `value` string, required: Value of the resource parameter
  - `tags` Tag[], required: List of tags assigned to the workflow template
    - `tagId` string, uuid, required: tag id
    - `key` string, required: tag key
    - `value` string, nullable: tag key value
  - `contentType` 'Shell', required: Format of the content field, only Shell is supported for now
  - `content` string, required: Content of the workflow template. For Shell contentType, it includes shell commands to execute.
  - `isContentValid` boolean, required: Indicates whether the content of the workflow template is valid. The content is validated against the contentType, e.g. for Shell contentType, the content is validated to be correct shell commands.
  - `contentParams` ContentParam[], required: List of parameters extracted from the content. These parameters can be used to fill in the blanks in the content when creating a workflow from the template.
    - `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, required: Maximum script execution time in minutes (1–30). Defaults to 10 when omitted on create/update.
  - `isDefault` boolean, required: Indicates whether this is a built-in default (system-provided) workflow template.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden - Access is denied
- `404`: Not found
- `409`: Conflict — another non-deleted workflow template of the company already uses the requested name
- `422`: Unprocessable entity
- `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)