# Replace a template

> operationId: `replaceTemplate`


## Request

Replaces the entire template. This is not a PATCH: missing required fields are not kept automatically, and arrays are replaced in full. Valid display metadata is preserved. For a private default value, submit plaintext to overwrite it, or submit `publicState:"retained"` on the same field of the same template to keep it. Omitting defaultValue, or setting enabled=false, clears it. For details, see [Private default values](/browser-rpa/api/workflow#3-private-default-values). Like GET, the response returns private parameter default values in plaintext. The idempotency receipt doesn't store template content. A replay with the same key rereads the cloud template and returns its current content; see [Private default values](/browser-rpa/api/workflow#3-private-default-values). Action nodes can specify only browserAction and browserUi.inputs. The server fills in missing title, inputs, inputsValues, browserUi.bindings, and browserUi.exception fields the same way the client editor does, and generates data.outputs (see [Fields filled in by the server](/browser-rpa/api/workflow#fields-the-server-fills-in)). The workflow in the response, and in later GET reads, is the complete filled-in structure.

- **Prerequisites**: You have read the current complete template and its ETag, and the candidate passes save validation. Inline validation should include source.base.
- **Authentication**: Same as the rest of the Local API; see [Authentication](/api-reference/getting-started/authentication). Resources belong to the current account/team data scope.
- **Side effects**: Atomically replaces the entire template and creates one new version and revision. The template is not run.
- **Completion signal**: 200 returns the new Template and a new ETag, which means the entire update was saved.
- **Retries**: Recover the same intent with the original key, the original body (if any), and the original If-Match (if this endpoint requires one). On an HTTP timeout, first [get the request receipt](/browser-rpa/api/get-request-receipt). Don't generate a new key.


### Endpoint

```http
PUT /api/rpa/browser/v1/templates/{templateId}
```

Local API: `http://127.0.0.1:<port>/api/rpa/browser/v1/templates/{templateId}`. Use the port configured in the client.

### Headers

| Parameter | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `Authorization` | string | When Local API authentication is enabled | See [Authentication](/api-reference/getting-started/authentication). |
| `Idempotency-Key` | string | No | Recommended. Generate a UUID for each new write intent and keep it when you retry after a disconnect; the same key never runs twice. Without it there is no duplicate protection, so a retry after a timeout can run the write again. When present, it must be a UUID. Format "uuid". |
| `X-RPA-Catalog-Revision` | string | Yes | The catalogRevision returned by GET capabilities. |
| `If-Match` | string | Yes | Exact ETag from the template response. Wildcards and multiple values are rejected. |


Content type: `Content-Type: application/json` (required).

### Path parameters

| Parameter | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `templateId` | string | Yes | ID of the target template: the cloud ID of the template in the client's "Custom Templates", as a numeric string. Min length 1; max length 128. |


### Query parameters

None.

### Request body

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `title` | string | Yes | Display name. On template writes, 1–100 characters after trimming. Min length 1; max length 100. |
| `description` | string | Yes | Description text. Required on template writes; an empty string clears it. Max length 1000. |
| `workflow` | [Workflow](/browser-rpa/api/data-types#workflow) | Yes | The editor's native workflow object. Execution follows the nodes/blocks order. |
| `dependencies` | array<[DependencyPin](/browser-rpa/api/data-types#dependencypin)> | Yes | Child template dependencies. They must match the child templates that applySubProcess references in the workflow, one to one. revisionId is the child template's current revisionId (`remote:<childTemplateId>@<version>`). If there are no dependencies, submit []. At run time, as in the client, each run freezes a snapshot of the latest child templates at that moment. Max items 1000. |


Full model: [TemplateWrite](/browser-rpa/api/data-types#templatewrite).

### Request example

This is a documentation example; it was not sent to a live client. Set `RPA_BASE_URL` as described in [API conventions](/browser-rpa/api/common). Resource variables, the catalog revision, and ETags come from actual responses.

Save the complete JSON below as `replace-template.request.json`. Replace every value whose identifier contains `example` with a value from an actual response. The node IDs in the creation sample are workflow-local IDs and can stay as they are.

```json
{
  "title": "Read the page URL",
  "description": "Visit the given page and return its URL",
  "workflow": {
    "editorVersion": 2,
    "editorParametersVersion": 1,
    "variables": {
      "type": "object",
      "properties": {
        "targetUrl": {
          "type": "string",
          "description": "HTTP(S) URL to visit"
        }
      },
      "required": [
        "targetUrl"
      ]
    },
    "nodes": [
      {
        "id": "start",
        "type": "start"
      },
      {
        "id": "visit",
        "type": "browser_gotoUrl",
        "data": {
          "browserAction": "gotoUrl",
          "browserUi": {
            "inputs": {
              "url": "${targetUrl}",
              "postWaitMs": 0
            }
          }
        }
      },
      {
        "id": "wait_before_read",
        "type": "browser_waitTime",
        "data": {
          "browserAction": "waitTime",
          "browserUi": {
            "inputs": {
              "timeoutType": "fixed",
              "timeout": 2000
            }
          }
        }
      },
      {
        "id": "url_result",
        "type": "browser_getUrl",
        "data": {
          "browserAction": "getUrl",
          "browserUi": {
            "inputs": {
              "type": "href"
            }
          }
        }
      },
      {
        "id": "end",
        "type": "end",
        "data": {
          "inputsValues": {
            "status": {
              "type": "constant",
              "content": "success"
            },
            "message": {
              "type": "ref",
              "content": [
                "url_result",
                "data",
                "value"
              ]
            }
          }
        }
      }
    ]
  },
  "dependencies": []
}
```

```bash
curl -i -X PUT "${RPA_BASE_URL}/templates/${RPA_TEMPLATE_ID}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${RPA_REQUEST_KEY}" \
  -H "X-RPA-Catalog-Revision: ${RPA_CATALOG_REVISION}" \
  -H "If-Match: ${RPA_ETAG}" \
  --data-binary @replace-template.request.json
```

## Response

### 200

200 returns the new Template and a new ETag, which means the entire update was saved.

| Header | Description |
|  --- | --- |
| `ETag` | Strong version identifier of the template in this response. Send it unchanged as If-Match in later modifications. |


Body: `application/json`. The top-level `data` uses the model below. For `meta`, see [Metadata](/browser-rpa/api/data-types#metadata).

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `title` | string | Yes | Display name. On template writes, 1–100 characters after trimming. |
| `description` | string | Yes | Description text. Required on template writes; an empty string clears it. |
| `workflow` | [Workflow structure](/browser-rpa/api/workflow) / [JSON Schema](/browser-rpa/local-api#local-machine-readable-contract) | Yes | The editor's native workflow object. Execution follows the nodes/blocks order. |
| `dependencies` | array<[DependencyPin](/browser-rpa/api/data-types#dependencypin)> | Yes | Child template dependencies. They must match the child templates that applySubProcess references in the workflow, one to one. revisionId is the child template's current revisionId (`remote:<childTemplateId>@<version>`). If there are no dependencies, submit []. At run time, as in the client, each run freezes a snapshot of the latest child templates at that moment. Max items 1000. |
| `id` | string | Yes | Unique ID of the resource or node. Take it from a previous response; don't guess it. Min length 1; max length 128. |
| `version` | integer | Yes | Current editable template version. Read it from an actual response. Minimum 1. |
| `revisionId` | string | Yes | Immutable revision ID. Min length 1; max length 128. |
| `createdAt` | integer | Yes | Creation time, Unix milliseconds. Minimum 0. |
| `updatedAt` | integer | Yes | Last update time, Unix milliseconds. Minimum 0. |
| `warnings` | array<[Issue](/browser-rpa/api/data-types#issue)> | Yes | Issues and limitations that don't block saving. Assess the impact of each one. |
| `redactedPaths` | array<string> | Yes | Compatibility field. It is always an empty array in the current version. The Local API doesn't redact template content. |


### Response example

The workflow in the response is the complete structure after the server fills in missing fields. Action nodes include title, inputs, inputsValues, outputs, and the complete browserUi.bindings/exception (exception fields you didn't write take the editor defaults; if timeout isn't written, it is 30000 for action nodes and 0, meaning no time limit, for control nodes). Fields you set explicitly stay unchanged.

All IDs, timestamps, hashes, and run results are sample data. They don't indicate that the sample was executed.

```json
{
  "data": {
    "title": "Read the page URL",
    "description": "Visit the given page and return its URL",
    "workflow": {
      "editorVersion": 2,
      "editorParametersVersion": 1,
      "variables": {
        "type": "object",
        "properties": {
          "targetUrl": {
            "type": "string",
            "description": "HTTP(S) URL to visit"
          }
        },
        "required": [
          "targetUrl"
        ]
      },
      "nodes": [
        {
          "id": "start",
          "type": "start"
        },
        {
          "id": "visit",
          "type": "browser_gotoUrl",
          "data": {
            "browserAction": "gotoUrl",
            "browserUi": {
              "inputs": {
                "url": "${targetUrl}",
                "postWaitMs": 0
              },
              "bindings": {},
              "exception": {
                "policy": "interrupt",
                "timeout": 30000,
                "retry": false,
                "retryTimes": 1,
                "retryInterval": 2,
                "screenshot": true
              }
            },
            "title": "Visit website",
            "inputs": {
              "type": "object",
              "properties": {}
            },
            "inputsValues": {},
            "outputs": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "description": "Execution status"
                },
                "startedAt": {
                  "type": "string",
                  "description": "Start time"
                },
                "endedAt": {
                  "type": "string",
                  "description": "End time"
                },
                "durationMs": {
                  "type": "number",
                  "description": "Duration (ms)"
                },
                "matchedIndex": {
                  "type": "number",
                  "description": "Match index"
                },
                "error": {
                  "type": "object",
                  "description": "Error message",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "data": {
                  "type": "object",
                  "description": "Result",
                  "properties": {
                    "tabId": {
                      "type": "string",
                      "description": "Tab ID"
                    },
                    "httpStatus": {
                      "type": "number",
                      "description": "HTTP status code"
                    },
                    "url": {
                      "type": "string",
                      "description": "URL"
                    },
                    "finalUrl": {
                      "type": "string",
                      "description": "Final URL"
                    },
                    "title": {
                      "type": "string",
                      "description": "Page title"
                    },
                    "isRedirected": {
                      "type": "boolean",
                      "description": "Redirected"
                    }
                  }
                }
              }
            }
          }
        },
        {
          "id": "wait_before_read",
          "type": "browser_waitTime",
          "data": {
            "browserAction": "waitTime",
            "browserUi": {
              "inputs": {
                "timeoutType": "fixed",
                "timeout": 2000
              },
              "bindings": {},
              "exception": {
                "policy": "interrupt",
                "timeout": 30000,
                "retry": false,
                "retryTimes": 1,
                "retryInterval": 2,
                "screenshot": true
              }
            },
            "title": "Wait",
            "inputs": {
              "type": "object",
              "properties": {}
            },
            "inputsValues": {},
            "outputs": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "description": "Execution status"
                },
                "startedAt": {
                  "type": "string",
                  "description": "Start time"
                },
                "endedAt": {
                  "type": "string",
                  "description": "End time"
                },
                "durationMs": {
                  "type": "number",
                  "description": "Duration (ms)"
                },
                "matchedIndex": {
                  "type": "number",
                  "description": "Match index"
                },
                "error": {
                  "type": "object",
                  "description": "Error message",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "data": {
                  "type": "object",
                  "description": "Result",
                  "properties": {
                    "waitedMs": {
                      "type": "number",
                      "description": "Actual wait duration"
                    }
                  }
                }
              }
            }
          }
        },
        {
          "id": "url_result",
          "type": "browser_getUrl",
          "data": {
            "browserAction": "getUrl",
            "browserUi": {
              "inputs": {
                "type": "href"
              },
              "bindings": {},
              "exception": {
                "policy": "interrupt",
                "timeout": 30000,
                "retry": false,
                "retryTimes": 1,
                "retryInterval": 2,
                "screenshot": true
              }
            },
            "title": "Get URL",
            "inputs": {
              "type": "object",
              "properties": {}
            },
            "inputsValues": {},
            "outputs": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "description": "Execution status"
                },
                "startedAt": {
                  "type": "string",
                  "description": "Start time"
                },
                "endedAt": {
                  "type": "string",
                  "description": "End time"
                },
                "durationMs": {
                  "type": "number",
                  "description": "Duration (ms)"
                },
                "matchedIndex": {
                  "type": "number",
                  "description": "Match index"
                },
                "error": {
                  "type": "object",
                  "description": "Error message",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "data": {
                  "type": "object",
                  "description": "Result",
                  "properties": {
                    "url": {
                      "type": "string",
                      "description": "URL"
                    },
                    "origin": {
                      "type": "string",
                      "description": "Origin"
                    },
                    "pathname": {
                      "type": "string",
                      "description": "Path"
                    },
                    "query": {
                      "type": "object",
                      "properties": {},
                      "description": "Query parameters"
                    }
                  }
                }
              }
            }
          }
        },
        {
          "id": "end",
          "type": "end",
          "data": {
            "inputsValues": {
              "status": {
                "type": "constant",
                "content": "success"
              },
              "message": {
                "type": "ref",
                "content": [
                  "url_result",
                  "data",
                  "value"
                ]
              }
            }
          }
        }
      ]
    },
    "dependencies": [],
    "id": "template_example",
    "version": 2,
    "revisionId": "revision_example_2",
    "createdAt": 1793318400000,
    "updatedAt": 1793318400000,
    "warnings": [],
    "redactedPaths": []
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### Error responses

| HTTP | error.code | What to do |
|  --- | --- | --- |
| 428 | RPA_PRECONDITION_REQUIRED | If-Match is missing. Read the template first. |
| 412 | RPA_VERSION_CONFLICT | Check the original receipt first. After you confirm that the write did not commit, reread and merge, then use a new key for the modified intent. |
| 409 | RPA_CATALOG_CHANGED | Check the receipt first. After you confirm that the write did not commit, refresh the catalog header. You can recover with the original body/If-Match/key. |
| 409 | RPA_REQUEST_CONFLICT | The method/path/body/If-Match sent with the same key differs from the original intent. |
| 504 | RPA_REQUEST_TIMEOUT | This only means that the HTTP wait timed out. Check the original request receipt first. |
| 422 | RPA_VALIDATION_FAILED | Fix the complete workflow as indicated by issues.path. |


A same-key write replay keeps the ETag of the original response (if there was one; it may be out of date). The receipt contains only data, without response headers. To continue editing, send a new GET first; see [API conventions](/browser-rpa/api/common).

For common 400/401/403/404/429/5xx errors and failure fields, see [Errors and recovery](/browser-rpa/api/common#errors-and-recovery). Error response example (403):

```json
{
  "error": {
    "code": "RPA_PERMISSION_DENIED",
    "message": "The request Host or Origin is not allowed, or the current identity can't access the target environment",
    "retryable": false,
    "issues": [],
    "details": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

## Related

[Local API reference](/browser-rpa/local-api) · [API conventions](/browser-rpa/api/common) · [Data models](/browser-rpa/api/data-types) · [Workflow structure](/browser-rpa/api/workflow) · [Quickstart](/browser-rpa/quickstart)