ConnectCloud Developers

Check a flow definition without storing it (tenant:flows:read|write|admin)

POST /api/flows/v1/validate

Module: Flows · operationId: validateFlowDefinition · Tag: Flows · Auth: access token (Authorization: Bearer <accessToken>)

Request body

application/json (required)

  • yaml (string, required): The definition (YAML, at most 256 KiB)

Example:

{
  "yaml": "schemaVersion: 1\nkey: kritische-tickets-zusammenfassen\nname: Kritische Tickets zusammenfassen\ntriggers:\n  - { id: neues_ticket, kind: event, event: desk.item.created }\nnodes:\n  ticket:\n    kind: action\n    action: desk.item.get\n    params: { ref: \"{{ trigger.data.itemId }}\" }\nedges:\n  - neues_ticket -\u003e ticket\n"
}

Responses

  • 200 The findings (application/json)
  • 400 Invalid input (invalid); field names the first invalid field, details.fields every one. (application/json)
  • 401 Missing, invalid or expired token (no body).
  • 403 The token lacks the permission or has no active tenant (forbidden). Also: person_required (a service-account key on personal flows or the task inbox), live_test_forbidden, forbidden_grant, starter_excluded. (application/json)

Fields of the 200 answer:

  • diagnostics (array of Diagnostic, required): Findings of the validator
    • code (string, required): Stable code, e.g. unknown_port, invalid_assignee, mail_option_not_allowed (a mail node sets mandatory or mailChannel in a personal or scoped flow)
    • message (string, required): Human-readable explanation
    • severity (string, required): Errors block publishing (one of error, warning)
    • col (integer): Column in the YAML (1-based)
    • line (integer): Line in the YAML (1-based)
    • nodeId (string): The node the finding is about
    • params (object): mail_option_not_allowed: option (mandatory or mailChannel)
    • path (string): Dotted path in the definition
  • permissions (array of array of string, required): The any-of permission groups of the actions and events the flow uses
  • valid (boolean, required): False when a finding has severity error
  • ports (object): The output ports of every node that parsed, by node id (the builder's handles)

Example 200 answer:

{
  "diagnostics": [
    {
      "code": "retry_unused",
      "col": 9,
      "line": 24,
      "message": "a mail node is never retried",
      "nodeId": "info",
      "path": "nodes.info.retry",
      "severity": "warning"
    }
  ],
  "permissions": [
    [
      "desk:read",
      "desk:write",
      "desk:admin"
    ]
  ],
  "ports": {
    "info": [
      "success",
      "error"
    ],
    "ticket": [
      "success",
      "error"
    ],
    "zusammenfassung": [
      "success",
      "error"
    ]
  },
  "valid": true
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/flows/v1/validate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"yaml":"schemaVersion: 1\nkey: kritische-tickets-zusammenfassen\nname: Kritische Tickets zusammenfassen\ntriggers:\n  - { id: neues_ticket, kind: event, event: desk.item.created }\nnodes:\n  ticket:\n    kind: action\n    action: desk.item.get\n    params: { ref: \"{{ trigger.data.itemId }}\" }\nedges:\n  - neues_ticket -\u003e ticket\n"}'

View as Markdown · Interactive reference · OpenAPI