# Create a template

> operationId: `createTemplate`


## Request

Creates a template. All four fields are required: title, description, workflow, and dependencies. The request must not include account, team, owner, active, or compiledDefinition. Submit private parameter default values directly in plain text. They are written into the cloud template content as is, the same way the desktop client editor saves them. A new template can't use the `publicState:"retained"` placeholder. Like GET, the response returns private parameter default values in plain text. The idempotency receipt doesn't store template content. On a replay with the same key, the server reads the cloud template again and returns its current content. See [Private default values](/browser-rpa/api/workflow#3-private-default-values). Fields such as scripts, local paths, and credentials can take literal values directly. After you receive the response, use the workflow that the server returned. Don't keep treating the draft you submitted as the final version. An action node can contain only browserAction and browserUi.inputs. The server fills in the missing fields of title, inputs, inputsValues, browserUi.bindings, and browserUi.exception the way the desktop client editor does, and it generates data.outputs (see [Fields completed 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 structure with these fields filled in.

- **Prerequisites**: You have read the node contracts and completed a preflight validation with purpose=save. Even with no dependencies, you must submit dependencies=[].
- **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**: Creates a template in the current account's "Custom Templates" in the desktop client (personal cloud templates). It appears after the client list refreshes. The workflow is not run.
- **Completion signal**: 201 returns the normalized Template, id, version, revisionId, and ETag, which means the save is complete.
- **Retries**: To recover the same intent, reuse the original key, the original body (if any), and the original If-Match (when this endpoint requires it). On an HTTP timeout, first [check the request receipt](/browser-rpa/api/get-request-receipt). Don't generate a new key.


### Endpoint

```http
POST /api/rpa/browser/v1/templates
```

Local API: `http://127.0.0.1:<port>/api/rpa/browser/v1/templates`. 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. |


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

### Path parameters

None.

### 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. Use an empty string to clear it. Max length 1000. |
| `workflow` | [Workflow](/browser-rpa/api/data-types#workflow) | Yes | Native editor workflow object. It runs in the order of nodes/blocks. |
| `dependencies` | array<[DependencyPin](/browser-rpa/api/data-types#dependencypin)> | Yes | List of child template dependencies. It must match the child templates referenced by applySubProcess in the workflow one to one. revisionId is the child template's current revisionId (`remote:<childTemplateId>@<version>`). With no dependencies, submit []. At run time, as in the desktop client, each run takes a frozen snapshot of the child template's latest version at that time. 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 `create-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": 500
            }
          }
        }
      },
      {
        "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 POST "${RPA_BASE_URL}/templates" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${RPA_REQUEST_KEY}" \
  -H "X-RPA-Catalog-Revision: ${RPA_CATALOG_REVISION}" \
  --data-binary @create-template.request.json
```

## Response

### 201

201 returns the normalized Template, id, version, revisionId, and ETag, which means the save is complete.

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


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. Use an empty string to clear it. |
| `workflow` | [Workflow structure](/browser-rpa/api/workflow) / [JSON Schema](/browser-rpa/local-api#local-machine-readable-contract) | Yes | Native editor workflow object. It runs in the order of nodes/blocks. |
| `dependencies` | array<[DependencyPin](/browser-rpa/api/data-types#dependencypin)> | Yes | List of child template dependencies. It must match the child templates referenced by applySubProcess in the workflow one to one. revisionId is the child template's current revisionId (`remote:<childTemplateId>@<version>`). With no dependencies, submit []. At run time, as in the desktop client, each run takes a frozen snapshot of the child template's latest version at that time. 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. 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 have title, inputs, inputsValues, outputs, and complete browserUi.bindings/exception. Exception fields you don't set get the editor defaults. When timeout isn't set, it is 30000 for action nodes and 0 (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": 500
              },
              "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": "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": 1,
    "revisionId": "revision_example_1",
    "createdAt": 1793318400000,
    "updatedAt": 1793318400000,
    "warnings": [],
    "redactedPaths": []
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### Error responses

| HTTP | error.code | What to do |
|  --- | --- | --- |
| 409 | RPA_CATALOG_CHANGED | Check the receipt first. After you confirm the write wasn't committed, refresh the catalog header. You can then recover with the original body/If-Match/key. |
| 409 | RPA_REQUEST_CONFLICT | The method/path/body/If-Match sent with this key differs from the original intent. |
| 504 | RPA_REQUEST_TIMEOUT | This only means the HTTP wait timed out. Check the original request receipt first. |
| 422 | RPA_VALIDATION_FAILED | Use issues.path to fix the complete workflow. |


A same-key write replay keeps the ETag of the original response (if there was one; it may be stale). A receipt contains only data, without response headers. Before you continue editing, you must GET the template. 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)