Say you are wiring up notifications for your product. You search Knock's API for the call that fires a workflow, and you find two that look identical. One is POST /v1/notify. The other is POST /v1/workflows/{key}/trigger. Both are summarized as "Trigger workflow." Both have a cancel partner summarized as "Cancel workflow." You pick one and move on.
That choice matters more than the summaries suggest. The Knock Workflow Triggers API on apis.io 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.
Start with how you name the workflow. On /v1/notify, the workflow name goes in the body. On the workflows path, the key goes in the URL. Then look at what you must send. The notify call requires name, actor and recipients. The workflows call requires recipients only, and it adds two optional fields, settings and tenant, that notify does not have. The rate limit tier is 3 on notify and 5 on the workflows path. A successful notify returns 200 with a result_id; the workflows trigger returns a plain 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. So if you ever write code that switches between the two, it will fail on the stricter one, not the looser one.
Now the part you would not guess from the page title. The OpenAPI rendered on apis.io is titled "Knock Notify Workflow Triggers API," and its description calls these "Internal notify endpoints used by the Knock event-driven trigger surface" — workflows that fire from source events, schedules, audiences or programmatic triggers. The operation IDs show how the page was put together: cancelWorkflow(2), carrying x-operation-id-original: cancelWorkflow (2) and x-operation-id-source: normalized. That is a name collision the catalog resolved by adding a suffix, because the Workflows API already uses cancelWorkflow. On the Workflows side, the trigger operation became triggerWorkflow(2) for the same reason.
This is where the post turns on the catalog's own record. By giving these endpoints their own page, apis.io presents a public-looking API for operations the contract itself calls internal. The catalog's counts are also not tidy. 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. The documentation the page links to, at 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.
Two payload limits apply 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 is a logging limit, not a delivery limit, but it will make large payloads hard to debug.
Cancellation has its own trap. 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, so you do not cancel the wrong run.
What you take away is simple. 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 identical summaries hide different required fields.
Read the original: https://apis.io/2026/11/10/knock-workflow-triggers-api-is-a-second-door-to-the-same-trigger-with-stricter-rules/