# Validate a workflow

> operationId: `validateWorkflow`


## Request

This endpoint validates a workflow. With purpose=save, environmentId/parameters are not allowed. With purpose=run, both must be provided. With source.kind=inline, send a complete TemplateWrite, and include base when you modify an existing template. With kind=template, specify the exact saved version. Errors in the internal structure of the workflow return 200+valid=false. Only errors in the request envelope return 400. Saving and starting a run still validate again. This endpoint does not produce a validationToken that could bypass that recheck.

- **Prerequisites**: An inline candidate does not need to be saved first. Reading a saved template, base, or dependencies also requires templates:read. With purpose=run, environments:read is also required.
- **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**: This call performs read-only validation. It does not save templates, secrets, or files. It does not open a browser or install a browser kernel.
- **Completion signal**: 200 only means that validation finished. You must check data.valid, issues, truncated, and runtimeChecks.
- **Retries**: Read-only calls can be retried. On 429 or 503, back off as indicated by Retry-After.


### Endpoint

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

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


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

### Path parameters

None.

### Query parameters

None.

### Request body

**Option 1**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `purpose` | `"save"` | Yes | With save, only the conditions for saving are checked. With run, parameters, the environment, and run limits are also checked. |
| `source` | [ValidationSource](/browser-rpa/api/data-types#validationsource) | Yes | Selects a candidate template or a saved template. Use exactly one option. |


**Option 2**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `purpose` | `"run"` | Yes | With save, only the conditions for saving are checked. With run, parameters, the environment, and run limits are also checked. |
| `source` | [ValidationSource](/browser-rpa/api/data-types#validationsource) | Yes | Selects a candidate template or a saved template. Use exactly one option. |
| `environmentId` | string | Yes | ID of an actual environment. Get it from an environment query. Min length 1; max length 128. |
| `parameters` | [ParameterValues](/browser-rpa/api/data-types#parametervalues) | Yes | Map from parameter names to {kind:json,value:JSON} (plain text for private parameters, absolute local paths for file parameters; see ParameterValues). Use {} when there are no parameters. |


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

For the two mutually exclusive structures of source, see [ValidationSource](/browser-rpa/api/data-types#validationsource). With purpose=run, the endpoint only performs a preflight and does not run the workflow.

### 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 `validate-workflow.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
{
  "purpose": "save",
  "source": {
    "kind": "inline",
    "template": {
      "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}/validations" \
  -H 'Content-Type: application/json' \
  --data-binary @validate-workflow.request.json
```

## Response

### 200

200 only means that validation finished. You must check data.valid, issues, truncated, and runtimeChecks.

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 |
|  --- | --- | --- | --- |
| `valid` | boolean | Yes | It is true when there are no static errors. It does not mean that an actual run succeeds. |
| `issues` | array<[Issue](/browser-rpa/api/data-types#issue)> | Yes | List of structured issues. It is [] when there are no issues. |
| `truncated` | boolean | Yes | It is true when the issue limit was reached. Validate again after you fix the issues. |
| `runtimeChecks` | array<object> | Yes | Items that still need confirmation at run time. An empty array does not prove that the real web page is usable, and it does not explain why there are no items. |
| `effectiveInputs` | object | Yes | Optional diagnostic summary keyed by nodeId. defaultsApplied contains only the safe defaults filled in by this validation, and unresolvedFields lists the input fields that were not resolved. Entries can be omitted, or {} can be returned, so a missing entry does not tell you whether normalization took place. |
| `workflowHash` | string | Yes | Content identifier for diagnostics. It is not guaranteed to stay stable across inline/saved sources, catalogs, or normalization steps, and it does not prove that the workflow was saved. See the supplementary rules in common.md. |
| `catalogRevision` | string | Yes | Content revision of the node contracts. Format: sha256: followed by 64 hexadecimal digits. |
| `dependencyRevisions` | array<[DependencyPin](/browser-rpa/api/data-types#dependencypin)> | Yes | Exact dependency revisions used for freezing or validation. |


**`runtimeChecks[]` fields**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `runtimeChecks[].nodeId` | string | Yes | Stable node ID in the template. Min length 1; max length 128. |
| `runtimeChecks[].field` | string | Yes | The corresponding node input field or rule field. |
| `runtimeChecks[].code` | string | Yes | The current general value is RPA_RUNTIME_CHECK_REQUIRED. An unknown code added in the future still means that confirmation at run time is pending. See common.md. |
| `runtimeChecks[].reason` | string | Yes | Reason for unavailability, isolation, or the runtime check. |


### Response example

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

```json
{
  "data": {
    "valid": true,
    "issues": [],
    "truncated": false,
    "runtimeChecks": [
      {
        "nodeId": "visit",
        "field": "url",
        "code": "RPA_RUNTIME_CHECK_REQUIRED",
        "reason": "Save validation does not visit the target website. Actual connectivity must be confirmed at run time"
      }
    ],
    "effectiveInputs": {},
    "workflowHash": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "dependencyRevisions": []
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### Error responses

| HTTP | error.code | What to do |
|  --- | --- | --- |
| 409 | RPA_TEMPLATE_VERSION_CONFLICT | The version in source.kind=template or the base.version in source.kind=inline is out of date. Both cases return this error with VersionConflictDetails. GET the latest version again, merge, and then validate again. A validation-only call has no receipt. |
| 409 | RPA_DEPENDENCY_VERSION_UNAVAILABLE | A dependency pin is not a currently available revision. |
| 503 | RPA_VALIDATION_TIMEOUT | The read-only validation timed out. Retry as indicated by Retry-After. |


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)

### Error locations in a run preflight

HTTP(S) URLs that can be determined from the actual parameters are validated during the preflight, and the issue points to `/parameters/<name>/value`. URLs that depend on the results of earlier nodes are still listed in runtimeChecks and are checked at execution time. A missing required parameter points to `/parameters/<name>`. When the environment does not exist or the client cannot resolve it, the response is 200 with valid=false and RPA_ENVIRONMENT_UNAVAILABLE, at the location `/environmentId`. When the environment is busy, the response has the same structure with code=RPA_ENVIRONMENT_BUSY. When the environment is outside the authorized scope, the response is HTTP 404, which does not reveal whether the environment exists.