listener definition it validates the stored
listener body instead.
POST /revisions/:id/data/query (Command: check_definition)
Request Body
Response
A failed validation is still
HTTP 200. The verdict is carried in the response body’s status field, not in
the HTTP status code. Clients must read status — treating 200 as “the definition is valid” accepts every
invalid definition. An HTTP error here means the request failed (malformed body, inaccessible definition), not
that validation found problems.
status is failure only when an event has type error. Warnings and informational events leave the status
at success, so a definition can validate successfully and still return events worth showing to an author.
events is never empty. When validation finds nothing to report, the platform appends a single info event
confirming the flow is ready, so a client can render the result uniformly without special-casing an empty array.
Each event has this shape:
Example
A structurally complete workflow:200:
listener definition is checked against its body rules and the limits, not the workflow manifest. A valid body
answers
success with one info event, “Verification completed. The listener is ready to act”. An invalid body answers
failure with one error event whose message is the refusal’s error code and message, such as
invalid_listener: batch.max_events: must be an integer of at least 1.
Notes
- Validation is not enforced on write. Upload Definition performs no structural validation of workflow documents, so an invalid definition stores successfully. This command is where structural problems surface, which is why it must be called explicitly before relying on a definition being executable.
- A listener body is checked, but the check does not resolve its
workflowreference; Upload Definition does. - An unknown or inaccessible
definition_idreturns403 forbidden, not404— an id that does not exist and one belonging to another revision are deliberately indistinguishable. An emptydefinition_idreturns400 invalid_request_body.

