Automations

From outside Cheqq you can read your automations, build new ones, change them, run them and answer them when they wait for you. An assistant connected over MCP can do all of it; the REST API covers everything except building a new automation step by step.

Build an automation with an assistant

Ask in your own words: "Every weekday at 8am, find yesterday's new leads, write each one a short intro email and wait for my approval before sending." The assistant builds it the way Cheqq's own agent does:

1. It starts a draft (cheqq_create_workflow_draft), or opens a saved automation for editing (cheqq_edit_workflow).
2. It adds steps and triggers one at a time: AI, code, API, email, notification, wait, branch, loop and more, plus steps built from your connected apps and your Wapps' record actions (cheqq_list_workflow_actions, then cheqq_add_workflow_action_step).
3. It checks the draft (cheqq_validate_workflow_draft) and can test it (cheqq_test_workflow_draft), which runs AI and read steps for real and simulates anything that sends or writes.
4. It finalizes the draft (cheqq_finalize_workflow_draft) and saves it (cheqq_save_workflow_draft), or throws it away (cheqq_discard_workflow_draft). A new automation is saved switched on; saving changes to a paused one keeps it paused.

This needs workflows:write, plus workflows:read to look around and workflows:run to test.

One draft at a time

Each API key, and each connected app, holds one automation draft at a time. Save or discard it before starting another. While a draft is open, replacing an automation's definition is refused with 409 WORKFLOW_DRAFT_CONFLICT (its details include the open draft's id).

Drafts made by one key or app are separate from your drafts in Cheqq and from those of your other keys, so two assistants never edit the same draft.

Replace a whole definition

A script that keeps automations in version control can send the whole definition at once:

curl -X PUT https://cheqq.ai/api/platform/v1/workflows/WORKFLOW_ID/definition \
  -H "Authorization: Bearer $CHEQQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d @weekly-report.json

The body takes definition (as GET /workflows/{workflowId} describes it), and optionally triggers (every trigger; leave it out to keep the saved ones), name, description and expectedUpdatedAt.

• It's checked first; nothing is saved if it doesn't hold together.
• The previous version stays in the automation's history, where you can restore it.
• Send expectedUpdatedAt with the updatedAt you read, and the write is refused with 409 WORKFLOW_CHANGED if someone changed the automation since.

Run an automation

curl -X POST https://cheqq.ai/api/platform/v1/workflows/WORKFLOW_ID/runs \
  -H "Authorization: Bearer $CHEQQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "execute", "wait": true, "timeoutMs": 60000 }'

input passes values to the automation's manual trigger. Real and test runs count toward your workspace's monthly step runs. An automation that's switched off can still have test and dry runs; a real run needs it on.

With wait, the answer comes when the run finishes or stops at an approval, up to timeoutMs (30 seconds by default, 60 at most). settled says whether it got there in time; if not, follow it with GET /runs/{runId}. Without wait, you get the runId straight away.

POST /runs/{runId}/cancel stops a run. Whatever it already did stays done.

Answer a run that waits

A run that reaches a Wait for approval step waits for the people it asks. GET /runs/{runId} shows who it asked and, in approval.canAnswer, whether you're one of them.

curl -X POST https://cheqq.ai/api/platform/v1/runs/RUN_ID/respond \
  -H "Authorization: Bearer $CHEQQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "approved": true }'

• Approve and the run carries on, as the automation's owner, exactly as if they'd approved it in Cheqq.
• Decline ("approved": false) and the run stops.
• Only the people an approval asks can answer it. Anyone else gets 403 NOT_YOUR_DECISION, whatever their key's scopes.
• "stopAsking": true with an approval also lets the automation run on its own from then on.
• A step that asked for more than a yes or no takes its answer in resumeData.

Answering needs workflows:approve, which a key only has if you ticked it: workflows:run starts and stops runs but can't answer them, so an assistant can't approve its own automation.

What can't be done from outside yet

• Creating an automation over REST. Build new ones over MCP or in Cheqq, then replace their definition over REST.
• Creating a new webhook address or email address for a trigger. Make them in Cheqq; an assistant can then build the rest of the automation around them.