GoRunner

Report every problem in a definition without writing anything

Requires scope workflow:read
POST
/api/workflows/validate

Judges a definition and returns EVERY problem it can prove, in one call. Nothing is written, nothing is created — this is the call to make BEFORE a create or an update, so you fix a whole definition at once instead of discovering faults one refused write at a time.

It answers 200 for any readable request: a definition full of errors is a RESULT, not a transport failure. Read ok (nothing blocking found) and diagnostics, not the status code. Non-2xx is reserved for a malformed body or a workflow you cannot see.

Send either definition (an unsaved tree you are about to POST/PUT) or workflowId (validate that stored workflow's current DRAFT). If both are present, definition wins. Diagnostics are capped at 200 with the dropped count in truncated. skipped names check families that could not run — most often because the worker fleet is down, which would otherwise make every piece look unknown; a short diagnostics list plus a non-empty skipped is NOT a clean bill of health.

This runs the same validator the publish gate runs, so anything reported blocking: true here is exactly what a publish would refuse on.

Authorization

bearerAuth
AuthorizationBearer <token>

An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Exactly one of definition or workflowId is required.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workflows/validate" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "schemaVersion": 2,      "trigger": {        "name": "trigger",        "type": "webhook",        "pieceId": "webhook",        "actionId": "catch_webhook",        "config": {},        "valid": true      },      "settings": {}    }  }'
{  "data": {    "ok": true,    "diagnostics": [      {        "severity": "error",        "code": "string",        "path": "string",        "step": "string",        "field": "string",        "message": "string",        "alternatives": [          "string"        ],        "moreAlternatives": 0,        "blocking": true      }    ],    "counts": {      "property1": 0,      "property2": 0    },    "skipped": [      "string"    ],    "truncated": 0  }}