Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add glossary page with filterable term definitions

Sushmitha Mallesh904228961bef
diff --git a/docs/.claude/context/fumadocs.md b/docs/.claude/context/fumadocs.md
index 068f2421f..79dcc657c 100644
--- a/docs/.claude/context/fumadocs.md
+++ b/docs/.claude/context/fumadocs.md
@@ -50,6 +50,7 @@ Available globally without imports:
- `CapabilityCard`, `CapabilityList`
- `ToolkitsLanding`
- `StepTitle`
+- `Glossary`, `GlossaryTerm` — filterable glossary table (see `components/glossary.tsx`)
- Lucide icons: `ShieldCheck`, `RouteIcon`, `Key`, `Wrench`, `Database`, `Zap`, `Rocket`, `Code`, `Blocks`, `Plug`, `Play`, `Terminal`, `Palette`, `BookOpen`
## Deployment
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 33d798fec..72a5186f0 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -74,6 +74,10 @@ Detailed documentation for Claude is organized in `.claude/`:
- Dynamic toolkit pages are validated against slugs from `public/data/toolkits.json`
- Non-Fumadocs `.md` files (like FAQ snippets) are picked up via `content/**/*.md` glob
+## Glossary
+
+`content/docs/glossary.mdx` defines key Composio terms (auth config, session, toolkit, etc.) using `<Glossary>` and `<GlossaryTerm name="...">` components (`components/glossary.tsx`). The component renders a filterable two-column table. The markdown converter in `lib/source.ts` converts `<GlossaryTerm>` tags to `### Term` headings for LLM-friendly output. When adding new Composio concepts, add a `<GlossaryTerm>` entry and update the `keywords` frontmatter array.
+
## Code Review Guidelines
**`docs/examples/` is tutorial code.** Review for correctness and clarity, not production-readiness. Skip accessibility (aria attributes, focus management), error boundaries, i18n, comprehensive error handling, and similar concerns that add noise to a teaching example. The goal is to teach Composio integration with minimal code.
diff --git a/docs/app/layout.tsx b/docs/app/layout.tsx
index f461eb484..1985dec42 100644
--- a/docs/app/layout.tsx
+++ b/docs/app/layout.tsx
@@ -12,6 +12,7 @@ const defaultLinkSlugs = [
['quickstart'],
['authentication'],
['configuring-sessions'],
+ ['glossary'],
['common-faq'],
['troubleshooting'],
];
diff --git a/docs/components/glossary.tsx b/docs/components/glossary.tsx
new file mode 100644
index 000000000..0cac6b0bd
--- /dev/null
+++ b/docs/components/glossary.tsx
@@ -0,0 +1,111 @@
+'use client';
+
+import {
+ useState,
+ createContext,
+ useContext,
+ useRef,
+ useEffect,
+ type ReactNode,
+} from 'react';
+import { cn } from '@/lib/utils';
+
+const FilterContext = createContext('');
+
+function slugify(text: string): string {
+ return text
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-|-$/g, '');
+}
+
+export function Glossary({ children }: { children: ReactNode }) {
+ const [filter, setFilter] = useState('');
+
+ return (
+ <FilterContext.Provider value={filter.toLowerCase()}>
+ <div className="not-prose mt-6">
+ <div className="hidden sm:grid grid-cols-[minmax(180px,1fr)_2fr] gap-4 border-b border-fd-border pb-3 mb-0">
+ <div className="text-xs font-semibold text-fd-muted-foreground tracking-wider uppercase">
+ Glossary Term
+ </div>
+ <div className="text-xs font-semibold text-fd-muted-foreground tracking-wider uppercase">
+ Definition
+ </div>
+ </div>
+ <div className="border-b border-fd-border py-3">
+ <div className="relative max-w-sm">
+ <svg
+ className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-fd-muted-foreground"
+ fill="none"
+ stroke="currentColor"
+ viewBox="0 0 24 24"
+ >
+ <path
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ strokeWidth={2}
+ d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+ />
+ </svg>
+ <input
+ type="text"
+ placeholder="Filter..."
+ value={filter}
+ onChange={(e) => setFilter(e.target.value)}
+ className="w-full pl-9 pr-3 py-1.5 text-sm border border-fd-border rounded-md bg-fd-background text-fd-foreground placeholder:text-fd-muted-foreground focus:outline-none focus:ring-2 focus:ring-fd-ring"
+ />
+ </div>
+ </div>
+ {children}
+ </div>
+ </FilterContext.Provider>
+ );
+}
+
+export function GlossaryTerm({
+ name,
+ children,
+}: {
+ name: string;
+ children: ReactNode;
+}) {
+ const filter = useContext(FilterContext);
+ const definitionRef = useRef<HTMLDivElement>(null);
+ const [definitionText, setDefinitionText] = useState('');
+ const id = slugify(name);
+
+ useEffect(() => {
+ if (definitionRef.current) {
+ setDefinitionText(definitionRef.current.textContent?.toLowerCase() || '');
+ }
+ }, []);
+
+ const matches =
+ !filter ||
+ name.toLowerCase().includes(filter) ||
+ definitionText.includes(filter);
+
+ if (!matches) return null;
+
+ return (
+ <div
+ id={id}
+ data-glossary-term={name}
+ className={cn(
+ 'border-b border-fd-border py-4 scroll-mt-20',
+ 'grid grid-cols-1 sm:grid-cols-[minmax(180px,1fr)_2fr] gap-1 sm:gap-4',
+ )}
+ >
+ <div className="font-medium text-fd-foreground text-sm">
+ {name}
+ </div>
+ <div
+ ref={definitionRef}
+ className="text-sm text-fd-muted-foreground leading-relaxed [&_a]:text-fd-primary [&_a]:underline [&_code]:text-xs [&_code]:bg-fd-muted [&_code]:px-1 [&_code]:py-0.5 [&_code]:rounded"
+ >
+ {children}
+ </div>
+ </div>
+ );
+}
diff --git a/docs/content/docs/glossary.mdx b/docs/content/docs/glossary.mdx
new file mode 100644
index 000000000..1337e4a2f
--- /dev/null
+++ b/docs/content/docs/glossary.mdx
@@ -0,0 +1,173 @@
+---
+title: Glossary
+description: Definitions of key Composio terms and concepts.
+llmGuardrails: "none"
+keywords:
+ [
+ auth config,
+ auth scheme,
+ callback url,
+ composio api key,
+ composio managed auth,
+ connect link,
+ connected account,
+ connection request,
+ custom tool,
+ in-chat authentication,
+ mcp,
+ model context protocol,
+ meta tools,
+ modifiers,
+ native tools,
+ organization,
+ organization api key,
+ project,
+ provider,
+ proxy execute,
+ session,
+ session id,
+ tool,
+ tool slug,
+ toolkit,
+ toolkit slug,
+ toolkit versioning,
+ trigger,
+ trigger instance,
+ user id,
+ white-labeling,
+ workbench,
+ glossary,
+ ]
+---
+
+<Glossary>
+
+<GlossaryTerm name="Auth Config">
+A blueprint defining how authentication works for a toolkit: auth method (OAuth2, API key, Bearer token, Basic Auth), scopes, and credentials. Created automatically by a session when needed. You can create a custom one to use your own OAuth credentials or non-default scopes.
+</GlossaryTerm>
+
+<GlossaryTerm name="Auth Scheme">
+The authentication method used by an auth config, such as `OAUTH2`, `API_KEY`, `BEARER_TOKEN`, or `BASIC`.
+</GlossaryTerm>
+
+<GlossaryTerm name="Callback URL">
+The URL a user is redirected to after completing an OAuth flow through a Connect Link. Passed as `callbackUrl` when initiating authentication.
+</GlossaryTerm>
+
+<GlossaryTerm name="Composio API Key">
+A project-scoped secret used to authenticate SDK and API requests. All resources created with it are scoped to that project.
+</GlossaryTerm>
+
+<GlossaryTerm name="Composio Managed Auth">
+The default mode where Composio provides its own OAuth app credentials for each toolkit. No setup required.
+</GlossaryTerm>
+
+<GlossaryTerm name="Connect Link">
+A hosted page where a user authorizes access to a toolkit. Returned as a `redirect_url` from `session.authorize()` or `connectedAccounts.initiate()`. Composio manages the full OAuth flow.
+</GlossaryTerm>
+
+<GlossaryTerm name="Connected Account">
+Created when a user authenticates with a toolkit. Stores credentials (OAuth tokens or API keys) linked to a user ID. Composio automatically refreshes OAuth tokens. A user can have multiple connected accounts for the same toolkit. IDs are prefixed `ca_`.
+</GlossaryTerm>
+
+<GlossaryTerm name="Connection Request">
+The object returned when you initiate authentication. Contains the Connect Link URL and a `waitForConnection()` method that resolves once the user completes the flow.
+</GlossaryTerm>
+
+<GlossaryTerm name="Custom Tool">
+A user-defined tool used alongside Composio's built-in tools. Can be standalone (no auth) or toolkit-based (authenticated API requests). Stored in memory, must be recreated on restart.
+</GlossaryTerm>
+
+<GlossaryTerm name="In-Chat Authentication">
+A flow where the AI agent handles authentication by calling `COMPOSIO_MANAGE_CONNECTIONS` to generate a Connect Link and send it to the user in the conversation.
+</GlossaryTerm>
+
+<GlossaryTerm name="MCP (Model Context Protocol)">
+An open protocol for connecting AI models to external tools. Every session exposes `session.mcp.url` and `session.mcp.headers`, an MCP-compatible endpoint any MCP client can connect to.
+</GlossaryTerm>
+
+<GlossaryTerm name="Manual Authentication">
+Authenticating users from your own code using `session.authorize()` or `connectedAccounts.initiate()`, as opposed to letting the AI agent handle it via in-chat authentication.
+</GlossaryTerm>
+
+<GlossaryTerm name="Meta Tools">
+A set of tools included in every session, including `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_MANAGE_CONNECTIONS`, `COMPOSIO_MULTI_EXECUTE_TOOL`, `COMPOSIO_REMOTE_WORKBENCH`, and `COMPOSIO_REMOTE_BASH_TOOL`. They let the agent discover tools, manage auth, execute in parallel, and run code without loading hundreds of tool definitions upfront.
+</GlossaryTerm>
+
+<GlossaryTerm name="Modifiers">
+Middleware that transforms tool behavior: **schema modifiers** change a tool's schema before the agent sees it, **before-execution modifiers** modify arguments before a tool runs, **after-execution modifiers** transform the result.
+</GlossaryTerm>
+
+<GlossaryTerm name="Native Tools">
+Tools accessed through provider packages via `session.tools()`, as opposed to connecting via MCP (`session.mcp.url`). Both methods give the agent the same capabilities, but native tools integrate directly with your AI framework.
+</GlossaryTerm>
+
+<GlossaryTerm name="Organization">
+The top-level Composio account entity. Contains team members and projects.
+</GlossaryTerm>
+
+<GlossaryTerm name="Organization API Key">
+A key (`x-org-api-key`) for organization-level operations like creating and managing projects. Distinct from the project-scoped Composio API Key.
+</GlossaryTerm>
+
+<GlossaryTerm name="Project">
+An isolated environment within an organization that scopes API keys, connected accounts, auth configs, and webhooks. Resources in one project are inaccessible from another. IDs are prefixed `proj_`.
+</GlossaryTerm>
+
+<GlossaryTerm name="Proxy Execute">
+Making authenticated HTTP requests through a toolkit's connected account without a predefined tool. Useful for API endpoints Composio doesn't have a built-in tool for.
+</GlossaryTerm>
+
+<GlossaryTerm name="Provider">
+An adapter package that transforms Composio tools into the format expected by an AI framework (OpenAI, Anthropic, LangChain, Vercel AI SDK, etc.).
+</GlossaryTerm>
+
+<GlossaryTerm name="Session">
+An ephemeral configuration object from `composio.create(userId)`. Ties together a user ID, available toolkits, auth config, and connected accounts. Immutable. Exposes `tools()`, `mcp.url`, `authorize()`, and `toolkits()`.
+</GlossaryTerm>
+
+<GlossaryTerm name="Session ID">
+Unique identifier for a session. Used internally by meta tools to share context across calls within the same session.
+</GlossaryTerm>
+
+<GlossaryTerm name="Tool">
+An individual action an agent can execute. Has an input schema and output schema. Named `{TOOLKIT}_{ACTION}` (e.g., `GITHUB_CREATE_ISSUE`).
+</GlossaryTerm>
+
+<GlossaryTerm name="Tool Slug">
+A tool's unique identifier, following the `{TOOLKIT}_{ACTION}` pattern, e.g. `GITHUB_CREATE_ISSUE`.
+</GlossaryTerm>
+
+<GlossaryTerm name="Toolkit">
+A collection of related tools for a single external service. Users connect to a toolkit via authentication, and all its tools execute with the user's credentials.
+</GlossaryTerm>
+
+<GlossaryTerm name="Toolkit Slug">
+The lowercase identifier for a toolkit, e.g. `github`, `gmail`, `slack`. Used when configuring sessions, fetching tools, or creating triggers.
+</GlossaryTerm>
+
+<GlossaryTerm name="Toolkit Versioning">
+Pinning a toolkit to a specific version so your integration uses a consistent set of tools even as Composio updates definitions.
+</GlossaryTerm>
+
+<GlossaryTerm name="Trigger">
+Sends structured payloads to your application when something happens in a connected app. Two delivery types: **webhook** (the app pushes events in real time, e.g. GitHub, Slack) and **polling** (Composio periodically checks for new data, e.g. Gmail).
+</GlossaryTerm>
+
+<GlossaryTerm name="Trigger Instance">
+A specific, active trigger scoped to a user's connected account.
+</GlossaryTerm>
+
+<GlossaryTerm name="User ID">
+An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between user IDs.
+</GlossaryTerm>
+
+<GlossaryTerm name="White-Labeling">
+Customizing the auth experience so users see your brand during the OAuth flow. You provide your own OAuth credentials, redirect URIs, and branding.
+</GlossaryTerm>
+
+<GlossaryTerm name="Workbench">
+A persistent Python sandbox via the `COMPOSIO_REMOTE_WORKBENCH` meta tool. State persists across calls within a session. Used for bulk operations, data transformations, and processing large tool responses.
+</GlossaryTerm>
+
+</Glossary>
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index f99eb9169..4f5c14a71 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -31,6 +31,7 @@
"auth-configuration",
"---Resources---",
"common-faq",
+ "glossary",
"debugging-info",
"migration-guide",
"troubleshooting"
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 1c8479378..3a53b18e2 100644
--- a/docs/lib/source.ts
+++ b/docs/lib/source.ts
@@ -234,6 +234,12 @@ export function mdxToCleanMarkdown(content: string): string {
'- [$2]($1): $3'
);
+ // Convert GlossaryTerm to heading + definition
+ result = result.replace(
+ /<GlossaryTerm[\s\S]*?name="([^"]*)"[\s\S]*?>([\s\S]*?)<\/GlossaryTerm>/g,
+ (_, name, content) => `### ${name}\n\n${content.trim()}`
+ );
+
// Convert AIToolsBanner to plain text
result = result.replace(
/<AIToolsBanner\s*\/>/g,
@@ -248,7 +254,7 @@ export function mdxToCleanMarkdown(content: string): string {
// Remove wrapper components (ProviderGrid, Tabs, Frame, div, QuickstartFlow, IntegrationTabs, Accordions, ToolTypeFlow, ToolkitsLanding, TemplateGrid, etc.)
// Note: Cards wrapper is removed earlier (before Card conversion) to prevent regex conflicts
- result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid)[^>]*>/g, '');
+ result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary)[^>]*>/g, '');
// Remove remaining self-closing JSX tags (including those with JSX expressions)
result = result.replace(/<[A-Z][a-zA-Z]*[\s\S]*?\/>/g, '');
@@ -386,7 +392,7 @@ ${page.data.description || ''}`;
const cleanContent = mdxToCleanMarkdown(content);
const footer = includeFooter
- ? `\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference)`
+ ? `\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/docs/glossary.md) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference)`
: '';
const guardrails = includeGuardrails ? getGuardrails(page.data.llmGuardrails) : '';
diff --git a/docs/mdx-components.tsx b/docs/mdx-components.tsx
index 90e216b7b..974b473a9 100644
--- a/docs/mdx-components.tsx
+++ b/docs/mdx-components.tsx
@@ -21,6 +21,7 @@ import { TemplateCard, TemplateGrid } from '@/components/template-card';
import { ToolkitsLanding } from '@/components/toolkits/toolkits-landing';
import { Mermaid } from '@/components/mermaid';
import { AIToolsBanner } from '@/components/ai-tools-banner';
+import { Glossary, GlossaryTerm } from '@/components/glossary';
import {
ShieldCheck,
Route as RouteIcon,
@@ -89,6 +90,8 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
Mermaid,
AIToolsBanner,
StepTitle,
+ Glossary,
+ GlossaryTerm,
// Lucide icons
ShieldCheck,
RouteIcon,