Executing actions

An execution runs one action on one of your connected apps. The recommended endpoint is POST /api/executions, which uses the canonical integration_id + action_id + input model.

`POST /api/executions`

string

required

The integration slug, e.g. gmail, slack, instagram. See discovering actions.

string

required

The action to run, e.g. send_email. This is the tool name with the integration prefix removed (gmail_send_email → send_email). The full tool name (gmail_send_email) also works.

object

required

The action’s arguments. Field names are specific to each action — fetch them with GET /api/actions/{integration_id}/{action_id}.

boolean

default:"false"

Required (true) for any write or destructive action. See The confirm field.

string

Optional client-supplied key to safely retry a request without running the action twice.

POST /api/executions runs against your default connection for the integration. If you have multiple connections for the same app and need to target a specific one, use the tool endpoint with connectionId.

Response

The response is a normalized execution summary. status is the field to branch on.

string

succeeded, blocked, or failed.

string | null

Stable ID of the run. null when the action was blocked before running (e.g. missing confirmation). Pass to GET /api/executions/{id}.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

any

The provider’s result payload. Present on success.

object

{ title, summary } — a short human-readable description of the outcome.

string

Present when blocked or failed. See Errors.

string

Human-readable error message (on blocked / failed).

string

Actionable guidance for recovering from a failure, when available.

object

e.g. { "tool": "clawlink.connect_app", "input": { "integration_id": "gmail" } } when the app needs connecting or re-authing.

HTTP status: 200 succeeded · 409 blocked · 500 failed. A malformed request (missing integration_id/action_id/input) returns 400.

{
  "execution_id": "f3c1…",
  "status": "succeeded",
  "integration_id": "gmail",
  "action_id": "send_email",
  "started_at": "2026-06-28T10:00:00.000Z",
  "finished_at": "2026-06-28T10:00:01.200Z",
  "output": { "id": "1990…", "threadId": "1990…", "labelIds": ["SENT"] },
  "display": { "title": "gmail_send_email succeeded", "summary": "Executed gmail_send_email successfully." }
}

{
  "execution_id": null,
  "status": "blocked",
  "integration_id": "gmail",
  "action_id": "send_email",
  "started_at": "2026-06-28T10:00:00.000Z",
  "finished_at": "2026-06-28T10:00:00.010Z",
  "display": { "title": "Execution blocked", "summary": "gmail_send_email requires explicit confirmation before execution." },
  "error_code": "policy_blocked",
  "message": "gmail_send_email requires explicit confirmation before execution."
}

{
  "execution_id": "a91b…",
  "status": "failed",
  "integration_id": "gmail",
  "action_id": "send_email",
  "started_at": "2026-06-28T10:00:00.000Z",
  "finished_at": "2026-06-28T10:00:00.800Z",
  "display": { "title": "Execution failed", "summary": "…" },
  "error_code": "execution_failed",
  "message": "…"
}

The confirm field

Read-only actions run immediately. Write and destructive actions require confirm: true — this is a deliberate safety gate so an agent can’t send an email or delete a record without an explicit go-ahead. If you omit confirm (or set it false) on a write action, the execution is blocked before it runs:

status is "blocked", execution_id is null
error_code is "policy_blocked"
HTTP status is 409

To proceed, repeat the request with confirm: true.

Not sure if an action is a write? Fetch it with GET /api/actions/{integration_id}/{action_id} and check side_effect_level (read / write / delete / admin) and requires_confirmation.

Examples

Field names below come from each action’s schema. Always confirm them with GET /api/actions/{integration_id}/{action_id} before going to production — schemas can change.

Gmail
Slack
Instagram

Send an email (gmail · send_email). user_id must be the literal string "me".

curl -X POST https://claw-link.dev/api/executions \
  -H "Authorization: Bearer cllk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "gmail",
    "action_id": "send_email",
    "input": {
      "user_id": "me",
      "to": ["[email protected]"],
      "subject": "Hello from the API",
      "body": "Sent directly through ClawLink.",
      "is_html": false
    },
    "confirm": true
  }'

Post a message to a channel (slack · send_message). Provide at least one of text, markdown_text, or blocks.

curl -X POST https://claw-link.dev/api/executions \
  -H "Authorization: Bearer cllk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "slack",
    "action_id": "send_message",
    "input": {
      "channel": "#general",
      "text": "Deploy finished :rocket:"
    },
    "confirm": true
  }'

Publishing a photo is a two-step action. First create a media container with a public image URL (instagram · post_ig_user_media), then publish the returned creation_id (post_ig_user_media_publish).

