---
title: "Validate a definition"
method: POST
path: "/workflows/definitions/{id}/validate"
tags: ["Workflow definitions"]
---

# Validate a definition

`POST /workflows/definitions/{id}/validate`

## Request

- Base URL: `https://api.nullplatform.com`
- URL: `https://api.nullplatform.com/workflows/definitions/{id}/validate`
- Auth: HTTP bearer

Dry-run validation of a definition (graph shape plus step configs) with no writes. Always returns 200; inspect `valid` and `errors`.

## Path parameters

- `id` string, required

## Request body

- WorkflowDefinition: The workflow definition: the same document the visual editor saves. Steps are a map of step id to step; triggers are always rebuilt server-side from steps of type `trigger`, so a client-supplied `triggers` value is discarded.
  - `name` string, required: Human-readable workflow name.
  - `key` string: Client-chosen slug (`^[a-z0-9][a-z0-9-]{0,62}$`), unique per organization and immutable. Enables GitOps-style upserts via `PUT /workflows/definitions/{key}`.
  - `description` string
  - `path` string: Folder in the workflows tree. Defaults to `/`.
  - `nrn` string: The nullplatform resource name the workflow is scoped to. Defaults to the caller's organization.
  - `steps` object, required: Map of step id to step definition. Step ids are alphanumeric (no hyphens).
  - `connections` object[]: Edges between steps.
  - `variables` object: Per-run variables with optional `initialValue`.
  - `metadata` object
  - `semanticVersion` string: Optional version label stored on the revision.

## Response `200`

The validation verdict, valid or not.

- ValidateResult
  - `valid` boolean
  - `errors` object[]: Graph and step-config findings. Includes warnings.
    - `path` string
    - `message` string
    - `severity` 'error' | 'warning'

## Other responses

- `4XX`: Client error. The body says what went wrong: an error `type`, a human-readable `detail`, and, on validation failures, one entry per offending field.
- `5XX`: Unexpected server error.

## Changes

- **2026-09-17** `43b3c1ecdfd8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nullplatform/apis/nullplatform-api/changes/workflows/definitions/:id/validate/post.md)

---

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