Actions

Actions are the tools Clu uses in the app, callable from code by a stable public name such as lists.rename, skills.run_on_list or sequences.enroll. Each runs through the same toolkit Clu uses, in your workspace, with your data and credit balance.

These endpoints are in the served OpenAPI spec but not in the SDKs yet. The CluGTM CLI wraps them as cleanlist actions list|run|confirm.

List actions

GET /actions

Returns the actions this credential can use, after the plan, connection and scope checks, plus the groups they fall in.

curl https://api.cleanlist.ai/api/v2/actions \
  -H "Authorization: Bearer clapi_your_api_key"

{
  "version": "5d2c...",
  "groups": [
    {
      "name": "lists",
      "title": "Lead lists",
      "summary": "Read, create, rename, import into, move and delete lead lists and their leads. 2 of its actions need lists:delete, which this credential doesn't hold, so they aren't listed.",
      "action_count": 6,
      "missing_scopes": ["lists:delete"]
    }
  ],
  "actions": [
    {
      "name": "lists.rename",
      "title": "Rename a list",
      "description": "...",
      "group": "lists",
      "effect": "write",
      "card": false,
      "scope": "lists:write",
      "input_schema": { "type": "object", "properties": { "...": {} }, "required": ["..."] }
    }
  ]
}

An action your plan doesn’t include, or one that needs a connection you haven’t made, isn’t listed. GET /actions is the source of truth; the tables below show what exists.

Groups and scopes

sequences:write and crm:write are opt-in scopes: every action in those groups that isn’t a read needs a key that opted into them. lists.delete and lists.delete_leads check lists:write and also need the lists:delete opt-in.

The actions

† Needs a key that opted into the group’s opt-in scope (lists:delete, sequences:write or crm:write). ‡ A person only: code can get the card but can’t confirm it (403 person_required).

Call an action

POST /actions/{name}

curl -X POST https://api.cleanlist.ai/api/v2/actions/lists.rename \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"list_id": "9c1f7e2a-...", "new_name": "Q4 ABM"}}'

Read each action’s argument names from its input_schema.

An action that runs answers with its result:

{
  "action": "lists.rename",
  "session_id": "0b8e6c1a-...",
  "kind": "result",
  "result": { "...": "..." },
  "card": null,
  "confirmed": null
}

A card action answers with kind: "card" and runs nothing:

{
  "action": "lists.delete",
  "session_id": "0b8e6c1a-...",
  "kind": "card",
  "result": null,
  "card": {
    "card_id": "5f2b9c0e7d4a4b1f8e6a3c2d1b0a9f8e",
    "title": "Delete a list",
    "summary": "... Confirming it adds the 0.2-credit action fee.",
    "credits_required": 0.2,
    "expires_at": "2026-11-12T15:10:00+00:00"
  },
  "confirmed": null
}

Show the card to a person: title, summary and credits_required say what will happen and what it costs. A card that names a lead list is refused with 404 list_not_found before it’s issued if the list isn’t in your workspace. Every issued card also sends an approval.needed event to your webhooks.

Reads stop after 60 seconds (504 action_timeout). A write runs to the end, so it’s never left half done.

Confirm a card

POST /actions/confirm

curl -X POST https://api.cleanlist.ai/api/v2/actions/confirm \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "5f2b9c0e7d4a4b1f8e6a3c2d1b0a9f8e", "session_id": "0b8e6c1a-..."}'

{ "card_id": "5f2b9c0e7d4a4b1f8e6a3c2d1b0a9f8e", "status": "done", "result": { "...": "..." } }

status is done or failed. A card runs exactly the arguments it was issued with, once:

• A card confirms only on the channel that issued it. A card from the CluGTM MCP can’t be confirmed with an API key, and the reverse (404 card_not_found).
• A card past its expires_at returns 410 card_expired. Call the action again.
• Confirming the same card again, for example after a dropped connection, returns its first result. If it’s still running you get 409 card_already_used; confirm again in a minute to read the result.

To issue and confirm in one call, send "commit": true on POST /actions/{name}. The response then has the card and, in confirmed, the same body POST /actions/confirm returns. The same rules apply.

Who can confirm what

From code, a key without the opt-in is refused before a card is issued, with 403 opt_in_scope_required and details.required_scope. The person ticks it on the key under Settings → API keys → Permissions (see Opt-in scopes).

Cost

Each call is metered like the same tool called from Clu, on its own usage receipt. A card’s credits_required is the work’s estimate plus the 0.2-credit action fee that confirming it charges, and its summary says so. If the balance can’t cover a call you get 402 insufficient_credits.

Errors

See Errors & Rate Limits for every code.

Related

• GTM Agents API
• Webhooks
• Authentication & scopes
• Lead Lists
• CluGTM CLI
• Connect CluGTM to Claude (MCP)