# Clad Documentation

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

Full text: https://docs.useclad.ai/llms-full.txt — every page is also available as Markdown by appending `.md` to its URL (e.g. `/widget/quickstart.md`, `/api/overview.md`).

Interactive setup: https://docs.useclad.ai/widget/builder — Vibestart, a visual widget builder that generates a tailored, copy-paste install prompt for AI coding agents.

# Widget SDK

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

## Widget SDK — Getting Started

- [How it works](https://docs.useclad.ai/widget/how-it-works.md): Architecture overview: how the SDK, hosted widget iframe, and Widget API fit together.
- [Quickstart](https://docs.useclad.ai/widget/quickstart.md): Add the widget with one script tag and start chatting in minutes.
- [Installation](https://docs.useclad.ai/widget/installation.md): Add Support Chat with a single script tag. Configure regions and self-hosting.
- [Brand & deploy](https://docs.useclad.ai/widget/brand-deploy.md): A start-to-finish guide to shipping a fully branded widget: create, install, theme, choose surfaces, and go live.

## Widget SDK — Configuration

- [Configuration](https://docs.useclad.ai/widget/configuration.md): Every widget configuration option — workspace, region, theming, launcher, and more.
- [The session lifecycle](https://docs.useclad.ai/widget/session-lifecycle.md): boot, identify, update, shutdown, and destroy — the full lifecycle of a chat session.

## Widget SDK — Identity & Auth

- [Identity verification (JWT)](https://docs.useclad.ai/widget/identity-verification.md): Securely identify logged-in users with short-lived, server-signed JWTs. Includes backend recipes.
- [Anonymous → authenticated](https://docs.useclad.ai/widget/identify-upgrade.md): Upgrade an anonymous session to an identified user and merge conversation history.

## Widget SDK — Widget UI

- [Visibility & launchers](https://docs.useclad.ai/widget/visibility-launchers.md): Open, close, show, and hide the messenger — or wire up your own custom launcher button.
- [Render modes](https://docs.useclad.ai/widget/render-modes.md): Floating, embedded, and custom-launcher render modes for the chat widget.
- [Theming, locale & z-index](https://docs.useclad.ai/widget/theming.md): Match the widget to your brand with theme colors, fonts, locale, and z-index control.

## Widget SDK — Messaging

- [Conversations](https://docs.useclad.ai/widget/conversations.md): Start, list, show, and send messages in conversations with idempotent retries.
- [Slack-native support](https://docs.useclad.ai/widget/slack.md): Answer widget conversations from Slack threads — replies, close/reopen, and follow-up alerts, no dashboard required.
- [Knowledge base & forms](https://docs.useclad.ai/widget/knowledge-base-forms.md): Let users search your knowledge base and submit ticket forms without leaving your app.
- [Context, tags & custom fields](https://docs.useclad.ai/widget/context-tags-fields.md): Attach page context, tags, and custom fields to conversations.

## Widget SDK — Realtime & Events

- [Events](https://docs.useclad.ai/widget/events.md): Subscribe to lifecycle, connection, conversation, and message events with on().
- [Error handling](https://docs.useclad.ai/widget/error-handling.md): Handle SupportChatError, inspect error codes, and retry recoverable failures.
- [Realtime behavior](https://docs.useclad.ai/widget/realtime.md): WebSocket transport, automatic reconnection, message de-duplication, and unread tracking.

## Widget SDK — Privacy & Security

- [Privacy & cookie consent](https://docs.useclad.ai/widget/privacy-cookie-consent.md): Control storage and analytics with granular cookie-consent levels.
- [Security best practices](https://docs.useclad.ai/widget/security.md): Identity verification, allowed origins, CSP, and data-handling guidance.

## Widget SDK — Guides

- [Framework recipes](https://docs.useclad.ai/widget/framework-recipes.md): Copy-paste integration recipes for React, Next.js (App Router), and Vue 3.
- [Browser support & performance](https://docs.useclad.ai/widget/browser-support.md): Supported browsers, lazy-loaded UI, and the single hosted script delivery.
- [Troubleshooting & FAQ](https://docs.useclad.ai/widget/troubleshooting.md): Solutions to common issues: widget not appearing, invalid origins, auth errors, and more.

## Widget SDK — API Reference

- [Public Widget API](https://docs.useclad.ai/widget/widget-api-reference.md): The underlying HTTP + WebSocket Widget API for advanced and self-hosted scenarios.
- [Widget configuration](https://docs.useclad.ai/widget/widget-configuration.md): The WidgetConfig schema: identity rules, routing, features, theme, and AI behavior.
- [Versioning & support](https://docs.useclad.ai/widget/versioning.md): How the widget and API are versioned, what stays stable, and how to get support.
- [TypeScript reference](https://docs.useclad.ai/widget/typescript-reference.md): Key types and the full SupportChat interface available on the global API.

# API

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

## API — Getting Started

- [Overview](https://docs.useclad.ai/api/overview.md): A single GraphQL endpoint for your Clad workspace: issues, replies, CRM, knowledge base, and webhooks.
- [How the API works](https://docs.useclad.ai/api/how-the-api-works.md): GraphQL in practice: one POST, selection sets, variables, and reading the response — for developers new to GraphQL.
- [Authentication](https://docs.useclad.ai/api/authentication.md): Create an API key in Settings → API, choose its permissions, and keep it backend-only.
- [Quickstart](https://docs.useclad.ai/api/quickstart.md): Send your first authenticated query, create an issue, and read it back.
- [Scopes & permissions](https://docs.useclad.ai/api/scopes.md): Coarse and resource scopes, admin-gated grants, and least-privilege keys.

## API — Core Objects

- [Issues](https://docs.useclad.ai/api/issues.md): Create issues from your systems, read the inbox, and manage status, priority, tags, and assignment.
- [Replies](https://docs.useclad.ai/api/replies.md): Post customer-facing replies or internal notes to an issue thread.
- [AI agents & escalation](https://docs.useclad.ai/api/ai-agents.md): Run investigations, work AI reply drafts with their grounding sources, and file engineering-tracker tickets.
- [Accounts & contacts](https://docs.useclad.ai/api/accounts-contacts.md): Read and write CRM accounts and contacts.
- [Knowledge base](https://docs.useclad.ai/api/knowledge-base.md): Manage knowledge-base collections and articles.

## API — Conventions

- [Pagination](https://docs.useclad.ai/api/pagination.md): Relay-style forward pagination with first/after and global object identity.
- [Errors](https://docs.useclad.ai/api/errors.md): In-band result errors, top-level GraphQL errors, and the canonical error-code taxonomy.
- [Idempotency](https://docs.useclad.ai/api/idempotency.md): Safe retries with idempotency keys and stable external ids.
- [Rate limits](https://docs.useclad.ai/api/rate-limits.md): Per-credential and per-IP request limits and back-off.

## API — Platform

- [Webhooks](https://docs.useclad.ai/api/webhooks.md): Subscribe to events, verify signed deliveries, and manage endpoints.
- [Versioning & support](https://docs.useclad.ai/api/versioning.md): API versioning, schema stability, introspection, and how to get support.

## API — Reference

- [Reference overview](https://docs.useclad.ai/api/reference.md): How to read the generated operation reference: queries, mutations, arguments, and return types.
- [Issues](https://docs.useclad.ai/api/reference-issues.md): Every issue query and mutation: inbox, create, reply, status, priority, tags, assignment, spam/trash.
- [CRM — accounts & contacts](https://docs.useclad.ai/api/reference-crm.md): Every account and contact query and mutation, plus saved views and custom fields.
- [Knowledge base](https://docs.useclad.ai/api/reference-knowledge-base.md): Every collection, article, article-template, and homepage-curation query and mutation.
- [AI agents & escalation](https://docs.useclad.ai/api/reference-ai-agents.md): Every investigation, draft, tracker-filing, and helpdesk-connection query and mutation.
- [Webhooks](https://docs.useclad.ai/api/reference-webhooks.md): Every webhook endpoint and delivery query and mutation.
- [API keys](https://docs.useclad.ai/api/reference-api-keys.md): Every API key and machine-user query and mutation.
- [Workspace](https://docs.useclad.ai/api/reference-workspace.md): Every teams, members, tags, widgets, SLA, and settings query and mutation.
- [Types](https://docs.useclad.ai/api/types.md): Object, input, enum, and scalar types referenced by the API operations.

# MCP

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

## MCP — Getting Started

- [Overview](https://docs.useclad.ai/mcp/overview.md): Connect AI agents to your Clad workspace with the hosted Model Context Protocol server — same permissions and object ids as the API.
- [Connect an agent (OAuth)](https://docs.useclad.ai/mcp/connect-agent.md): Add the server to Cursor, Claude, ChatGPT, or Codex and authorize with your Clad login — no keys to copy.
- [Connect a service (API key)](https://docs.useclad.ai/mcp/connect-service.md): Use an API key bearer token for headless automation on the same MCP endpoint.
- [Working with a helpdesk (Pylon, Zendesk)](https://docs.useclad.ai/mcp/helpdesk.md): Mirrored helpdesk tickets are regular issues: the same tools triage them, and replies deliver into Pylon or Zendesk.
- [Investigations, drafts & escalation](https://docs.useclad.ai/mcp/agents.md): Run Clad's AI-agent workflow over MCP: investigate tickets, review grounded reply drafts, approve or deny them, and escalate to the tracker.

## MCP — Reference

- [Scopes & the tool list](https://docs.useclad.ai/mcp/scopes.md): The tool list is scope-filtered: a credential only sees the tools it can actually call.
- [Tool reference](https://docs.useclad.ai/mcp/tools.md): Every tool an agent can use, by area — and what is deliberately not exposed.
- [Security](https://docs.useclad.ai/mcp/security.md): OAuth 2.1, live role clamping, audit logging, rate limits, and instant revocation.
- [Troubleshooting](https://docs.useclad.ai/mcp/troubleshooting.md): Missing tools, insufficient-scope errors, reply attribution, and picking the right client config.