Checks

A check is a named assertion about a task — "tests pass", "reviewed", "deployed". You define the checks a space uses in its registry, and each task carries a result for a check: pending, passed, or failed. A check rule ties a check to a stage, either creating a pending result on entry or gating entry until the check passes.

See Authentication for the role each level needs. Replace https://cadence.example.com with your instance's address.

The check registry

GET/POST /api/v1/spaces/:space_key/checks, PATCH/DELETE .../checks/:code; MCP checks_registry_list, checks_registry_create, checks_registry_update, checks_registry_delete; the space settings Checks section. Every one of these needs admin — including listing the registry.

A registry entry has a code and an optional description. The code must be lowercase letters, digits, and underscores, starting with a letter — for example tests_pass. It is immutable once created; an update only changes the description.

curl -X POST https://cadence.example.com/api/v1/spaces/OPS/checks \
  -H "Authorization: Bearer smc_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "code": "tests_pass", "description": "The test suite is green" }'

Updating over the API rejects any field other than description with 422 and unpermitted_fields. Deleting a check that a rule or a result still references is refused with check is referenced by a rule or result and cannot be deleted — remove those first.

Check results on a task

GET/POST /api/v1/tasks/:task_key/check_results; MCP checks_list, checks_set. Listing needs read; setting needs member.

Set a result by check_code and state, where state is pending, passed, or failed:

curl -X POST https://cadence.example.com/api/v1/tasks/OPS-42/check_results \
  -H "Authorization: Bearer smc_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "check_code": "tests_pass", "state": "passed" }'

A check_code that is not registered in the task's space is refused with unknown_check_code — over the API, no Check with that code is registered in the task's Space; over MCP, unknown check_code for the task's space.

Setting a check to passed is what satisfies a require check rule, letting the task move on. It is also what a sentinel rule reads to decide whether to advance the task on its own — so setting a check can trigger that evaluation. See What moves a task without a person.

Invalidate a result

The web interface can invalidate a check result — POST /spaces/:space_key/tasks/:id/invalidate_check — which resets it to pending. This needs member. There is no /api/v1 route or MCP tool for it; to reset a result elsewhere, set it back to pending with checks_set.