The Knock Workflow Triggers API has exactly two operations: POST /v1/notify to fire a workflow and POST /v1/notify/cancel to stop one. Knock’s separate Workflows API already has POST /v1/workflows/{key}/trigger and POST /v1/workflows/{key}/cancel, which do the same jobs. The two pairs are not interchangeable, and the differences show up in the contracts, not the summaries. Both pairs carry the same summaries: “Trigger workflow” and “Cancel workflow”.
Knock scores 59.7 on the Kin Score (strong) and 57.4 on Agent Readiness (agent-native). Its overview says it publishes 32 APIs on the network. Its header counts 2 published, and its score block counts 56 contracts.
Same job, two shapes
/v1/notify |
/v1/workflows/{key}/trigger |
|
|---|---|---|
| Workflow key | name in the body |
key in the path |
| Required fields | name, actor, recipients |
recipients only |
| Extra fields | none | settings, tenant |
| Rate limit tier | 3 | 5 |
| Success | 200 with result_id |
200 |
The cancel pair follows the same pattern. /v1/notify/cancel takes name, cancellation_key and optional recipients in the body. /v1/workflows/{key}/cancel moves the key into the path and requires only cancellation_key. Both return 204.
The practical difference is the actor. On the notify path, you cannot fire a workflow without one. On the workflows path, an actor is optional. Code that switches between them will fail on the stricter one, not the looser one.
The contract describes itself as internal
The OpenAPI rendered on the apis.io page is titled “Knock Notify Workflow Triggers API”. Its description calls these “Internal notify endpoints used by the Knock event-driven trigger surface”, meaning workflows that fire from source events, schedules, audiences or programmatic triggers. The operation ID shows how it was assembled: cancelWorkflow(2), carrying x-operation-id-original: cancelWorkflow (2) and x-operation-id-source: normalized. That is a name collision we resolved by suffixing, because the Workflows API already uses cancelWorkflow. On the Workflows side, the trigger operation became triggerWorkflow(2) for the same reason.
So the apis.io page gives a public-looking API page to endpoints the contract itself calls internal. The documentation it links (docs.knock.app/api-reference/workflows and the triggering-workflows guide) describes the path-keyed version. If you are starting fresh, that is the one to build on.
What the payload limits tell you
The notify request schema documents two limits worth knowing whichever path you use. The full data payload is capped at 10MB, and any individual string over 1024 bytes is truncated in Knock’s API logs. The second limit is a logging limit, not a delivery limit, but it will make large payloads hard to debug. The cancellation_key must be set at trigger time, because a run cannot be cancelled later without one. It should also be unique across trigger requests to avoid cancelling the wrong run.
Takeaway
Treat /v1/notify as the event-surface entry point it says it is, and send programmatic triggers through /v1/workflows/{key}/trigger. Set a cancellation_key on every trigger you might want to stop, and do not let the identical summaries hide the different required fields. Compare both at apis.io/apis/knock-app/knock-app-workflow-triggers-api/ and apis.io/apis/knock-app/knock-app-workflows-api/.