> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claw-link.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer API

> Call ClawLink's integrations directly over HTTPS — the same runtime that powers the OpenClaw plugin, Hermes, the CLI, and the MCP server.

The ClawLink Developer API lets you run actions on your connected apps (Gmail, Slack,
Instagram, Notion, and 80+ more) with plain HTTP requests. It is the same execution
runtime the OpenClaw plugin and the MCP/CLI surfaces call — so anything an agent can do
through ClawLink, you can do directly with `curl` or any HTTP client.

**Base URL**

```
https://claw-link.dev
```

All endpoints are JSON over HTTPS and authenticate with a `cllk_live_` API key.

<Note>
  You only need this API if you are building your own integration or script. If you use
  OpenClaw, Hermes, the CLI (`@useclawlink/cli`), or any MCP client, use those surfaces
  instead — they wrap this API and handle pairing, discovery, and retries for you. See
  [Quick Start](/quickstart).
</Note>

## The mental model

ClawLink models everything as **integrations → actions → executions**:

<CardGroup cols={3}>
  <Card title="Integration" icon="plug">
    A connected app, identified by an `integration_id` (its slug), e.g. `gmail`,
    `slack`, `instagram`. You connect apps once in the dashboard.
  </Card>

  <Card title="Action" icon="bolt">
    Something an integration can do, identified by an `action_id`, e.g. `send_email`,
    `send_message`, `post_ig_user_media`.
  </Card>

  <Card title="Execution" icon="play">
    One run of an action with a specific `input`. You `POST` an execution and get back a
    normalized result.
  </Card>
</CardGroup>

Connecting an app is a **hosted, browser-based flow** done from the dashboard
(**Connections → Add connection**) — there is no API to submit OAuth credentials. Once an
app is connected, every execution below works against it.

## Your first request

Verify your API key and see who it belongs to:

```bash theme={null}
curl https://claw-link.dev/api/agent/whoami \
  -H "Authorization: Bearer cllk_live_YOUR_KEY"
```

```json theme={null}
{
  "user_id": "usr_123",
  "workspace_id": "usr_123",
  "workspace_name": "you@example.com",
  "environment": "production",
  "region": "global",
  "capabilities": { "can_execute": true, "can_begin_connection": true }
}
```

A `200` with this body means your key is valid. A `401 {"error":"Unauthorized"}` means the
key is missing or wrong — see [Authentication](/api/authentication).

## Run an action

Send a Gmail message in one call. Write actions require `confirm: true`:

```bash theme={null}
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": ["sarah@example.com"],
      "subject": "Hello from the API",
      "body": "Sent directly through ClawLink."
    },
    "confirm": true
  }'
```

Full request/response details, the `confirm` field, and runnable examples for Slack and
Instagram are in [Executing actions](/api/executions).

## What's in this section

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    API keys, the two accepted auth headers, and how to verify a key.
  </Card>

  <Card title="Executing actions" icon="bolt" href="/api/executions">
    `POST /api/executions`, the `confirm` field, discovering action IDs and input
    schemas, plus curl for Gmail, Slack, and Instagram.
  </Card>

  <Card title="File uploads" icon="paperclip" href="/api/file-uploads">
    Attaching images and documents — public URLs, the file-uploadable shape, and the
    base64 envelope for local bytes.
  </Card>

  <Card title="Multi-step flows" icon="diagram-project" href="/api/flows">
    Start, poll, approve, resume, and cancel server-run multi-step automations.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api/errors">
    The error envelopes, HTTP status codes, the full error-code list, and how to recover.
  </Card>

  <Card title="Discovery" icon="magnifying-glass" href="/api/executions#discovering-actions">
    List integrations and actions, and fetch an action's exact input schema.
  </Card>
</CardGroup>

## Conventions

* **Transport** — JSON request and response bodies over HTTPS. Send
  `Content-Type: application/json` on every `POST`.
* **Auth** — every endpoint requires a `cllk_live_` key (see
  [Authentication](/api/authentication)). Unauthenticated requests get `401`.
* **Scope** — a key acts as one ClawLink user. Executions run against that user's
  connections.
* **Rate limits** — providers (Gmail, Slack, etc.) enforce their own rate limits;
  ClawLink surfaces them as `rate_limited` / HTTP `429`. Honor `Retry-After` where present.