# 1. Create the media container
curl -X POST https://claw-link.dev/api/executions \
  -H "Authorization: Bearer cllk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "instagram",
    "action_id": "post_ig_user_media",
    "input": {
      "image_url": "https://example.com/photo.jpg",
      "caption": "Posted via ClawLink"
    },
    "confirm": true
  }'
# → output contains the new container id, e.g. { "id": "1789…" }

# 2. Publish it
curl -X POST https://claw-link.dev/api/executions \
  -H "Authorization: Bearer cllk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "instagram",
    "action_id": "post_ig_user_media_publish",
    "input": { "creation_id": "1789…" },
    "confirm": true
  }'

image_url can be almost any public URL — ClawLink fetches and re-hosts the bytes for Instagram. See File uploads for the rules and for sending local files.

Discovering actions

You don’t have to hard-code action IDs or guess input fields — the catalog is queryable.

List integrations

curl "https://claw-link.dev/api/integrations?connected_only=true" \
  -H "Authorization: Bearer cllk_live_YOUR_KEY"

Returns { items, page, page_size, total }. Each item includes integration_id, name, connected, connection_state, and capabilities (the action IDs it supports). Query params: query, category, connected_only, supports_action, page, page_size.

List an integration’s actions

curl "https://claw-link.dev/api/actions?integration_id=gmail" \
  -H "Authorization: Bearer cllk_live_YOUR_KEY"

Returns { integration_id, items: [...] } where each item has action_id, title, description, and side_effect_level. Add &intent=send%20an%20email to rank by intent.

Get an action schema

This is how you find the exact input field names for an action:

curl "https://claw-link.dev/api/actions/gmail/send_email" \
  -H "Authorization: Bearer cllk_live_YOUR_KEY"

Returns the action detail, including input_schema (full JSON Schema), input_summary.required / input_summary.optional, requires_confirmation, side_effect_level, examples, and preconditions.

Search the whole catalog

curl "https://claw-link.dev/api/search?query=send%20message&connected_only=true" \
  -H "Authorization: Bearer cllk_live_YOUR_KEY"

Returns { items: [{ kind, integration_id, action_id, title, summary, connected, connection_state }] }.

Fetch a past execution

curl "https://claw-link.dev/api/executions/EXECUTION_ID" \
  -H "Authorization: Bearer cllk_live_YOUR_KEY"

Returns the same execution-summary shape with the stored output.

Alternative: tool-name endpoint

POST /api/tools/{tool_name}/execute is the lower-level endpoint the OpenClaw plugin itself uses. Reach for it when you need to target a specific connection or attach local file bytes (see File uploads). It is tool-name-centric — use the full tool name (e.g. gmail_send_email) in the path.

Two differences from /api/executions that bite people:

The confirmation field is confirmed (not confirm).
Omitting it on a write returns HTTP 412 with error.code: "confirmation_required" (the canonical endpoint returns 409).

curl -X POST https://claw-link.dev/api/tools/gmail_send_email/execute \
  -H "Authorization: Bearer cllk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "user_id": "me",
      "to": ["[email protected]"],
      "subject": "Hello",
      "body": "Sent via the tool endpoint."
    },
    "connectionId": 42,
    "confirmed": true
  }'

Request fields:

object

The action arguments. If omitted, top-level keys (other than connectionId, confirmed, files) are treated as the arguments.

number | string

Target a specific connection when you have more than one for the app. Omit to use the default.

boolean

default:"false"

Confirmation gate for write actions (note the -ed spelling).

array

Base64 file attachments. See File uploads.

The response carries the raw execution payload (ok, data/result, error, meta) plus a canonical object with the same execution-summary shape as /api/executions. The error envelope is documented in Errors.

Get Started

Dashboard

Developer API

Integrations

Guides

Help

Executing actions

`POST /api/executions`

Response

The confirm field

Examples

Discovering actions

List integrations

List an integration’s actions

Get an action schema

Search the whole catalog

Fetch a past execution

Alternative: tool-name endpoint

​POST /api/executions

​Response

​The confirm field

​Examples

​Discovering actions

​List integrations

​List an integration’s actions

​Get an action schema

​Search the whole catalog

​Fetch a past execution

​Alternative: tool-name endpoint

`POST /api/executions`

Response

The confirm field

Examples

Discovering actions

List integrations

List an integration’s actions

Get an action schema

Search the whole catalog

Fetch a past execution

Alternative: tool-name endpoint