# Clad — Full Documentation

> Documentation for Clad: the in-app Support Chat widget SDK and the Clad GraphQL API.

Source: https://docs.useclad.ai

---

# Widget SDK

> Native, in-app support chat — embed the widget with knowledge base, AI answers, and live conversations.

---

## How it works

> Architecture overview: how the SDK, hosted widget iframe, and Widget API fit together.

URL: https://docs.useclad.ai/widget/how-it-works

Support Chat has three moving parts that work together:

1. **The SDK on your page.** You add a single `<script>` tag (see
   [Quickstart](#quickstart)) — there's nothing to bundle or install. The SDK
   exposes a typed, Promise‑based API and owns *identity* and *lifecycle*: who
   the current user is, and when the messenger boots, updates, or shuts down.

2. **The hosted widget UI.** The chat interface itself renders inside a
   **hosted iframe** served by Clad — not on your page. The SDK communicates
   with it over `postMessage`. Because the UI lives in an isolated iframe, your
   CSS can never collide with it and your page never gains access to the session
   token; the iframe acts as a security boundary.

3. **The Widget API and your support platform.** The widget talks to Clad's
   backend over HTTPS, plus a WebSocket for realtime updates. Messages a visitor
   sends become real conversations in your support inbox, and replies from your
   agents (or AI) stream back into the widget in real time.

In short: the SDK lives on your site and controls identity, the hosted iframe
renders the conversation, and Clad's backend routes everything into your
support platform — tickets, agents, and knowledge base.

Teams that live in Slack can also answer widget chats from Slack — each
conversation becomes a thread in a channel you pick, and replies in the
thread reach the visitor in the widget exactly like inbox replies. See
[Slack‑native support](#slack-native-support).

You reference each widget from your code with a `workspaceId` and `widgetId`.
Two things live in two different places:

- **Presentation and behavior live in your install code** — set the theme and
  brand via [`theme`](#theming-locale--z-index) and show/hide surfaces via
  [`features`](#feature-visibility-overrides-features) on your settings or
  `SupportChat.createChat`. This is what makes the widget match _your_ app, and
  it's the focus of the [Theming](#theming-locale--z-index) and
  [Brand & deploy](#brand--deploy-from-scratch) pages.
- **Identity, access, and intake live in the dashboard** — under **Settings →
  Integrations → Web Widget** you manage the widget's **name**, **allowed
  origins**, **JWT secret**, **knowledge base**, **ticket forms**, and
  **identity rules**. (Everything is also editable over the admin API for
  scripting.)

---

## Quickstart

> Add the widget with one script tag and start chatting in minutes.

URL: https://docs.useclad.ai/widget/quickstart

Paste this snippet just before `</body>`. It boots an **anonymous** session
automatically — visitors can start chatting immediately.

```html
<script>
  window.SupportChatSettings = {
    workspaceId: "{YOUR_WORKSPACE_ID}",
    widgetId: "{YOUR_WIDGET_ID}",
    region: "us",
  };
  (function (w, d) {
    w.SupportChat = w.SupportChat || function () {
      (w.SupportChat.q = w.SupportChat.q || []).push(arguments);
    };
    var s = d.createElement("script");
    s.async = true;
    s.src = "https://clad-server-production.up.railway.app/widget/v1/widget.js";
    d.head.appendChild(s);
  })(window, document);
</script>
```

> Find your `workspaceId` and `widgetId` in **Settings → Integrations → Web
> Widget**.

That's it — a launcher appears in the corner. To identify logged‑in users and
unlock per‑user history, continue to [Identity verification](#identity-verification-jwt).

<!--
<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">The launcher after install</p>
  <p class="img-ph__desc">A web page with the Support Chat <strong>launcher button</strong> in the bottom corner, right after adding the snippet — to show the immediate result of the Quickstart.</p>
</div>
-->

---

## Installation

> Add Support Chat with a single script tag. Configure regions and self-hosting.

URL: https://docs.useclad.ai/widget/installation

Support Chat installs with a single `<script>` tag — there's no package to add
and no build step. Drop the [Quickstart](#quickstart) snippet in just before your
closing `</body>` tag and you're done.

### Using the widget

After the script loads, the booted, typed instance is available as
`window.supportChat`. A legacy string API is also supported for quick,
imperative calls:

```js
SupportChat("open");
SupportChat("on", "unread:change", ({ payload }) => console.log(payload.count));
```

Commands invoked before the script finishes loading are queued and replayed once
it's ready, so it's safe to call the API at any time.

For full programmatic control — for example in a single‑page app where you want
to hold a reference to the instance — the loader also exposes a factory on the
global once it has loaded:

```js
const chat = SupportChat.createChat({
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
});

await chat.boot();
```

> Throughout these docs, `chat` refers to your Support Chat instance — either
> `window.supportChat` (created automatically from your settings) or one you
> create yourself with `SupportChat.createChat(...)`.

### Regions & self‑hosting

`region` selects the data‑residency endpoints. It defaults to `us`. Set it in
`window.SupportChatSettings` (or pass it to `SupportChat.createChat`).

| Region | Value |
|---|---|
| United States | `us` |
| European Union | `eu` |
| Australia | `au` |
| Custom / self‑hosted / staging | `custom` (also set `apiBase` + `widgetBase`) |

```js
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  region: "custom",
  apiBase: "https://support-api.example.com",
  widgetBase: "https://support-widget.example.com/v1",
};
```

---

## Brand & deploy

> A start-to-finish guide to shipping a fully branded widget: create, install, theme, choose surfaces, and go live.

URL: https://docs.useclad.ai/widget/brand-deploy

A start‑to‑finish guide to shipping a **fully branded** widget on your own site.
Prefer to let an AI agent do it for you? Use **[Vibestart](/builder)** to pick a
look, drop in your IDs, and copy a one‑shot prompt instead — it follows these
same steps. Each step below links to its reference section.

### 1. Create the widget (dashboard)

In **Settings → Integrations → Web Widget**, note your **Workspace ID**
(`ws_…`) and **Widget ID** (`wgt_…`), and add your site to the widget's
**allowed origins** (exact origins, or single‑level wildcards like
`https://*.acme.com`). See [Workspace & widget configuration](#workspace--widget-configuration).

### 2. Install the SDK

Add the [Quickstart](#quickstart) `<script>` snippet just before `</body>` — one
tag, no build step, no package manager. An **anonymous** session boots
automatically, so visitors can chat right away.

### 3. Brand it

All presentation lives in your **install code** (`theme`) — not the dashboard.
Set your palette, header, fonts, shape, and logo:

- **Colors & shape** → [Theming](#theming-locale--z-index) (`theme.colors`,
  `borderRadius`, `bubbleRadius`, `elevation`).
- **Header & home copy** (replace "Support", the home greeting/subtext, add a
  logo/banner, recolor) → [Header & branding](#header--branding). Text copy is
  set in code via [`content`](#configuration).
- **Fonts** (system stack or a loaded web font) → [Fonts](#fonts).
- **Icons & launcher** (custom launcher glyph/colors) →
  [Icons & iconography](#icons--iconography).
- **Pixel‑level control** of any element → [Custom CSS](#custom-css).

### 4. Choose what shows + how AI responds

- **Surfaces:** toggle the knowledge base, ticket forms, and conversation entry
  points per page with [`features`](#feature-visibility-overrides-features).
- **AI assistant:** turn the search bar into a grounded, multi‑turn AI chat
  (`features.aiAnswers`) → [AI assistant chat](#ai-assistant-chat).
- **Ticket forms:** define forms in the dashboard, then surface or open them from
  code → [Where ticket forms come from](#where-ticket-forms-come-from).

### 5. Go live

- **Identify logged‑in users** so chats carry their name/history →
  [Identity verification (JWT)](#identity-verification-jwt).
- **Pass context/tags/custom fields** for better routing →
  [Context, tags & custom fields](#context-tags--custom-fields).
- **Cookie consent**, if required → [Privacy & cookie consent](#privacy--cookie-consent).

### A fully branded example

Everything below is set once in `window.SupportChatSettings` (the same object the
Quickstart snippet defines), so the widget is branded on first paint:

```js
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",

  // Surfaces
  features: { knowledgeBase: true, aiAnswers: true, ticketForms: true },

  // Header text + launcher
  launcher: { position: "bottom-right", label: "Acme Support" },

  // Brand
  theme: {
    mode: "system",
    logoUrl: "https://acme.com/mark.svg",
    colors: {
      primary: "#4f46e5",
      headerBackground: "#0f172a",
      headerText: "#ffffff",
    },
    borderRadius: "lg",
    fontFamily: '"Plus Jakarta Sans", system-ui, sans-serif',
    customCss: `
      @import url("https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;600;700&display=swap");
      .sc-header { background: linear-gradient(120deg, #4f46e5, #9333ea); --sc-header-text: #fff; }
      .sc-iconbtn { color: #fff; }
    `,
  },
};
```

> Prefer to keep brand defaults out of every page's code? The same `theme`,
> `features`, and `launcher` settings can be stored on the widget config via the
> admin API; install‑code settings win per page.

---

## Configuration

> Every widget configuration option — workspace, region, theming, launcher, and more.

URL: https://docs.useclad.ai/widget/configuration

You configure a widget either by assigning `window.SupportChatSettings` before
the loader runs (the Quickstart snippet does exactly this) or by passing the same
options to `SupportChat.createChat(...)`:

```js
// Option 1 — set settings, let the loader auto‑boot:
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
};

// Option 2 — create an instance programmatically:
const chat = SupportChat.createChat({
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
});
```

| Option | Type | Default | Description |
|---|---|---|---|
| `workspaceId` | `string` | — | **Required.** Your workspace id (`ws_…`). |
| `widgetId` | `string` | — | Widget id (`wgt_…`). Optional only if the workspace has a default widget. |
| `region` | `"us" \| "eu" \| "au" \| "custom"` | `"us"` | Data‑residency endpoints. |
| `apiBase` | `string` | region default | API base URL (for `custom`/self‑host). |
| `widgetBase` | `string` | region default | Hosted widget UI base URL. |
| `autoBoot` | `boolean` | `true` | Auto‑boot an anonymous session on load. |
| `autorender` | `boolean` | `true` | Mount the floating widget automatically. Set `false` to mount it yourself with [`render()`](#render-modes). |
| `locale` | `string` | workspace default | BCP‑47 locale, e.g. `"en-US"`. |
| `theme` | `ThemeConfig` | workspace default | Initial theme overrides. See [Theming](#theming-locale--z-index). |
| `launcher` | `LauncherConfig` | workspace default | Launcher position/label/badge/icon. |
| `content` | `ContentConfig` | built‑in defaults | Header title + home greeting/subtitle copy. See [Header & branding](#header--branding). |
| `privacy` | `PrivacyConfig` | `{}` | Initial cookie‑consent level. |
| `features` | `FeatureOverrides` | workspace default | Show/hide in‑iframe surfaces from code. See below. |
| `debug` | `boolean` | `false` | Verbose console diagnostics. |

These options are read once when the session is created; network work happens on
[`boot()`](#the-session-lifecycle). Ongoing changes are made with the runtime
methods documented below (for example [`update()`](#the-session-lifecycle) and
`setTheme()`).

### Feature visibility overrides (`features`)

Each widget has server‑side feature flags (managed under **Settings →
Integrations → Web Widget**, or via the admin API). The `features` option lets
you override those **from your install code** for a given page/app — so you can
toggle surfaces without round‑tripping through the dashboard:

```js
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  features: {
    knowledgeBase: false,  // hide the "Find an answer" search
    ticketForms: true,     // show the "Quick requests" form cards
    conversations: true,   // show the message entry point + recent list
  },
};
```

| Key | Surface |
|---|---|
| `conversations` | "Send us a message" entry point + the conversation list (live chat + past conversations). |
| `knowledgeBase` | Knowledge base search on the home screen. |
| `ticketForms` | "Quick requests" ticket‑form cards on the home screen. |
| `aiAnswers` | AI answers / deflection (turns KB search into the [AI assistant chat](#ai-assistant-chat)). |
| `customLauncher` | Use a custom launcher in place of the default bubble. |

Semantics: a value of `false` **always hides** the surface; a value of `true`
shows it, but the data behind it stays gated server‑side, so a force‑enabled
surface only appears when the feature is also enabled on the widget config (e.g.
ticket forms must exist and be enabled to show). Leave a key unset to inherit the
dashboard setting. These are also accepted on `SupportChat.createChat({ features })`.

---

## The session lifecycle

> boot, identify, update, shutdown, and destroy — the full lifecycle of a chat session.

URL: https://docs.useclad.ai/widget/session-lifecycle

A Support Chat session moves through a predictable set of phases. After the
script loads, it goes from **`not_initialized`** to **`loading`** and then
**`ready`**. Calling [`boot()`](#bootoptions) transitions it through
**`booting`** into either an **`anonymous`** or an **`authenticated`** session,
depending on whether you supplied a user.

Calling [`shutdown()`](#shutdownoptions) ends the session (**`shutdown`**), and
[`destroy()`](#destroy) tears the widget down entirely (**`destroyed`**).

```
not_initialized → loading → ready → booting → anonymous | authenticated
        → shutdown → destroyed
```

You can read the current phase at any time via `chat.state` — it reflects the
**session / identity** lifecycle above.

> **Live connection status is reported separately, as an event — not via
> `chat.state`.** Transient realtime drops and recoveries surface through the
> [`connection:state`](#events) event (`connecting` / `connected` /
> `reconnecting` / `disconnected`), and are handled for you automatically.
> Subscribe to that event if you want to reflect online/offline status in your
> own UI; `chat.state` itself does not change for connection blips.

### `boot(options?)`

Creates or resumes a session. With no `user`, the session is **anonymous**.
With a `user`, you should supply a `tokenProvider` (see
[Identity verification](#identity-verification-jwt)).

Anonymous visitors appear to your support team under a stable, friendly
pseudonym (e.g. **"Amber Falcon"**) instead of a generic "Website visitor"
label, so agents can tell concurrent chats apart. When the visitor later
identifies (or submits an email through a ticket form), their real name and
email replace the pseudonym on the same contact.

```ts
await chat.boot({
  user: {
    id: currentUser.id,
    email: currentUser.email,
    name: currentUser.name,
  },
  company: {
    id: currentOrg.id,
    name: currentOrg.name,
    plan: currentOrg.plan,
  },
  tokenProvider: () =>
    fetch("/api/support-chat-token").then((r) => r.text()),
});
```

- Idempotent for the same identity.
- Calling `boot()` with a **different** identified user throws — call
  [`shutdown()`](#shutdownoptions) first, or use [`identify()`](#identifyoptions).

### `identify(options)`

Upgrades an anonymous session to an authenticated user (and merges anonymous
history when possible). See [Anonymous → authenticated upgrade](#anonymous--authenticated-upgrade).

### `update(options)`

Refreshes the **ephemeral page context** attached to future conversations and
messages (it behaves like [`setContext`](#context-tags--custom-fields)). Safe to
call on SPA route changes.

```ts
await chat.update({
  context: { currentPage: "billing", accountHealth: "red" },
});
```

> **Note:** `update()` currently applies only `context`. To change the
> **signed‑in user**, call [`identify()`](#identifyoptions) with a fresh token —
> passing `user` / `company` to `update()` does **not** propagate trait changes
> today.

### `shutdown(options?)`

Call on **logout**. Clears user‑specific state and closes the realtime
connection. Pass `{ clearStorage: true }` to also remove anonymous/session
identifiers — important on shared computers so a previous user's conversations
don't linger.

```ts
await chat.shutdown({ clearStorage: true });
```

### `destroy()`

Removes the iframe, listeners, and timers. Persistent storage is left intact
unless you previously called `shutdown({ clearStorage: true })`.

```ts
await chat.destroy();
```

---

## Identity verification (JWT)

> Securely identify logged-in users with short-lived, server-signed JWTs. Includes backend recipes.

URL: https://docs.useclad.ai/widget/identity-verification

Authenticated users must be verified with a **short‑lived JWT minted by your
backend** — never put secrets in the browser. The SDK calls your
`tokenProvider` on boot, before expiry, and after a `401`.

### 1. Get your widget's signing secret

In **Settings → Integrations → Web Widget**, copy the **JWT secret**. Store it
as a backend environment variable (e.g. `SUPPORT_CHAT_WIDGET_SECRET`). Treat it
like a password; rotate it from the same screen if leaked.

### 2. Expose a token endpoint on your backend

The endpoint returns a signed JWT (HS256) for the currently logged‑in user.

**Required claims:** `sub` (your stable user id), `widget_id`, `workspace_id`,
and `exp`. Recommended: `email`, `name`, `company_id`, `jti`.

```jsonc
{
  "iss": "your_backend",
  "aud": "clad_support_chat",
  "sub": "user_123",
  "email": "rachel@example.com",
  "name": "Rachel",
  "company_id": "org_456",
  "workspace_id": "{YOUR_WORKSPACE_ID}",
  "widget_id": "{YOUR_WIDGET_ID}",
  "iat": 1760000000,
  "exp": 1760000900,
  "jti": "a-unique-token-id"
}
```

<details>
<summary><b>Node.js (Express)</b></summary>

```ts
import jwt from "jsonwebtoken";

app.get("/api/support-chat-token", requireLogin, (req, res) => {
  const token = jwt.sign(
    {
      sub: req.user.id,
      email: req.user.email,
      name: req.user.name,
      company_id: req.user.orgId,
      workspace_id: "{YOUR_WORKSPACE_ID}",
      widget_id: "{YOUR_WIDGET_ID}",
    },
    process.env.SUPPORT_CHAT_WIDGET_SECRET,
    { expiresIn: "15m", audience: "clad_support_chat" }
  );
  res.type("text/plain").send(token);
});
```
</details>

<details>
<summary><b>Python (Flask)</b></summary>

```python
import jwt, time, os
from flask import Response

@app.get("/api/support-chat-token")
@login_required
def support_chat_token():
    now = int(time.time())
    token = jwt.encode({
        "sub": current_user.id,
        "email": current_user.email,
        "name": current_user.name,
        "company_id": current_user.org_id,
        "workspace_id": "{YOUR_WORKSPACE_ID}",
        "widget_id": "{YOUR_WIDGET_ID}",
        "iat": now, "exp": now + 900,
        "aud": "clad_support_chat",
    }, os.environ["SUPPORT_CHAT_WIDGET_SECRET"], algorithm="HS256")
    return Response(token, mimetype="text/plain")
```
</details>

<details>
<summary><b>Ruby (Rails)</b></summary>

```ruby
def support_chat_token
  payload = {
    sub: current_user.id, email: current_user.email, name: current_user.name,
    company_id: current_user.org_id, workspace_id: "{YOUR_WORKSPACE_ID}", widget_id: "{YOUR_WIDGET_ID}",
    iat: Time.now.to_i, exp: 15.minutes.from_now.to_i, aud: "clad_support_chat"
  }
  render plain: JWT.encode(payload, ENV["SUPPORT_CHAT_WIDGET_SECRET"], "HS256")
end
```
</details>

<details>
<summary><b>Go</b></summary>

```go
claims := jwt.MapClaims{
    "sub": user.ID, "email": user.Email, "name": user.Name,
    "company_id": user.OrgID, "workspace_id": "{YOUR_WORKSPACE_ID}", "widget_id": "{YOUR_WIDGET_ID}",
    "iat": time.Now().Unix(), "exp": time.Now().Add(15 * time.Minute).Unix(),
    "aud": "clad_support_chat",
}
tok, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).
    SignedString([]byte(os.Getenv("SUPPORT_CHAT_WIDGET_SECRET")))
w.Write([]byte(tok))
```
</details>

### 3. Wire it into the SDK

```ts
await chat.boot({
  user: { id: user.id, email: user.email, name: user.name },
  tokenProvider: () => fetch("/api/support-chat-token").then((r) => r.text()),
});
```

### Token lifecycle

- The SDK requests a token on boot, refreshes it **before** expiry, and again
  after any `401`.
- Keep tokens short‑lived (≤ 15 minutes). The widget handles refresh
  transparently; expiry surfaces as an [`auth:expired`](#events) event.
- The platform verifies signature, expiration, audience, and that
  `workspace_id` / `widget_id` match the widget — and that the request origin
  is allow‑listed.

---

## Anonymous → authenticated

> Upgrade an anonymous session to an identified user and merge conversation history.

URL: https://docs.useclad.ai/widget/identify-upgrade

If a visitor chats anonymously and later logs in, call `identify()` to upgrade
the session in place. Anonymous conversation history is merged into the
identified user when safe; if the user already had conversations, those appear
after the upgrade.

```ts
await chat.identify({
  user: { id: "user_123", email: "rachel@example.com", name: "Rachel" },
  company: { id: "org_456", name: "Acme Inc" },
  tokenProvider: fetchSupportChatToken,
});
```

---

## Visibility & launchers

> Open, close, show, and hide the messenger — or wire up your own custom launcher button.

URL: https://docs.useclad.ai/widget/visibility-launchers

All visibility methods are safe to call before or after boot; calls made before
the widget is ready are queued.

```ts
await chat.open();   // open the messenger panel
await chat.close();  // close the panel (launcher stays visible)

chat.show();         // show all widget surfaces
chat.hide();         // hide all widget surfaces

chat.showLauncher();
chat.hideLauncher();
chat.setLauncherVisible(false);
```

### Custom launcher

Hide the built‑in launcher and trigger the widget from your own button. Unread
counts are still delivered via events.

```ts
const chat = SupportChat.createChat({
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  launcher: { showUnreadBadge: false },
});

chat.hideLauncher();

document.querySelector("#support-button")
  ?.addEventListener("click", () => chat.open());

const off = chat.on("unread:change", ({ payload }) => {
  document.querySelector("#support-badge")!.textContent = String(payload.count);
});
```

---

## Render modes

> Floating, embedded, and custom-launcher render modes for the chat widget.

URL: https://docs.useclad.ai/widget/render-modes

```ts
await chat.render({ mode: "floating" });                         // default

await chat.render({ mode: "embedded", target: "#support-panel" }); // inline

await chat.render({ mode: "custom-launcher", launcher: false });   // your launcher
```

| Mode | Behavior |
|---|---|
| `floating` | Default. Floating launcher + panel anchored to a corner. |
| `embedded` | Renders the widget inside a container you provide (`target`). |
| `custom-launcher` | Hides our launcher; you control open/close. Events still fire. |

For **full manual control** of when and where the widget mounts, set
[`autorender: false`](#configuration) and then call `render(...)` yourself —
nothing is mounted until you do.

<!--
<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">Floating vs. embedded</p>
  <p class="img-ph__desc">A side‑by‑side (or two stacked shots) showing the <strong>floating</strong> widget anchored to a corner and the <strong>embedded</strong> widget rendered inline inside a page container, so readers can see the difference between render modes.</p>
</div>
-->

---

## Theming, locale & z-index

> Match the widget to your brand with theme colors, fonts, locale, and z-index control.

URL: https://docs.useclad.ai/widget/theming

Theming is **code‑owned**: you brand the widget entirely from your install code,
not the dashboard. Out of the box the widget renders a **monochrome default** — a
matte near‑black accent on a matte off‑white surface that automatically inverts
to off‑white‑on‑near‑black for dark host pages (when `mode: "system"`). Every
surface is driven by a `--sc-*` design token, so a few values rebrand the
launcher, header, buttons, message bubbles, inputs, and links consistently.

Set the theme initially in `window.SupportChatSettings` (or
`SupportChat.createChat({ theme })`) for the first paint, and/or at runtime via
`chat.setTheme(...)`. Omit `colors` entirely to keep the monochrome default.

```ts
chat.setTheme({
  mode: "system",                // "light" | "dark" | "system" (default: system)
  logoUrl: "https://acme.com/mark.svg", // shown in the widget header (omit → no logo, title only)
  colors: {
    // Every key is optional — anything you omit falls back to the monochrome
    // default token. Example brand palette:
    primary: "#4f46e5",          // accent: buttons, links, focus, launcher, user bubble
    primaryText: "#ffffff",      // text/icon rendered on top of `primary`
    background: "#ffffff",       // panel + header base
    surface: "#f6f7f9",          // conversation/content background
    text: "#1b1d24",
    mutedText: "#6a7282",
    border: "#e8eaf0",
    headerBackground: "#ffffff", // defaults to `background`
    headerText: "#1b1d24",       // defaults to `text`
    launcher: "#4f46e5",         // defaults to `primary`
    launcherIcon: "#ffffff",     // defaults to `primaryText`
    userMessage: "#4f46e5",
    userMessageText: "#ffffff",  // defaults to `primaryText`
    agentMessage: "#ffffff",
    agentMessageText: "#1b1d24", // defaults to `text`
    danger: "#e5484d",
  },
  borderRadius: "lg",            // none | sm | md | lg | xl | <css length> — panel + launcher
  bubbleRadius: "lg",            // none | sm | md | lg | xl | full | <css length> — message bubbles
  elevation: "lg",               // none | sm | md | lg | xl — panel shadow depth
  fontFamily: "Inter, system-ui, sans-serif",
});

chat.setLocale("en-US");
chat.setZIndex(999999);
```

`setTheme` merges with the current theme (including a deep merge of `colors`), so
you can update tokens incrementally (e.g. flip `mode` or one color) without
re‑specifying the whole object.

> A single `primary` gives you a coherent monochrome‑style look in your brand
> color (it drives the launcher, buttons, links, and outbound bubbles). Set the
> neutral tokens (`background`, `surface`, `text`, `border`) too for a fully
> custom palette.

<!--
<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">A themed widget</p>
  <p class="img-ph__desc">The widget styled to match a brand — custom primary color, font, and rounded corners — ideally next to the default monochrome look, to show what theming achieves.</p>
</div>
-->

### Custom CSS

For pixel‑level control beyond the tokens, inject CSS into the (isolated) widget
iframe via `theme.customCss`. Target the stable `.sc-*` class contract or
override any `--sc-*` custom property. The CSS is applied as a stylesheet
**inside** the sandboxed UI — it can restyle any element but cannot execute
scripts.

```ts
chat.setTheme({
  customCss: `
    .sc-header { background: linear-gradient(90deg, #4f46e5, #7c3aed); --sc-header-text: #fff; }
    .sc-launcher { box-shadow: 0 10px 30px rgba(79,70,229,.45); }
    .sc-msg.in { border-radius: 14px; }
  `,
});
```

> Note: the **"Powered by Clad"** footer is a permanent part of the widget and is
> not removable via theme or custom CSS.

### Header & branding

The header bar is the most‑branded surface. Its anatomy on the home screen is:

```
┌───────────────────────────────────────────────┐
│  [logo?]  Title                            ✕   │   ← .sc-header
└───────────────────────────────────────────────┘
```

By default the title reads **"Support"** and no logo is shown. You can change all
of this:

**1 — Replace the "Support" text.** Set it from your install code with
`content.headerTitle`. The title is, in priority order, `content.headerTitle` →
the legacy `launcher.label` → `"Support"`:

```js
SupportChat.createChat({ workspaceId: "{YOUR_WORKSPACE_ID}", widgetId: "{YOUR_WIDGET_ID}", content: { headerTitle: "Acme Support" } });
```

This copy is configured in code — not the dashboard — so there's a single source
of truth and no risk of conflicting edits. (The widget's **Name** in the
dashboard is just an internal label; visitors never see it.)

**2 — Add a logo next to the title.** Set `theme.logoUrl` to an image URL; it
renders as a small rounded mark to the left of the title (omit it for a clean
title‑only header):

```js
SupportChat.createChat({
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  theme: { logoUrl: "https://acme.com/mark.svg" },
  launcher: { label: "Acme Support" },
});
```

**3 — Recolor the header.** Two tokens control it (both default to the panel
`background` / `text`):

```ts
chat.setTheme({ colors: { headerBackground: "#0f172a", headerText: "#ffffff" } });
```

**4 — Go further: banners, gradients, custom type, a bigger logo.** Anything
beyond a solid color is done with [`customCss`](#custom-css) targeting the
header's stable classes. Because `customCss` is a *stylesheet* (it styles
existing elements; it can't inject new DOM), use real elements (the logo image,
the title) plus backgrounds and `::before`/`::after` for decoration:

```ts
chat.setTheme({
  // A gradient (or image) banner with white text, taller header, larger logo.
  customCss: `
    .sc-header {
      background: linear-gradient(120deg, #4f46e5, #9333ea);
      /* or a hosted banner image: */
      /* background: url("https://acme.com/widget-banner.png") center/cover; */
      --sc-header-text: #fff;
      min-height: 76px;
    }
    .sc-brand-mark { width: 36px; height: 36px; border-radius: 10px; background: #fff; }
    .sc-brand-mark img { object-fit: contain; padding: 4px; }
    .sc-header h1 { font-size: 17px; font-weight: 700; }
    .sc-iconbtn { color: #fff; }
  `,
});
```

**5 — Change the home greeting.** The home screen opens with a large greeting
(**"Hi there 👋"**) and a line of subtext (**"How can we help you today?"**).
Override the header title and both home lines from your install code with the
`content` option:

```js
SupportChat.createChat({
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  content: {
    headerTitle: "Acme Support",
    greeting: "Welcome back 👋",
    subtitle: "We usually reply in a few minutes.",
  },
});
```

Each `content` field is optional and, when unset, falls back to the built‑in
default — so you can override only the lines you care about.

| You want… | How |
|---|---|
| Different header text than "Support" | `content.headerTitle` |
| Different home greeting / subtext | `content.greeting` / `content.subtitle` |
| A logo in the header | `theme.logoUrl` |
| Solid header colors | `colors.headerBackground` / `colors.headerText` |
| A gradient / image **banner** | `customCss` → `.sc-header { background: … }` |
| Bigger / differently‑shaped logo | `customCss` → `.sc-brand-mark` / `.sc-brand-mark img` |
| Header font / weight | `theme.fontFamily` (whole widget) or `customCss` → `.sc-header h1` |

**What is fixed:** the **close** button (and the contextual **back** button on
sub‑pages) always render, and the **"Powered by Clad"** footer is permanent and
cannot be removed via theme or `customCss`. There is no separate header
*subtitle* field — add decorative copy with a `.sc-header::after { content: … }`
rule if you need it.

### Fonts

`theme.fontFamily` sets the `--sc-font` token used across the whole widget. Pass
any CSS font stack; the widget inherits whatever you list:

```ts
chat.setTheme({ fontFamily: '"Plus Jakarta Sans", system-ui, sans-serif' });
```

Because the UI runs in an isolated iframe, a **custom web font must be loaded
inside the iframe** — list a websafe/system stack, or load the font file via
`customCss`:

```ts
chat.setTheme({
  customCss: `
    @import url("https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;600;700&display=swap");
  `,
  fontFamily: '"Plus Jakarta Sans", system-ui, sans-serif',
});
```

### Icons & iconography

- **Launcher icon:** the floating bubble shows a chat glyph by default. Swap it
  for your own mark with `launcher.iconUrl`, or recolor the default with
  `colors.launcher` (bubble) and `colors.launcherIcon` (glyph). For a fully
  custom launcher element of your own, see [Custom launcher](#custom-launcher)
  (`features.customLauncher` + render mode `custom-launcher`).
- **In‑widget icons** (search, send, the AI ✨ mark, chevrons) are line‑art SVGs
  that inherit `currentColor`, so they follow your text/primary tokens
  automatically. To restyle or replace one, target it via `customCss` (e.g.
  `.sc-launcher svg { … }`, `.sc-search-icon svg { … }`).

### Customizing which surfaces appear

Beyond colors, you control **which parts of the UI show** from code via the
[`features`](#feature-visibility-overrides-features) option — hide the knowledge
base search, ticket forms, or the conversation entry points per page. Combine
that with [render modes](#render-modes) (floating, embedded, or a custom
launcher) and the `launcher` options (position, label, icon) to fit the widget
into your app.

```js
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  theme: { colors: { primary: "#0f766e" }, borderRadius: "md" }, // brand look
  features: { ticketForms: false },                              // hide a surface
  launcher: { position: "bottom-left", label: "Help" },          // launcher
};
```

---

## Conversations

> Start, list, show, and send messages in conversations with idempotent retries.

URL: https://docs.useclad.ai/widget/conversations

### Start a conversation

```ts
const conversation = await chat.startConversation({
  subject: "Billing issue",
  message: "I need help understanding this invoice.",
  tags: ["billing", "high-value-account"],
  customFields: { plan: "enterprise", mrr: 25000 },
  metadata: { invoiceId: "inv_123", source: "billing_page" },
});
```

If `message` is omitted, the composer opens for the user to type. `tags` and
`customFields` map to your platform's tags/fields where configured.

### List, show, send, mark read

```ts
const page = await chat.listConversations({ limit: 20 });      // Page<Conversation>
await chat.showConversation(conversation.id);

const message = await chat.sendMessage({
  conversationId: conversation.id,
  text: "Here is more context.",
  clientMessageId: crypto.randomUUID(),   // optional, for idempotent retries
});

await chat.markConversationRead(conversation.id);
```

- `listConversations` returns only the current user's conversations (anonymous
  users see only their browser session's conversations).
- `clientMessageId` makes retries idempotent — the same id never creates a
  duplicate message.
- Agent replies display with the agent's **first name and avatar** (with an
  initials fallback), regardless of whether the agent answered from the inbox
  or from Slack.

### Prefill a new message

```ts
await chat.showNewMessage({
  prefill: "I ran into an error while upgrading my plan.",
  metadata: { source: "upgrade_error_modal" },
});
```

Opens the composer pre‑filled (it does **not** send automatically).

---

## Slack-native support

> Answer widget conversations from Slack threads — replies, close/reopen, and follow-up alerts, no dashboard required.

URL: https://docs.useclad.ai/widget/slack

If your team lives in Slack, agents can answer widget conversations without
opening the dashboard. In **Settings → Web Widget → Answer widget chats in
Slack**, connect your Slack workspace and pick a channel (internal channels
only — channels shared externally via Slack Connect are never offered). From
then on:

- **Each conversation becomes a Slack thread** in that channel, opened with a
  context card showing who the visitor is (verified identity and company, or
  their anonymous pseudonym).
- **Replies in the thread reach the visitor in the widget in real time** — the
  same realtime path as inbox replies, attributed to the agent by first name
  and avatar.
- **Close or reopen from Slack** with the card's button or a ✅ reaction;
  status changes fire the SDK's `conversation:resolved` /
  `conversation:updated` events like any other status change.
- **Follow‑up alerts:** if a visitor follows up and nobody has replied, the
  thread is surfaced to the channel after a configurable quiet period (or
  immediately, or never — your choice in the same settings section).

This is entirely a dashboard/workspace setting — nothing changes in your
install code, and the events your page receives are identical either way.
Agents answering from the inbox and from Slack can mix freely in the same
conversation; everything stays in one thread on both sides.

---

## Knowledge base & forms

> Let users search your knowledge base and submit ticket forms without leaving your app.

URL: https://docs.useclad.ai/widget/knowledge-base-forms

```ts
const articles = await chat.searchArticles("how do I update billing");
await chat.showArticle(articles[0].id);

await chat.showTicketForm("contact", {
  prefill: { summary: "Cannot log in", severity: "high" },
});
```

- `searchArticles` returns only **published**, end‑user‑visible articles.
- **Ticket forms are one‑way intake.** Submitting a form creates an **issue in
  your inbox** (agents triage it like any other ticket) and shows the user a
  **confirmation screen** — it does *not* open a chat thread and never appears in
  the user's conversation list. Since there's no thread for the user to read, the
  agent **"Reply to customer" composer is disabled** for these issues (internal
  notes still work). `form:submitted` fires on submit; unknown prefill fields are
  ignored.

<!--
<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">Knowledge base in the widget</p>
  <p class="img-ph__desc">The widget showing <strong>knowledge base search results</strong> (and/or an open article), so users can see they can self‑serve answers without leaving your app.</p>
</div>
-->

### AI assistant chat

When **AI answers** are enabled, the in‑widget search becomes a **conversational
AI assistant**. The user types a question, presses Enter, and lands in a
back‑and‑forth chat: the assistant answers from your help center, asks a
clarifying follow‑up when the question is ambiguous, and keeps context as the
user asks more. The source articles it used collapse into a **"Related
articles"** dropdown at the bottom of the chat.

It behaves like a support rep trained on your **public docs** — and is built to
be **honest**:

- Every reply is grounded **only** in your **published, end‑user‑facing** KB
  articles — internal or draft articles are never used and can never leak into a
  reply. Optionally scoped further to the widget's enabled KB collections.
- If the question is unclear, it asks a short **clarifying question** instead of
  guessing.
- If the docs don't cover the question, it says so plainly and offers a
  **"Start a conversation"** button to reach a human.

**Conversations are saved.** Each AI chat (the turns + the asker's identity and
page/locale/device metadata) is persisted server‑side so your team can review
what users ask and where the docs fall short. AI chats are **deflections** — they
do **not** create inbox tickets; only escalating to a human does.

**Enabling it.** The assistant turns on when both
[`features`](#feature-visibility-overrides-features) flags are set (from your
install code or the widget config):

```js
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  features: { knowledgeBase: true, aiAnswers: true }, // search → AI assistant chat
};
```

- `knowledgeBase` provides the articles the assistant is grounded in.
- `aiAnswers` turns the search bar into the assistant chat.
- Set the widget's `ai.mode` to **`human_first`** to disable the assistant and
  route users straight to a human. With `aiAnswers` off, the search bar stays a
  plain published‑article search.

> Replies are generated server‑side; the widget only ever receives the final
> message text and the public article list. (A one‑shot, non‑conversational
> variant is also available programmatically at `POST /widget/v1/ai/answer`.)

### Where ticket forms come from

Ticket forms render **out of the box** in the widget — you don't build any form
UI. They are **data‑driven**: the *content* of a form (its name and fields) is
defined in the dashboard, while *whether and when it shows* can be driven from
code:

- **Define forms in the dashboard:** **Settings → Integrations → Web Widget →
  Ticket forms**. Create/edit/delete forms with a field builder (text, textarea,
  email, select, image), toggle each form on/off, and choose which forms appear.
  One‑click **Bug report** and **Feature request** templates are available.
  (Equivalently via the admin API — `GET/POST/PATCH/DELETE /api/widget-admin/forms`.)
  Form definitions **cannot** be authored from install code.
- **Image uploads (screenshots):** an **`image`** field lets users attach a
  screenshot (e.g. on a bug report). Uploads are **image‑only** and
  **size‑capped**, stored privately, and surfaced on the **agent's issue card**
  via short‑lived signed URLs — not shown back inside the widget.
- **Surface them automatically:** when the `ticketForms` feature is enabled and
  at least one enabled form exists, the widget home shows the forms as **"Quick
  requests"** cards near the top. The **Live chat** entry point ("Send us a
  message") stays anchored to the bottom of the home screen, and **past
  conversations** live on their own page.
- **Or open one from code:** `chat.showTicketForm(slugOrId, { prefill })` opens a
  specific form on demand (e.g. from a button in your app), optionally
  pre‑filling fields. `startConversation({ formId })` is also supported.
- **Control visibility from code:** the
  [`features`](#feature-visibility-overrides-features) override (`ticketForms:
  false`) hides the forms surface for a given page; `ticketForms: true` shows it
  but still only renders forms that exist and are enabled server‑side.

<!--
<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">A ticket form in the widget</p>
  <p class="img-ph__desc">The widget showing an <strong>embedded ticket form</strong> with a couple of fields (including an image/screenshot upload), to illustrate submitting an async request from inside the messenger.</p>
</div>
-->

---

## Context, tags & custom fields

> Attach page context, tags, and custom fields to conversations.

URL: https://docs.useclad.ai/widget/context-tags-fields

```ts
chat.setContext({ page: "billing", url: location.href, accountHealth: "red" });
chat.setConversationTags(["billing", "enterprise"]);
chat.setCustomFields({ plan: "enterprise", mrr: 25000, onboarding_complete: true });
```

- **Context** is ephemeral and attached to future conversations/messages.
- **Tags** and **custom fields** apply to new conversations (and future
  messages where supported); they are not retroactive.
- Custom‑field keys should be slugs; values should be JSON primitives.

> ⚠️ Never put passwords, secrets, full card numbers, access tokens, or other
> sensitive data in `metadata`/`customFields`.

---

## Privacy & cookie consent

> Control storage and analytics with granular cookie-consent levels.

URL: https://docs.useclad.ai/widget/privacy-cookie-consent

```ts
await chat.setCookieConsent("functional"); // all | functional | essential | none
```

| Level | Behavior |
|---|---|
| `all` | Essential + functional + analytics storage allowed. |
| `functional` | Essential + functional; analytics disabled. |
| `essential` | Only strictly necessary storage. |
| `none` | Hides the widget, clears local/session storage, disables chat. |

For logout on shared devices, prefer `shutdown({ clearStorage: true })`.

---

## Events

> Subscribe to lifecycle, connection, conversation, and message events with on().

URL: https://docs.useclad.ai/widget/events

Subscribe with `on()`, which returns an **unsubscribe** function. Every event
uses the same envelope.

```ts
const off = chat.on("message:received", (event) => {
  console.log(event.payload.conversation.id, event.payload.message.id);
});

off(); // stop listening
```

```ts
interface ChatEvent<TPayload> {
  id: string;
  type: ChatEventName;
  createdAt: string;   // ISO‑8601
  payload: TPayload;
}
```

### Event reference

| Event | Payload (key fields) | Fires when |
|---|---|---|
| `ready` | `{ identityType }` | The widget has booted and is ready. |
| `error` | `{ code, message }` | A recoverable/visible error occurred. |
| `open` / `close` | — | The messenger panel opened/closed. |
| `auth:expired` | — | The identity token expired (refresh underway). |
| `auth:changed` | `{ identityType }` | The user became identified. |
| `connection:state` | `{ state }` | `connecting` / `connected` / `reconnecting` / `disconnected`. |
| `unread:change` | `{ count }` | The total unread count changed. |
| `conversation:started` | `{ conversation }` | A conversation was created. |
| `conversation:opened` | `{ conversation }` | A conversation was opened in the UI. |
| `conversation:updated` | `{ conversation }` | Status/assignee/etc. changed. |
| `conversation:resolved` | `{ conversation }` | A conversation was resolved/closed. |
| `conversation:assigned` | `{ conversation }` | An agent/team was assigned. |
| `message:sending` | `{ conversation, message }` | An outbound message is being sent. |
| `message:sent` | `{ conversation, message }` | An outbound message was accepted. |
| `message:received` | `{ conversation, message }` | An agent/bot message arrived. |
| `message:failed` | `{ conversation, error }` | A message failed to send. |
| `typing:start` / `typing:stop` | `{ conversationId }` | Typing indicator changed. |
| `article:opened` | `{ articleId }` | A KB article was opened. |
| `form:opened` | `{ formId }` | A ticket form was opened. |
| `form:submitted` | `{ formId, conversationId }` | A ticket form was submitted. |

> A few names are present in the `ChatEventName` type for forward‑compatibility
> but are **not currently emitted**, so don't rely on them firing today:
> `show`, `hide`, `launcher:show`, `launcher:hide`, and `message:read`. To track
> message read state, read `message.status === "read"` / `conversation.unreadCount`
> (and listen for `unread:change`); to mirror `show`/`hide`/launcher visibility,
> drive it from your own calls to `show()` / `hide()` / `showLauncher()` /
> `hideLauncher()`.

---

## Error handling

> Handle SupportChatError, inspect error codes, and retry recoverable failures.

URL: https://docs.useclad.ai/widget/error-handling

Async methods reject with a `SupportChatError`, exposed on the global as
`SupportChat.Error`:

```js
try {
  await chat.sendMessage({ conversationId, text });
} catch (err) {
  if (err instanceof SupportChat.Error) {
    console.error(err.code, err.message, err.requestId);
    if (err.recoverable) {
      // safe to retry (often after a short backoff)
    }
  }
}
```

| Field | Description |
|---|---|
| `code` | Machine‑readable error code (below). |
| `message` | Human‑readable description. |
| `reason` | Optional finer‑grained reason. |
| `requestId` | Correlation id — include it in support requests. |
| `recoverable` | Whether a retry may succeed. |

**Codes:** `not_ready`, `not_booted`, `auth_required`, `auth_expired`,
`invalid_token`, `invalid_origin`, `widget_disabled`, `rate_limited`,
`network_error`, `conversation_not_found`, `message_invalid`,
`message_send_failed`, `attachment_too_large`, `unsupported_file_type`,
`form_not_found`, `article_not_found`, `validation_error`, `internal_error`.

---

## Realtime behavior

> WebSocket transport, automatic reconnection, message de-duplication, and unread tracking.

URL: https://docs.useclad.ai/widget/realtime

- **Transport:** WebSocket, established after boot. If WebSocket is unavailable,
  delivery automatically falls back so messages still arrive.
- **Reconnect:** automatic with exponential backoff. On reconnect, missed
  messages are replayed and de‑duplicated — you never see duplicates, and
  `clientMessageId` makes your own retries idempotent.
- **Unread:** the widget tracks unread counts across the user's conversations
  and emits `unread:change`, even while the panel is closed.
- **Connection state:** subscribe to `connection:state` to reflect
  online/offline status in your own UI if desired.

No infrastructure is required on your side — the realtime gateway is hosted.

---

## Framework recipes

> Copy-paste integration recipes for React, Next.js (App Router), and Vue 3.

URL: https://docs.useclad.ai/widget/framework-recipes

### React

Include the [Quickstart](#quickstart) `<script>` snippet once in your app shell,
then use a small hook to identify the user on login and shut down on logout.
Calls made before the widget finishes loading are queued and replayed, so you
don't need to wait for it to be ready.

```jsx
import { useEffect } from "react";

export function useSupportChat(user) {
  useEffect(() => {
    if (user) {
      SupportChat("identify", {
        user,
        tokenProvider: () =>
          fetch("/api/support-chat-token").then((r) => r.text()),
      });
    } else {
      SupportChat("shutdown", { clearStorage: true });
    }
  }, [user?.id]);
}
```

### Next.js (App Router)

Load the widget with `next/script` and render it once in your root layout:

```jsx
"use client";
import Script from "next/script";

export default function SupportChatLoader() {
  return (
    <Script id="support-chat" strategy="afterInteractive">
      {`
        window.SupportChatSettings = { workspaceId: "{YOUR_WORKSPACE_ID}", widgetId: "{YOUR_WIDGET_ID}" };
        (function (w, d) {
          w.SupportChat = w.SupportChat || function () {
            (w.SupportChat.q = w.SupportChat.q || []).push(arguments);
          };
          var s = d.createElement("script");
          s.async = true;
          s.src = "https://clad-server-production.up.railway.app/widget/v1/widget.js";
          d.head.appendChild(s);
        })(window, document);
      `}
    </Script>
  );
}
```

### Vue 3

With the [Quickstart](#quickstart) `<script>` snippet included once in your
`index.html`, drive the widget from your components:

```js
import { onMounted } from "vue";

export function useSupportChat(user) {
  onMounted(() => {
    if (user) {
      SupportChat("identify", {
        user,
        tokenProvider: () =>
          fetch("/api/support-chat-token").then((r) => r.text()),
      });
    }
  });
}
```

---

## Security best practices

> Identity verification, allowed origins, CSP, and data-handling guidance.

URL: https://docs.useclad.ai/widget/security

- **Verify identity with server‑minted JWTs.** Never embed the widget secret in
  frontend code. Keep tokens short‑lived.
- **Configure allowed origins** for your widget. Session creation is rejected
  from any other origin.
- **Don't send sensitive data** in `metadata`/`customFields` (passwords,
  secrets, full card numbers, tokens, PII you don't need).
- **Always `shutdown({ clearStorage: true })` on logout**, especially for shared
  devices.
- The widget renders end‑user text as plain text; agent replies and article
  bodies render as **sanitized HTML** (allowlist sanitizer — scripts, event
  handlers, and unsafe URLs are stripped). The UI runs in an isolated iframe
  as a security boundary.
- A reasonable **Content‑Security‑Policy** on your site can allow the widget
  explicitly, e.g. `script-src https://clad-server-production.up.railway.app; frame-src https://clad-server-production.up.railway.app; connect-src https://clad-server-production.up.railway.app wss://clad-server-production.up.railway.app`.

---

## Browser support & performance

> Supported browsers, lazy-loaded UI, and the single hosted script delivery.

URL: https://docs.useclad.ai/widget/browser-support

- Modern evergreen browsers (Chrome, Edge, Firefox, Safari). **IE is not
  supported.** Mobile web works; native mobile SDKs are separate.
- The loader is `async` and small; the chat UI loads lazily in its iframe and
  does not block your page.
- The SDK is delivered as a single hosted script from Clad's CDN — there's
  nothing to bundle. TypeScript definitions are available for typed access to
  the global API.

---

## Public Widget API

> The underlying HTTP + WebSocket Widget API for advanced and self-hosted scenarios.

URL: https://docs.useclad.ai/widget/widget-api-reference

> Most integrators use the SDK and never call these directly. They are
> documented for self‑hosted/advanced scenarios and debugging. Base path:
> `https://clad-server-production.up.railway.app/widget/v1`.

| Method & path | Purpose |
|---|---|
| `GET /config?workspace_id=&widget_id=` | Public, end‑user‑safe widget config. |
| `POST /sessions/anonymous` | Create/resume an anonymous session. |
| `POST /sessions/identify` | Upgrade to an authenticated session (send the identity JWT; the anonymous session token authorizes the merge). |
| `POST /sessions/refresh` | Extend a session. |
| `POST /sessions/shutdown` | Revoke the current session (logout). |
| `POST /sessions/realtime-token` | Mint a short‑lived token for the realtime gateway. |
| `GET /conversations` | List the session's conversations (cursor paginated). |
| `POST /conversations` | Create a conversation (`subject`, `message`, `tags`, `customFields`, `metadata`). |
| `GET /conversations/{id}` | Fetch one conversation. |
| `POST /conversations/{id}/read` | Mark read. |
| `GET /conversations/{id}/messages` | List messages (cursor paginated). |
| `POST /conversations/{id}/messages` | Send a message (`text`, `clientMessageId`). |
| `GET /articles/search?q=` | Search published articles. |
| `GET /articles/{id}` | Fetch an article. |
| `POST /ai/chat` | Conversational AI assistant turn (multi‑turn RAG grounded in published articles). This is what the in‑widget AI assistant uses. |
| `POST /ai/escalate` | Mark an AI chat as escalated to a human (logs the deflection hand‑off). |
| `POST /ai/answer` | One‑shot, non‑conversational answer / article suggestions for a single question (honors `ai.mode` of `answer_first` / `suggest_articles`). |
| `GET /forms` · `GET /forms/{id}` | List/fetch ticket forms. |
| `POST /forms/{id}/submissions` | Submit a ticket form. |
| `POST /attachments` | Upload a ticket‑form image (raw bytes, `X-Filename` header; image‑only + size‑capped). Returns a short‑lived signed handle to include in a submission. |
| `POST /events` | Ingest client analytics/audit events. |
| `WS /realtime?session_token=` | Realtime gateway (WebSocket). |

**Auth:** all endpoints except `GET /config`, `POST /sessions/anonymous`, and
`POST /sessions/identify` (both create a session — `identify` uses the anonymous
session token only to merge history) require `Authorization: Bearer <session
token>`. Mutating endpoints validate the request `Origin` against the widget's
allow‑list. Errors use a consistent envelope:
`{ "error": { code, message, reason?, requestId?, recoverable } }`.

---

## Widget configuration

> The WidgetConfig schema: identity rules, routing, features, theme, and AI behavior.

URL: https://docs.useclad.ai/widget/widget-configuration

Configure widgets in **Settings → Integrations → Web Widget**, or over the admin
API. The dashboard screen manages the widget's **name**, **allowed origins**,
**JWT secret**, **knowledge base**, **ticket forms**, and **identity rules** —
while **theme and feature visibility are set from your install code**
([`theme`](#theming-locale--z-index) / [`features`](#feature-visibility-overrides-features)),
not this screen. The full config object is editable over the admin API for
everything else, and looks like:

```ts
interface WidgetConfig {
  id: string;                 // wgt_…
  workspaceId: string;        // ws_…
  name: string;
  enabled: boolean;
  allowedOrigins: string[];   // e.g. ["https://app.customer.com", "https://*.customer.com"]

  identity: {
    anonymousAllowed: boolean;
    jwtRequiredForIdentifiedUsers: boolean;
    allowAnonymousToIdentifiedMerge: boolean;
  };

  routing: {
    defaultTeamId?: string;
    // Reserved — not yet applied by routing; only `defaultTeamId` is honored today.
    assignmentStrategy?: "platform_default" | "round_robin" | "least_busy";
  };

  features: {
    conversations: boolean;
    knowledgeBase: boolean;
    aiAnswers: boolean;
    ticketForms: boolean;
    customLauncher: boolean;
  };

  theme: ThemeConfig;
  launcher: LauncherConfig;
  forms: { visibleFormIds: string[] };
  knowledgeBase: { enabledCollectionIds?: string[] };
  ai: {
    enabled: boolean;
    mode: "answer_first" | "suggest_articles" | "human_first";
    escalationBehavior: "attach_context" | "summary_only" | "none";
  };
}
```

`allowedOrigins` supports exact origins and single‑level subdomain wildcards
(`https://*.customer.com`).

---

## Troubleshooting & FAQ

> Solutions to common issues: widget not appearing, invalid origins, auth errors, and more.

URL: https://docs.useclad.ai/widget/troubleshooting

**The widget doesn't appear.**
Check the browser console for errors, confirm `workspaceId`/`widgetId`, and that
your page's origin is in the widget's **allowed origins**. The `GET /config`
call must succeed.

**`invalid_origin` when starting a session.**
Add your site's exact origin (scheme + host + port) to the widget's allowed
origins. Wildcards are single‑label (`https://*.customer.com` matches
`app.customer.com` but not `a.b.customer.com`).

**`auth_required` / `auth_expired` for logged‑in users.**
Ensure `tokenProvider` returns a valid JWT signed with the widget secret and
including `sub`, `widget_id`, `workspace_id`, and a future `exp`. The SDK
refreshes automatically; a thrown `tokenProvider` surfaces as `error`.

**Agent replies don't appear in real time.**
Confirm the page can reach the API over HTTPS **and** WebSocket
(`wss://`). Corporate proxies sometimes block WebSocket; the widget falls back
but with slightly higher latency.

**Conversations from before login disappeared.**
Use `identify()` (not a fresh `boot` with a new user) to merge anonymous
history. Ensure `allowAnonymousToIdentifiedMerge` is enabled.

**Multiple users on one browser see each other's chats.**
Call `shutdown({ clearStorage: true })` on logout.

**How do I theme it to match my brand?**
Theming is code‑owned. Set `theme` in `window.SupportChatSettings` (or
`SupportChat.createChat`) for the first paint, or call `setTheme(...)` at
runtime. See [Theming, locale & z‑index](#theming-locale--z-index) for the full
token list, custom CSS, header/branding, fonts, and icons.

---

## Versioning & support

> How the widget and API are versioned, what stays stable, and how to get support.

URL: https://docs.useclad.ai/widget/versioning

- The hosted widget UI and API are versioned in the URL path (`/v1/`); breaking
  changes ship under a new version, so your existing `<script>` tag keeps
  working.
- The public SDK method names, the Promise‑based API, the event system, the
  identity/JWT model, and the hosted‑iframe default are stable contracts within
  a major version.
- Include the `requestId` from a `SupportChatError` when contacting support.

---

## TypeScript reference

> Key types and the full SupportChat interface available on the global API.

URL: https://docs.useclad.ai/widget/typescript-reference

Type definitions for the global Support Chat API are available for TypeScript
projects. The members below live on the global `SupportChat` object once the
loader script has run. Key types:

```ts
// Exposed on the global, e.g. `SupportChat.createChat(...)`.
function createChat(options: CreateChatOptions): SupportChat;
const version: string;

// Exposed as `SupportChat.Error`.
class SupportChatError extends Error {
  code: SupportChatErrorCode;
  reason?: string;
  requestId?: string;
  recoverable: boolean;
}

interface SupportChat {
  boot(options?: BootOptions): Promise<void>;
  identify(options: IdentifyOptions): Promise<void>;
  update(options: UpdateOptions): Promise<void>;
  shutdown(options?: ShutdownOptions): Promise<void>;
  destroy(): Promise<void>;

  open(): Promise<void>;
  close(): Promise<void>;
  show(): void;
  hide(): void;
  showLauncher(): void;
  hideLauncher(): void;
  setLauncherVisible(visible: boolean): void;

  render(options: RenderOptions): Promise<void>;

  startConversation(options?: StartConversationOptions): Promise<Conversation>;
  showConversation(conversationId: string): Promise<void>;
  listConversations(options?: PaginationOptions): Promise<Page<Conversation>>;
  sendMessage(options: SendMessageOptions): Promise<Message>;
  markConversationRead(conversationId: string): Promise<void>;
  showNewMessage(options?: ShowNewMessageOptions): Promise<void>;

  searchArticles(query: string): Promise<Article[]>;
  showArticle(articleId: string): Promise<void>;
  showTicketForm(formId: string, options?: ShowTicketFormOptions): Promise<void>;

  setContext(context: Record<string, JsonValue>): void;
  setConversationTags(tags: string[]): void;
  setCustomFields(fields: Record<string, JsonValue>): void;

  setTheme(theme: ThemeConfig): void;
  setLocale(locale: string): void;
  setZIndex(zIndex: number): void;
  setCookieConsent(consent: CookieConsent): Promise<void>;

  on<E extends ChatEventName>(event: E, handler: ChatEventHandler<E>): () => void;
  off<E extends ChatEventName>(event: E, handler: ChatEventHandler<E>): void;

  readonly state: SdkState;
}
```

See the Support Chat `.d.ts` type definitions for the complete set
(`Conversation`, `Message`, `ThemeConfig`, `LauncherConfig`, `ContentConfig`, event
payload maps, and more).

---

# API

> The GraphQL API for your Clad workspace: issues, replies, CRM, knowledge base, and webhooks.

---

## Overview

> A single GraphQL endpoint for your Clad workspace: issues, replies, CRM, knowledge base, and webhooks.

URL: https://docs.useclad.ai/api/overview

The Clad API is a GraphQL API served from a single endpoint. You send queries
(to read data) and mutations (to change data) as HTTP `POST` requests with a
JSON body.

Production endpoint:

```text
https://clad-server-production.up.railway.app/graphql
```

If your Clad team gives you a different endpoint, use that one instead. The
endpoint shown in **Settings → API** is the source of truth for your workspace.

Every request must send an `Authorization: Bearer <api-key>` header. A request
body looks like this:

```json
{
  "query": "query { apiInfo }",
  "variables": {}
}
```

### API Explorer

Open the endpoint in a browser to load the **Clad API Explorer**, an interactive
GraphiQL IDE with full schema documentation and autocomplete. Browsing the
schema needs no key. To actually run a query or mutation, add your key in the
Explorer's **Headers** tab:

```json
{ "Authorization": "Bearer clad_mk_..." }
```

**[Open the API Explorer →](https://clad-server-production.up.railway.app/graphql)**

### Schema & codegen

The GraphQL schema is the full, machine-readable contract for the API — every
type, query, and mutation. You can feed it to a code generator (for example
[GraphQL Code Generator](https://the-guild.dev/graphql/codegen)) to produce
typed client code for your project, so you get autocomplete and compile-time
checks instead of hand-writing types.

You don't download a schema file — instead your codegen tool **asks the live API
to describe itself** (a built-in GraphQL feature called *introspection*). The
schema is public, so just point the tool at the endpoint — no key required:

```yaml
# codegen.yml — GraphQL Code Generator
schema:
  - https://clad-server-production.up.railway.app/graphql
generates:
  src/clad-types.ts:
    plugins:
      - typescript
```

Because the schema comes straight from the running server, your generated types
always match the current contract — just re-run codegen whenever the schema
changes. Prefer to explore by hand first? The API Explorer above browses the same
schema interactively.

### Health check

`apiInfo` is the simplest query and needs only a valid key. Use it to confirm
connectivity, the API version, and the current schema hash:

```graphql
query { apiInfo }
```

---

## How the API works

> GraphQL in practice: one POST, selection sets, variables, and reading the response — for developers new to GraphQL.

URL: https://docs.useclad.ai/api/how-the-api-works

If you've used REST but not GraphQL, this is everything you need to be
productive. You don't need to learn GraphQL in depth first — the format below
covers the vast majority of real usage.

### It's one POST request

There are no per-resource URLs like `GET /issues/123`. **Every** call — reading
or writing — is an HTTP `POST` to the single `/graphql` endpoint with a JSON
body containing two things:

```json
{
  "query": "…the operation you want to run…",
  "variables": { "…values the operation uses…": "…" }
}
```

That's the whole transport. If you can send a JSON `POST` with a header, you can
call this API in any language — no GraphQL client library required.

### Reading the query string

The `query` field holds a **GraphQL operation**. It starts with a keyword:

- `query { … }` — read data (like a `GET`).
- `mutation { … }` — change data (like `POST`/`PATCH`/`DELETE`).

Inside the braces you name the operation you want, then — and this is the part
REST doesn't have — you **list exactly which fields you want back**. The server
returns those fields and nothing else, so you never over- or under-fetch:

```graphql
query {
  issue(id: "SXNzdWU6MTAyNA==") {
    ticketNumber        # ← ask for the fields you want
    subject
    status
  }
}
```

If you leave a field out, it isn't returned. If you ask for a field that has its
own sub-fields (a nested object), you open another `{ … }` and list those too:

```graphql
query {
  issue(id: "SXNzdWU6MTAyNA==") {
    subject
    messages(first: 5) {          # a connection…
      edges { node { body } }     # …so drill in for the fields you want
    }
  }
}
```

The **Reference** section lists every operation, its arguments, and the type it
returns — so you always know which fields are available to request.

### Use variables, not string interpolation

Don't paste values into the query string. Declare them with a `$name` and pass
them in the separate `variables` object. This is safer (no injection, correct
typing) and is how every example in these docs is written:

```json
{
  "query": "mutation Create($input: CreateIssueInput!) { createIssue(input: $input) { issue { id ticketNumber } error { code message } } }",
  "variables": {
    "input": { "subject": "Login broken", "requesterEmail": "jane@example.com" }
  }
}
```

The `$input: CreateIssueInput!` part declares a variable named `input` of type
`CreateIssueInput` (the `!` means required). The matching value lives in
`variables`. Every input type is documented in the [Reference](#reference).

### Reading the response

The response mirrors your query. Successful data comes back under `data`, keyed
by the operation and shaped like the fields you asked for:

```json
{ "data": { "issue": { "ticketNumber": 1024, "subject": "Login broken", "status": "open" } } }
```

Two kinds of failure can appear:

- **Transport / query errors** (bad syntax, unknown field, missing auth) come
  back in a top-level `errors` array — often with `data: null`.
- **Business errors** (validation, not-found, forbidden) come back as an
  `error` object *inside* the mutation payload, so `data` is still present. This
  is why most mutations here select an `error { code message }` field. See
  [Errors](#errors) for the full taxonomy.

### Try it without writing code

Open the endpoint in a browser to get the **API Explorer** (a GraphiQL IDE) with
live schema docs, autocomplete, and a run button — the fastest way to learn the
shape of an operation before you wire it into code.

**[Open the API Explorer →](https://clad-server-production.up.railway.app/graphql)**

> **Want the language itself?** This page covers everything you need for Clad. To
> go deeper on GraphQL as a language, see the official intro at
> [graphql.org/learn](https://graphql.org/learn/).

---

## Authentication

> Create an API key in Settings → API, choose its permissions, and keep it backend-only.

URL: https://docs.useclad.ai/api/authentication

The API authenticates with **API keys** you create in **Settings → API**. A key
is scoped to one workspace and carries a fixed set of permissions. Keys look
like `clad_mk_...` and are passed as a Bearer token:

```http
POST /graphql HTTP/1.1
Host: clad-server-production.up.railway.app
Authorization: Bearer clad_mk_xxxxxxxxxxxxxxxxxx_...
Content-Type: application/json
```

### Creating a key

In Clad, go to **Settings → API** (org admins only), then:

1. Enter a **key name** — a label so you can recognize it later (e.g.
   `Production backend`).
2. Pick its **permissions**:
   - **Full access** — read and write everything this workspace exposes over the
     API, including admin-only settings.
   - **Read-only** — fetch issues, contacts, accounts, articles, and more, but
     make no changes.
   - **Custom** — grant exactly the scopes you need (see
     [Scopes & permissions](#scopes--permissions)).
3. Click **Create key** and copy the `clad_mk_...` secret immediately — it is
   shown **exactly once**. Store it in your backend secret manager.

Use the key from server-side code only. Never expose it in a browser, mobile
app, or public repo. Revoke a key anytime from the same page; integrations using
it stop working immediately.

> You don't create a "user" for the key — Clad manages the underlying API
> principal for you. You just name the key and choose its permissions.

### Creating keys programmatically

Org admins can also mint keys with the `createApiKey` mutation using an
admin-scoped key. `machineUserId` is the API principal a key is attached to; call
`machineUsers` to list existing ones or `createMachineUser` to make a new one for
grouping keys by system.

```graphql
mutation CreateKey($input: CreateApiKeyInput!) {
  createApiKey(input: $input) {
    apiKey { id keyPrefix scopes }
    secret   # returned once — store it now
    error { code message }
  }
}
```

```json
{
  "input": {
    "machineUserId": "<machine-user-id>",
    "name": "Production backend",
    "scopes": ["issues:read", "issues:write", "thread:reply"]
  }
}
```

Revoke a compromised key immediately with `revokeApiKey(id)`.

### Legacy keys

Existing REST `/v1` keys (`clad_live_...`) also authenticate against GraphQL,
but they are bridged to a single `issues:create` scope — they can call
`createIssue` and nothing else. To do more, mint a `clad_mk_...` key with
explicit scopes.

---

## Quickstart

> Send your first authenticated query, create an issue, and read it back.

URL: https://docs.useclad.ai/api/quickstart

Send your first authenticated query, then create an issue.

### 1. Confirm your key works

```bash
curl https://clad-server-production.up.railway.app/graphql \
  -H "Authorization: Bearer clad_mk_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"query { apiInfo }"}'
```

### 2. Create an issue

```bash
curl https://clad-server-production.up.railway.app/graphql \
  -H "Authorization: Bearer clad_mk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Create($input: CreateIssueInput!) { createIssue(input: $input) { issue { id ticketNumber } error { code message } } }",
    "variables": {
      "input": {
        "subject": "Cannot reset my password",
        "body": "The reset email never arrives.",
        "requesterEmail": "jane@example.com",
        "requesterName": "Jane Doe",
        "priority": "high"
      }
    }
  }'
```

A successful response returns the created issue's global id and ticket number:

```json
{
  "data": {
    "createIssue": {
      "issue": { "id": "SXNzdWU6...", "ticketNumber": 1024 },
      "error": null
    }
  }
}
```

### 3. Read it back

```graphql
query GetIssue($id: ID!) {
  issue(id: $id) {
    id
    ticketNumber
    subject
    status
    priority
    messages(first: 20) {
      edges { node { senderName body createdAt } }
    }
  }
}
```

---

## Scopes & permissions

> Coarse and resource scopes, admin-gated grants, and least-privilege keys.

URL: https://docs.useclad.ai/api/scopes

Every API key carries a set of scopes. A field runs only if the key holds a
scope that satisfies it. Requests missing a scope fail with `FORBIDDEN`.

Scopes come in two forms:

- **Coarse:** `read`, `write`, `admin`. `read` satisfies any `*:read` scope;
  `write` satisfies any non-admin `*:write` scope; `admin` satisfies everything
  in the schema.
- **Resource:** fine-grained `resource:action` grants for least-privilege keys.

Common resource scopes:

| Scope | Grants |
| --- | --- |
| `issues:read` | Read issues and their messages |
| `issues:write` | Create and mutate issues (status, priority, tags, assignment) |
| `issues:create` | Create-only intake (open an issue; cannot list or mutate others) |
| `thread:reply` | Reply to issue threads |
| `spam:write` | Mark issues as spam |
| `investigations:read` / `investigations:run` | Read / start AI investigations (runs are spend-capped per org) |
| `drafts:read` / `drafts:write` | Read / generate, approve, deny AI reply drafts |
| `accounts:read` / `accounts:write` | Read / write CRM accounts |
| `contacts:read` / `contacts:write` | Read / write CRM contacts |
| `articles:read` / `articles:write` | Read / write knowledge-base articles |
| `articles:publish` | Publish articles with public visibility |
| `collections:write` | Manage KB collections |
| `tags:write` | Manage workspace tags |
| `views:read` / `views:write` | Read / write saved account views |
| `members:read` | Read org members |
| `teams:write` | Manage teams and team membership |
| `settings:read` / `settings:write` | Read / write workspace settings |
| `sla:read` | Read SLA policies and support-hours schedules |
| `customfields:write` | Manage account/contact custom fields |
| `widget:write` | Manage web widgets and widget forms |
| `webhooks:manage` | Manage webhook endpoints |
| `apikeys:read` / `apikeys:revoke` | Read key metadata / revoke keys |

Some scopes are **admin-gated** (`settings:write`, `customfields:write`,
`webhooks:manage`, `apikeys:read`, `apikeys:revoke`): a coarse `write` does not
satisfy them — the key needs the exact scope or `admin`.

Grant each key the narrowest set of scopes it needs.

---

## Issues

> Create issues from your systems, read the inbox, and manage status, priority, tags, and assignment.

URL: https://docs.useclad.ai/api/issues

Issues (tickets) are the core object. Create them from your own systems, read
the inbox, and manage status, priority, tags, assignment, and spam/trash state.

### Create an issue

```graphql
mutation Create($input: CreateIssueInput!) {
  createIssue(input: $input) {
    issue { id ticketNumber subject status }
    error { code message fields { path message } }
  }
}
```

`CreateIssueInput` fields:

| Field | Required | Description |
| --- | --- | --- |
| `subject` | Yes | Issue title. |
| `body` | Yes | First inbound message (plain text). |
| `priority` | No | `low` \| `normal` \| `high` \| `urgent`. |
| `requesterEmail` | No | Requester email; used to create/link a contact. |
| `requesterName` | No | Requester display name. |
| `contactId` | No | Link to an existing CRM contact (opaque id). |
| `accountId` | No | Link to an existing CRM account (opaque id). |
| `tags` | No | Tags to apply. |
| `externalId` | No | Your stable id; reusing it returns the original issue. |
| `idempotencyKey` | No | Dedupe key for safe retries. |

### List the inbox

```graphql
query Inbox($after: String) {
  issues(first: 25, after: $after, target: all, status: new, sortKey: createdAt) {
    edges { node { id ticketNumber subject status priority lastMessageAt } }
    pageInfo { hasNextPage endCursor }
  }
}
```

`issues` supports filters: `target` (`all` \| `my` \| `following` \| `spam` \|
`trash`), `status`, `tag`, `accountId`, `assigneeProfileId`, `search`, and
`sortKey` (`createdAt` \| `updatedAt`).

### Manage an issue

```graphql
mutation Triage($id: ID!) {
  setIssueStatus(issueId: $id, status: on_hold) { issue { id status } error { code message } }
  setIssuePriority(issueId: $id, priority: urgent) { issue { id priority } error { code message } }
  setIssueTags(issueId: $id, tags: ["billing", "escalated"]) { issue { id tags } error { code message } }
  assignIssue(issueId: $id, assigneeProfileId: "<profile-id>") { issue { id assignedTo } error { code message } }
}
```

Other issue mutations: `setIssueAccount`, `setIssueTeams`, `setIssueSpam`,
`setIssueTrashed`, `followIssue`, `unfollowIssue`.

### Helpdesk-mirrored issues

If the workspace has Pylon or Zendesk connected, tickets from the helpdesk
appear here as regular issues — same shape, same queries and mutations, full
conversation thread included. New tickets and customer messages arrive within
seconds of landing in the helpdesk. Triage (status, priority, tags,
assignment) applies in Clad; replies deliver into the helpdesk itself — see
[Replies](/api/replies).

---

## Replies

> Post customer-facing replies or internal notes to an issue thread.

URL: https://docs.useclad.ai/api/replies

Post a customer-facing reply or an internal note to an issue thread.

```graphql
mutation Reply($input: ReplyToIssueInput!) {
  replyToIssue(input: $input) {
    messageId
    delivery
    error { code message }
  }
}
```

```json
{
  "input": {
    "issueId": "<issue-id>",
    "body": "Thanks for reaching out — we've reset your password.",
    "isInternal": false
  }
}
```

- Set `isInternal: true` for a note only your team can see.
- `delivery` reports how the reply was sent: `in_thread` (recorded only) or an
  egress status (`pending` / `delivered` / `failed`), depending on the issue's
  source channel and your integration's reply-delivery configuration.
- For issues created through this API, outbound delivery is configured in
  **Settings → API → Outbound replies**: choose no outbound replies, email
  from Clad, or a signed webhook event.

Requires the `thread:reply` scope.

### Replying on helpdesk-mirrored tickets

If the workspace has Pylon or Zendesk connected, tickets mirrored from the
helpdesk are regular issues in this API — but replies to them are delivered
into the helpdesk itself, as the connected support seat. `delivery` returns
`pylon` or `zendesk` on success (`pylon_deduplicated` / `zendesk_deduplicated`
when an identical retry was already sent — the send is idempotent, so retrying
never double-posts).

Delivery is all-or-nothing: if the helpdesk rejects the reply, the mutation
returns an error and nothing is recorded. Two errors are worth handling:

- `FORBIDDEN` — the connection is in **Observe** mode (Clad never writes to the
  helpdesk) or paused. An admin can switch it to **Assist** in
  Settings → Integrations.
- `CONFLICT` — the same reply is already being sent by a concurrent request.

Internal notes (`isInternal: true`) stay in Clad and are never written to the
helpdesk.

---

## AI agents & escalation

> Run investigations, work AI reply drafts with their grounding sources, and file engineering-tracker tickets.

URL: https://docs.useclad.ai/api/ai-agents

Clad's AI-agent workflow — investigations, suggested-reply drafts, and
engineering-tracker filing — is available in the API, so an external agent can
run the same playbook a teammate runs in the Clad app or the in-helpdesk panel.

### Investigations

`startInvestigation` kicks off an asynchronous root-cause dig for an issue:
`kind: code` works through the connected GitHub repo, `kind: billing` works
through Stripe. Runs take a few minutes — poll `investigation(id)` (or
`investigations(issueId)`) until `status` is `complete` or `failed`, then read
`output` (markdown findings), `summary`, and `answerFound`.

```graphql
mutation Investigate($input: StartInvestigationInput!) {
  startInvestigation(input: $input) {
    investigation { id status }
    error { code message }
  }
}
```

Per-organization in-flight and daily caps protect spend (`RATE_LIMITED` when
hit). Requires `investigations:run`; reads require `investigations:read`.

### Drafts

Clad auto-drafts a suggested reply when a customer message arrives and the
knowledge base has a confident answer. `latestDraft(issueId)` returns the
newest attempt in any status — `generating`, `pending` (awaiting review),
`discarded_*` (the gate declined), `approved`, `rejected` — including the
draft body and its `sources`: the knowledge-base articles and resolved tickets
the answer was grounded in.

- `generateDraft` produces a draft on demand through the same gated pipeline
  (optionally steered with `instructions`). A declined gate returns
  `withheld: true` with a reason — that's a valid outcome, not an error. It
  returns `CONFLICT` if a pending draft already exists; deny that one first.
- `generateDraftFromInvestigation` turns a completed investigation's findings
  into a pending draft.
- `approveDraft` sends the draft to the customer. This requires a
  **human-authorized credential** (OAuth) — the send is attributed to the
  approving person, so headless machine keys are refused with `FORBIDDEN`.
  v1 delivers approvals on helpdesk-mirrored issues (Pylon/Zendesk), with the
  same Observe/Assist mode gate and idempotent delivery as
  [replies](#replying-on-helpdesk-mirrored-tickets); other channels approve in
  the Clad app.
- `denyDraft` rejects a pending draft with a reason, which feeds regeneration
  and quality analytics.

Draft reads require `drafts:read`; generate/approve/deny require `drafts:write`.

### Tracker escalation

When a ticket needs engineering, `fileTrackerTicket` files a Linear ticket
from the issue and links it: the Clad issue moves to On hold and the tracker
ticket gets a back-link comment with the customer context. `linkedTickets`
returns the linked tickets' live state and comment threads (check it before
filing to avoid duplicates), and `commentOnLinkedTicket` posts follow-up
context for the engineers. These use the `issues:read` / `issues:write`
scopes.

### Helpdesk connection

`helpdeskConnections` reports the connected helpdesks (provider, status,
operating mode, sync scope) with `settings:read` — check it before attempting
replies or approvals: in **Observe** mode every write to the helpdesk returns
`FORBIDDEN` until an admin switches the connection to **Assist**.

---

## Accounts & contacts

> Read and write CRM accounts and contacts.

URL: https://docs.useclad.ai/api/accounts-contacts

Read and write your CRM. Accounts are companies; contacts are people, optionally
linked to an account.

### Read

```graphql
query Crm {
  accounts(first: 20, search: "acme") {
    edges { node { id companyName primaryDomain projectedArr } }
    pageInfo { hasNextPage endCursor }
  }
  contacts(first: 20, accountId: "<account-id>") {
    edges { node { id name email accountId } }
  }
}
```

### Write

```graphql
mutation NewAccount($input: CreateAccountInput!) {
  createAccount(input: $input) {
    account { id companyName primaryDomain }
    error { code message }
  }
}
```

```json
{
  "input": {
    "companyName": "Acme Inc",
    "primaryDomain": "acme.com",
    "arrAmount": 12000,
    "arrCadence": "annual",
    "tags": ["enterprise"]
  }
}
```

Contacts follow the same pattern with `createContact` / `updateContact` /
`deleteContact`. Updates merge `customData` per key; pass a null value to clear a
single key. CRM reads need `accounts:read` / `contacts:read`; writes need the
matching `*:write` scope.

---

## Knowledge base

> Manage knowledge-base collections and articles.

URL: https://docs.useclad.ai/api/knowledge-base

Manage collections (folders) and articles.

```graphql
query Kb {
  collections(first: 20) { edges { node { id name } } }
  articles(first: 20, status: published, search: "billing") {
    edges { node { id title slug status visibility } }
  }
  featuredArticles {
    id title position isAvailable unavailableReason
  }
  featuredArticleCandidates(search: "getting started", first: 20) {
    id title currentPosition
  }
}

mutation NewArticle($input: CreateArticleInput!) {
  createArticle(input: $input) {
    article { id title slug status }
    error { code message }
  }
}
```

Article `status` is `draft` or `published`; `visibility` is `public`,
`customer`, `internal`, or `ai_agent_only`. Reads need `articles:read`; writes
need `articles:write` (and `collections:write` to manage collections). Creating
or transitioning an article to `published` + `public` also requires the
`articles:publish` scope. This scope is member-eligible and is satisfied by
coarse `write`; an `articles:write`-only key still needs the explicit publish
scope.

Use `featuredArticles` to read the complete manually pinned help-center homepage
set. It includes retained pins that are temporarily unavailable, so clients can
preserve or reorder them rather than silently dropping them. Candidate search is
metadata-only and returns at most 50 published, public, listed articles from
included collections.

`replaceFeaturedArticles` atomically replaces the **entire** ordered pin set:

```graphql
mutation FeatureArticles($input: ReplaceFeaturedArticlesInput!) {
  replaceFeaturedArticles(input: $input) {
    featuredCount
    articleIds
    error { code message fields { path message } }
  }
}
```

Pass up to six unique Article ids. Omitted existing pins are unpinned; pass an
empty list to clear manual pins and restore automatic recency. The mutation
requires `articles:write` plus the same supplemental `articles:publish` grant as
other public-publication actions. New pins must be published, public, listed,
and belong to an included collection; already-pinned unavailable articles may
still be retained or reordered.

---

## Pagination

> Relay-style forward pagination with first/after and global object identity.

URL: https://docs.useclad.ai/api/pagination

List fields follow the Relay connection spec and paginate **forward only** with
`first` + `after`:

```graphql
query Page($after: String) {
  issues(first: 50, after: $after) {
    edges { cursor node { id ticketNumber } }
    pageInfo { hasNextPage endCursor }
  }
}
```

Loop until `pageInfo.hasNextPage` is `false`, passing the previous
`pageInfo.endCursor` as the next `after`. Cursors are opaque — do not construct
or parse them yourself.

### Global object identity

Every major object implements the `Node` interface with a globally unique
opaque `id`. Refetch any object by id with `node`, or up to 50 at once with
`nodes`:

```graphql
query { node(id: "<opaque-id>") { id } }
```

---

## Errors

> In-band result errors, top-level GraphQL errors, and the canonical error-code taxonomy.

URL: https://docs.useclad.ai/api/errors

The API uses two error channels:

**1. In-band result errors (expected failures).** Mutations return a result
union whose `error` member is non-null on failure. Always select `error` and
check it:

```graphql
mutation {
  createIssue(input: { subject: "", body: "" }) {
    issue { id }
    error { code message retryable fields { path message } }
  }
}
```

**2. Top-level GraphQL errors (request-shape / auth failures).** Malformed
queries, missing auth, and rate limits appear in the response's top-level
`errors` array. Each carries `extensions.code`, `extensions.retryable`, and
`extensions.requestId` (also returned as the `x-request-id` response header —
include it in support requests).

Error codes:

| Code | Meaning | Retryable |
| --- | --- | --- |
| `VALIDATION` | Bad input; see `fields` for per-field detail | No |
| `UNAUTHENTICATED` | Missing, invalid, revoked, or expired key | No |
| `FORBIDDEN` | Key lacks the required scope | No |
| `NOT_FOUND` | Object does not exist (or not in your org) | No |
| `CONFLICT` | Uniqueness/state conflict (e.g. duplicate slug) | No |
| `RATE_LIMITED` | Too many requests | Yes |
| `DEPENDENCY_FAILED` | A downstream dependency failed | Yes |
| `INTERNAL` | Unexpected server error | Yes |

Internal errors never include internal detail on the wire — use the `requestId`
when contacting support.

---

## Idempotency

> Safe retries with idempotency keys and stable external ids.

URL: https://docs.useclad.ai/api/idempotency

For issue creation, set `idempotencyKey` (or a stable `externalId`) on
`CreateIssueInput`. Retrying with the same key returns the **original** issue
instead of creating a duplicate — safe for at-least-once delivery from your
systems.

---

## Rate limits

> Per-credential and per-IP request limits and back-off.

URL: https://docs.useclad.ai/api/rate-limits

Limits are enforced per minute:

- **Per credential:** 240 requests/min (keyed on your API key).
- **Per IP:** 600 requests/min (backstop, includes unauthenticated traffic).

Over the limit returns `RATE_LIMITED` (`retryable: true`). Standard rate-limit
headers are returned; back off and retry. Requests are also capped at a 1 MB
body and a bounded query depth/complexity.

---

## Webhooks

> Subscribe to events, verify signed deliveries, and manage endpoints.

URL: https://docs.useclad.ai/api/webhooks

Subscribe to events (e.g. `issue.reply.created`) so your backend hears about
changes without polling.

```graphql
mutation Endpoint($input: CreateWebhookEndpointInput!) {
  createWebhookEndpoint(input: $input) {
    endpoint { id url events isActive }
    secret   # signing secret — shown once
    error { code message }
  }
}
```

```json
{ "input": { "url": "https://api.example.com/clad/webhooks", "events": ["*"] } }
```

Deliveries are signed. Each request includes:

- `Clad-Event-Id` — unique per event; use it as your idempotency key.
- `Clad-Event-Type`
- `Clad-Webhook-Timestamp`
- `Clad-Webhook-Signature: v1=<hex>` — HMAC-SHA256 over
  `timestamp.event_id.raw_body` using your signing secret.

Verify the signature before trusting a delivery. Respond `2xx` to acknowledge;
non-2xx responses are retried. Use `pingWebhookEndpoint` to send a test
`webhook.ping`, `webhookDeliveries` to inspect recent attempts, and
`webhookEventTypes` to list every event you can subscribe to. Rotate a secret
with `rotateWebhookSecret` (the old one stops working immediately). Managing
webhooks requires the `webhooks:manage` scope.

---

## Versioning & support

> API versioning, schema stability, introspection, and how to get support.

URL: https://docs.useclad.ai/api/versioning

- This is **API v1**. `apiInfo` returns the current version and schema hash.
- The schema is additive-first: new fields and types may be added without
  notice; breaking changes are avoided within v1.
- Introspection is open to any valid credential, so the live schema in the API
  Explorer is always the current contract.
- For help, contact your Clad team and include the `requestId` (the
  `x-request-id` header) from the failing request.

<!-- BEGIN GENERATED REFERENCE -->

---

## Reference overview

> How to read the generated operation reference: queries, mutations, arguments, and return types.

URL: https://docs.useclad.ai/api/reference

A complete, generated reference for every query and mutation in the API, grouped by domain. Each entry shows the operation signature, its arguments, and the return type. Reads are **queries**; writes are **mutations**. Every list argument follows the [pagination](#pagination) convention, every mutation returns an `error` you should check (see [Errors](#errors)), and every operation is gated by a [scope](#scopes--permissions).

> This reference is generated directly from the GraphQL schema, so it always matches the live contract. You can also browse the same schema interactively in the API Explorer.

---

## Issues

> Every issue query and mutation: inbox, create, reply, status, priority, tags, assignment, spam/trash.

URL: https://docs.useclad.ai/api/reference-issues

Create issues, read the inbox, reply, and manage status, priority, tags, assignment, and spam/trash state.

### Queries

#### `issue`

```graphql
issue(id: ID!): Issue
```

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `issues`

```graphql
issues(accountId: ID, after: String, assigneeProfileId: ID, first: Int, search: String, sortKey: IssueSortKey, status: IssueStatus, tag: String, target: InboxTarget): IssueConnection
```

| Argument | Type | Description |
| --- | --- | --- |
| `accountId` | `ID` | Filter to issues linked to this account (opaque Account id). |
| `after` | `String` |  |
| `assigneeProfileId` | `ID` | Filter to issues assigned to this org member (opaque Profile id). |
| `first` | `Int` |  |
| `search` | `String` | Case-insensitive match on subject or last message preview. |
| `sortKey` | `IssueSortKey` | Sort anchor (descending). Defaults to createdAt. |
| `status` | `IssueStatus` |  |
| `tag` | `String` | Filter to issues carrying this tag (exact match). |
| `target` | `InboxTarget` |  |

### Mutations

#### `assignIssue`

```graphql
assignIssue(assigneeProfileId: ID, issueId: ID!): IssueMutationResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `assigneeProfileId` | `ID` | Opaque Profile id of an org member, or null to unassign. |
| `issueId` | `ID!` | Required. |

#### `createIssue`

```graphql
createIssue(input: CreateIssueInput!): CreateIssueResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateIssueInput!` | Required. |

#### `followIssue`

```graphql
followIssue(issueId: ID!, profileId: ID): IssueMutationResult
```

Add a follower to an issue. Humans follow themselves when profileId is omitted; machine actors must name an org member.

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |
| `profileId` | `ID` | Opaque Profile id of the member to add (defaults to the caller for human sessions). |

#### `replyToIssue`

```graphql
replyToIssue(input: ReplyToIssueInput!): ReplyToIssueResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `ReplyToIssueInput!` | Required. |

#### `setIssueAccount`

```graphql
setIssueAccount(accountId: ID, issueId: ID!): IssueMutationResult
```

Link an issue to a CRM account (null unlinks). Team routing inherited from the account follows automatically.

| Argument | Type | Description |
| --- | --- | --- |
| `accountId` | `ID` | Opaque Account id, or null to unlink. |
| `issueId` | `ID!` | Required. |

#### `setIssuePriority`

```graphql
setIssuePriority(issueId: ID!, priority: IssuePriority!): IssueMutationResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |
| `priority` | `IssuePriority!` | Required. |

#### `setIssueSpam`

```graphql
setIssueSpam(isSpam: Boolean!, issueId: ID!): IssueMutationResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `isSpam` | `Boolean!` | Required. |
| `issueId` | `ID!` | Required. |

#### `setIssueStatus`

```graphql
setIssueStatus(issueId: ID!, status: IssueStatus!): IssueMutationResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |
| `status` | `IssueStatus!` | Required. |

#### `setIssueTags`

```graphql
setIssueTags(issueId: ID!, tags: [String!]!): IssueMutationResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |
| `tags` | `[String!]!` | Required. |

#### `setIssueTeams`

```graphql
setIssueTeams(issueId: ID!, teamIds: [ID!]!): IssueMutationResult
```

Replace the manual team assignments on an issue (same semantics as the inbox team picker).

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |
| `teamIds` | `[ID!]!` | Opaque Team ids; empty list clears manual assignments. |

#### `setIssueTrashed`

```graphql
setIssueTrashed(issueId: ID!, trashed: Boolean!): IssueMutationResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |
| `trashed` | `Boolean!` | true to move to trash, false to restore. |

#### `unfollowIssue`

```graphql
unfollowIssue(issueId: ID!, profileId: ID): IssueMutationResult
```

Remove a follower from an issue (defaults to the caller for human sessions).

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |
| `profileId` | `ID` | Opaque Profile id of the member to remove (defaults to the caller for human sessions). |

---

## CRM — accounts & contacts

> Every account and contact query and mutation, plus saved views and custom fields.

URL: https://docs.useclad.ai/api/reference-crm

Read and write CRM accounts and contacts, saved account views, and account/contact custom fields.

### Queries

#### `account`

```graphql
account(id: ID!): Account
```

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `accounts`

```graphql
accounts(after: String, first: Int, search: String): AccountConnection
```

| Argument | Type | Description |
| --- | --- | --- |
| `after` | `String` |  |
| `first` | `Int` |  |
| `search` | `String` |  |

#### `accountViews`

```graphql
accountViews: [AccountView!]
```

Saved account views (filters) for the organization.

#### `contact`

```graphql
contact(id: ID!): Contact
```

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `contacts`

```graphql
contacts(accountId: ID, after: String, first: Int, search: String): ContactConnection
```

| Argument | Type | Description |
| --- | --- | --- |
| `accountId` | `ID` |  |
| `after` | `String` |  |
| `first` | `Int` |  |
| `search` | `String` |  |

#### `customFields`

```graphql
customFields(entity: CustomFieldEntity!): [CustomField!]
```

| Argument | Type | Description |
| --- | --- | --- |
| `entity` | `CustomFieldEntity!` | Required. |

### Mutations

#### `createAccount`

```graphql
createAccount(input: CreateAccountInput!): AccountResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateAccountInput!` | Required. |

#### `createAccountView`

```graphql
createAccountView(input: CreateAccountViewInput!): AccountViewResult
```

Create a saved account view (filter). The org's first view is auto-starred.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateAccountViewInput!` | Required. |

#### `createContact`

```graphql
createContact(input: CreateContactInput!): ContactResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateContactInput!` | Required. |

#### `createCustomField`

```graphql
createCustomField(input: CreateCustomFieldInput!): CustomFieldResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateCustomFieldInput!` | Required. |

#### `deleteAccount`

```graphql
deleteAccount(id: ID!): DeleteAccountResult
```

Hard-delete a CRM account. Contacts keep existing; issues are not touched.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `deleteAccountView`

```graphql
deleteAccountView(id: ID!): DeleteAccountViewResult
```

Delete a saved account view.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `deleteContact`

```graphql
deleteContact(id: ID!): DeleteContactResult
```

Hard-delete a CRM contact.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `deleteCustomField`

```graphql
deleteCustomField(input: DeleteCustomFieldInput!): DeleteCustomFieldResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `DeleteCustomFieldInput!` | Required. |

#### `updateAccount`

```graphql
updateAccount(input: UpdateAccountInput!): AccountResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateAccountInput!` | Required. |

#### `updateAccountView`

```graphql
updateAccountView(input: UpdateAccountViewInput!): AccountViewResult
```

Rename, reconfigure, or star/unstar a saved account view.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateAccountViewInput!` | Required. |

#### `updateContact`

```graphql
updateContact(input: UpdateContactInput!): ContactResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateContactInput!` | Required. |

#### `updateCustomField`

```graphql
updateCustomField(input: UpdateCustomFieldInput!): CustomFieldResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateCustomFieldInput!` | Required. |

---

## Knowledge base

> Every collection, article, article-template, and homepage-curation query and mutation.

URL: https://docs.useclad.ai/api/reference-knowledge-base

Manage help-center collections, articles, article templates, and homepage curation.

### Queries

#### `article`

```graphql
article(id: ID!): Article
```

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `articles`

```graphql
articles(after: String, collectionId: ID, first: Int, search: String, status: ArticleStatus): ArticleConnection
```

| Argument | Type | Description |
| --- | --- | --- |
| `after` | `String` |  |
| `collectionId` | `ID` |  |
| `first` | `Int` |  |
| `search` | `String` |  |
| `status` | `ArticleStatus` |  |

#### `articleTemplates`

```graphql
articleTemplates: [ArticleTemplate!]
```

All article templates in the organization (newest first).

#### `collection`

```graphql
collection(id: ID!): Collection
```

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `collections`

```graphql
collections(after: String, first: Int, search: String): CollectionConnection
```

| Argument | Type | Description |
| --- | --- | --- |
| `after` | `String` |  |
| `first` | `Int` |  |
| `search` | `String` |  |

#### `featuredArticleCandidates`

```graphql
featuredArticleCandidates(first: Int, search: String): [FeaturedArticleCandidate!]
```

Search up to 50 metadata-only, publicly eligible articles that can be newly pinned to the help-center homepage.

| Argument | Type | Description |
| --- | --- | --- |
| `first` | `Int` | Maximum rows to return (default 25, max 50). |
| `search` | `String` | Optional case-insensitive title search (max 128 characters). |

#### `featuredArticles`

```graphql
featuredArticles: [FeaturedArticle!]
```

The complete explicitly pinned help-center homepage set in manual order, including retained pins that are temporarily unavailable.

### Mutations

#### `createArticle`

```graphql
createArticle(input: CreateArticleInput!): ArticleResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateArticleInput!` | Required. |

#### `createArticleTemplate`

```graphql
createArticleTemplate(input: CreateArticleTemplateInput!): ArticleTemplateResult
```

Create an article template.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateArticleTemplateInput!` | Required. |

#### `createCollection`

```graphql
createCollection(input: CreateCollectionInput!): CollectionResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateCollectionInput!` | Required. |

#### `deleteArticle`

```graphql
deleteArticle(id: ID!): DeleteArticleResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `deleteArticleTemplate`

```graphql
deleteArticleTemplate(id: ID!): DeleteArticleTemplateResult
```

Delete an article template.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `deleteCollection`

```graphql
deleteCollection(id: ID!): DeleteCollectionResult
```

Delete a collection AND every article in it (with search-index cleanup).

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `replaceFeaturedArticles`

```graphql
replaceFeaturedArticles(input: ReplaceFeaturedArticlesInput!): ReplaceFeaturedArticlesResult
```

Atomically replace the complete ordered help-center homepage pin set. Requires article write plus public-publication permission.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `ReplaceFeaturedArticlesInput!` | Required. |

#### `updateArticle`

```graphql
updateArticle(input: UpdateArticleInput!): ArticleResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateArticleInput!` | Required. |

#### `updateArticleTemplate`

```graphql
updateArticleTemplate(input: UpdateArticleTemplateInput!): ArticleTemplateResult
```

Rename or re-body an article template.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateArticleTemplateInput!` | Required. |

#### `updateCollection`

```graphql
updateCollection(input: UpdateCollectionInput!): CollectionResult
```

Rename or restyle a collection. Name collisions return CONFLICT.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateCollectionInput!` | Required. |

---

## AI agents & escalation

> Every investigation, draft, tracker-filing, and helpdesk-connection query and mutation.

URL: https://docs.useclad.ai/api/reference-ai-agents

Run investigations, work AI-suggested reply drafts (with grounding sources), file engineering-tracker tickets, and read the helpdesk connection.

### Queries

#### `helpdeskConnections`

```graphql
helpdeskConnections: [HelpdeskConnection!]
```

Connected external helpdesks (Pylon/Zendesk) with status and operating mode. Empty when none.

#### `investigation`

```graphql
investigation(id: ID!): Investigation
```

One investigation run by id (null when unknown).

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `investigations`

```graphql
investigations(issueId: ID!): [Investigation!]
```

Investigation runs for an issue, newest first (latest 20).

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |

#### `latestDraft`

```graphql
latestDraft(issueId: ID!): Draft
```

The most recent AI draft attempt for an issue, any status — lets a caller distinguish generating / pending / discarded / approved in one read.

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |

#### `linkedTickets`

```graphql
linkedTickets(issueId: ID!): [TrackerTicket!]
```

Engineering-tracker tickets linked to an issue, with live state and comments.

| Argument | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` | Required. |

### Mutations

#### `approveDraft`

```graphql
approveDraft(input: ApproveDraftInput!): DraftResult
```

Approve a pending draft and deliver it to the customer. Requires a human-authorized credential (OAuth) — the send is attributed to the approving person. v1 delivers on helpdesk-mirrored issues (Pylon/Zendesk); the helpdesk operating mode is enforced (FORBIDDEN in Observe).

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `ApproveDraftInput!` | Required. |

#### `commentOnLinkedTicket`

```graphql
commentOnLinkedTicket(input: CommentOnLinkedTicketInput!): TrackerTicketCommentResult
```

Post a comment on a tracker ticket linked to an issue. Only tickets linked to the issue are reachable.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CommentOnLinkedTicketInput!` | Required. |

#### `denyDraft`

```graphql
denyDraft(input: DenyDraftInput!): DraftResult
```

Reject a pending draft with an optional reason.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `DenyDraftInput!` | Required. |

#### `fileTrackerTicket`

```graphql
fileTrackerTicket(input: FileTrackerTicketInput!): TrackerTicketResult
```

File an engineering-tracker ticket (Linear) from an issue and link it. The Clad issue moves to On hold; a back-link comment is posted on the tracker ticket. Check linkedTickets first to avoid duplicates.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `FileTrackerTicketInput!` | Required. |

#### `generateDraft`

```graphql
generateDraft(input: GenerateDraftInput!): GenerateDraftResult
```

Generate a KB-grounded suggested reply through the same gated pipeline as automatic drafts. A declined gate returns withheld=true, not an error. CONFLICT when a pending draft already exists.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `GenerateDraftInput!` | Required. |

#### `generateDraftFromInvestigation`

```graphql
generateDraftFromInvestigation(investigationId: ID!): DraftResult
```

Turn a completed investigation's findings into a pending customer-reply draft. CONFLICT when the run is incomplete or reported no deliverable answer.

| Argument | Type | Description |
| --- | --- | --- |
| `investigationId` | `ID!` | Required. |

#### `startInvestigation`

```graphql
startInvestigation(input: StartInvestigationInput!): InvestigationResult
```

Start an asynchronous code or billing investigation for an issue. Per-org in-flight and daily caps apply (RATE_LIMITED when hit). Poll the investigation query for completion.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `StartInvestigationInput!` | Required. |

---

## Webhooks

> Every webhook endpoint and delivery query and mutation.

URL: https://docs.useclad.ai/api/reference-webhooks

Subscribe to events, verify signed deliveries, and manage endpoints.

### Queries

#### `webhookDeliveries`

```graphql
webhookDeliveries(endpointId: ID!, first: Int): [WebhookDelivery!]
```

Recent deliveries for an endpoint, newest first (max 100).

| Argument | Type | Description |
| --- | --- | --- |
| `endpointId` | `ID!` | Required. |
| `first` | `Int` |  |

#### `webhookEndpoints`

```graphql
webhookEndpoints: [WebhookEndpoint!]
```

All webhook endpoints registered for the organization.

#### `webhookEventTypes`

```graphql
webhookEventTypes: [String!]
```

Every event type webhooks can subscribe to.

### Mutations

#### `createWebhookEndpoint`

```graphql
createWebhookEndpoint(input: CreateWebhookEndpointInput!): WebhookEndpointWithSecretResult
```

Register a webhook endpoint. Returns the signing secret exactly once.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateWebhookEndpointInput!` | Required. |

#### `deleteWebhookEndpoint`

```graphql
deleteWebhookEndpoint(id: ID!): DeleteWebhookEndpointResult
```

Delete a webhook endpoint (pending deliveries are dropped).

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `pingWebhookEndpoint`

```graphql
pingWebhookEndpoint(id: ID!): PingWebhookResult
```

Queue a signed webhook.ping delivery to test an endpoint end to end.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `rotateWebhookSecret`

```graphql
rotateWebhookSecret(id: ID!): WebhookEndpointWithSecretResult
```

Rotate an endpoint's signing secret. The new secret is returned exactly once; the old one stops working immediately.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `updateWebhookEndpoint`

```graphql
updateWebhookEndpoint(input: UpdateWebhookEndpointInput!): WebhookEndpointResult
```

Update a webhook endpoint's URL, description, event filter, or active flag.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateWebhookEndpointInput!` | Required. |

---

## API keys

> Every API key and machine-user query and mutation.

URL: https://docs.useclad.ai/api/reference-api-keys

Manage programmatic access itself: API keys and the machine users (API principals) they belong to.

### Queries

#### `apiKeys`

```graphql
apiKeys(machineUserId: ID): [ApiKey!]
```

API key metadata (never secrets), optionally filtered to one machine user.

| Argument | Type | Description |
| --- | --- | --- |
| `machineUserId` | `ID` |  |

#### `machineUsers`

```graphql
machineUsers: [MachineUser!]
```

Service accounts in this organization.

### Mutations

#### `createApiKey`

```graphql
createApiKey(input: CreateApiKeyInput!): CreateApiKeyResult
```

Mint an API key for a service account. Human org admins only; the secret is returned exactly once.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateApiKeyInput!` | Required. |

#### `createMachineUser`

```graphql
createMachineUser(input: CreateMachineUserInput!): MachineUserResult
```

Create a service account. Human org admins only.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateMachineUserInput!` | Required. |

#### `revokeApiKey`

```graphql
revokeApiKey(id: ID!): ApiKeyResult
```

Revoke an API key immediately. Requires apikeys:revoke (admin-gated).

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `setMachineUserActive`

```graphql
setMachineUserActive(id: ID!, isActive: Boolean!): MachineUserResult
```

Enable/disable a service account (disabling blocks all of its keys). Human org admins only.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |
| `isActive` | `Boolean!` | Required. |

---

## Workspace

> Every teams, members, tags, widgets, SLA, and settings query and mutation.

URL: https://docs.useclad.ai/api/reference-workspace

Teams, members, tags, widgets, SLA policies, and workspace settings.

### Queries

#### `apiInfo`

```graphql
apiInfo: JSON
```

Public API metadata: version, schema hash, and server time.

#### `autoResponseSettings`

```graphql
autoResponseSettings: AutoResponseSettings
```

#### `members`

```graphql
members: [Member!]
```

All members of the authenticated organization.

#### `node`

```graphql
node(id: ID!): Node
```

Fetch any node-capable object by its globally unique opaque id.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `nodes`

```graphql
nodes(ids: [ID!]!): [Node]!
```

Fetch up to 50 nodes by globally unique opaque ids (null for unknown/foreign ids).

| Argument | Type | Description |
| --- | --- | --- |
| `ids` | `[ID!]!` | Required. |

#### `slaPolicies`

```graphql
slaPolicies: [SlaPolicy!]
```

The org's SLA policies with version history (evaluation order).

#### `supportHoursSchedules`

```graphql
supportHoursSchedules: [SupportHoursSchedule!]
```

The org's support-hours schedules (with intervals and holidays).

#### `tags`

```graphql
tags: [Tag!]
```

All workspace tags, alphabetical.

#### `teams`

```graphql
teams: [Team!]
```

All teams in the organization, each with its members.

#### `widget`

```graphql
widget(id: ID): Widget
```

A widget by id. Omit id to get (and lazily provision) the org's default widget.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID` |  |

#### `widgetForms`

```graphql
widgetForms: [WidgetForm!]
```

All widget intake forms for the organization.

#### `widgets`

```graphql
widgets: [Widget!]
```

#### `workspaceSettings`

```graphql
workspaceSettings: WorkspaceSettings
```

### Mutations

#### `addTeamMembers`

```graphql
addTeamMembers(profileIds: [ID!]!, teamId: ID!): TeamResult
```

Add org members to a team (skips profiles already on the team).

| Argument | Type | Description |
| --- | --- | --- |
| `profileIds` | `[ID!]!` | Opaque Profile ids of org members to add. |
| `teamId` | `ID!` | Required. |

#### `createTag`

```graphql
createTag(input: CreateTagInput!): TagResult
```

Create a workspace tag.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateTagInput!` | Required. |

#### `createTeam`

```graphql
createTeam(name: String!): TeamResult
```

Create a team.

| Argument | Type | Description |
| --- | --- | --- |
| `name` | `String!` | Required. |

#### `createWidget`

```graphql
createWidget(name: String): WidgetResult
```

Create an additional web widget (the org's first widget is the default).

| Argument | Type | Description |
| --- | --- | --- |
| `name` | `String` |  |

#### `createWidgetForm`

```graphql
createWidgetForm(input: CreateWidgetFormInput!): WidgetFormResult
```

Create a widget intake form (org-unique slug).

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `CreateWidgetFormInput!` | Required. |

#### `deleteTag`

```graphql
deleteTag(id: ID!): DeleteTagResult
```

Delete a tag and strip it from every issue and account.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `deleteTeam`

```graphql
deleteTeam(teamId: ID!): DeleteTeamResult
```

Delete a team (memberships and issue assignments cascade).

| Argument | Type | Description |
| --- | --- | --- |
| `teamId` | `ID!` | Required. |

#### `deleteWidget`

```graphql
deleteWidget(id: ID!): DeleteWidgetResult
```

Delete a web widget. Default resolution falls back to the earliest remaining widget.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `deleteWidgetForm`

```graphql
deleteWidgetForm(id: ID!): DeleteWidgetFormResult
```

Delete a widget intake form.

| Argument | Type | Description |
| --- | --- | --- |
| `id` | `ID!` | Required. |

#### `removeTeamMember`

```graphql
removeTeamMember(profileId: ID!, teamId: ID!): TeamResult
```

Remove a member from a team.

| Argument | Type | Description |
| --- | --- | --- |
| `profileId` | `ID!` | Opaque Profile id of the member to remove. |
| `teamId` | `ID!` | Required. |

#### `renameTeam`

```graphql
renameTeam(name: String!, teamId: ID!): TeamResult
```

Rename a team.

| Argument | Type | Description |
| --- | --- | --- |
| `name` | `String!` | Required. |
| `teamId` | `ID!` | Required. |

#### `updateAutoResponseSettings`

```graphql
updateAutoResponseSettings(input: UpdateAutoResponseInput!): AutoResponseResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateAutoResponseInput!` | Required. |

#### `updateTag`

```graphql
updateTag(input: UpdateTagInput!): TagResult
```

Rename/recolor a tag. Renames cascade to every issue and account carrying it.

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateTagInput!` | Required. |

#### `updateWidget`

```graphql
updateWidget(input: UpdateWidgetInput!): WidgetResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateWidgetInput!` | Required. |

#### `updateWidgetForm`

```graphql
updateWidgetForm(input: UpdateWidgetFormInput!): WidgetFormResult
```

Update a widget intake form (name, slug, fields, enabled).

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateWidgetFormInput!` | Required. |

#### `updateWorkspaceSettings`

```graphql
updateWorkspaceSettings(input: UpdateWorkspaceSettingsInput!): WorkspaceSettingsResult
```

| Argument | Type | Description |
| --- | --- | --- |
| `input` | `UpdateWorkspaceSettingsInput!` | Required. |

---

## Types

> Object, input, enum, and scalar types referenced by the API operations.

URL: https://docs.useclad.ai/api/types

Object, input, enum, and scalar types referenced by the operations above. Fields marked `!` are non-null.

List queries return a **connection** (`{ edges { node } pageInfo }`) — see [Pagination](#pagination). Mutations return a **result** payload that wraps the affected object plus an `error` field — see [Errors](#errors). Those wrapper types are omitted below; the objects they wrap are documented here.

### Objects

#### Account

A customer account (company) in the org's CRM.

| Field | Type | Description |
| --- | --- | --- |
| `arrAmount` | `Float` |  |
| `arrCadence` | `String` | monthly | quarterly | annual |
| `channelName` | `String` |  |
| `companyName` | `String` |  |
| `contractNextRenewal` | `String` | Next upcoming renewal date, rolled forward by cadence. |
| `contractNotes` | `String` |  |
| `contractRenewalDate` | `String` | ISO date of the contract anchor renewal. |
| `contractSeats` | `Int` |  |
| `createdAt` | `DateTime` |  |
| `customData` | `JSON` |  |
| `id` | `ID` |  |
| `lastActivityAt` | `DateTime` |  |
| `logoUrl` | `String` |  |
| `notes` | `String` |  |
| `ownerId` | `ID` | Profile id of the account owner (org member), if any. |
| `primaryDomain` | `String` |  |
| `projectedArr` | `Float` | Annualized ARR derived from amount x cadence. |
| `tags` | `[String!]` |  |
| `updatedAt` | `DateTime` |  |

#### AccountView

A saved filter/view for the Accounts surface (org-wide).

| Field | Type | Description |
| --- | --- | --- |
| `config` | `JSON` |  |
| `createdAt` | `DateTime` |  |
| `createdBy` | `ID` | Opaque Profile id of the view's creator. |
| `id` | `ID` |  |
| `isStarred` | `Boolean` |  |
| `name` | `String` |  |
| `updatedAt` | `DateTime` |  |

#### ApiKey

Metadata for a graph-native API key. The secret is only returned at mint time.

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `expiresAt` | `DateTime` |  |
| `id` | `ID` |  |
| `keyPrefix` | `String` |  |
| `lastUsedAt` | `DateTime` |  |
| `machineUserId` | `ID` |  |
| `name` | `String` |  |
| `revokedAt` | `DateTime` |  |
| `scopes` | `[String!]` |  |

#### Article

A knowledge-base article.

| Field | Type | Description |
| --- | --- | --- |
| `collectionId` | `ID` |  |
| `content` | `String` |  |
| `createdAt` | `DateTime` |  |
| `id` | `ID` |  |
| `isAiGenerated` | `Boolean` |  |
| `publishedAt` | `DateTime` |  |
| `slug` | `String` |  |
| `status` | `ArticleStatus` |  |
| `title` | `String` |  |
| `updatedAt` | `DateTime` |  |
| `visibility` | `ArticleVisibility` |  |

#### ArticleTemplate

A reusable starting-point template for new KB articles.

| Field | Type | Description |
| --- | --- | --- |
| `content` | `String` |  |
| `createdAt` | `DateTime` |  |
| `createdBy` | `ID` | Opaque Profile id of the creator (null for machine-created templates). |
| `id` | `ID` |  |
| `name` | `String` |  |
| `updatedAt` | `DateTime` |  |

#### AutoResponseSettings

Org-level AI auto-response configuration.

| Field | Type | Description |
| --- | --- | --- |
| `enabled` | `Boolean` |  |
| `ignoredAccountIds` | `[ID!]` | Accounts whose issues never receive auto-responses. |
| `kbScope` | `JSON` | Knowledge-base scope: { mode: all|custom, collection_ids, article_ids, statuses }. |
| `prompt` | `String` |  |

#### Collection

A knowledge-base collection (folder) grouping articles.

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `description` | `String` |  |
| `icon` | `String` |  |
| `id` | `ID` |  |
| `name` | `String` |  |
| `updatedAt` | `DateTime` |  |

#### Contact

A contact (end user) in the org's CRM, optionally linked to an account.

| Field | Type | Description |
| --- | --- | --- |
| `accountId` | `ID` |  |
| `avatarUrl` | `String` |  |
| `createdAt` | `DateTime` |  |
| `customData` | `JSON` |  |
| `email` | `String` |  |
| `id` | `ID` |  |
| `name` | `String` |  |
| `updatedAt` | `DateTime` |  |

#### CustomField

A custom-field (metadata) definition for accounts or contacts.

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `String` |  |
| `description` | `String` |  |
| `fieldKey` | `String` |  |
| `fieldType` | `CustomFieldType` |  |
| `id` | `ID` |  |
| `label` | `String` |  |
| `options` | `JSON` |  |
| `position` | `Int` |  |
| `width` | `Int` |  |

#### Draft

An AI-suggested reply awaiting human review. Lifecycle: generating → pending → approved (sent) | rejected | superseded; low-value attempts land in discarded_* statuses.

| Field | Type | Description |
| --- | --- | --- |
| `approvedAt` | `DateTime` |  |
| `body` | `String` | Suggested reply (HTML). |
| `createdAt` | `DateTime` |  |
| `generatedBy` | `String` |  |
| `generationTrigger` | `String` | auto | manual | retry | regenerate | replay |
| `id` | `ID` |  |
| `issueId` | `ID` |  |
| `modelConfidence` | `Float` |  |
| `rejectionReason` | `String` |  |
| `sources` | `[DraftSource!]` | Grounding sources the draft was generated from. |
| `status` | `String` |  |
| `type` | `String` | response | investigation | acknowledgement | clarify | partial_findings |
| `updatedAt` | `DateTime` |  |

#### DraftSource

One grounding source behind a draft: a knowledge-base article or a previously resolved ticket.

| Field | Type | Description |
| --- | --- | --- |
| `articleId` | `ID` | Opaque Article id when the source is a KB article. |
| `confidence` | `Float` |  |
| `excerpt` | `String` |  |
| `resolvedAt` | `DateTime` |  |
| `sourceIssueId` | `ID` | Opaque Issue id when the source is a resolved ticket. |
| `title` | `String` |  |
| `type` | `String` | knowledge_base | similar_issue | account | contact | open_issue |
| `url` | `String` |  |

#### FeaturedArticle

An explicitly pinned help-center homepage article. Unavailable pins remain listed so clients can preserve or reorder them.

| Field | Type | Description |
| --- | --- | --- |
| `collectionId` | `ID` |  |
| `id` | `ID` |  |
| `isAvailable` | `Boolean` | Whether the article is currently eligible to render publicly: published, public, listed, and in an included collection. |
| `isUnlisted` | `Boolean` |  |
| `position` | `Int` | Zero-based manual homepage position. |
| `slug` | `String` |  |
| `status` | `ArticleStatus` |  |
| `title` | `String` |  |
| `unavailableReason` | `String` | Stable reason the retained pin is hidden, or null when available. |
| `updatedAt` | `DateTime` |  |
| `visibility` | `ArticleVisibility` |  |

#### FeaturedArticleCandidate

Lightweight metadata for a live article eligible for a new homepage pin.

| Field | Type | Description |
| --- | --- | --- |
| `collectionId` | `ID` |  |
| `currentPosition` | `Int` | Current zero-based pin position, or null when the article is not pinned. |
| `id` | `ID` |  |
| `slug` | `String` |  |
| `title` | `String` |  |
| `updatedAt` | `DateTime` |  |

#### Investigation

An AI investigation run (code or billing) for an issue. Runs are asynchronous: poll status until complete/failed. The raw agent transcript is never exposed.

| Field | Type | Description |
| --- | --- | --- |
| `answerFound` | `Boolean` | Whether the run reached a deliverable answer. false blocks generateDraftFromInvestigation. |
| `completedAt` | `DateTime` |  |
| `createdAt` | `DateTime` |  |
| `error` | `String` |  |
| `id` | `ID` |  |
| `issueId` | `ID` |  |
| `kind` | `String` | code | billing |
| `output` | `String` | Findings (markdown). Null until complete. |
| `provider` | `String` | Engine that ran it (claude/codex/cursor, or stripe for billing). |
| `repo` | `String` | GitHub repo investigated (code runs). |
| `startedAt` | `DateTime` |  |
| `status` | `String` | queued | running | complete | failed |
| `subjectRef` | `String` | Stripe customer investigated (billing runs). |
| `summary` | `String` | Short triage summary of the findings. |

#### Issue

A support issue (ticket) in an organization's inbox.

| Field | Type | Description |
| --- | --- | --- |
| `account` | `Account` | The linked CRM account, if any. Requires accounts:read. |
| `accountId` | `ID` | Opaque Account id this issue is linked to, if any. |
| `assignedTo` | `ID` | Opaque Profile id of the assigned org member, if any. |
| `contact` | `Contact` | The linked CRM contact (requester), if any. Requires contacts:read. |
| `contactId` | `ID` | Opaque Contact id of the requester, if linked. |
| `createdAt` | `DateTime` |  |
| `followers` | `[Profile!]` | Org members following this issue. Requires members:read. |
| `id` | `ID` |  |
| `intakeSource` | `String` |  |
| `isSpam` | `Boolean` |  |
| `isTrashed` | `Boolean` |  |
| `lastMessageAt` | `DateTime` |  |
| `lastMessagePreview` | `String` |  |
| `manualTeamIds` | `[ID!]` | Opaque Team ids assigned directly on this issue (excludes account-inherited teams). |
| `messages` | `MessageConnection` | Thread messages for this issue, oldest first (cursor-paginated). |
| `priority` | `IssuePriority` |  |
| `status` | `IssueStatus` |  |
| `subject` | `String` |  |
| `tags` | `[String!]` |  |
| `teamIds` | `[ID!]` | Opaque Team ids routed to this issue (manual assignments merged with teams inherited from the linked account). |
| `ticketNumber` | `Int` |  |
| `updatedAt` | `DateTime` |  |

#### MachineUser

A non-human API principal (service account) that owns API keys.

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `id` | `ID` |  |
| `isActive` | `Boolean` |  |
| `name` | `String` |  |
| `publicDisplayName` | `String` |  |

#### Member

An organization membership (a person + their role in the org).

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `id` | `ID` |  |
| `profile` | `Profile` |  |
| `profileId` | `ID` |  |
| `role` | `String` |  |

#### Message

A single message in an issue's thread (inbound or outbound).

| Field | Type | Description |
| --- | --- | --- |
| `attachments` | `JSON` |  |
| `body` | `String` |  |
| `createdAt` | `DateTime` |  |
| `direction` | `String` |  |
| `externalMessageId` | `String` |  |
| `id` | `ID` |  |
| `isInternal` | `Boolean` |  |
| `senderAvatarUrl` | `String` |  |
| `senderName` | `String` |  |
| `senderType` | `String` |  |

#### Node

An object with a globally unique opaque ID (Relay global object identification).

| Field | Type | Description |
| --- | --- | --- |
| `id` | `ID` | Globally unique opaque id. |

#### Profile

A person's profile (org member / team member).

| Field | Type | Description |
| --- | --- | --- |
| `availability` | `String` |  |
| `avatarUrl` | `String` |  |
| `displayName` | `String` |  |
| `email` | `String` |  |
| `id` | `ID` |  |

#### SlaPolicy

An SLA policy (evaluation order = priorityOrder ascending). Read-only in API v1.

| Field | Type | Description |
| --- | --- | --- |
| `conditionJson` | `JSON` |  |
| `createdAt` | `DateTime` |  |
| `description` | `String` |  |
| `id` | `ID` |  |
| `isActive` | `Boolean` |  |
| `isDefault` | `Boolean` |  |
| `name` | `String` |  |
| `priorityFilter` | `[String!]` | Issue priorities this policy applies to (null = all). |
| `priorityOrder` | `Int` |  |
| `scheduleId` | `ID` | Opaque SupportHoursSchedule id the timers run against (null = 24/7). |
| `scope` | `String` |  |
| `teamId` | `ID` | Opaque Team id when the policy is team-scoped. |
| `updatedAt` | `DateTime` |  |
| `versions` | `[SlaPolicyVersion!]` | Version history, newest first (versions[0] is in force). |

#### SlaPolicyVersion

An immutable version of an SLA policy's timing targets.

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `firstResponseMinutes` | `Int` |  |
| `id` | `ID` |  |
| `nextResponseMinutes` | `Int` |  |
| `pauseOnStatuses` | `[String!]` |  |
| `prebreachMinutes` | `Int` |  |
| `resolutionMinutes` | `Int` |  |
| `versionNumber` | `Int` |  |

#### SupportHoursHoliday

| Field | Type | Description |
| --- | --- | --- |
| `holidayDate` | `String` | ISO date (YYYY-MM-DD). |
| `id` | `ID` |  |
| `name` | `String` |  |

#### SupportHoursInterval

| Field | Type | Description |
| --- | --- | --- |
| `dayOfWeek` | `Int` | 0 = Sunday … 6 = Saturday. |
| `endTime` | `String` |  |
| `id` | `ID` |  |
| `startTime` | `String` | HH:MM (schedule timezone). |

#### SupportHoursSchedule

A business-hours schedule SLA timers can run against. Read-only in API v1.

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `holidays` | `[SupportHoursHoliday!]` |  |
| `id` | `ID` |  |
| `intervals` | `[SupportHoursInterval!]` |  |
| `isDefault` | `Boolean` |  |
| `name` | `String` |  |
| `timezone` | `String` |  |

#### Tag

A workspace tag applied to issues and accounts.

| Field | Type | Description |
| --- | --- | --- |
| `color` | `String` |  |
| `createdAt` | `DateTime` |  |
| `id` | `ID` |  |
| `name` | `String` |  |

#### Team

A team within an organization.

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `id` | `ID` |  |
| `members` | `[TeamMember!]` |  |
| `name` | `String` |  |
| `updatedAt` | `DateTime` |  |

#### TeamMember

| Field | Type | Description |
| --- | --- | --- |
| `id` | `ID` |  |
| `profile` | `Profile` |  |

#### TrackerTicket

An engineering-tracker ticket (Linear) linked to a Clad issue, with live state and discussion.

| Field | Type | Description |
| --- | --- | --- |
| `assigneeName` | `String` |  |
| `comments` | `[TrackerTicketComment!]` |  |
| `identifier` | `String` | Human identifier, e.g. ENG-123. |
| `priorityLabel` | `String` |  |
| `state` | `String` | Workflow state name, e.g. In Progress. |
| `stateType` | `String` | backlog | unstarted | started | completed | canceled |
| `ticketId` | `String` | Tracker-native ticket id. |
| `title` | `String` |  |
| `tracker` | `String` | Currently always linear. |
| `updatedAt` | `DateTime` |  |
| `url` | `String` |  |

#### TrackerTicketComment

A comment on a linked engineering-tracker ticket.

| Field | Type | Description |
| --- | --- | --- |
| `authorName` | `String` |  |
| `body` | `String` |  |
| `createdAt` | `DateTime` |  |
| `id` | `String` |  |

#### WebhookDelivery

One delivery attempt record for an event → endpoint pair (debug surface).

| Field | Type | Description |
| --- | --- | --- |
| `attemptCount` | `Int` |  |
| `createdAt` | `DateTime` |  |
| `eventId` | `String` | Consumer-side dedupe key (also the clad-webhook-id header). |
| `eventType` | `String` |  |
| `id` | `ID` |  |
| `lastAttemptAt` | `DateTime` |  |
| `lastError` | `String` |  |
| `nextAttemptAt` | `DateTime` |  |
| `payload` | `JSON` |  |
| `responseStatus` | `Int` |  |
| `status` | `String` | pending | delivering | succeeded | dead |

#### WebhookEndpoint

A customer-registered webhook receiver. The signing secret is returned exactly once (create/rotate) and never readable again.

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `description` | `String` |  |
| `events` | `[String!]` | Subscribed event types ("*" = all). |
| `id` | `ID` |  |
| `isActive` | `Boolean` |  |
| `updatedAt` | `DateTime` |  |
| `url` | `String` |  |

#### Widget

A web chat widget's configuration (the product-platform surface: toggles, theme, launcher, features).

| Field | Type | Description |
| --- | --- | --- |
| `ai` | `JSON` |  |
| `allowedOrigins` | `[String!]` |  |
| `createdAt` | `DateTime` |  |
| `enabled` | `Boolean` |  |
| `features` | `JSON` |  |
| `id` | `ID` |  |
| `identity` | `JSON` |  |
| `isDefault` | `Boolean` |  |
| `launcher` | `JSON` |  |
| `locale` | `String` |  |
| `name` | `String` |  |
| `routing` | `JSON` |  |
| `theme` | `JSON` |  |
| `updatedAt` | `DateTime` |  |

#### WidgetForm

A structured intake form rendered by the web widget.

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `DateTime` |  |
| `description` | `String` |  |
| `enabled` | `Boolean` |  |
| `fields` | `JSON` |  |
| `id` | `ID` |  |
| `name` | `String` |  |
| `slug` | `String` |  |
| `updatedAt` | `DateTime` |  |

#### WorkspaceSettings

Org-level workspace toggles: email signature, trash retention, reactions behavior.

| Field | Type | Description |
| --- | --- | --- |
| `emailSignature` | `String` |  |
| `issueClosedAutoArchiveDays` | `Int` | Auto-archive closed issues out of the Closed column after N days (null = never; 7, 14, 30, or 90). Display-only; archived issues stay in search, analytics, and AI context. |
| `issueTrashAutoClearDays` | `Int` | Auto-clear trashed issues after N days (null = never; 30 or 90). |
| `reactionsChangeStatus` | `Boolean` |  |

### Input objects

#### ApproveDraftInput

| Field | Type | Description |
| --- | --- | --- |
| `draftId` | `ID!` |  |
| `editedBody` | `String` | Optional replacement body (HTML) to send instead of the draft text. |

#### CommentOnLinkedTicketInput

| Field | Type | Description |
| --- | --- | --- |
| `body` | `String!` |  |
| `issueId` | `ID!` |  |
| `ticketIdentifier` | `String` | Which linked ticket to comment on (e.g. ENG-123). Optional when exactly one is linked. |

#### CreateAccountInput

| Field | Type | Description |
| --- | --- | --- |
| `arrAmount` | `Float` |  |
| `arrCadence` | `String` | monthly | quarterly | annual |
| `companyName` | `String!` |  |
| `contractNotes` | `String` |  |
| `contractRenewalDate` | `String` | ISO date (YYYY-MM-DD). |
| `contractSeats` | `Int` |  |
| `customData` | `JSON` |  |
| `logoUrl` | `String` |  |
| `notes` | `String` |  |
| `ownerId` | `ID` | Profile id of the org member who owns this account. |
| `primaryDomain` | `String` |  |
| `tags` | `[String!]` |  |

#### CreateAccountViewInput

| Field | Type | Description |
| --- | --- | --- |
| `config` | `JSON` |  |
| `isStarred` | `Boolean` |  |
| `name` | `String!` |  |

#### CreateApiKeyInput

| Field | Type | Description |
| --- | --- | --- |
| `expiresAt` | `DateTime` |  |
| `machineUserId` | `ID!` |  |
| `name` | `String` |  |
| `scopes` | `[String!]!` |  |

#### CreateArticleInput

| Field | Type | Description |
| --- | --- | --- |
| `collectionId` | `ID` |  |
| `content` | `String` |  |
| `slug` | `String` |  |
| `status` | `ArticleStatus` |  |
| `title` | `String!` |  |
| `visibility` | `ArticleVisibility` |  |

#### CreateArticleTemplateInput

| Field | Type | Description |
| --- | --- | --- |
| `content` | `String` |  |
| `name` | `String!` |  |

#### CreateCollectionInput

| Field | Type | Description |
| --- | --- | --- |
| `description` | `String` |  |
| `icon` | `String` |  |
| `name` | `String!` |  |

#### CreateContactInput

| Field | Type | Description |
| --- | --- | --- |
| `accountId` | `ID` |  |
| `customData` | `JSON` |  |
| `email` | `String` |  |
| `name` | `String!` |  |

#### CreateCustomFieldInput

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `String` |  |
| `description` | `String` |  |
| `entity` | `CustomFieldEntity!` |  |
| `fieldType` | `CustomFieldType!` |  |
| `label` | `String!` |  |
| `options` | `JSON` |  |
| `position` | `Int` | Column position; defaults to the end. |
| `width` | `Int` |  |

#### CreateIssueInput

| Field | Type | Description |
| --- | --- | --- |
| `accountId` | `ID` |  |
| `body` | `String!` |  |
| `contactId` | `ID` |  |
| `externalId` | `String` |  |
| `idempotencyKey` | `String` |  |
| `priority` | `IssuePriority` |  |
| `requesterEmail` | `String` |  |
| `requesterName` | `String` |  |
| `subject` | `String!` |  |
| `tags` | `[String!]` |  |

#### CreateMachineUserInput

| Field | Type | Description |
| --- | --- | --- |
| `name` | `String!` |  |
| `publicDisplayName` | `String` |  |

#### CreateTagInput

| Field | Type | Description |
| --- | --- | --- |
| `color` | `String` |  |
| `name` | `String!` |  |

#### CreateWebhookEndpointInput

| Field | Type | Description |
| --- | --- | --- |
| `description` | `String` |  |
| `events` | `[String!]` | Event types to subscribe to; omit or ["*"] for all. |
| `url` | `String!` | HTTPS receiver URL. |

#### CreateWidgetFormInput

| Field | Type | Description |
| --- | --- | --- |
| `description` | `String` |  |
| `enabled` | `Boolean` |  |
| `fields` | `JSON` | Array of field definitions. |
| `name` | `String!` |  |
| `slug` | `String!` | Lowercase letters/numbers/hyphens; unique per org. |

#### DeleteCustomFieldInput

| Field | Type | Description |
| --- | --- | --- |
| `entity` | `CustomFieldEntity!` |  |
| `id` | `ID!` |  |

#### DenyDraftInput

| Field | Type | Description |
| --- | --- | --- |
| `draftId` | `ID!` |  |
| `reason` | `String` | Why the draft was rejected — feeds regeneration and quality analytics. |

#### FileTrackerTicketInput

| Field | Type | Description |
| --- | --- | --- |
| `description` | `String` | Ticket body (markdown). Include the relevant findings/context yourself. |
| `issueId` | `ID!` |  |
| `team` | `String` | Tracker team key or name. Optional when the workspace has exactly one team. |
| `title` | `String!` |  |

#### GenerateDraftInput

| Field | Type | Description |
| --- | --- | --- |
| `instructions` | `String` | Optional steering folded into the generation prompt (max ~2000 chars). |
| `issueId` | `ID!` |  |

#### ReplaceFeaturedArticlesInput

The complete ordered homepage pin set. Omitted prior pins are unpinned; an empty list restores automatic recency.

| Field | Type | Description |
| --- | --- | --- |
| `articleIds` | `[ID!]!` | Up to 6 unique opaque Article ids in the desired order. |

#### ReplyToIssueInput

| Field | Type | Description |
| --- | --- | --- |
| `body` | `String!` |  |
| `isInternal` | `Boolean` |  |
| `issueId` | `ID!` |  |

#### StartInvestigationInput

| Field | Type | Description |
| --- | --- | --- |
| `issueId` | `ID!` |  |
| `kind` | `InvestigationKind!` |  |
| `repo` | `String` | Code runs: https://github.com/<owner>/<repo> to investigate. Defaults to the workspace's configured repo. |
| `subjectRef` | `String` | Billing runs: Stripe customer id (cus_…) override. |

#### UpdateAccountInput

| Field | Type | Description |
| --- | --- | --- |
| `arrAmount` | `Float` |  |
| `arrCadence` | `String` | monthly | quarterly | annual |
| `companyName` | `String` |  |
| `contractNotes` | `String` |  |
| `contractRenewalDate` | `String` | ISO date (YYYY-MM-DD); null to clear. |
| `contractSeats` | `Int` |  |
| `customData` | `JSON` | Merged into existing custom data (per-key set; pass a null value to clear a key; pass null to clear all user-defined keys). Clad-reserved system keys (merge/integration metadata) are ignored on write and survive a clear. |
| `id` | `ID!` |  |
| `logoUrl` | `String` |  |
| `notes` | `String` |  |
| `ownerId` | `ID` | Profile id of the org member who owns this account; null to clear. |
| `primaryDomain` | `String` |  |
| `tags` | `[String!]` |  |

#### UpdateAccountViewInput

| Field | Type | Description |
| --- | --- | --- |
| `config` | `JSON` |  |
| `id` | `ID!` |  |
| `isStarred` | `Boolean` |  |
| `name` | `String` |  |

#### UpdateArticleInput

| Field | Type | Description |
| --- | --- | --- |
| `collectionId` | `ID` |  |
| `content` | `String` |  |
| `id` | `ID!` |  |
| `slug` | `String` |  |
| `status` | `ArticleStatus` |  |
| `title` | `String` |  |
| `visibility` | `ArticleVisibility` |  |

#### UpdateArticleTemplateInput

| Field | Type | Description |
| --- | --- | --- |
| `content` | `String` |  |
| `id` | `ID!` |  |
| `name` | `String` |  |

#### UpdateAutoResponseInput

| Field | Type | Description |
| --- | --- | --- |
| `enabled` | `Boolean` |  |
| `ignoredAccountIds` | `[ID!]` | Account ids whose issues never receive auto-responses. |
| `kbScope` | `JSON` | { mode: all|custom, collection_ids: [uuid], article_ids: [uuid], statuses: [published|draft] } |
| `prompt` | `String` |  |

#### UpdateCollectionInput

| Field | Type | Description |
| --- | --- | --- |
| `description` | `String` | Explicit null clears the description. |
| `icon` | `String` | Explicit null resets to the default icon. |
| `id` | `ID!` |  |
| `name` | `String` |  |

#### UpdateContactInput

| Field | Type | Description |
| --- | --- | --- |
| `accountId` | `ID` |  |
| `customData` | `JSON` |  |
| `email` | `String` |  |
| `id` | `ID!` |  |
| `name` | `String` |  |

#### UpdateCustomFieldInput

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `String` | null clears. |
| `description` | `String` | null clears. |
| `entity` | `CustomFieldEntity!` |  |
| `fieldType` | `CustomFieldType` |  |
| `id` | `ID!` |  |
| `label` | `String` |  |
| `options` | `JSON` |  |
| `position` | `Int` | Column position (drag-order). |
| `width` | `Int` | null clears (falls back to default width). |

#### UpdateTagInput

| Field | Type | Description |
| --- | --- | --- |
| `color` | `String` |  |
| `id` | `ID!` |  |
| `name` | `String` |  |

#### UpdateWebhookEndpointInput

| Field | Type | Description |
| --- | --- | --- |
| `description` | `String` | null clears. |
| `events` | `[String!]` |  |
| `id` | `ID!` |  |
| `isActive` | `Boolean` |  |
| `url` | `String` |  |

#### UpdateWidgetFormInput

| Field | Type | Description |
| --- | --- | --- |
| `description` | `String` |  |
| `enabled` | `Boolean` |  |
| `fields` | `JSON` |  |
| `id` | `ID!` |  |
| `name` | `String` |  |
| `slug` | `String` |  |

#### UpdateWidgetInput

| Field | Type | Description |
| --- | --- | --- |
| `ai` | `JSON` |  |
| `allowedOrigins` | `[String!]` |  |
| `enabled` | `Boolean` |  |
| `features` | `JSON` |  |
| `id` | `ID!` |  |
| `identity` | `JSON` |  |
| `launcher` | `JSON` |  |
| `locale` | `String` |  |
| `name` | `String` |  |
| `routing` | `JSON` |  |
| `theme` | `JSON` |  |

#### UpdateWorkspaceSettingsInput

| Field | Type | Description |
| --- | --- | --- |
| `emailSignature` | `String` | Signature appended to outbound email replies; null to clear. |
| `issueClosedAutoArchiveDays` | `Int` | null = never, 7, 14, 30, or 90. |
| `issueTrashAutoClearDays` | `Int` | null = never, 30, or 90. |
| `reactionsChangeStatus` | `Boolean` |  |

### Enums

#### ArticleStatus

`draft` · `published`

#### ArticleVisibility

`ai_agent_only` · `customer` · `internal` · `public`

#### CustomFieldEntity

`account` · `contact`

#### CustomFieldType

`boolean` · `date` · `datetime` · `multi_select` · `number` · `select` · `text` · `url` · `user`

#### InboxTarget

`all` · `following` · `my` · `spam` · `trash`

#### InvestigationKind

`billing` · `code`

#### IssuePriority

`high` · `low` · `normal` · `urgent`

#### IssueSortKey

`createdAt` · `updatedAt`

#### IssueStatus

`closed` · `new` · `on_customer` · `on_hold` · `on_you`

### Scalars

- `DateTime` — Custom scalar.
- `JSON` — Custom scalar.

<!-- END GENERATED REFERENCE -->

---

# MCP

> Connect AI agents — Claude, Cursor, ChatGPT, Codex — to your workspace with the hosted Model Context Protocol server.

---

## Overview

> Connect AI agents to your Clad workspace with the hosted Model Context Protocol server — same permissions and object ids as the API.

URL: https://docs.useclad.ai/mcp/overview

The MCP server lets any MCP-compatible agent act in your Clad workspace with the
same permission model as the API.

```
https://clad-server-production.up.railway.app/mcp
```

- **Transport**: Streamable HTTP — the current MCP standard. There is no local
  install and no stdio bridge; point your client at the URL above.
- **Tools, not schema**: the server exposes more than 60 purpose-built tools
  (`search_issues`, `reply_to_issue`, `create_article`, …) with typed inputs and
  human-readable descriptions. Agents call these far more reliably than they
  navigate a raw GraphQL schema.
- **Same objects, same ids**: every id an MCP tool returns is a global object id
  that works verbatim in the GraphQL API, and vice versa — so you can start in an
  agent and finish in a script without translating ids.

Two ways to connect, depending on who is acting:

| | Who acts | Auth | Best for |
|---|---|---|---|
| **OAuth** | A person, through their agent | Sign in with your Clad account | Cursor, Claude, ChatGPT, day-to-day agent use |
| **API key** | A headless service | `Authorization: Bearer clad_mk_...` | Backend automation, cron jobs, CI |

Copy-ready connection snippets for every client live in **Settings → MCP** in the
Clad app.

---

## Connect an agent (OAuth)

> Add the server to Cursor, Claude, ChatGPT, or Codex and authorize with your Clad login — no keys to copy.

URL: https://docs.useclad.ai/mcp/connect-agent

Add the server to your client and complete the sign-in prompt — there are no keys
to copy.

**Cursor** — add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "clad": { "url": "https://clad-server-production.up.railway.app/mcp" }
  }
}
```

**Claude Code**:

```bash
claude mcp add --transport http clad https://clad-server-production.up.railway.app/mcp
```

**OpenClaw** — add to `~/.openclaw/openclaw.json` under `mcp.servers`, then run
`openclaw mcp login clad` to sign in and `openclaw mcp probe clad` to verify:

```json
{
  "mcp": {
    "servers": {
      "clad": {
        "url": "https://clad-server-production.up.railway.app/mcp",
        "transport": "streamable-http",
        "auth": "oauth"
      }
    }
  }
}
```

**Other clients** — Claude Desktop custom connectors, VS Code, and ChatGPT
developer mode all accept the same URL. Copy-ready snippets for each live in
**Settings → MCP**.

### The sign-in flow

On first connect your agent opens a browser window:

1. Sign in with your Clad account.
2. Pick the workspace to connect.
3. Review the exact scopes the agent requested, then authorize.

Clad runs a full **OAuth 2.1** authorization server — PKCE, dynamic client
registration, refresh-token rotation with reuse detection, and RFC 8707 resource
audiencing — the flow your client drives automatically. You never paste a secret.

### Acting as you

An OAuth connection acts on your behalf: issues you reply to and records you
create are attributed to **you**, not to the agent's name. The connection's
identity (e.g. "Cursor") is only used for the audit trail of which agent made the
call.

### Live role enforcement

Grants follow your role **live**: if you are demoted or removed from the
workspace, the agent's tokens and refreshes are clamped or revoked immediately —
an agent never keeps powers its owner lost. Review and disconnect agents anytime
from **Settings → MCP → Connected agents**; disconnecting takes effect instantly.

---

## Connect a service (API key)

> Use an API key bearer token for headless automation on the same MCP endpoint.

URL: https://docs.useclad.ai/mcp/connect-service

For headless automation, the MCP endpoint accepts the same API keys as the
GraphQL API. Create a key in **Settings → API**, choose its scopes, and send it
as a bearer token:

```
Authorization: Bearer clad_mk_...
```

The key's scopes decide which tools the credential sees (see
[Scopes & the tool list](#scopes--the-tool-list)). Use least-privilege keys:
a read-only key for reporting agents, a write key only where the automation needs
to make changes.

Keep API keys backend-only — never ship them in browser, mobile, or agent config
that a customer could read. For anything a person drives interactively, prefer
[OAuth](#connect-an-agent-oauth).

---

## Scopes & the tool list

> The tool list is scope-filtered: a credential only sees the tools it can actually call.

URL: https://docs.useclad.ai/mcp/scopes

The MCP server reuses the API [scope taxonomy](/api/scopes) unchanged, and **the
tool list itself is scope-filtered**: a credential only ever sees the tools it
can actually call.

- A **read-only** grant sees search/get/list tools.
- `issues:write` adds issue mutations; `accounts:write` adds CRM writes; and so
  on per resource.
- **Admin-gated** scopes (`settings:write`, `webhooks:manage`, …) require an
  admin grant and unlock the settings and webhook tools.

Article create/update tools use `articles:write`; a request that makes an
article both `published` and `public` additionally requires
`articles:publish`. Publication is member-eligible and coarse `write` satisfies
the publish scope; a narrowly scoped `articles:write` key needs the explicit
`articles:publish` grant.

Help-center homepage curation follows the same permission model. Call
`list_featured_articles` before `replace_featured_articles`: replacement is
atomic and complete, so omitted pins are unpinned, while unavailable pins remain
listed for explicit preservation. Pass an empty `articleIds` list to clear
manual pins and restore automatic recency. The replacement tool is visible
only when the credential satisfies both `articles:write` and
`articles:publish`. New pins must be live and belong to an included collection;
already-pinned unavailable articles may still be retained or reordered.

Because the surface is filtered, an agent can't even attempt a tool it lacks the
scope for — there's nothing to call.

> Agents should call **`whoami` first**. It returns the workspace, the granted
> scopes, and guidance on what to do if an expected tool is missing (usually: the
> credential needs a broader scope, or an admin grant).

---

## Working with a helpdesk (Pylon, Zendesk)

> Mirrored helpdesk tickets are regular issues: the same tools triage them, and replies deliver into Pylon or Zendesk.

URL: https://docs.useclad.ai/mcp/helpdesk

If the workspace has Pylon or Zendesk connected, tickets from the helpdesk are
mirrored into Clad as regular issues. Nothing changes for your agent: the same
issue tools work on them, no helpdesk-specific tools or scopes needed.

- **Read and triage** — `search_issues`, `get_issue`, `set_issue_status`,
  `set_issue_priority`, `assign_issue`, `set_issue_tags` all work on mirrored
  tickets. New customer messages arrive via the helpdesk's webhook within
  seconds.
- **Reply** — `reply_to_issue` delivers the reply **into the helpdesk itself**,
  as the workspace's connected support seat. The customer sees it in Pylon or
  Zendesk (and by email if that's the ticket's channel). The result's
  `delivery` field is `pylon` or `zendesk` on success.
- **Internal notes** — `reply_to_issue` with `isInternal: true` stays in Clad
  and is never written to the helpdesk.

Two things to know before replying:

1. **The connection must be in Assist mode.** In Observe mode Clad never writes
   to the helpdesk; the tool returns a `FORBIDDEN` error saying so. An admin
   switches modes in Settings → Integrations — this is enforced server-side, so
   there is no way around it from the agent.
2. **Sends are idempotent.** Retrying the same reply to the same customer
   message never double-posts; the duplicate returns
   `delivery: pylon_deduplicated` / `zendesk_deduplicated`.

### How this relates to Clad's built-in agents

Clad also ships its own agents for helpdesk workspaces, and they run in two
places: the Clad app, and the **Clad panel embedded inside the Zendesk ticket
sidebar / Pylon issue view**. The panel is where human agents run code and
billing investigations on the ticket they're viewing, turn findings into a
suggested reply, approve it, and file tracker tickets — all without leaving
the helpdesk. Clad also auto-drafts suggested replies on new customer
messages, which teammates approve in Clad or in the panel.

The same workflow is exposed to external agents too — see
[Investigations, drafts & escalation](#investigations-drafts--escalation) for
running investigations, reviewing and approving drafts, and filing tracker
tickets over MCP. Customer messages and approved replies all land in the
issue's message thread, so `get_issue` gives an external agent the same
conversation your team sees.

That's the whole model: connect your helpdesk in Clad once (Settings →
Integrations, or the guided setup under Agents), connect your agent to this MCP
server, and the agent can work the helpdesk queue end to end — triage,
investigate, draft, reply, escalate — without a helpdesk API integration of
its own.

---

## Investigations, drafts & escalation

> Run Clad's AI-agent workflow over MCP: investigate tickets, review grounded reply drafts, approve or deny them, and escalate to the tracker.

URL: https://docs.useclad.ai/mcp/agents

Beyond the inbox tools, the server exposes Clad's AI-agent workflow itself, so
an external agent can run the same playbook a human runs in the Clad panel.

**Check the connection first.** `get_helpdesk_connection` reports the provider
(Pylon/Zendesk), status, and operating mode. In **Observe** mode Clad never
writes to the helpdesk — drafts can still be generated and reviewed, but
`approve_draft` (and `reply_to_issue`) will return `FORBIDDEN` until an admin
switches the connection to **Assist**.

**Investigations.** `start_investigation` kicks off an asynchronous dig into
the root cause of a ticket: `kind: "code"` works through the connected GitHub
repo, `kind: "billing"` works through Stripe for the customer's billing state.
Runs take a few minutes — poll `get_investigation` until `status` is
`complete` (or `failed`), then read `output` (markdown findings), `summary`,
and `answerFound`. Per-workspace in-flight and daily caps protect spend; when
you hit one the tool returns `RATE_LIMITED`.

**Drafts.** Clad auto-drafts a suggested reply when a customer message comes
in and the knowledge base has a confident answer. `get_latest_draft` reads the
newest attempt for an issue — its `status` tells you whether it's `generating`,
`pending` (awaiting review), `discarded_*` (the gate declined), `approved`, or
`rejected` — and its `sources` list the knowledge-base articles and resolved
tickets the answer was grounded in, so you can verify it before acting.
`generate_draft` produces one on demand through the same gated pipeline
(optionally steered with `instructions`); a declined gate returns
`withheld: true` with the reason, not an error.
`generate_draft_from_investigation` turns a completed investigation's findings
into a pending draft.

**Review.** `approve_draft` sends the draft to the customer;
`deny_draft` rejects it with a reason (which feeds regeneration and quality
analytics). Approving requires a **human-authorized credential** — an OAuth
grant from a signed-in teammate — because the send is attributed to the
approving person; headless API keys can generate and deny drafts but not
approve them. v1 delivers approvals on helpdesk-mirrored issues
(Pylon/Zendesk); other channels approve in the Clad app.

**Escalation.** When a ticket needs engineering, `file_tracker_ticket` files a
Linear ticket from the issue and links it — the Clad issue moves to On hold
and the tracker ticket gets a back-link comment with the customer context.
`get_linked_tickets` reads the linked tickets' live state and comment threads,
and `comment_on_linked_ticket` posts follow-up context for the engineers.
Check `get_linked_tickets` before filing to avoid duplicates.

A typical loop for a helpdesk ticket: `get_issue` → `get_latest_draft` (is
there already a reviewed answer?) → if not, `start_investigation` → poll →
`generate_draft_from_investigation` → review the body and sources →
`approve_draft` — and `file_tracker_ticket` when the root cause needs a code
fix. Everything is scope-gated (`investigations:read` / `investigations:run` /
`drafts:read` / `drafts:write`), so a key can be limited to exactly the steps
you want automated.

---

## Tool reference

> Every tool an agent can use, by area — and what is deliberately not exposed.

URL: https://docs.useclad.ai/mcp/tools

The exact tool list is scope-filtered per credential, so you'll only see the rows
your grant allows. This is the full surface an admin OAuth grant exposes.

<!-- BEGIN GENERATED TOOLS -->
_80 tools, generated from the live registry (`server/src/mcp/tools`) — regenerate with `npm run mcp:docs`, never hand-edit._

### Identity, SLA & webhooks

Who the credential is, SLA policies, and webhook administration.

| Tool | Kind | Scope | What it does |
|---|---|---|---|
| `whoami` | Read | — | Describe the current credential: actor type, display identity, workspace (organization) name, and the granted scopes. |
| `list_sla_policies` | Read | `sla:read` | List SLA policies with their response/resolution targets (versions, newest first). |
| `list_support_hours` | Read | `sla:read` | List support-hours schedules with weekly intervals and holidays. |
| `list_webhooks` | Read | `webhooks:manage` | List webhook endpoints (admin-scoped). |
| `list_webhook_deliveries` | Read | `webhooks:manage` | List recent delivery attempts for one webhook endpoint (admin-scoped). |
| `ping_webhook` | Write | `webhooks:manage` | Send a test ping event to a webhook endpoint and return the queued delivery (admin-scoped). |

### Issues

Search the inbox, read threads, create issues, reply, and manage triage state.

| Tool | Kind | Scope | What it does |
|---|---|---|---|
| `search_issues` | Read | `issues:read` | Search and list support issues (tickets) with filters: free-text search, status, assignee, tag, account, inbox target (all/spam/trash). |
| `get_issue` | Read | `issues:read` | Fetch a single issue by id, including its conversation thread (messages, oldest first) and followers. |
| `create_issue` | Write | `issues:write` or `issues:create` | Create a new support issue with an initial message. |
| `reply_to_issue` | Write | `thread:reply` | Post a reply on an issue's conversation thread. |
| `set_issue_status` | Write | `issues:write` | Set an issue's status. |
| `set_issue_priority` | Write | `issues:write` | Set an issue's priority. |
| `assign_issue` | Write | `issues:write` | Assign an issue to a workspace member (assigneeProfileId = profileId from list_members), or pass null to unassign. |
| `set_issue_tags` | Write | `issues:write` | Replace an issue's tags with the given list (full replacement, not append). |
| `set_issue_spam` | Write | `spam:write` | Mark an issue as spam (moves it to the spam inbox) or unmark it. |
| `set_issue_trashed` | Write | `issues:write` | Move an issue to the trash or restore it. |
| `set_issue_account` | Write | `issues:write` | Link an issue to a CRM account (or null to unlink). |
| `set_issue_teams` | Write | `issues:write` | Replace the list of teams an issue is routed to (full replacement). |
| `follow_issue` | Write | `issues:write` | Add a workspace member as a follower of an issue (they get notified of updates). |
| `unfollow_issue` | Write | `issues:write` | Remove a workspace member from an issue's followers. |

### CRM — accounts & contacts

Read and write accounts, contacts, and saved account views.

| Tool | Kind | Scope | What it does |
|---|---|---|---|
| `search_accounts` | Read | `accounts:read` | Search and list CRM accounts (customers) by company name, channel name, or domain. |
| `get_account` | Read | `accounts:read` | Fetch a single CRM account by id, including ARR/contract data and custom fields. |
| `create_account` | Write | `accounts:write` | Create a CRM account. |
| `update_account` | Write | `accounts:write` | Update fields on a CRM account. |
| `search_contacts` | Read | `contacts:read` | Search and list contacts by name or email, optionally filtered to one account. |
| `get_contact` | Read | `contacts:read` | Fetch a single contact by id. |
| `create_contact` | Write | `contacts:write` | Create a contact. |
| `update_contact` | Write | `contacts:write` | Update fields on a contact. |

### Knowledge base

Collections, articles, article templates, and homepage curation.

| Tool | Kind | Scope | What it does |
|---|---|---|---|
| `search_articles` | Read | `articles:read` | Search knowledge base articles by title/content, optionally filtered by status or collection. |
| `get_article` | Read | `articles:read` | Fetch a single knowledge base article by id, including its full content. |
| `list_featured_articles` | Read | `articles:read` | List the complete ordered set of help-center homepage pins, including unavailable pins that must be included in a replacement to preserve them. |
| `search_featured_article_candidates` | Read | `articles:read` | Search bounded, metadata-only live articles in included collections that can be newly pinned to the help-center homepage. |
| `replace_featured_articles` | Write | `articles:write` and `articles:publish` | Atomically replace the complete ordered help-center homepage pin set (0-6); omitted pins are unpinned, so first list the set and include unavailable pins you want to preserve; new pins must be live and belong to an included collection. |
| `create_article` | Write | `articles:write` | Create a knowledge base article. |
| `update_article` | Write | `articles:write` | Update an article. |
| `list_collections` | Read | `articles:read` | List knowledge base collections (folders for articles), optionally filtered by name. |
| `get_collection` | Read | `articles:read` | Fetch a single knowledge base collection by id. |
| `create_collection` | Write | `collections:write` | Create a knowledge base collection. |
| `update_collection` | Write | `collections:write` | Update a knowledge base collection's name, description, or icon. |
| `list_article_templates` | Read | `articles:read` | List reusable article templates (newest first). |
| `create_article_template` | Write | `articles:write` | Create a reusable article template. |
| `update_article_template` | Write | `articles:write` | Update an article template's name or content. |

### Directory

Workspace members, teams, and tags.

| Tool | Kind | Scope | What it does |
|---|---|---|---|
| `list_members` | Read | `members:read` | List all members of the workspace with their profile ids, emails, display names, roles, and availability. |
| `list_teams` | Read | `members:read` | List all teams in the workspace with their members. |
| `create_team` | Write | `teams:write` | Create a new team. |
| `rename_team` | Write | `teams:write` | Rename an existing team. |
| `add_team_members` | Write | `teams:write` | Add workspace members (by Profile id) to a team. |
| `remove_team_member` | Write | `teams:write` | Remove one member (by Profile id) from a team. |
| `list_account_views` | Read | `views:read` | List saved account views (custom CRM table configurations), alphabetical. |
| `create_account_view` | Write | `views:write` | Create a saved account view with an optional config (columns, filters, sorting as JSON). |
| `update_account_view` | Write | `views:write` | Update a saved account view's name, config, or starred flag. |

### Settings & admin

Workspace settings, custom fields, widgets, forms, SLA, and webhooks.

| Tool | Kind | Scope | What it does |
|---|---|---|---|
| `list_tags` | Read | `settings:read` | List all workspace tags (name + color), alphabetical. |
| `create_tag` | Write | `tags:write` | Create a workspace tag. |
| `update_tag` | Write | `tags:write` | Rename a tag or change its color. |
| `get_workspace_settings` | Read | `settings:read` | Read workspace settings: email signature, trash auto-clear retention, closed-ticket auto-archive retention, and reactions behavior. |
| `update_workspace_settings` | Write | `settings:write` | Update workspace settings (admin only): email signature (max 500 chars), trash retention, closed-ticket auto-archive retention, and reactions behavior. |
| `get_auto_response_settings` | Read | `settings:read` | Read the AI auto-response configuration: enabled flag, custom prompt, knowledge-base scope, ignored accounts. |
| `update_auto_response_settings` | Write | `settings:write` | Update the AI auto-response configuration (admin only). |
| `list_custom_fields` | Read | `settings:read` | List custom field definitions for accounts or contacts. |
| `create_custom_field` | Write | `customfields:write` | Create a custom field definition (admin only). |
| `update_custom_field` | Write | `customfields:write` | Update a custom field definition (admin only). |
| `list_widgets` | Read | `settings:read` | List all web chat widget configurations for the workspace. |
| `get_widget` | Read | `settings:read` | Fetch one widget configuration by id. |
| `create_widget` | Write | `widget:write` | Create a new web chat widget configuration. |
| `update_widget` | Write | `widget:write` | Patch a widget's configuration. |
| `list_widget_forms` | Read | `settings:read` | List all widget intake forms for the workspace. |
| `create_widget_form` | Write | `widget:write` | Create a widget intake form. |
| `update_widget_form` | Write | `widget:write` | Update a widget intake form. |

### AI agents & escalation

Run investigations, work suggested-reply drafts (with grounding sources), file engineering-tracker tickets, and read the helpdesk connection.

| Tool | Kind | Scope | What it does |
|---|---|---|---|
| `get_helpdesk_connection` | Read | `settings:read` | Read the workspace's external helpdesk connections (Pylon, Zendesk): provider, status (active/paused), operating mode (observe = read-only mirror, assist = approved replies are delivered), sync scope, and the helpdesk identity Clad acts as. |
| `start_investigation` | Write | `investigations:run` | Start an asynchronous AI investigation for an issue. |
| `get_investigation` | Read | `investigations:read` | Read one investigation run by id: status (queued/running/complete/failed), findings (markdown), whether an answer was found, and the triage summary. |
| `list_investigations` | Read | `investigations:read` | List investigation runs for an issue, newest first (latest 20). |
| `get_latest_draft` | Read | `drafts:read` | Read the most recent AI-suggested reply draft for an issue, any status — distinguishes generating, pending (awaiting review), discarded (gate declined), approved (sent), and rejected in one read. |
| `generate_draft` | Write | `drafts:write` | Generate a knowledge-base-grounded suggested reply for an issue through the same gated pipeline as Clad's automatic drafts (source retrieval + confidence gate). |
| `generate_draft_from_investigation` | Write | `drafts:write` | Turn a completed investigation's findings into a pending customer-reply draft (the same flow as the helpdesk panel's Generate response). |
| `approve_draft` | Write | `drafts:write` | Approve a pending draft and deliver it to the customer. |
| `deny_draft` | Write | `drafts:write` | Reject a pending draft with an optional reason. |
| `get_linked_tickets` | Read | `issues:read` | List the engineering-tracker tickets (Linear) linked to an issue, with live state (e.g. |
| `file_tracker_ticket` | Write | `issues:write` | File an engineering-tracker ticket (Linear) from an issue and link it. |
| `comment_on_linked_ticket` | Write | `issues:write` | Post a comment on a tracker ticket linked to an issue (e.g. |
<!-- END GENERATED TOOLS -->

### Not exposed, by design

The following are deliberately absent from every credential, regardless of scope:

- **Deletes** of any kind (moving an issue to trash is the reversible exception).
- **Credential minting** or key management.
- **Webhook creation / rotation** (agents can list and `ping`, not create).
- **Billing.**

An agent with a compromised token cannot destroy data or mint itself new
credentials.

---

## Security

> OAuth 2.1, live role clamping, audit logging, rate limits, and instant revocation.

URL: https://docs.useclad.ai/mcp/security

The MCP server inherits the API's security model and adds OAuth on top.

- **OAuth 2.1** — PKCE (S256), dynamic client registration, refresh-token
  rotation with reuse detection, and RFC 8707 resource audiencing.
- **Live scope clamping** — every request re-checks the authorizing user's
  current role; lost permissions apply immediately to existing tokens.
- **Least privilege by construction** — the tool list is scope-filtered, and
  destructive / credential operations are not exposed at all.
- **Audit logged** — every MCP mutation records the acting credential (which
  agent, on behalf of which user).
- **Rate limited** — both the MCP endpoint and the OAuth routes are rate-limited
  per credential and per IP.

Instant revocation: disconnecting an agent in **Settings → MCP → Connected
agents** revokes its access token and refresh token immediately.

---

## Troubleshooting

> Missing tools, insufficient-scope errors, reply attribution, and picking the right client config.

URL: https://docs.useclad.ai/mcp/troubleshooting

**The agent connects but sees no tools (or too few).**
The tool list is scope-filtered. Call `whoami` to see the granted scopes. A
read-only grant won't show write tools; admin tools require an admin grant.
Re-authorize with the scopes you need, or ask a workspace admin.

**A tool returns "insufficient scope".**
The credential is missing the resource scope for that action (e.g. `issues:write`
to reply). Reconnect with the broader scope, or use an API key that has it.

**Replies show up as the agent's name instead of mine.**
Use an **OAuth** connection rather than a shared API key — OAuth attributes
actions to the signed-in user. (A machine-user API key has no human owner to
attribute to.)

**The connection stopped working after a role change.**
That's expected. Grants follow your role live; if your role was reduced or you
were removed from the workspace, the agent's access is clamped or revoked. An
admin can restore your role, then re-authorize.

**Which client config do I use?**
Open **Settings → MCP** in the Clad app for copy-ready snippets for Cursor,
Claude Code, Claude Desktop, VS Code, Codex, OpenClaw, and any generic
remote-MCP client.

---