Check an automation's definition without storing it (tenant:forge:read)
POST /api/forge/v1/projects/{key}/automations/validate
Module: Forge · operationId: validateForgeAutomation · Tag: Automations · Auth: access token (Authorization: Bearer <accessToken>)
Requires tenant:forge:read and a project the caller sees. Validates the YAML with the inline profile against forge's catalogue and answers the findings (the same codes, paths and positions as flows) and the ports of every node. needsDurable says that the definition is fine but for parts only a flow in the background can run.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key |
path | string | yes | Project key (e.g. APP) |
Request body
application/json (required)
yaml(string, required): The definition (YAML of the flow language)
Example:
{
"yaml": "schemaVersion: 1\nkey: review-erinnerung\nname: Review-Erinnerung\ntriggers:\n - { id: review, kind: event, event: forge.item.status_changed, filter: 'trigger.data.statusKey == \"review\"' }\nnodes:\n warten:\n kind: wait\n duration: 48h\n erinnern:\n kind: action\n action: forge.comment.add\n params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", body: Das Review wartet seit zwei Tagen. }\nedges:\n - review -\u003e warten\n - warten -\u003e erinnern\n"
}
Responses
- 200 The findings (
application/json) - 400 Error (
application/json) - 404 Error (
application/json)
Fields of the 200 answer:
diagnostics(array of AutomationDiagnostic, required): The findings, errors and warningscode(string, required): Stable code, e.g.unknown_action,missing_param,expression,needs_durable,inline_ignoredmessage(string, required): Human-readable text of the findingseverity(string, required): Errors keep the automation from being enabled (one oferror,warning)col(integer): Column in the YAML definition (when known)line(integer): Line in the YAML definition (when known)nodeId(string): The node the finding is aboutparams(object):needs_durable:reason(trigger, kind, action, foreign_action, foreign_event, recipient, mail_option – a mail node setsmandatoryormailChannel, which only a tenant flow without scope may –, too_many_nodes)path(string): Dotted path in the definition
needsDurable(boolean, required): A finding isneeds_durable: the definition runs only as a flow in the backgroundpermissions(array of array of string, required): The any-of permission groups a flow with this definition would needports(object, required): The output ports of every node that parsed, by node id (the builder's handles)profile(string, required): The profile the definition was checked with (one ofinline)valid(boolean, required): No finding is an error
Example 200 answer:
{
"diagnostics": [
{
"code": "needs_durable",
"col": 3,
"line": 8,
"message": "Der Knoten „warten“ kann nicht sofort laufen; als Flow im Hintergrund ist er möglich.",
"nodeId": "warten",
"params": {
"reason": "kind"
},
"path": "nodes.warten",
"severity": "error"
}
],
"needsDurable": true,
"permissions": [
[
"tenant:forge:write",
"tenant:forge:admin"
]
],
"ports": {
"erinnern": [
"main",
"error"
],
"warten": [
"main",
"error"
]
},
"profile": "inline",
"valid": false
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/validate' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"yaml":"schemaVersion: 1\nkey: review-erinnerung\nname: Review-Erinnerung\ntriggers:\n - { id: review, kind: event, event: forge.item.status_changed, filter: '\''trigger.data.statusKey == \"review\"'\'' }\nnodes:\n warten:\n kind: wait\n duration: 48h\n erinnern:\n kind: action\n action: forge.comment.add\n params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", body: Das Review wartet seit zwei Tagen. }\nedges:\n - review -\u003e warten\n - warten -\u003e erinnern\n"}'