Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: dual API version reference (v3.1 + v3.0) (#3179)
Sushmitha Malleshb14810b3a4f4
diff --git a/.github/workflows/docs-update-data.yml b/.github/workflows/docs-update-data.ymlindex 475da4892..b94f4f81f 100644--- a/.github/workflows/docs-update-data.yml+++ b/.github/workflows/docs-update-data.yml@@ -60,14 +60,14 @@ jobs:id: changesrun: |cd ..- git add -N docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null || true- if git diff --quiet docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null; then+ git add -N docs/public/data/ docs/public/openapi.json docs/public/openapi-v3.json docs/content/reference/api-reference/ docs/content/reference/v3/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null || true+ if git diff --quiet docs/public/data/ docs/public/openapi.json docs/public/openapi-v3.json docs/content/reference/api-reference/ docs/content/reference/v3/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null; thenecho "has_changes=false" >> $GITHUB_OUTPUTecho "No changes detected"elseecho "has_changes=true" >> $GITHUB_OUTPUTecho "Changes detected:"- git diff --stat docs/public/data/ docs/public/openapi.json docs/content/reference/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null || true+ git diff --stat docs/public/data/ docs/public/openapi.json docs/public/openapi-v3.json docs/content/reference/api-reference/ docs/content/reference/v3/api-reference/ docs/content/reference/meta-tools/ 2>/dev/null || truefi- name: Create Pull Request@@ -83,15 +83,17 @@ jobs:## What changed- **Toolkit catalog** (`docs/public/data/toolkits.json`, `toolkits-list.json`) — refreshed list of available toolkits, auth schemes, and tools from the backend API- - **OpenAPI spec** (`docs/public/openapi.json`) — latest API specification fetched from production- - **API reference pages** (`docs/content/reference/api-reference/*.mdx`) — regenerated index pages from the updated OpenAPI spec+ - **OpenAPI specs** (`docs/public/openapi.json`, `docs/public/openapi-v3.json`) — latest v3.1 and v3.0 API specifications fetched from production+ - **API reference pages** (`docs/content/reference/api-reference/`, `docs/content/reference/v3/api-reference/`) — regenerated index pages for both API versions- **Meta tools reference** (`docs/public/data/meta-tools.json`, `docs/content/reference/meta-tools/*.mdx`) — updated meta tool schemas and reference docsbranch: docs/auto-update-database: nextadd-paths: |docs/public/data/docs/public/openapi.json+ docs/public/openapi-v3.jsondocs/content/reference/api-reference/+ docs/content/reference/v3/api-reference/docs/content/reference/meta-tools/- name: Request review from trigger actordiff --git a/docs/.claude/context/api-reference.md b/docs/.claude/context/api-reference.mdindex cf04e47ca..d62c8b198 100644--- a/docs/.claude/context/api-reference.md+++ b/docs/.claude/context/api-reference.md@@ -7,7 +7,8 @@ The API reference is auto-generated from `public/openapi.json` using [fumadocs-o## Architecture```-public/openapi.json ← Auto-fetched from backend (don't edit manually)+public/openapi.json ← v3.1 spec (auto-fetched, don't edit manually)+public/openapi-v3.json ← v3.0 spec (auto-fetched, don't edit manually)components/api-page.tsx ← createAPIPage config, schema render hookcomponents/api-page.client.tsx ← Client-side playground configcomponents/schema-generator.tsx ← Server-side: walks OpenAPI schema → SchemaUIGeneratedData@@ -49,12 +50,65 @@ All in `app/global.css` under the "OpenAPI Reference" section. These target fuma| `div.border.rounded-lg:not(:has(*))` | Hide empty schema wrapper divs (when Error schema returns null) | Wrapper div rendered outside `schemaUI.render` hook || `p.text-fd-muted-foreground.not-prose:has(> code.text-xs)` | Hide `application/json` content type labels | No hook to control content type display |+## API Versioning (v3.0 / v3.1)++Two API versions are served side-by-side with a Stripe-style version selector in the top nav bar.++### URL structure+- **v3.1 (default):** `/reference/...` — e.g. `/reference/api-reference/tools/getTools`+- **v3.0:** `/reference/v3/...` — e.g. `/reference/v3/api-reference/tools/getTools`+- All existing v3.1 URLs are unchanged — no breaking changes.++### How it works++```+lib/openapi.ts ← Creates two OpenAPI instances (v3.1 + v3.0)+lib/source.ts ← Combined source: v3.1 at api-reference/, v3.0 at v3/api-reference/+lib/api-version.ts ← Shared detectApiVersion() utility (single source of truth)+lib/use-api-version.ts ← Client hook wrapping detectApiVersion for React components+lib/filter-api-version.ts ← Tree filter: hides V3 folder for v3.1, lifts V3 children for v3.0+app/(home)/reference/(v31)/layout.tsx ← v3.1 layout: hardcodes version, renders DocsLayout with filtered tree+app/(home)/reference/v3/layout.tsx ← v3.0 layout: hardcodes version, renders DocsLayout with filtered tree+components/version-selector.tsx ← Dropdown in top nav, navigates between /reference/ ↔ /reference/v3/+components/api-base-url.tsx ← Dynamic base URL: v3.1 or v3 based on current path+components/api-endpoints-table.tsx ← Endpoint tables in index pages, shows versioned paths+components/version-badge.tsx ← Badge on endpoint pages showing API version+```++### Content structure++v3.0 has its own complete page tree under `content/reference/v3/`:+- `v3/index.mdx` — Overview (with v3 links and base URL)+- `v3/authentication.mdx` — Auth docs (with v3 curl examples)+- `v3/rate-limits.mdx`, `v3/errors.mdx` — Duplicated non-API pages+- `v3/api-reference/` — Auto-generated index pages + OpenAPI endpoint pages+- `v3/meta.json` — Sidebar ordering++SDK Reference and Meta Tools are version-independent and shared across both trees.++### Version selector behavior+- On an API page: swaps `/reference/` ↔ `/reference/v3/` (stays on same endpoint/category)+- On overview (`/reference`): navigates to `/reference/v3` (v3 has its own overview)+- Full page reload on every version switch (server re-renders layout with filtered tree)++### Auto-generation pipeline (`docs-update-data.yml`)+1. `fetch-openapi.mjs` — fetches both v3.1 and v3.0 specs from backend+2. `generate-api-index.ts` — generates index pages for both `api-reference/` and `v3/api-reference/`+3. CI tracks: `openapi.json`, `openapi-v3.json`, `api-reference/`, `v3/api-reference/`++### Adding/modifying v3 content+- API endpoint pages are auto-generated from the OpenAPI spec — no manual work needed+- Index pages are auto-generated by `bun run generate:api-index`+- Non-API pages (`v3/index.mdx`, `v3/authentication.mdx`, etc.) are manual copies — update both versions when content changes+- `v3/meta.json` and `v3/api-reference/meta.json` control sidebar ordering+## OpenAPI Spec Notes-- Spec is OAS 3.0.0 with 60 endpoints-- All error responses (400, 401, 403, 404, 500, etc.) use identical `#/components/schemas/Error` schema-- Error descriptions vary per endpoint and are useful (e.g., 410 means different things on different endpoints)+- v3.1 spec is OAS 3.0.0 format+- v3.0 spec is also OAS 3.0.0 format with the same tag structure+- All error responses use identical `#/components/schemas/Error` schema+- Error descriptions vary per endpoint and are useful- `info.description` is empty (backend issue)-- 0/60 endpoints have response examples (backend issue)+- No response examples (backend issue)- `nullable: true` (OAS 3.0) is converted by fumadocs-openapi's dereferencer- Some properties named `deprecated` are required fields (spec issue, not the OpenAPI deprecated flag)diff --git a/docs/.claude/context/pipelines.md b/docs/.claude/context/pipelines.mdindex 59b87fc6d..17d338e44 100644--- a/docs/.claude/context/pipelines.md+++ b/docs/.claude/context/pipelines.md@@ -6,7 +6,7 @@ Reference for all GitHub Actions workflows related to docs.| Workflow | File | Trigger | What it does ||---|---|---|---|-| **Update Data** | `docs-update-data.yml` | Cron (every 5h), `repository_dispatch` (Apollo deploy), manual | Fetches toolkits data, OpenAPI spec, API index pages, and meta tools reference. Creates PR via `peter-evans/create-pull-request` targeting `next`. |+| **Update Data** | `docs-update-data.yml` | Cron (every 5h), `repository_dispatch` (Apollo deploy), manual | Fetches toolkits data, both OpenAPI specs (v3.1 + v3.0), generates API index pages for both versions, and meta tools reference. Creates PR via `peter-evans/create-pull-request` targeting `next`. Tracks: `openapi.json`, `openapi-v3.json`, `api-reference/`, `v3/api-reference/`. || **Sync Connect Clients** | `docs.sync-connect-clients.yml` | Cron (daily 8 AM UTC), manual | Claude Code action syncs client definitions from `ComposioHQ/composio_dashboard` to `composio-connect.mdx`. Creates PR targeting `next`. Agent instructions: `docs/.claude/agents/connect-clients-sync.md`. || **Changelog → Docs** | `docs.changelog-to-docs.yml` | Push to `next` (changelog files) | Codex action reads new changelog entries and updates docs pages. Creates PR targeting `next`. Agent instructions: `docs/.claude/agents/changelog-docs-updater.md`. || **Check Links** | `docs-check-links.yml` | PR changes to `docs/` | Runs `bun run scripts/validate-links.ts` to catch broken internal links. |diff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 898ea74f2..b382a2d9a 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -81,6 +81,19 @@ Detailed documentation for Claude is organized in `.claude/`:`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.+## API Versioning++The API reference supports v3.1 (latest, default) and v3.0 side-by-side:+- **v3.1:** `/reference/api-reference/...` (default, all existing URLs unchanged)+- **v3.0:** `/reference/v3/api-reference/...`++Version selector in the top nav switches between them. See [api-reference.md](.claude/context/api-reference.md) for full architecture.++Key maintenance notes:+- Non-API pages under `content/reference/v3/` (overview, authentication, errors, rate-limits) are manual copies — update both when content changes+- API index pages and OpenAPI specs are auto-generated by CI (`docs-update-data.yml`)+- SDK Reference and Meta Tools are shared across both versions (not duplicated)+## 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/(home)/reference/[[...slug]]/page.tsx b/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsxsimilarity index 79%rename from docs/app/(home)/reference/[[...slug]]/page.tsxrename to docs/app/(home)/reference/(v31)/[[...slug]]/page.tsxindex e34fc9d0c..d52982d97 100644--- a/docs/app/(home)/reference/[[...slug]]/page.tsx+++ b/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx@@ -1,4 +1,3 @@-import type { ComponentType } from 'react';import { getReferenceSource, getOgImageUrl } from '@/lib/source';import { APIPage } from '@/components/api-page';import {@@ -12,6 +11,7 @@ import type { Metadata } from 'next';import { createRelativeLink } from 'fumadocs-ui/mdx';import type { ApiPageProps } from 'fumadocs-openapi/ui';import { PageActions } from '@/components/page-actions';+import { VersionBadge, extractVersionFromPath } from '@/components/version-badge';interface OpenAPIPageData {title: string;@@ -29,21 +29,30 @@ export default async function Page({const page = referenceSource.getPage(slug);if (!page) notFound();- // Check if this is an OpenAPI page (has getAPIPageProps method)if ('getAPIPageProps' in page.data) {const pageData = page.data as OpenAPIPageData;+ const apiProps = pageData.getAPIPageProps();+ const detectedVersion = apiProps.operations?.[0]?.path+ ? extractVersionFromPath(apiProps.operations[0].path)+ : null;return (<DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>- <h1 className="text-2xl font-semibold mb-4">{pageData.title}</h1>+ <h1 className="text-2xl font-semibold mb-4">+ {pageData.title}+ {detectedVersion && (+ <span className="ml-2 align-middle">+ <VersionBadge version={detectedVersion} />+ </span>+ )}+ </h1><PageActions path={page.url} /><DocsBody>- <APIPage {...pageData.getAPIPageProps()} />+ <APIPage {...apiProps} /></DocsBody></DocsPage>);}- // Regular MDX page - cast to any to avoid complex type issues// eslint-disable-next-line @typescript-eslint/no-explicit-anyconst mdxData = page.data as any;const MDX = mdxData.body;@@ -66,7 +75,9 @@ export default async function Page({export async function generateStaticParams() {const referenceSource = await getReferenceSource();- return referenceSource.generateParams();+ const allParams: { slug: string[] }[] = referenceSource.generateParams();+ // Exclude v3 pages — those are handled by the /reference/v3/ route+ return allParams.filter((p) => p.slug[0] !== 'v3');}export async function generateMetadata({@@ -76,7 +87,6 @@ export async function generateMetadata({}): Promise<Metadata> {const { slug } = await params;- // Index page - show custom metadataif (!slug || slug.length === 0) {const ogImage = getOgImageUrl('reference', [], 'API Reference', 'REST API and SDK reference for Composio');return {@@ -92,8 +102,6 @@ export async function generateMetadata({const page = referenceSource.getPage(slug);if (!page) notFound();- // Use description if available, otherwise fall back to title for SEO- // This handles OpenAPI pages where description may be null in the specconst description = page.data.description || page.data.title;const ogImage = getOgImageUrl('reference', page.slugs, page.data.title, description);diff --git a/docs/app/(home)/reference/(v31)/layout.tsx b/docs/app/(home)/reference/(v31)/layout.tsxnew file mode 100644index 000000000..14aee9fa8--- /dev/null+++ b/docs/app/(home)/reference/(v31)/layout.tsx@@ -0,0 +1,21 @@+import { getReferenceSource } from '@/lib/source';+import { DocsLayout } from 'fumadocs-ui/layouts/docs';+import type { ReactNode } from 'react';+import { prepareTree } from '@/lib/filter-api-version';++export default async function Layout({ children }: { children: ReactNode }) {+ const source = await getReferenceSource();+ const tree = prepareTree(source.pageTree, '3.1');++ return (+ <DocsLayout+ tree={tree}+ nav={{ enabled: true, title: null }}+ searchToggle={{ enabled: false }}+ sidebar={{ collapsible: false, footer: null, tabs: false }}+ themeSwitch={{ enabled: false }}+ >+ {children}+ </DocsLayout>+ );+}diff --git a/docs/app/(home)/reference/layout.tsx b/docs/app/(home)/reference/layout.tsxindex 8fd01f851..30108d945 100644--- a/docs/app/(home)/reference/layout.tsx+++ b/docs/app/(home)/reference/layout.tsx@@ -1,18 +1,5 @@-import { getReferenceSource } from '@/lib/source';-import { DocsLayout } from 'fumadocs-ui/layouts/docs';import type { ReactNode } from 'react';-export default async function Layout({ children }: { children: ReactNode }) {- const source = await getReferenceSource();- return (- <DocsLayout- tree={source.pageTree}- nav={{ enabled: true, title: null }}- searchToggle={{ enabled: false }}- sidebar={{ collapsible: false, footer: null, tabs: false }}- themeSwitch={{ enabled: false }}- >- {children}- </DocsLayout>- );+export default function Layout({ children }: { children: ReactNode }) {+ return children;}diff --git a/docs/app/(home)/reference/v3/[[...slug]]/page.tsx b/docs/app/(home)/reference/v3/[[...slug]]/page.tsxnew file mode 100644index 000000000..ae9ed764b--- /dev/null+++ b/docs/app/(home)/reference/v3/[[...slug]]/page.tsx@@ -0,0 +1,126 @@+import { getReferenceSource, getOgImageUrl } from '@/lib/source';+import { APIPage } from '@/components/api-page';+import {+ DocsBody,+ DocsPage,+ DocsTitle,+} from 'fumadocs-ui/layouts/docs/page';+import { notFound } from 'next/navigation';+import { getMDXComponents } from '@/mdx-components';+import type { Metadata } from 'next';+import { createRelativeLink } from 'fumadocs-ui/mdx';+import type { ApiPageProps } from 'fumadocs-openapi/ui';+import { PageActions } from '@/components/page-actions';+import { VersionBadge, extractVersionFromPath } from '@/components/version-badge';++interface OpenAPIPageData {+ title: string;+ description?: string;+ getAPIPageProps: () => ApiPageProps;+}++/**+ * Prepend 'v3' to the slug array since Next.js strips the /v3/ route segment+ * but the source has pages registered under v3/...+ */+function toSourceSlug(slug?: string[]): string[] {+ return ['v3', ...(slug || [])];+}++export default async function Page({+ params,+}: {+ params: Promise<{ slug?: string[] }>;+}) {+ const { slug } = await params;+ const referenceSource = await getReferenceSource();+ const page = referenceSource.getPage(toSourceSlug(slug));+ if (!page) notFound();++ if ('getAPIPageProps' in page.data) {+ const pageData = page.data as OpenAPIPageData;+ const apiProps = pageData.getAPIPageProps();+ const detectedVersion = apiProps.operations?.[0]?.path+ ? extractVersionFromPath(apiProps.operations[0].path)+ : null;+ return (+ <DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>+ <h1 className="text-2xl font-semibold mb-4">+ {pageData.title}+ {detectedVersion && (+ <span className="ml-2 align-middle">+ <VersionBadge version={detectedVersion} />+ </span>+ )}+ </h1>+ <PageActions path={page.url} />+ <DocsBody>+ <APIPage {...apiProps} />+ </DocsBody>+ </DocsPage>+ );+ }++ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ const mdxData = page.data as any;+ const MDX = mdxData.body;++ return (+ <DocsPage toc={mdxData.toc} full={mdxData.full} footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>+ <DocsTitle>{mdxData.title}</DocsTitle>+ <PageActions path={page.url} />+ <DocsBody>+ <MDX+ components={getMDXComponents({+ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ a: createRelativeLink(referenceSource as any, page),+ })}+ />+ </DocsBody>+ </DocsPage>+ );+}++export async function generateStaticParams() {+ const referenceSource = await getReferenceSource();+ const allParams: { slug: string[] }[] = referenceSource.generateParams();+ // Only return params that start with 'v3', with the prefix stripped+ return allParams+ .filter((p) => p.slug[0] === 'v3')+ .map((p) => ({ slug: p.slug.slice(1) }));+}++export async function generateMetadata({+ params,+}: {+ params: Promise<{ slug?: string[] }>;+}): Promise<Metadata> {+ const { slug } = await params;+ const sourceSlug = toSourceSlug(slug);++ if (!slug || slug.length === 0) {+ const ogImage = getOgImageUrl('reference', [], 'API Reference (v3)', 'REST API reference for Composio v3');+ return {+ title: 'API Reference (v3)',+ description: 'REST API reference for Composio v3',+ alternates: { canonical: '/reference/v3' },+ openGraph: { images: [ogImage] },+ twitter: { card: 'summary_large_image', images: [ogImage] },+ };+ }++ const referenceSource = await getReferenceSource();+ const page = referenceSource.getPage(sourceSlug);+ if (!page) notFound();++ const description = page.data.description || page.data.title;+ const ogImage = getOgImageUrl('reference', page.slugs, page.data.title, description);++ return {+ title: page.data.title,+ description,+ alternates: { canonical: page.url },+ openGraph: { images: [ogImage] },+ twitter: { card: 'summary_large_image', images: [ogImage] },+ };+}diff --git a/docs/app/(home)/reference/v3/layout.tsx b/docs/app/(home)/reference/v3/layout.tsxnew file mode 100644index 000000000..aa9f48866--- /dev/null+++ b/docs/app/(home)/reference/v3/layout.tsx@@ -0,0 +1,21 @@+import { getReferenceSource } from '@/lib/source';+import { DocsLayout } from 'fumadocs-ui/layouts/docs';+import type { ReactNode } from 'react';+import { prepareTree } from '@/lib/filter-api-version';++export default async function Layout({ children }: { children: ReactNode }) {+ const source = await getReferenceSource();+ const tree = prepareTree(source.pageTree, '3.0');++ return (+ <DocsLayout+ tree={tree}+ nav={{ enabled: true, title: null }}+ searchToggle={{ enabled: false }}+ sidebar={{ collapsible: false, footer: null, tabs: false }}+ themeSwitch={{ enabled: false }}+ >+ {children}+ </DocsLayout>+ );+}diff --git a/docs/components/api-base-url.tsx b/docs/components/api-base-url.tsxnew file mode 100644index 000000000..a2037e5b3--- /dev/null+++ b/docs/components/api-base-url.tsx@@ -0,0 +1,18 @@+'use client';++import { useApiVersion } from '@/lib/use-api-version';++const BASE_URLS: Record<string, string> = {+ '3.1': 'https://backend.composio.dev/api/v3.1',+ '3.0': 'https://backend.composio.dev/api/v3',+};++/**+ * Renders the API base URL for the currently selected version.+ * Detects version from URL path (/reference/v3/ = v3.0, otherwise v3.1).+ */+export function ApiBaseUrl() {+ const version = useApiVersion();+ return <code>{BASE_URLS[version] ?? BASE_URLS['3.1']}</code>;+}+diff --git a/docs/components/api-endpoints-table.tsx b/docs/components/api-endpoints-table.tsxnew file mode 100644index 000000000..0b6b69003--- /dev/null+++ b/docs/components/api-endpoints-table.tsx@@ -0,0 +1,41 @@+'use client';++import { useApiVersion } from '@/lib/use-api-version';++interface Endpoint {+ method: string;+ pathV31: string;+ pathV3: string;+ summary: string;+ href: string;+}++/**+ * Renders an endpoint table that updates based on the selected API version.+ * Used in auto-generated index pages.+ */+export function ApiEndpointsTable({ endpoints }: { endpoints: Endpoint[] }) {+ const version = useApiVersion();++ return (+ <table>+ <thead>+ <tr>+ <th>Endpoint</th>+ <th>Quick Link</th>+ </tr>+ </thead>+ <tbody>+ {endpoints.map((ep, i) => {+ const path = version === '3.0' ? ep.pathV3 : ep.pathV31;+ return (+ <tr key={i}>+ <td><code>{ep.method} {path}</code></td>+ <td><a href={ep.href}>{ep.summary}</a></td>+ </tr>+ );+ })}+ </tbody>+ </table>+ );+}diff --git a/docs/components/version-badge.tsx b/docs/components/version-badge.tsxnew file mode 100644index 000000000..2e9386f94--- /dev/null+++ b/docs/components/version-badge.tsx@@ -0,0 +1,27 @@+/**+ * Badge component for displaying API version (v3.0, v3.1, etc.)+ */+export function VersionBadge({ version }: { version: string }) {+ const isLatest = version === '3.1';+ return (+ <span+ className={`inline-flex items-center rounded-md px-2 py-0.5 text-xs font-medium ring-1 ring-inset ${+ isLatest+ ? 'bg-green-50 text-green-700 ring-green-600/20 dark:bg-green-500/10 dark:text-green-400 dark:ring-green-500/20'+ : 'bg-fd-muted text-fd-muted-foreground ring-fd-border'+ }`}+ >+ v{version}+ </span>+ );+}++/**+ * Extract API version from an endpoint path like /api/v3.1/tools/...+ * Returns normalized version string (e.g., "3.0", "3.1")+ */+export function extractVersionFromPath(path: string): string | null {+ const match = path.match(/\/api\/v([\d.]+)\//);+ if (!match) return null;+ return match[1] === '3' ? '3.0' : match[1];+}diff --git a/docs/components/version-selector.tsx b/docs/components/version-selector.tsxnew file mode 100644index 000000000..fda8c35ce--- /dev/null+++ b/docs/components/version-selector.tsx@@ -0,0 +1,146 @@+'use client';++import { usePathname } from 'next/navigation';+import { useState, useRef, useEffect } from 'react';+import { useApiVersion } from '@/lib/use-api-version';++const VERSIONS = [+ { value: '3.1', label: 'v3.1', badge: 'Latest' },+ { value: '3.0', label: 'v3.0' },+] as const;++export function NavVersionSelector() {+ const pathname = usePathname();+ const isReferencePage = pathname.startsWith('/reference');+ const version = useApiVersion();+ const [open, setOpen] = useState(false);+ const ref = useRef<HTMLDivElement>(null);++ useEffect(() => {+ const handler = (e: MouseEvent) => {+ if (ref.current && !ref.current.contains(e.target as Node)) {+ setOpen(false);+ }+ };+ document.addEventListener('mousedown', handler);+ return () => document.removeEventListener('mousedown', handler);+ }, []);++ if (!isReferencePage) return null;++ const navigate = (newVersion: string) => {+ setOpen(false);+ if (newVersion === version) return;+ const path = window.location.pathname;++ if (newVersion === '3.0') {+ // Shared pages — go to v3 overview+ if (path.includes('/sdk-reference') || path.includes('/meta-tools') || path === '/reference') {+ window.location.href = '/reference/v3';+ } else {+ window.location.href = path.replace('/reference/', '/reference/v3/');+ }+ } else if (newVersion === '3.1') {+ if (path === '/reference/v3') {+ window.location.href = '/reference';+ } else {+ window.location.href = path.replace('/reference/v3/', '/reference/');+ }+ }+ };++ const current = VERSIONS.find((v) => v.value === version)!;++ return (+ <div ref={ref} className="relative">+ <button+ onClick={(e) => {+ e.preventDefault();+ e.stopPropagation();+ setOpen(!open);+ }}+ onKeyDown={(e) => { if (e.key === 'Escape') setOpen(false); }}+ aria-haspopup="listbox"+ aria-expanded={open}+ aria-label={`API version: ${current.label}. Switch version`}+ className="inline-flex items-center gap-1 rounded-md border px-1.5 py-0.5 text-xs font-medium transition-colors hover:bg-fd-accent/50"+ style={{+ borderColor: 'color-mix(in srgb, var(--composio-orange, #f97316) 40%, transparent)',+ color: 'var(--composio-orange, #f97316)',+ }}+ >+ {current.label}+ <svg+ aria-hidden="true"+ width="10"+ height="10"+ viewBox="0 0 24 24"+ fill="none"+ stroke="currentColor"+ strokeWidth="2.5"+ strokeLinecap="round"+ strokeLinejoin="round"+ className={`transition-transform ${open ? 'rotate-180' : ''}`}+ >+ <path d="m6 9 6 6 6-6" />+ </svg>+ </button>++ {open && (+ <div+ role="listbox"+ aria-label="API version"+ className="absolute left-0 top-full z-50 mt-1.5 min-w-[120px] overflow-hidden rounded-lg border border-fd-border bg-fd-popover p-1 shadow-lg"+ onClick={(e) => e.stopPropagation()}+ >+ {VERSIONS.map((v) => (+ <button+ key={v.value}+ role="option"+ aria-selected={v.value === version}+ onClick={(e) => {+ e.preventDefault();+ e.stopPropagation();+ navigate(v.value);+ }}+ className={`flex w-full items-center gap-2 rounded-md px-2.5 py-1.5 text-xs transition-colors ${+ v.value === version+ ? 'bg-fd-accent text-fd-accent-foreground font-medium'+ : 'text-fd-muted-foreground hover:bg-fd-accent/50 hover:text-fd-foreground'+ }`}+ >+ <span>{v.label}</span>+ {'badge' in v && v.badge && (+ <span+ className="rounded px-1 py-0.5 text-[10px] font-medium leading-none"+ style={{+ backgroundColor: 'color-mix(in srgb, var(--composio-orange, #f97316) 15%, transparent)',+ color: 'var(--composio-orange, #f97316)',+ }}+ >+ {v.badge}+ </span>+ )}+ {v.value === version && (+ <svg+ aria-hidden="true"+ width="12"+ height="12"+ viewBox="0 0 24 24"+ fill="none"+ stroke="currentColor"+ strokeWidth="3"+ strokeLinecap="round"+ strokeLinejoin="round"+ className="ml-auto"+ >+ <path d="M20 6 9 17l-5-5" />+ </svg>+ )}+ </button>+ ))}+ </div>+ )}+ </div>+ );+}diff --git a/docs/content/docs/auth-configuration/connected-accounts.mdx b/docs/content/docs/auth-configuration/connected-accounts.mdxindex 82ba89cae..9b9a49abd 100644--- a/docs/content/docs/auth-configuration/connected-accounts.mdx+++ b/docs/content/docs/auth-configuration/connected-accounts.mdx@@ -245,7 +245,7 @@ If you need full credential values (e.g., to use tokens in your own API calls),2. **API**:```bash-curl -X PATCH https://backend.composio.dev/api/v3/org/project/config \+curl -X PATCH https://backend.composio.dev/api/v3.1/org/project/config \-H "x-api-key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{"mask_secret_keys_in_connected_account": false}'diff --git a/docs/content/docs/common-faq.mdx b/docs/content/docs/common-faq.mdxindex ece471e5a..c2f8e7cb4 100644--- a/docs/content/docs/common-faq.mdx+++ b/docs/content/docs/common-faq.mdx@@ -95,12 +95,12 @@ This applies to direct tool execution only. Sessions with meta tools always use</Accordion><Accordion title="Why does the API return fewer tools than the platform UI?">-When calling the Get Tools API (`GET /api/v3/tools`) without specifying a `toolkit_versions` parameter, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. The platform UI shows tools from the latest version.+When calling the Get Tools API (`GET /api/v3.1/tools`) without specifying a `toolkit_versions` parameter, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. The platform UI shows tools from the latest version.To get all available tools, pass `toolkit_versions=latest`:```bash-curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \+curl 'https://backend.composio.dev/api/v3.1/tools?toolkit_slug=googledrive&toolkit_versions=latest' \-H 'x-api-key: YOUR_API_KEY'```@@ -198,7 +198,7 @@ Use your own credentials when you're going to production and users will see OAutCall the toolkits API and check the `composio_managed_auth_schemes` field:```bash-curl 'https://backend.composio.dev/api/v3/toolkits/github' \+curl 'https://backend.composio.dev/api/v3.1/toolkits/github' \-H 'x-api-key: YOUR_API_KEY'```@@ -207,7 +207,7 @@ If the array is empty, you'll need to provide your own credentials.To fetch all toolkits and filter by managed auth availability, use the list endpoint:```bash-curl 'https://backend.composio.dev/api/v3/toolkits' \+curl 'https://backend.composio.dev/api/v3.1/toolkits' \-H 'x-api-key: YOUR_API_KEY'```diff --git a/docs/content/docs/custom-app-vs-managed-app.mdx b/docs/content/docs/custom-app-vs-managed-app.mdxindex 1af5e9ace..b986a6833 100644--- a/docs/content/docs/custom-app-vs-managed-app.mdx+++ b/docs/content/docs/custom-app-vs-managed-app.mdx@@ -137,7 +137,7 @@ If your users already have connections through Composio managed auth, you can imSome toolkits don't have Composio managed auth. For these, you must create a custom auth config with your own credentials. You can check whether a toolkit has managed auth by calling the API:```bash-curl 'https://backend.composio.dev/api/v3/toolkits/posthog' \+curl 'https://backend.composio.dev/api/v3.1/toolkits/posthog' \-H 'x-api-key: YOUR_API_KEY'```diff --git a/docs/content/docs/projects.mdx b/docs/content/docs/projects.mdxindex c8bd3b328..71d5fa242 100644--- a/docs/content/docs/projects.mdx+++ b/docs/content/docs/projects.mdx@@ -34,7 +34,7 @@ Project management endpoints use the `x-org-api-key` header, not the regular `x-### Create a project```bash-curl -X POST https://backend.composio.dev/api/v3/org/owner/project/new \+curl -X POST https://backend.composio.dev/api/v3.1/org/owner/project/new \-H "x-org-api-key: YOUR_ORG_API_KEY" \-H "Content-Type: application/json" \-d '{@@ -56,7 +56,7 @@ The response includes the project ID and, if requested, an API key:### List projects```bash-curl https://backend.composio.dev/api/v3/org/owner/project/list \+curl https://backend.composio.dev/api/v3.1/org/owner/project/list \-H "x-org-api-key: YOUR_ORG_API_KEY"```@@ -65,7 +65,7 @@ Supports pagination with `limit` and `cursor` query parameters.### Get project details```bash-curl https://backend.composio.dev/api/v3/org/owner/project/proj_abc123xyz456 \+curl https://backend.composio.dev/api/v3.1/org/owner/project/proj_abc123xyz456 \-H "x-org-api-key: YOUR_ORG_API_KEY"```@@ -76,7 +76,7 @@ Returns the full project object including its API keys.Each project has settings that control security, logging, and display behavior. These endpoints use your **project API key** (`x-api-key`), not the org key.```bash-curl -X PATCH https://backend.composio.dev/api/v3/org/project/config \+curl -X PATCH https://backend.composio.dev/api/v3.1/org/project/config \-H "x-api-key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{diff --git a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdxindex 5fd91f081..51b3ae824 100644--- a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx+++ b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx@@ -16,7 +16,7 @@ Webhooks are the recommended way to receive trigger events in production. To staSet your webhook URL in the [dashboard settings](https://platform.composio.dev?next_page=/settings/webhook) or via the [Webhook Subscriptions API](/reference/api-reference/webhooks):```bash-curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \+curl -X POST https://backend.composio.dev/api/v3.1/webhook_subscriptions \-H "X-API-KEY: <your-composio-api-key>" \-H "Content-Type: application/json" \-d '{@@ -197,7 +197,7 @@ ngrok http 8000Then use the ngrok URL as your webhook endpoint:```bash-curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \+curl -X POST https://backend.composio.dev/api/v3.1/webhook_subscriptions \-H "X-API-KEY: <your-composio-api-key>" \-H "Content-Type: application/json" \-d '{diff --git a/docs/content/docs/subscribing-to-connection-expiry-events.mdx b/docs/content/docs/subscribing-to-connection-expiry-events.mdxindex fbefae1b8..e02d83ede 100644--- a/docs/content/docs/subscribing-to-connection-expiry-events.mdx+++ b/docs/content/docs/subscribing-to-connection-expiry-events.mdx@@ -17,7 +17,7 @@ This event is only available with [V3 webhook payloads](/docs/webhook-verificatiAdd `composio.connected_account.expired` to your webhook subscription's `enabled_events`:```bash-curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \+curl -X POST https://backend.composio.dev/api/v3.1/webhook_subscriptions \-H "X-API-KEY: <your-composio-api-key>" \-H "Content-Type: application/json" \-d '{diff --git a/docs/content/docs/tools-direct/toolkit-versioning.mdx b/docs/content/docs/tools-direct/toolkit-versioning.mdxindex 13d64811e..3539a3183 100644--- a/docs/content/docs/tools-direct/toolkit-versioning.mdx+++ b/docs/content/docs/tools-direct/toolkit-versioning.mdx@@ -31,11 +31,11 @@ This applies to both the SDK and direct REST API calls:```bash# Without version — returns only tools from the base version-curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive' \+curl 'https://backend.composio.dev/api/v3.1/tools?toolkit_slug=googledrive' \-H 'x-api-key: YOUR_API_KEY'# With version=latest — returns all tools including newer ones-curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \+curl 'https://backend.composio.dev/api/v3.1/tools?toolkit_slug=googledrive&toolkit_versions=latest' \-H 'x-api-key: YOUR_API_KEY'```diff --git a/docs/content/docs/troubleshooting/api.mdx b/docs/content/docs/troubleshooting/api.mdxindex 78729c09f..cf890ba4c 100644--- a/docs/content/docs/troubleshooting/api.mdx+++ b/docs/content/docs/troubleshooting/api.mdx@@ -15,7 +15,7 @@ When reporting API issues to support, provide the following:- **Request ID**: Add `x-request-id: <uuid>` header to your request and share the UUID (generate at [uuidgenerator.net](https://www.uuidgenerator.net/))```bash- curl 'https://backend.composio.dev/api/v3/tools' \+ curl 'https://backend.composio.dev/api/v3.1/tools' \-H 'x-api-key: YOUR_API_KEY' \-H 'x-request-id: YOUR_UUID_HERE'```diff --git a/docs/content/docs/troubleshooting/index.mdx b/docs/content/docs/troubleshooting/index.mdxindex bf85d6b85..b6e3b1e40 100644--- a/docs/content/docs/troubleshooting/index.mdx+++ b/docs/content/docs/troubleshooting/index.mdx@@ -33,7 +33,7 @@ See [Troubleshooting MCP](/docs/troubleshooting/mcp#reporting-mcp-issues) for aAdd an `x-request-id` header with a UUID to your API request. This lets support trace your exact request in server logs.```bash-curl 'https://backend.composio.dev/api/v3/tools' \+curl 'https://backend.composio.dev/api/v3.1/tools' \-H 'x-api-key: YOUR_API_KEY' \-H 'x-request-id: YOUR_UUID_HERE'```diff --git a/docs/content/docs/troubleshooting/tools.mdx b/docs/content/docs/troubleshooting/tools.mdxindex 872ef0030..5c433be79 100644--- a/docs/content/docs/troubleshooting/tools.mdx+++ b/docs/content/docs/troubleshooting/tools.mdx@@ -21,14 +21,14 @@ Verify the connected account has necessary permissions:## API returning fewer tools than expected-If the Get Tools API (`GET /api/v3/tools`) returns fewer tools than what's shown on the [platform UI](https://platform.composio.dev), you likely need to specify a toolkit version.+If the Get Tools API (`GET /api/v3.1/tools`) returns fewer tools than what's shown on the [platform UI](https://platform.composio.dev), you likely need to specify a toolkit version.When `toolkit_versions` is not provided, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. Tools added in later versions won't appear.To get all available tools, pass `toolkit_versions=latest`:```bash-curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \+curl 'https://backend.composio.dev/api/v3.1/tools?toolkit_slug=googledrive&toolkit_versions=latest' \-H 'x-api-key: YOUR_API_KEY'```diff --git a/docs/content/reference/api-reference/auth-configs/index.mdx b/docs/content/reference/api-reference/auth-configs/index.mdxindex 6c8e8d3ee..5f7e79843 100644--- a/docs/content/reference/api-reference/auth-configs/index.mdx+++ b/docs/content/reference/api-reference/auth-configs/index.mdx@@ -9,11 +9,4 @@ Authentication configuration management## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `POST /api/v3/auth_configs` | [Create new authentication configuration](/reference/api-reference/auth-configs/postAuthConfigs) |-| `GET /api/v3/auth_configs` | [List authentication configurations with optional filters](/reference/api-reference/auth-configs/getAuthConfigs) |-| `GET /api/v3/auth_configs/{nanoid}` | [Get single authentication configuration by ID](/reference/api-reference/auth-configs/getAuthConfigsByNanoid) |-| `PATCH /api/v3/auth_configs/{nanoid}` | [Update an authentication configuration](/reference/api-reference/auth-configs/patchAuthConfigsByNanoid) |-| `DELETE /api/v3/auth_configs/{nanoid}` | [Delete an authentication configuration](/reference/api-reference/auth-configs/deleteAuthConfigsByNanoid) |-| `PATCH /api/v3/auth_configs/{nanoid}/{status}` | [Enable or disable an authentication configuration](/reference/api-reference/auth-configs/patchAuthConfigsByNanoidByStatus) |+<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/auth_configs","pathV3":"/api/v3/auth_configs","summary":"Create new authentication configuration","href":"/reference/api-reference/auth-configs/postAuthConfigs"},{"method":"GET","pathV31":"/api/v3.1/auth_configs","pathV3":"/api/v3/auth_configs","summary":"List authentication configurations with optional filters","href":"/reference/api-reference/auth-configs/getAuthConfigs"},{"method":"GET","pathV31":"/api/v3.1/auth_configs/{nanoid}","pathV3":"/api/v3/auth_configs/{nanoid}","summary":"Get single authentication configuration by ID","href":"/reference/api-reference/auth-configs/getAuthConfigsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/auth_configs/{nanoid}","pathV3":"/api/v3/auth_configs/{nanoid}","summary":"Update an authentication configuration","href":"/reference/api-reference/auth-configs/patchAuthConfigsByNanoid"},{"method":"DELETE","pathV31":"/api/v3.1/auth_configs/{nanoid}","pathV3":"/api/v3/auth_configs/{nanoid}","summary":"Delete an authentication configuration","href":"/reference/api-reference/auth-configs/deleteAuthConfigsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/auth_configs/{nanoid}/{status}","pathV3":"/api/v3/auth_configs/{nanoid}/{status}","summary":"Enable or disable an authentication configuration","href":"/reference/api-reference/auth-configs/patchAuthConfigsByNanoidByStatus"}]} />diff --git a/docs/content/reference/api-reference/authentication/index.mdx b/docs/content/reference/api-reference/authentication/index.mdxindex 061db945c..d5f7661cf 100644--- a/docs/content/reference/api-reference/authentication/index.mdx+++ b/docs/content/reference/api-reference/authentication/index.mdx@@ -9,6 +9,4 @@ Authentication related endpoints## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/auth/session/info` | [Get current user session information](/reference/api-reference/authentication/getAuthSessionInfo) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/auth/session/info","pathV3":"/api/v3/auth/session/info","summary":"Get current user session information","href":"/reference/api-reference/authentication/getAuthSessionInfo"}]} />diff --git a/docs/content/reference/api-reference/connected-accounts/index.mdx b/docs/content/reference/api-reference/connected-accounts/index.mdxindex 78311db72..dfecc803d 100644--- a/docs/content/reference/api-reference/connected-accounts/index.mdx+++ b/docs/content/reference/api-reference/connected-accounts/index.mdx@@ -9,13 +9,4 @@ Connected account management## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/connected_accounts` | [List connected accounts with optional filters](/reference/api-reference/connected-accounts/getConnectedAccounts) |-| `POST /api/v3/connected_accounts` | [Create a new connected account](/reference/api-reference/connected-accounts/postConnectedAccounts) |-| `GET /api/v3/connected_accounts/{nanoid}` | [Get connected account details by ID](/reference/api-reference/connected-accounts/getConnectedAccountsByNanoid) |-| `DELETE /api/v3/connected_accounts/{nanoid}` | [Delete a connected account](/reference/api-reference/connected-accounts/deleteConnectedAccountsByNanoid) |-| `PATCH /api/v3/connected_accounts/{nanoid}` | [Update a connected account](/reference/api-reference/connected-accounts/patchConnectedAccountsByNanoid) |-| `PATCH /api/v3/connected_accounts/{nanoId}/status` | [Enable or disable a connected account](/reference/api-reference/connected-accounts/patchConnectedAccountsByNanoIdStatus) |-| `POST /api/v3/connected_accounts/{nanoid}/refresh` | [Refresh authentication for a connected account](/reference/api-reference/connected-accounts/postConnectedAccountsByNanoidRefresh) |-| `POST /api/v3/connected_accounts/link` | [Create a new auth link session](/reference/api-reference/connected-accounts/postConnectedAccountsLink) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/connected_accounts","pathV3":"/api/v3/connected_accounts","summary":"List connected accounts with optional filters","href":"/reference/api-reference/connected-accounts/getConnectedAccounts"},{"method":"POST","pathV31":"/api/v3.1/connected_accounts","pathV3":"/api/v3/connected_accounts","summary":"Create a new connected account","href":"/reference/api-reference/connected-accounts/postConnectedAccounts"},{"method":"GET","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Get connected account details by ID","href":"/reference/api-reference/connected-accounts/getConnectedAccountsByNanoid"},{"method":"DELETE","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Delete a connected account","href":"/reference/api-reference/connected-accounts/deleteConnectedAccountsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Update a connected account","href":"/reference/api-reference/connected-accounts/patchConnectedAccountsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/connected_accounts/{nanoId}/status","pathV3":"/api/v3/connected_accounts/{nanoId}/status","summary":"Enable or disable a connected account","href":"/reference/api-reference/connected-accounts/patchConnectedAccountsByNanoIdStatus"},{"method":"POST","pathV31":"/api/v3.1/connected_accounts/{nanoid}/refresh","pathV3":"/api/v3/connected_accounts/{nanoid}/refresh","summary":"Refresh authentication for a connected account","href":"/reference/api-reference/connected-accounts/postConnectedAccountsByNanoidRefresh"},{"method":"POST","pathV31":"/api/v3.1/connected_accounts/link","pathV3":"/api/v3/connected_accounts/link","summary":"Create a new auth link session","href":"/reference/api-reference/connected-accounts/postConnectedAccountsLink"}]} />diff --git a/docs/content/reference/api-reference/files/index.mdx b/docs/content/reference/api-reference/files/index.mdxindex 9b951b36b..0e756bdab 100644--- a/docs/content/reference/api-reference/files/index.mdx+++ b/docs/content/reference/api-reference/files/index.mdx@@ -9,7 +9,4 @@ File management## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/files/list` | [List files with optional app and action filters](/reference/api-reference/files/getFilesList) |-| `POST /api/v3/files/upload/request` | [Create presigned URL for request file upload to S3](/reference/api-reference/files/postFilesUploadRequest) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/files/list","pathV3":"/api/v3/files/list","summary":"List files with optional app and action filters","href":"/reference/api-reference/files/getFilesList"},{"method":"POST","pathV31":"/api/v3.1/files/upload/request","pathV3":"/api/v3/files/upload/request","summary":"Create presigned URL for request file upload to S3","href":"/reference/api-reference/files/postFilesUploadRequest"}]} />diff --git a/docs/content/reference/api-reference/mcp/index.mdx b/docs/content/reference/api-reference/mcp/index.mdxindex c9f03bc21..2c694dcf5 100644--- a/docs/content/reference/api-reference/mcp/index.mdx+++ b/docs/content/reference/api-reference/mcp/index.mdx@@ -9,16 +9,4 @@ MCP server management## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/mcp/servers` | [List MCP servers with optional filters and pagination](/reference/api-reference/mcp/getMcpServers) |-| `POST /api/v3/mcp/servers` | [Create a new MCP server](/reference/api-reference/mcp/postMcpServers) |-| `POST /api/v3/mcp/servers/custom` | [Create a new custom MCP server with multiple apps](/reference/api-reference/mcp/postMcpServersCustom) |-| `POST /api/v3/mcp/servers/generate` | [Generate MCP URL with custom parameters](/reference/api-reference/mcp/postMcpServersGenerate) |-| `GET /api/v3/mcp/{id}` | [Get MCP server details by ID](/reference/api-reference/mcp/getMcpById) |-| `PATCH /api/v3/mcp/{id}` | [Update MCP server configuration](/reference/api-reference/mcp/patchMcpById) |-| `DELETE /api/v3/mcp/{id}` | [Delete an MCP server](/reference/api-reference/mcp/deleteMcpById) |-| `GET /api/v3/mcp/app/{appKey}` | [List MCP servers for a specific app](/reference/api-reference/mcp/getMcpAppByAppKey) |-| `GET /api/v3/mcp/servers/{serverId}/instances` | [List all instances for an MCP server](/reference/api-reference/mcp/getMcpServersByServerIdInstances) |-| `POST /api/v3/mcp/servers/{serverId}/instances` | [Create a new MCP server instance](/reference/api-reference/mcp/postMcpServersByServerIdInstances) |-| `DELETE /api/v3/mcp/servers/{serverId}/instances/{instanceId}` | [Delete an MCP server instance and associated connected accounts](/reference/api-reference/mcp/deleteMcpServersByServerIdInstancesByInstanceId) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/mcp/servers","pathV3":"/api/v3/mcp/servers","summary":"List MCP servers with optional filters and pagination","href":"/reference/api-reference/mcp/getMcpServers"},{"method":"POST","pathV31":"/api/v3.1/mcp/servers","pathV3":"/api/v3/mcp/servers","summary":"Create a new MCP server","href":"/reference/api-reference/mcp/postMcpServers"},{"method":"POST","pathV31":"/api/v3.1/mcp/servers/custom","pathV3":"/api/v3/mcp/servers/custom","summary":"Create a new custom MCP server with multiple apps","href":"/reference/api-reference/mcp/postMcpServersCustom"},{"method":"POST","pathV31":"/api/v3.1/mcp/servers/generate","pathV3":"/api/v3/mcp/servers/generate","summary":"Generate MCP URL with custom parameters","href":"/reference/api-reference/mcp/postMcpServersGenerate"},{"method":"GET","pathV31":"/api/v3.1/mcp/{id}","pathV3":"/api/v3/mcp/{id}","summary":"Get MCP server details by ID","href":"/reference/api-reference/mcp/getMcpById"},{"method":"PATCH","pathV31":"/api/v3.1/mcp/{id}","pathV3":"/api/v3/mcp/{id}","summary":"Update MCP server configuration","href":"/reference/api-reference/mcp/patchMcpById"},{"method":"DELETE","pathV31":"/api/v3.1/mcp/{id}","pathV3":"/api/v3/mcp/{id}","summary":"Delete an MCP server","href":"/reference/api-reference/mcp/deleteMcpById"},{"method":"GET","pathV31":"/api/v3.1/mcp/app/{appKey}","pathV3":"/api/v3/mcp/app/{appKey}","summary":"List MCP servers for a specific app","href":"/reference/api-reference/mcp/getMcpAppByAppKey"},{"method":"GET","pathV31":"/api/v3.1/mcp/servers/{serverId}/instances","pathV3":"/api/v3/mcp/servers/{serverId}/instances","summary":"List all instances for an MCP server","href":"/reference/api-reference/mcp/getMcpServersByServerIdInstances"},{"method":"POST","pathV31":"/api/v3.1/mcp/servers/{serverId}/instances","pathV3":"/api/v3/mcp/servers/{serverId}/instances","summary":"Create a new MCP server instance","href":"/reference/api-reference/mcp/postMcpServersByServerIdInstances"},{"method":"DELETE","pathV31":"/api/v3.1/mcp/servers/{serverId}/instances/{instanceId}","pathV3":"/api/v3/mcp/servers/{serverId}/instances/{instanceId}","summary":"Delete an MCP server instance and associated connected accounts","href":"/reference/api-reference/mcp/deleteMcpServersByServerIdInstancesByInstanceId"}]} />diff --git a/docs/content/reference/api-reference/migration/index.mdx b/docs/content/reference/api-reference/migration/index.mdxindex c2112ffd7..61e8783d4 100644--- a/docs/content/reference/api-reference/migration/index.mdx+++ b/docs/content/reference/api-reference/migration/index.mdx@@ -9,6 +9,4 @@ Endpoints to help with migration from v1 to v3## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/migration/get-nanoid` | [Get NanoId from UUID](/reference/api-reference/migration/getMigrationGetNanoid) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/migration/get-nanoid","pathV3":"/api/v3/migration/get-nanoid","summary":"Get NanoId from UUID","href":"/reference/api-reference/migration/getMigrationGetNanoid"}]} />diff --git a/docs/content/reference/api-reference/organization/index.mdx b/docs/content/reference/api-reference/organization/index.mdxindex f209db49e..c5a15de77 100644--- a/docs/content/reference/api-reference/organization/index.mdx+++ b/docs/content/reference/api-reference/organization/index.mdx@@ -9,6 +9,4 @@ Organization management## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/org/usage/summary` | [Org usage summary](/reference/api-reference/organization/getOrgUsageSummary) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/org/usage/summary","pathV3":"/api/v3/org/usage/summary","summary":"Org usage summary","href":"/reference/api-reference/organization/getOrgUsageSummary"}]} />diff --git a/docs/content/reference/api-reference/projects/index.mdx b/docs/content/reference/api-reference/projects/index.mdxindex 1ada4df42..7466f634b 100644--- a/docs/content/reference/api-reference/projects/index.mdx+++ b/docs/content/reference/api-reference/projects/index.mdx@@ -9,13 +9,4 @@ Projects API endpoints## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/org/project/config` | [Get project configuration](/reference/api-reference/projects/getOrgProjectConfig) |-| `PATCH /api/v3/org/project/config` | [Update project configuration](/reference/api-reference/projects/patchOrgProjectConfig) |-| `GET /api/v3/org/project/usage/summary` | [Project usage summary](/reference/api-reference/projects/getOrgProjectUsageSummary) |-| `POST /api/v3/org/owner/project/new` | [Create a new project](/reference/api-reference/projects/postOrgOwnerProjectNew) |-| `GET /api/v3/org/owner/project/list` | [List all projects](/reference/api-reference/projects/getOrgOwnerProjectList) |-| `GET /api/v3/org/owner/project/{nano_id}` | [Get project details by ID With Org Api key](/reference/api-reference/projects/getOrgOwnerProjectByNanoId) |-| `DELETE /api/v3/org/owner/project/{nano_id}` | [Delete a project](/reference/api-reference/projects/deleteOrgOwnerProjectByNanoId) |-| `POST /api/v3/org/owner/project/{nano_id}/regenerate_api_key` | [Delete and generate new API key for project](/reference/api-reference/projects/postOrgOwnerProjectByNanoIdRegenerateApiKey) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/org/project/config","pathV3":"/api/v3/org/project/config","summary":"Get project configuration","href":"/reference/api-reference/projects/getOrgProjectConfig"},{"method":"PATCH","pathV31":"/api/v3.1/org/project/config","pathV3":"/api/v3/org/project/config","summary":"Update project configuration","href":"/reference/api-reference/projects/patchOrgProjectConfig"},{"method":"GET","pathV31":"/api/v3.1/org/project/usage/summary","pathV3":"/api/v3/org/project/usage/summary","summary":"Project usage summary","href":"/reference/api-reference/projects/getOrgProjectUsageSummary"},{"method":"POST","pathV31":"/api/v3.1/org/owner/project/new","pathV3":"/api/v3/org/owner/project/new","summary":"Create a new project","href":"/reference/api-reference/projects/postOrgOwnerProjectNew"},{"method":"GET","pathV31":"/api/v3.1/org/owner/project/list","pathV3":"/api/v3/org/owner/project/list","summary":"List all projects","href":"/reference/api-reference/projects/getOrgOwnerProjectList"},{"method":"GET","pathV31":"/api/v3.1/org/owner/project/{nano_id}","pathV3":"/api/v3/org/owner/project/{nano_id}","summary":"Get project details by ID With Org Api key","href":"/reference/api-reference/projects/getOrgOwnerProjectByNanoId"},{"method":"DELETE","pathV31":"/api/v3.1/org/owner/project/{nano_id}","pathV3":"/api/v3/org/owner/project/{nano_id}","summary":"Delete a project","href":"/reference/api-reference/projects/deleteOrgOwnerProjectByNanoId"},{"method":"POST","pathV31":"/api/v3.1/org/owner/project/{nano_id}/regenerate_api_key","pathV3":"/api/v3/org/owner/project/{nano_id}/regenerate_api_key","summary":"Delete and generate new API key for project","href":"/reference/api-reference/projects/postOrgOwnerProjectByNanoIdRegenerateApiKey"}]} />diff --git a/docs/content/reference/api-reference/tool-router/index.mdx b/docs/content/reference/api-reference/tool-router/index.mdxindex de45d2423..eedb95e5d 100644--- a/docs/content/reference/api-reference/tool-router/index.mdx+++ b/docs/content/reference/api-reference/tool-router/index.mdx@@ -9,18 +9,4 @@ description: "(Labs) Tool router endpoints"## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `POST /api/v3/tool_router/session` | [Create a new tool router session](/reference/api-reference/tool-router/postToolRouterSession) |-| `POST /api/v3/tool_router/session/{session_id}/execute` | [Execute a tool within a tool router session](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdExecute) |-| `POST /api/v3/tool_router/session/{session_id}/execute_meta` | [Execute a meta tool within a tool router session](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdExecuteMeta) |-| `GET /api/v3/tool_router/session/{session_id}` | [Get a tool router session by ID](/reference/api-reference/tool-router/getToolRouterSessionBySessionId) |-| `POST /api/v3/tool_router/session/{session_id}/link` | [Create a link session for a toolkit in a tool router session](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdLink) |-| `POST /api/v3/tool_router/session/{session_id}/proxy_execute` | [Execute proxy request within a tool router session](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdProxyExecute) |-| `GET /api/v3/tool_router/session/{session_id}/toolkits` | [Get toolkits for a tool router session](/reference/api-reference/tool-router/getToolRouterSessionBySessionIdToolkits) |-| `GET /api/v3/tool_router/session/{session_id}/tools` | [List meta tools with schemas for a tool router session](/reference/api-reference/tool-router/getToolRouterSessionBySessionIdTools) |-| `POST /api/v3/tool_router/session/{session_id}/search` | [Search for tools using a query](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdSearch) |-| `GET /api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items` | [List files in a session mount](/reference/api-reference/tool-router/getToolRouterSessionBySessionIdMountsByMountIdItems) |-| `POST /api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url` | [Create a presigned download URL for a mount file](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdDownloadUrl) |-| `POST /api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url` | [Create a presigned upload URL for a mount file](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdUploadUrl) |-| `POST /api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete` | [Delete a file from a session mount](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdDelete) |+<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/tool_router/session","pathV3":"/api/v3/tool_router/session","summary":"Create a new tool router session","href":"/reference/api-reference/tool-router/postToolRouterSession"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/execute","pathV3":"/api/v3/tool_router/session/{session_id}/execute","summary":"Execute a tool within a tool router session","href":"/reference/api-reference/tool-router/postToolRouterSessionBySessionIdExecute"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/execute_meta","pathV3":"/api/v3/tool_router/session/{session_id}/execute_meta","summary":"Execute a meta tool within a tool router session","href":"/reference/api-reference/tool-router/postToolRouterSessionBySessionIdExecuteMeta"},{"method":"GET","pathV31":"/api/v3.1/tool_router/session/{session_id}","pathV3":"/api/v3/tool_router/session/{session_id}","summary":"Get a tool router session by ID","href":"/reference/api-reference/tool-router/getToolRouterSessionBySessionId"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/link","pathV3":"/api/v3/tool_router/session/{session_id}/link","summary":"Create a link session for a toolkit in a tool router session","href":"/reference/api-reference/tool-router/postToolRouterSessionBySessionIdLink"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/proxy_execute","pathV3":"/api/v3/tool_router/session/{session_id}/proxy_execute","summary":"Execute proxy request within a tool router session","href":"/reference/api-reference/tool-router/postToolRouterSessionBySessionIdProxyExecute"},{"method":"GET","pathV31":"/api/v3.1/tool_router/session/{session_id}/toolkits","pathV3":"/api/v3/tool_router/session/{session_id}/toolkits","summary":"Get toolkits for a tool router session","href":"/reference/api-reference/tool-router/getToolRouterSessionBySessionIdToolkits"},{"method":"GET","pathV31":"/api/v3.1/tool_router/session/{session_id}/tools","pathV3":"/api/v3/tool_router/session/{session_id}/tools","summary":"List meta tools with schemas for a tool router session","href":"/reference/api-reference/tool-router/getToolRouterSessionBySessionIdTools"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/search","pathV3":"/api/v3/tool_router/session/{session_id}/search","summary":"Search for tools using a query","href":"/reference/api-reference/tool-router/postToolRouterSessionBySessionIdSearch"},{"method":"GET","pathV31":"/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/items","pathV3":"/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items","summary":"List files in a session mount","href":"/reference/api-reference/tool-router/getToolRouterSessionBySessionIdMountsByMountIdItems"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/download_url","pathV3":"/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url","summary":"Create a presigned download URL for a mount file","href":"/reference/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdDownloadUrl"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/upload_url","pathV3":"/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url","summary":"Create a presigned upload URL for a mount file","href":"/reference/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdUploadUrl"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/delete","pathV3":"/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete","summary":"Delete a file from a session mount","href":"/reference/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdDelete"}]} />diff --git a/docs/content/reference/api-reference/toolkits/index.mdx b/docs/content/reference/api-reference/toolkits/index.mdxindex bd9b91e30..8e5b74b1a 100644--- a/docs/content/reference/api-reference/toolkits/index.mdx+++ b/docs/content/reference/api-reference/toolkits/index.mdx@@ -9,10 +9,4 @@ Toolkit and tool management## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/toolkits` | [List available toolkits](/reference/api-reference/toolkits/getToolkits) |-| `GET /api/v3/toolkits/categories` | [List toolkit categories](/reference/api-reference/toolkits/getToolkitsCategories) |-| `GET /api/v3/toolkits/{slug}` | [Get toolkit by slug](/reference/api-reference/toolkits/getToolkitsBySlug) |-| `POST /api/v3/toolkits/multi` | [Fetch multiple toolkits](/reference/api-reference/toolkits/postToolkitsMulti) |-| `GET /api/v3/toolkits/changelog` | [Get toolkits changelog](/reference/api-reference/toolkits/getToolkitsChangelog) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/toolkits","pathV3":"/api/v3/toolkits","summary":"List available toolkits","href":"/reference/api-reference/toolkits/getToolkits"},{"method":"GET","pathV31":"/api/v3.1/toolkits/categories","pathV3":"/api/v3/toolkits/categories","summary":"List toolkit categories","href":"/reference/api-reference/toolkits/getToolkitsCategories"},{"method":"GET","pathV31":"/api/v3.1/toolkits/{slug}","pathV3":"/api/v3/toolkits/{slug}","summary":"Get toolkit by slug","href":"/reference/api-reference/toolkits/getToolkitsBySlug"},{"method":"POST","pathV31":"/api/v3.1/toolkits/multi","pathV3":"/api/v3/toolkits/multi","summary":"Fetch multiple toolkits","href":"/reference/api-reference/toolkits/postToolkitsMulti"},{"method":"GET","pathV31":"/api/v3.1/toolkits/changelog","pathV3":"/api/v3/toolkits/changelog","summary":"Get toolkits changelog","href":"/reference/api-reference/toolkits/getToolkitsChangelog"}]} />diff --git a/docs/content/reference/api-reference/tools/index.mdx b/docs/content/reference/api-reference/tools/index.mdxindex 5fa246f09..5c81ea735 100644--- a/docs/content/reference/api-reference/tools/index.mdx+++ b/docs/content/reference/api-reference/tools/index.mdx@@ -9,11 +9,4 @@ Tool execution endpoints## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `GET /api/v3/tools` | [List available tools](/reference/api-reference/tools/getTools) |-| `GET /api/v3/tools/enum` | [Get tool enum list](/reference/api-reference/tools/getToolsEnum) |-| `GET /api/v3/tools/{tool_slug}` | [Get tool by slug](/reference/api-reference/tools/getToolsByToolSlug) |-| `POST /api/v3/tools/execute/{tool_slug}` | [Execute tool](/reference/api-reference/tools/postToolsExecuteByToolSlug) |-| `POST /api/v3/tools/execute/{tool_slug}/input` | [Generate tool inputs from natural language](/reference/api-reference/tools/postToolsExecuteByToolSlugInput) |-| `POST /api/v3/tools/execute/proxy` | [Execute proxy request](/reference/api-reference/tools/postToolsExecuteProxy) |+<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/tools","pathV3":"/api/v3/tools","summary":"List available tools","href":"/reference/api-reference/tools/getTools"},{"method":"GET","pathV31":"/api/v3.1/tools/enum","pathV3":"/api/v3/tools/enum","summary":"Get tool enum list","href":"/reference/api-reference/tools/getToolsEnum"},{"method":"GET","pathV31":"/api/v3.1/tools/{tool_slug}","pathV3":"/api/v3/tools/{tool_slug}","summary":"Get tool by slug","href":"/reference/api-reference/tools/getToolsByToolSlug"},{"method":"POST","pathV31":"/api/v3.1/tools/execute/{tool_slug}","pathV3":"/api/v3/tools/execute/{tool_slug}","summary":"Execute tool","href":"/reference/api-reference/tools/postToolsExecuteByToolSlug"},{"method":"POST","pathV31":"/api/v3.1/tools/execute/{tool_slug}/input","pathV3":"/api/v3/tools/execute/{tool_slug}/input","summary":"Generate tool inputs from natural language","href":"/reference/api-reference/tools/postToolsExecuteByToolSlugInput"},{"method":"POST","pathV31":"/api/v3.1/tools/execute/proxy","pathV3":"/api/v3/tools/execute/proxy","summary":"Execute proxy request","href":"/reference/api-reference/tools/postToolsExecuteProxy"},{"method":"POST","pathV31":"/api/v3.1/tools/scopes/required","pathV3":"/api/v3/tools/scopes/required","summary":"Get required scopes for tools","href":"/reference/api-reference/tools/postToolsScopesRequired"}]} />diff --git a/docs/content/reference/api-reference/triggers/index.mdx b/docs/content/reference/api-reference/triggers/index.mdxindex a2bfe710e..414677989 100644--- a/docs/content/reference/api-reference/triggers/index.mdx+++ b/docs/content/reference/api-reference/triggers/index.mdx@@ -9,12 +9,4 @@ Trigger management and execution## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `POST /api/v3/trigger_instances/{slug}/upsert` | [Create or update a trigger](/reference/api-reference/triggers/postTriggerInstancesBySlugUpsert) |-| `GET /api/v3/trigger_instances/active` | [List active triggers](/reference/api-reference/triggers/getTriggerInstancesActive) |-| `DELETE /api/v3/trigger_instances/manage/{triggerId}` | [Delete a trigger](/reference/api-reference/triggers/deleteTriggerInstancesManageByTriggerId) |-| `PATCH /api/v3/trigger_instances/manage/{triggerId}` | [Enable or disable a trigger](/reference/api-reference/triggers/patchTriggerInstancesManageByTriggerId) |-| `GET /api/v3/triggers_types/list/enum` | [List trigger type enums](/reference/api-reference/triggers/getTriggersTypesListEnum) |-| `GET /api/v3/triggers_types/{slug}` | [Get trigger type by slug](/reference/api-reference/triggers/getTriggersTypesBySlug) |-| `GET /api/v3/triggers_types` | [List trigger types](/reference/api-reference/triggers/getTriggersTypes) |+<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/trigger_instances/{slug}/upsert","pathV3":"/api/v3/trigger_instances/{slug}/upsert","summary":"Create or update a trigger","href":"/reference/api-reference/triggers/postTriggerInstancesBySlugUpsert"},{"method":"GET","pathV31":"/api/v3.1/trigger_instances/active","pathV3":"/api/v3/trigger_instances/active","summary":"List active triggers","href":"/reference/api-reference/triggers/getTriggerInstancesActive"},{"method":"DELETE","pathV31":"/api/v3.1/trigger_instances/manage/{triggerId}","pathV3":"/api/v3/trigger_instances/manage/{triggerId}","summary":"Delete a trigger","href":"/reference/api-reference/triggers/deleteTriggerInstancesManageByTriggerId"},{"method":"PATCH","pathV31":"/api/v3.1/trigger_instances/manage/{triggerId}","pathV3":"/api/v3/trigger_instances/manage/{triggerId}","summary":"Enable or disable a trigger","href":"/reference/api-reference/triggers/patchTriggerInstancesManageByTriggerId"},{"method":"GET","pathV31":"/api/v3.1/triggers_types/list/enum","pathV3":"/api/v3/triggers_types/list/enum","summary":"List trigger type enums","href":"/reference/api-reference/triggers/getTriggersTypesListEnum"},{"method":"GET","pathV31":"/api/v3.1/triggers_types/{slug}","pathV3":"/api/v3/triggers_types/{slug}","summary":"Get trigger type by slug","href":"/reference/api-reference/triggers/getTriggersTypesBySlug"},{"method":"GET","pathV31":"/api/v3.1/triggers_types","pathV3":"/api/v3/triggers_types","summary":"List trigger types","href":"/reference/api-reference/triggers/getTriggersTypes"}]} />diff --git a/docs/content/reference/api-reference/webhooks/index.mdx b/docs/content/reference/api-reference/webhooks/index.mdxindex 35a6b2d4e..5eb98a298 100644--- a/docs/content/reference/api-reference/webhooks/index.mdx+++ b/docs/content/reference/api-reference/webhooks/index.mdx@@ -9,12 +9,4 @@ Webhook configuration## Endpoints-| Endpoint | Quick Link |-|----------|------------|-| `POST /api/v3/webhook_subscriptions` | [Create webhook subscription](/reference/api-reference/webhooks/postWebhookSubscriptions) |-| `GET /api/v3/webhook_subscriptions` | [List webhook subscriptions](/reference/api-reference/webhooks/getWebhookSubscriptions) |-| `GET /api/v3/webhook_subscriptions/{id}` | [Get webhook subscription](/reference/api-reference/webhooks/getWebhookSubscriptionsById) |-| `PATCH /api/v3/webhook_subscriptions/{id}` | [Update webhook subscription](/reference/api-reference/webhooks/patchWebhookSubscriptionsById) |-| `DELETE /api/v3/webhook_subscriptions/{id}` | [Delete webhook subscription](/reference/api-reference/webhooks/deleteWebhookSubscriptionsById) |-| `POST /api/v3/webhook_subscriptions/{id}/rotate_secret` | [Rotate webhook secret](/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret) |-| `GET /api/v3/webhook_subscriptions/event_types` | [List available event types](/reference/api-reference/webhooks/getWebhookSubscriptionsEventTypes) |+<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/webhook_subscriptions","pathV3":"/api/v3/webhook_subscriptions","summary":"Create webhook subscription","href":"/reference/api-reference/webhooks/postWebhookSubscriptions"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions","pathV3":"/api/v3/webhook_subscriptions","summary":"List webhook subscriptions","href":"/reference/api-reference/webhooks/getWebhookSubscriptions"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Get webhook subscription","href":"/reference/api-reference/webhooks/getWebhookSubscriptionsById"},{"method":"PATCH","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Update webhook subscription","href":"/reference/api-reference/webhooks/patchWebhookSubscriptionsById"},{"method":"DELETE","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Delete webhook subscription","href":"/reference/api-reference/webhooks/deleteWebhookSubscriptionsById"},{"method":"POST","pathV31":"/api/v3.1/webhook_subscriptions/{id}/rotate_secret","pathV3":"/api/v3/webhook_subscriptions/{id}/rotate_secret","summary":"Rotate webhook secret","href":"/reference/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions/event_types","pathV3":"/api/v3/webhook_subscriptions/event_types","summary":"List available event types","href":"/reference/api-reference/webhooks/getWebhookSubscriptionsEventTypes"}]} />diff --git a/docs/content/reference/authentication.mdx b/docs/content/reference/authentication.mdxindex 2869fa00d..e12a6aca3 100644--- a/docs/content/reference/authentication.mdx+++ b/docs/content/reference/authentication.mdx@@ -35,14 +35,14 @@ For organization-level access across multiple projects, use the `x-org-api-key`Include your API key in the request header:```bash-curl https://backend.composio.dev/api/v3/tools \+curl https://backend.composio.dev/api/v3.1/tools \-H "x-api-key: $COMPOSIO_API_KEY"```For organization-level endpoints:```bash-curl https://backend.composio.dev/api/v3/org/projects \+curl https://backend.composio.dev/api/v3.1/org/projects \-H "x-org-api-key: $COMPOSIO_ORG_API_KEY"```diff --git a/docs/content/reference/index.mdx b/docs/content/reference/index.mdxindex 6d459de66..1a86578c7 100644--- a/docs/content/reference/index.mdx+++ b/docs/content/reference/index.mdx@@ -8,7 +8,7 @@ Composio powers tool discovery, execution, authentication, and context managemen## Quick Reference-- **Base URL**: `https://backend.composio.dev/api/v3`+- **Base URL**: <ApiBaseUrl />- **[Authentication](/reference/authentication)**: `x-api-key` (project) or `x-org-api-key` (organization) header- **[Rate Limits](/reference/rate-limits)**: 20K-100K requests per 10 minutes (plan-dependent)diff --git a/docs/content/reference/meta.json b/docs/content/reference/meta.jsonindex 2c971b067..715c1b241 100644--- a/docs/content/reference/meta.json+++ b/docs/content/reference/meta.json@@ -6,6 +6,7 @@"rate-limits","errors","api-reference",+ "v3","meta-tools","sdk-reference"]diff --git a/docs/content/reference/v3/api-reference/auth-configs/index.mdx b/docs/content/reference/v3/api-reference/auth-configs/index.mdxnew file mode 100644index 000000000..415b09549--- /dev/null+++ b/docs/content/reference/v3/api-reference/auth-configs/index.mdx@@ -0,0 +1,12 @@+---+title: Auth Configs+description: "Authentication configuration management"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Authentication configuration management++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/auth_configs","pathV3":"/api/v3/auth_configs","summary":"Create new authentication configuration","href":"/reference/v3/api-reference/auth-configs/postAuthConfigs"},{"method":"GET","pathV31":"/api/v3.1/auth_configs","pathV3":"/api/v3/auth_configs","summary":"List authentication configurations with optional filters","href":"/reference/v3/api-reference/auth-configs/getAuthConfigs"},{"method":"GET","pathV31":"/api/v3.1/auth_configs/{nanoid}","pathV3":"/api/v3/auth_configs/{nanoid}","summary":"Get single authentication configuration by ID","href":"/reference/v3/api-reference/auth-configs/getAuthConfigsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/auth_configs/{nanoid}","pathV3":"/api/v3/auth_configs/{nanoid}","summary":"Update an authentication configuration","href":"/reference/v3/api-reference/auth-configs/patchAuthConfigsByNanoid"},{"method":"DELETE","pathV31":"/api/v3.1/auth_configs/{nanoid}","pathV3":"/api/v3/auth_configs/{nanoid}","summary":"Delete an authentication configuration","href":"/reference/v3/api-reference/auth-configs/deleteAuthConfigsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/auth_configs/{nanoid}/{status}","pathV3":"/api/v3/auth_configs/{nanoid}/{status}","summary":"Enable or disable an authentication configuration","href":"/reference/v3/api-reference/auth-configs/patchAuthConfigsByNanoidByStatus"}]} />diff --git a/docs/content/reference/v3/api-reference/authentication/index.mdx b/docs/content/reference/v3/api-reference/authentication/index.mdxnew file mode 100644index 000000000..75f1b0df4--- /dev/null+++ b/docs/content/reference/v3/api-reference/authentication/index.mdx@@ -0,0 +1,12 @@+---+title: Authentication+description: "Authentication related endpoints"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Authentication related endpoints++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/auth/session/info","pathV3":"/api/v3/auth/session/info","summary":"Get current user session information","href":"/reference/v3/api-reference/authentication/getAuthSessionInfo"}]} />diff --git a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx b/docs/content/reference/v3/api-reference/connected-accounts/index.mdxnew file mode 100644index 000000000..c9b9f7023--- /dev/null+++ b/docs/content/reference/v3/api-reference/connected-accounts/index.mdx@@ -0,0 +1,12 @@+---+title: Connected Accounts+description: "Connected account management"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Connected account management++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/connected_accounts","pathV3":"/api/v3/connected_accounts","summary":"List connected accounts with optional filters","href":"/reference/v3/api-reference/connected-accounts/getConnectedAccounts"},{"method":"POST","pathV31":"/api/v3.1/connected_accounts","pathV3":"/api/v3/connected_accounts","summary":"Create a new connected account","href":"/reference/v3/api-reference/connected-accounts/postConnectedAccounts"},{"method":"GET","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Get connected account details by ID","href":"/reference/v3/api-reference/connected-accounts/getConnectedAccountsByNanoid"},{"method":"DELETE","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Delete a connected account","href":"/reference/v3/api-reference/connected-accounts/deleteConnectedAccountsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Update a connected account","href":"/reference/v3/api-reference/connected-accounts/patchConnectedAccountsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/connected_accounts/{nanoId}/status","pathV3":"/api/v3/connected_accounts/{nanoId}/status","summary":"Enable or disable a connected account","href":"/reference/v3/api-reference/connected-accounts/patchConnectedAccountsByNanoIdStatus"},{"method":"POST","pathV31":"/api/v3.1/connected_accounts/{nanoid}/refresh","pathV3":"/api/v3/connected_accounts/{nanoid}/refresh","summary":"Refresh authentication for a connected account","href":"/reference/v3/api-reference/connected-accounts/postConnectedAccountsByNanoidRefresh"},{"method":"POST","pathV31":"/api/v3.1/connected_accounts/link","pathV3":"/api/v3/connected_accounts/link","summary":"Create a new auth link session","href":"/reference/v3/api-reference/connected-accounts/postConnectedAccountsLink"}]} />diff --git a/docs/content/reference/v3/api-reference/files/index.mdx b/docs/content/reference/v3/api-reference/files/index.mdxnew file mode 100644index 000000000..64c41cb83--- /dev/null+++ b/docs/content/reference/v3/api-reference/files/index.mdx@@ -0,0 +1,12 @@+---+title: Files+description: "File management"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++File management++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/files/list","pathV3":"/api/v3/files/list","summary":"List files with optional app and action filters","href":"/reference/v3/api-reference/files/getFilesList"},{"method":"POST","pathV31":"/api/v3.1/files/upload/request","pathV3":"/api/v3/files/upload/request","summary":"Create presigned URL for request file upload to S3","href":"/reference/v3/api-reference/files/postFilesUploadRequest"}]} />diff --git a/docs/content/reference/v3/api-reference/mcp/index.mdx b/docs/content/reference/v3/api-reference/mcp/index.mdxnew file mode 100644index 000000000..c89f55d1a--- /dev/null+++ b/docs/content/reference/v3/api-reference/mcp/index.mdx@@ -0,0 +1,12 @@+---+title: MCP+description: "MCP server management"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++MCP server management++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/mcp/servers","pathV3":"/api/v3/mcp/servers","summary":"List MCP servers with optional filters and pagination","href":"/reference/v3/api-reference/mcp/getMcpServers"},{"method":"POST","pathV31":"/api/v3.1/mcp/servers","pathV3":"/api/v3/mcp/servers","summary":"Create a new MCP server","href":"/reference/v3/api-reference/mcp/postMcpServers"},{"method":"POST","pathV31":"/api/v3.1/mcp/servers/custom","pathV3":"/api/v3/mcp/servers/custom","summary":"Create a new custom MCP server with multiple apps","href":"/reference/v3/api-reference/mcp/postMcpServersCustom"},{"method":"POST","pathV31":"/api/v3.1/mcp/servers/generate","pathV3":"/api/v3/mcp/servers/generate","summary":"Generate MCP URL with custom parameters","href":"/reference/v3/api-reference/mcp/postMcpServersGenerate"},{"method":"GET","pathV31":"/api/v3.1/mcp/{id}","pathV3":"/api/v3/mcp/{id}","summary":"Get MCP server details by ID","href":"/reference/v3/api-reference/mcp/getMcpById"},{"method":"PATCH","pathV31":"/api/v3.1/mcp/{id}","pathV3":"/api/v3/mcp/{id}","summary":"Update MCP server configuration","href":"/reference/v3/api-reference/mcp/patchMcpById"},{"method":"DELETE","pathV31":"/api/v3.1/mcp/{id}","pathV3":"/api/v3/mcp/{id}","summary":"Delete an MCP server","href":"/reference/v3/api-reference/mcp/deleteMcpById"},{"method":"GET","pathV31":"/api/v3.1/mcp/app/{appKey}","pathV3":"/api/v3/mcp/app/{appKey}","summary":"List MCP servers for a specific app","href":"/reference/v3/api-reference/mcp/getMcpAppByAppKey"},{"method":"GET","pathV31":"/api/v3.1/mcp/servers/{serverId}/instances","pathV3":"/api/v3/mcp/servers/{serverId}/instances","summary":"List all instances for an MCP server","href":"/reference/v3/api-reference/mcp/getMcpServersByServerIdInstances"},{"method":"POST","pathV31":"/api/v3.1/mcp/servers/{serverId}/instances","pathV3":"/api/v3/mcp/servers/{serverId}/instances","summary":"Create a new MCP server instance","href":"/reference/v3/api-reference/mcp/postMcpServersByServerIdInstances"},{"method":"DELETE","pathV31":"/api/v3.1/mcp/servers/{serverId}/instances/{instanceId}","pathV3":"/api/v3/mcp/servers/{serverId}/instances/{instanceId}","summary":"Delete an MCP server instance and associated connected accounts","href":"/reference/v3/api-reference/mcp/deleteMcpServersByServerIdInstancesByInstanceId"}]} />diff --git a/docs/content/reference/v3/api-reference/meta.json b/docs/content/reference/v3/api-reference/meta.jsonnew file mode 100644index 000000000..51b32ff19--- /dev/null+++ b/docs/content/reference/v3/api-reference/meta.json@@ -0,0 +1,5 @@+{+ "title": "API Reference",+ "defaultOpen": true,+ "pages": ["..."]+}diff --git a/docs/content/reference/v3/api-reference/migration/index.mdx b/docs/content/reference/v3/api-reference/migration/index.mdxnew file mode 100644index 000000000..cd4b045ea--- /dev/null+++ b/docs/content/reference/v3/api-reference/migration/index.mdx@@ -0,0 +1,12 @@+---+title: Migration+description: "Endpoints to help with migration from v1 to v3"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Endpoints to help with migration from v1 to v3++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/migration/get-nanoid","pathV3":"/api/v3/migration/get-nanoid","summary":"Get NanoId from UUID","href":"/reference/v3/api-reference/migration/getMigrationGetNanoid"}]} />diff --git a/docs/content/reference/v3/api-reference/organization/index.mdx b/docs/content/reference/v3/api-reference/organization/index.mdxnew file mode 100644index 000000000..fc3b5d2ca--- /dev/null+++ b/docs/content/reference/v3/api-reference/organization/index.mdx@@ -0,0 +1,12 @@+---+title: Organization+description: "Organization management"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Organization management++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/org/usage/summary","pathV3":"/api/v3/org/usage/summary","summary":"Org usage summary","href":"/reference/v3/api-reference/organization/getOrgUsageSummary"}]} />diff --git a/docs/content/reference/v3/api-reference/projects/index.mdx b/docs/content/reference/v3/api-reference/projects/index.mdxnew file mode 100644index 000000000..f2578c080--- /dev/null+++ b/docs/content/reference/v3/api-reference/projects/index.mdx@@ -0,0 +1,12 @@+---+title: Projects+description: "Projects API endpoints"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Projects API endpoints++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/org/project/config","pathV3":"/api/v3/org/project/config","summary":"Get project configuration","href":"/reference/v3/api-reference/projects/getOrgProjectConfig"},{"method":"PATCH","pathV31":"/api/v3.1/org/project/config","pathV3":"/api/v3/org/project/config","summary":"Update project configuration","href":"/reference/v3/api-reference/projects/patchOrgProjectConfig"},{"method":"GET","pathV31":"/api/v3.1/org/project/usage/summary","pathV3":"/api/v3/org/project/usage/summary","summary":"Project usage summary","href":"/reference/v3/api-reference/projects/getOrgProjectUsageSummary"},{"method":"POST","pathV31":"/api/v3.1/org/owner/project/new","pathV3":"/api/v3/org/owner/project/new","summary":"Create a new project","href":"/reference/v3/api-reference/projects/postOrgOwnerProjectNew"},{"method":"GET","pathV31":"/api/v3.1/org/owner/project/list","pathV3":"/api/v3/org/owner/project/list","summary":"List all projects","href":"/reference/v3/api-reference/projects/getOrgOwnerProjectList"},{"method":"GET","pathV31":"/api/v3.1/org/owner/project/{nano_id}","pathV3":"/api/v3/org/owner/project/{nano_id}","summary":"Get project details by ID With Org Api key","href":"/reference/v3/api-reference/projects/getOrgOwnerProjectByNanoId"},{"method":"DELETE","pathV31":"/api/v3.1/org/owner/project/{nano_id}","pathV3":"/api/v3/org/owner/project/{nano_id}","summary":"Delete a project","href":"/reference/v3/api-reference/projects/deleteOrgOwnerProjectByNanoId"},{"method":"POST","pathV31":"/api/v3.1/org/owner/project/{nano_id}/regenerate_api_key","pathV3":"/api/v3/org/owner/project/{nano_id}/regenerate_api_key","summary":"Delete and generate new API key for project","href":"/reference/v3/api-reference/projects/postOrgOwnerProjectByNanoIdRegenerateApiKey"}]} />diff --git a/docs/content/reference/v3/api-reference/tool-router/index.mdx b/docs/content/reference/v3/api-reference/tool-router/index.mdxnew file mode 100644index 000000000..a6aaf70f9--- /dev/null+++ b/docs/content/reference/v3/api-reference/tool-router/index.mdx@@ -0,0 +1,12 @@+---+title: Tool Router+description: "(Labs) Tool router endpoints"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++(Labs) Tool router endpoints++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/tool_router/session","pathV3":"/api/v3/tool_router/session","summary":"Create a new tool router session","href":"/reference/v3/api-reference/tool-router/postToolRouterSession"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/execute","pathV3":"/api/v3/tool_router/session/{session_id}/execute","summary":"Execute a tool within a tool router session","href":"/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdExecute"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/execute_meta","pathV3":"/api/v3/tool_router/session/{session_id}/execute_meta","summary":"Execute a meta tool within a tool router session","href":"/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdExecuteMeta"},{"method":"GET","pathV31":"/api/v3.1/tool_router/session/{session_id}","pathV3":"/api/v3/tool_router/session/{session_id}","summary":"Get a tool router session by ID","href":"/reference/v3/api-reference/tool-router/getToolRouterSessionBySessionId"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/link","pathV3":"/api/v3/tool_router/session/{session_id}/link","summary":"Create a link session for a toolkit in a tool router session","href":"/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdLink"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/proxy_execute","pathV3":"/api/v3/tool_router/session/{session_id}/proxy_execute","summary":"Execute proxy request within a tool router session","href":"/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdProxyExecute"},{"method":"GET","pathV31":"/api/v3.1/tool_router/session/{session_id}/toolkits","pathV3":"/api/v3/tool_router/session/{session_id}/toolkits","summary":"Get toolkits for a tool router session","href":"/reference/v3/api-reference/tool-router/getToolRouterSessionBySessionIdToolkits"},{"method":"GET","pathV31":"/api/v3.1/tool_router/session/{session_id}/tools","pathV3":"/api/v3/tool_router/session/{session_id}/tools","summary":"List meta tools with schemas for a tool router session","href":"/reference/v3/api-reference/tool-router/getToolRouterSessionBySessionIdTools"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/search","pathV3":"/api/v3/tool_router/session/{session_id}/search","summary":"Search for tools using a query","href":"/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdSearch"},{"method":"GET","pathV31":"/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/items","pathV3":"/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items","summary":"List files in a session mount","href":"/reference/v3/api-reference/tool-router/getToolRouterSessionBySessionIdMountsByMountIdItems"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/download_url","pathV3":"/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url","summary":"Create a presigned download URL for a mount file","href":"/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdDownloadUrl"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/upload_url","pathV3":"/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url","summary":"Create a presigned upload URL for a mount file","href":"/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdUploadUrl"},{"method":"POST","pathV31":"/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/delete","pathV3":"/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete","summary":"Delete a file from a session mount","href":"/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdMountsByMountIdDelete"}]} />diff --git a/docs/content/reference/v3/api-reference/toolkits/index.mdx b/docs/content/reference/v3/api-reference/toolkits/index.mdxnew file mode 100644index 000000000..a32ea5864--- /dev/null+++ b/docs/content/reference/v3/api-reference/toolkits/index.mdx@@ -0,0 +1,12 @@+---+title: Toolkits+description: "Toolkit and tool management"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Toolkit and tool management++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/toolkits","pathV3":"/api/v3/toolkits","summary":"List available toolkits","href":"/reference/v3/api-reference/toolkits/getToolkits"},{"method":"GET","pathV31":"/api/v3.1/toolkits/categories","pathV3":"/api/v3/toolkits/categories","summary":"List toolkit categories","href":"/reference/v3/api-reference/toolkits/getToolkitsCategories"},{"method":"GET","pathV31":"/api/v3.1/toolkits/{slug}","pathV3":"/api/v3/toolkits/{slug}","summary":"Get toolkit by slug","href":"/reference/v3/api-reference/toolkits/getToolkitsBySlug"},{"method":"POST","pathV31":"/api/v3.1/toolkits/multi","pathV3":"/api/v3/toolkits/multi","summary":"Fetch multiple toolkits","href":"/reference/v3/api-reference/toolkits/postToolkitsMulti"},{"method":"GET","pathV31":"/api/v3.1/toolkits/changelog","pathV3":"/api/v3/toolkits/changelog","summary":"Get toolkits changelog","href":"/reference/v3/api-reference/toolkits/getToolkitsChangelog"}]} />diff --git a/docs/content/reference/v3/api-reference/tools/index.mdx b/docs/content/reference/v3/api-reference/tools/index.mdxnew file mode 100644index 000000000..269e4c7b7--- /dev/null+++ b/docs/content/reference/v3/api-reference/tools/index.mdx@@ -0,0 +1,12 @@+---+title: Tools+description: "Tool execution endpoints"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Tool execution endpoints++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/tools","pathV3":"/api/v3/tools","summary":"List available tools","href":"/reference/v3/api-reference/tools/getTools"},{"method":"GET","pathV31":"/api/v3.1/tools/enum","pathV3":"/api/v3/tools/enum","summary":"Get tool enum list","href":"/reference/v3/api-reference/tools/getToolsEnum"},{"method":"GET","pathV31":"/api/v3.1/tools/{tool_slug}","pathV3":"/api/v3/tools/{tool_slug}","summary":"Get tool by slug","href":"/reference/v3/api-reference/tools/getToolsByToolSlug"},{"method":"POST","pathV31":"/api/v3.1/tools/execute/{tool_slug}","pathV3":"/api/v3/tools/execute/{tool_slug}","summary":"Execute tool","href":"/reference/v3/api-reference/tools/postToolsExecuteByToolSlug"},{"method":"POST","pathV31":"/api/v3.1/tools/execute/{tool_slug}/input","pathV3":"/api/v3/tools/execute/{tool_slug}/input","summary":"Generate tool inputs from natural language","href":"/reference/v3/api-reference/tools/postToolsExecuteByToolSlugInput"},{"method":"POST","pathV31":"/api/v3.1/tools/execute/proxy","pathV3":"/api/v3/tools/execute/proxy","summary":"Execute proxy request","href":"/reference/v3/api-reference/tools/postToolsExecuteProxy"}]} />diff --git a/docs/content/reference/v3/api-reference/triggers/index.mdx b/docs/content/reference/v3/api-reference/triggers/index.mdxnew file mode 100644index 000000000..973375c1a--- /dev/null+++ b/docs/content/reference/v3/api-reference/triggers/index.mdx@@ -0,0 +1,12 @@+---+title: Triggers+description: "Trigger management and execution"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Trigger management and execution++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/trigger_instances/{slug}/upsert","pathV3":"/api/v3/trigger_instances/{slug}/upsert","summary":"Create or update a trigger","href":"/reference/v3/api-reference/triggers/postTriggerInstancesBySlugUpsert"},{"method":"GET","pathV31":"/api/v3.1/trigger_instances/active","pathV3":"/api/v3/trigger_instances/active","summary":"List active triggers","href":"/reference/v3/api-reference/triggers/getTriggerInstancesActive"},{"method":"DELETE","pathV31":"/api/v3.1/trigger_instances/manage/{triggerId}","pathV3":"/api/v3/trigger_instances/manage/{triggerId}","summary":"Delete a trigger","href":"/reference/v3/api-reference/triggers/deleteTriggerInstancesManageByTriggerId"},{"method":"PATCH","pathV31":"/api/v3.1/trigger_instances/manage/{triggerId}","pathV3":"/api/v3/trigger_instances/manage/{triggerId}","summary":"Enable or disable a trigger","href":"/reference/v3/api-reference/triggers/patchTriggerInstancesManageByTriggerId"},{"method":"GET","pathV31":"/api/v3.1/triggers_types/list/enum","pathV3":"/api/v3/triggers_types/list/enum","summary":"List trigger type enums","href":"/reference/v3/api-reference/triggers/getTriggersTypesListEnum"},{"method":"GET","pathV31":"/api/v3.1/triggers_types/{slug}","pathV3":"/api/v3/triggers_types/{slug}","summary":"Get trigger type by slug","href":"/reference/v3/api-reference/triggers/getTriggersTypesBySlug"},{"method":"GET","pathV31":"/api/v3.1/triggers_types","pathV3":"/api/v3/triggers_types","summary":"List trigger types","href":"/reference/v3/api-reference/triggers/getTriggersTypes"}]} />diff --git a/docs/content/reference/v3/api-reference/webhooks/index.mdx b/docs/content/reference/v3/api-reference/webhooks/index.mdxnew file mode 100644index 000000000..064068d92--- /dev/null+++ b/docs/content/reference/v3/api-reference/webhooks/index.mdx@@ -0,0 +1,12 @@+---+title: Webhooks+description: "Webhook configuration"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++Webhook configuration++## Endpoints++<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/webhook_subscriptions","pathV3":"/api/v3/webhook_subscriptions","summary":"Create webhook subscription","href":"/reference/v3/api-reference/webhooks/postWebhookSubscriptions"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions","pathV3":"/api/v3/webhook_subscriptions","summary":"List webhook subscriptions","href":"/reference/v3/api-reference/webhooks/getWebhookSubscriptions"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Get webhook subscription","href":"/reference/v3/api-reference/webhooks/getWebhookSubscriptionsById"},{"method":"PATCH","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Update webhook subscription","href":"/reference/v3/api-reference/webhooks/patchWebhookSubscriptionsById"},{"method":"DELETE","pathV31":"/api/v3.1/webhook_subscriptions/{id}","pathV3":"/api/v3/webhook_subscriptions/{id}","summary":"Delete webhook subscription","href":"/reference/v3/api-reference/webhooks/deleteWebhookSubscriptionsById"},{"method":"POST","pathV31":"/api/v3.1/webhook_subscriptions/{id}/rotate_secret","pathV3":"/api/v3/webhook_subscriptions/{id}/rotate_secret","summary":"Rotate webhook secret","href":"/reference/v3/api-reference/webhooks/postWebhookSubscriptionsByIdRotateSecret"},{"method":"GET","pathV31":"/api/v3.1/webhook_subscriptions/event_types","pathV3":"/api/v3/webhook_subscriptions/event_types","summary":"List available event types","href":"/reference/v3/api-reference/webhooks/getWebhookSubscriptionsEventTypes"}]} />diff --git a/docs/content/reference/v3/authentication.mdx b/docs/content/reference/v3/authentication.mdxnew file mode 100644index 000000000..9d6e2cc9a--- /dev/null+++ b/docs/content/reference/v3/authentication.mdx@@ -0,0 +1,56 @@+---+title: Authentication+description: How to authenticate with Composio APIs using project and organization API keys+keywords: [API authentication, API key, x-api-key, x-org-api-key, Composio authentication, authorization]+---++All Composio API endpoints require authentication via API key.++## API Key Authentication++Include your API key in the `x-api-key` header.++### Getting Your API Key++1. Sign in to [composio.dev](https://composio.dev)+2. Navigate to **Settings**+3. In **Project Settings**, copy the key from the **API Keys** section++<Video src="/videos/fetch-project-key.mp4" autoPlay />++## Organization API Key++For organization-level access across multiple projects, use the `x-org-api-key` header instead.++### Getting Your Organization API Key++1. Sign in to [composio.dev](https://composio.dev)+2. Navigate to **Organization Settings** → **General Settings**+3. Copy the token under **Organization Access Tokens**++<Video src="/videos/fetch-org-key.mp4" autoPlay />++## Using the API Key++Include your API key in the request header:++```bash+curl https://backend.composio.dev/api/v3/tools \+ -H "x-api-key: $COMPOSIO_API_KEY"+```++For organization-level endpoints:++```bash+curl https://backend.composio.dev/api/v3/org/projects \+ -H "x-org-api-key: $COMPOSIO_ORG_API_KEY"+```++<Cards>+ <Card title="Errors" href="/reference/v3/errors">+ Understanding API error responses+ </Card>+ <Card title="Rate Limits" href="/reference/v3/rate-limits">+ API rate limits by plan+ </Card>+</Cards>diff --git a/docs/content/reference/v3/errors.mdx b/docs/content/reference/v3/errors.mdxnew file mode 100644index 000000000..0f46aaa69--- /dev/null+++ b/docs/content/reference/v3/errors.mdx@@ -0,0 +1,122 @@+---+title: Errors+description: Composio API error codes, HTTP status codes, and troubleshooting guide+keywords: [API errors, error codes, HTTP status codes, error handling, troubleshooting, "400 bad request", "401 unauthorized", "429 rate limit"]+---++Composio uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error with the information provided, and codes in the `5xx` range indicate an error with Composio's servers.++## The error object++```json+{+ "error": {+ "message": "No connected account found for this user and toolkit",+ "status": 400,+ "request_id": "req_abc123def456",+ "suggested_fix": "Connect the user to the toolkit first"+ }+}+```++### Attributes++| Attribute | Description |+|-----------|-------------|+| `message` | A human-readable message providing details about the error. |+| `status` | The HTTP status code. |+| `request_id` | A unique identifier for this request. Include this when contacting support. |+| `suggested_fix` | When available, guidance on how to resolve the error. |++## HTTP status codes++| Code | Status | Description |+|------|--------|-------------|+| 200 | OK | Everything worked as expected. |+| 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. |+| 401 | Unauthorized | No valid API key provided. |+| 403 | Forbidden | The API key doesn't have permissions to perform the request. |+| 404 | Not Found | The requested resource doesn't exist. |+| 409 | Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |+| 422 | Unprocessable Entity | The request was valid but cannot be processed. |+| 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |+| 500, 502, 503, 504 | Server Errors | Something went wrong on Composio's end. |++## Error types++### Authentication errors++Composio uses two types of API keys:+- **Project API key** (`x-api-key`) — For project-level operations+- **Organization API key** (`x-org-api-key`) — For organization-level access across projects++| Error | Cause |+|-------|-------|+| Invalid API key | The API key is incorrect or revoked. Verify in [Settings](https://platform.composio.dev/settings). |+| No authentication provided | The request is missing the `x-api-key` or `x-org-api-key` header. |+| Invalid organization key | The organization API key is incorrect or revoked. Verify in Organization Settings. |+| Insufficient permissions | The API key doesn't have access to this resource. |++<Callout>+See [Authentication Troubleshooting](/docs/troubleshooting/authentication) for more help.+</Callout>++### Tool errors++Errors that occur when fetching or executing tools.++| Error | Cause |+|-------|-------|+| Tool not found | The tool slug doesn't exist. Tool slugs are case-sensitive and use `SCREAMING_SNAKE_CASE`. |+| No connected account | The user hasn't connected to this toolkit yet. |+| Tool execution failed | The external service returned an error. Check tool parameters and user permissions. |++<Callout>+See [Tools Troubleshooting](/docs/troubleshooting/tools) for more help.+</Callout>++### Connection errors++Errors related to connected accounts.++| Error | Cause |+|-------|-------|+| Connected account not found | The `connectedAccountId` doesn't exist or was deleted. |+| Auth refresh required | The OAuth token has expired. Prompt the user to re-authenticate. |+| Connected account deleted | The connection was removed. Create a new connection. |++### Trigger errors++Errors related to trigger subscriptions.++| Error | Cause |+|-------|-------|+| Trigger not found | The trigger slug doesn't exist for this toolkit. |+| Trigger instance deleted | The trigger subscription or its connected account was removed. |++<Callout>+See [Triggers Troubleshooting](/docs/troubleshooting/triggers) for more help.+</Callout>++## Rate limiting++When you hit rate limits, you'll receive a `429` status code. See [Rate Limits](/reference/v3/rate-limits) for details on limits by plan and best practices for handling rate limit errors.++## Getting help++When contacting support, include the `request_id` from the error response.++<Cards>+ <Card title="Troubleshooting" href="/docs/troubleshooting">+ Common issues and solutions+ </Card>+ <Card title="Discord" href="https://discord.com/channels/1170785031560646836/1268871288156323901">+ Community support+ </Card>+ <Card title="Email" href="mailto:[email protected]">+ Contact support team+ </Card>+ <Card title="GitHub" href="https://github.com/ComposioHQ/composio/issues/new?labels=bug">+ Report a bug+ </Card>+</Cards>diff --git a/docs/content/reference/v3/index.mdx b/docs/content/reference/v3/index.mdxnew file mode 100644index 000000000..9ef274065--- /dev/null+++ b/docs/content/reference/v3/index.mdx@@ -0,0 +1,24 @@+---+title: Overview+description: Composio REST API and SDK reference for AI agent tool execution, authentication, and integrations+keywords: [Composio API, REST API, SDK reference, AI agent tools, tool execution, API documentation]+---++Composio powers tool discovery, execution, authentication, and context management for your AI agents with 1000+ toolkits. This reference covers our REST APIs and SDKs.++## Quick Reference++- **Base URL**: <ApiBaseUrl />+- **[Authentication](/reference/v3/authentication)**: `x-api-key` (project) or `x-org-api-key` (organization) header+- **[Rate Limits](/reference/v3/rate-limits)**: 20K-100K requests per 10 minutes (plan-dependent)++## REST API++| API | Description |+|-----|-------------|+| [Tool Router](/reference/v3/api-reference/tool-router) | Session-based API for AI agents to discover and execute tools |+| [Tools](/reference/v3/api-reference/tools) | List, search, and execute individual actions |+| [Connected Accounts](/reference/v3/api-reference/connected-accounts) | Manage user OAuth connections to apps |+| [Auth Configs](/reference/v3/api-reference/auth-configs) | Configure how users authenticate to toolkits |+| [Triggers](/reference/v3/api-reference/triggers) | Subscribe to webhooks from connected apps |+| [Toolkits](/reference/v3/api-reference/toolkits) | Browse available apps and their tools |diff --git a/docs/content/reference/v3/meta.json b/docs/content/reference/v3/meta.jsonnew file mode 100644index 000000000..8f8d1d558--- /dev/null+++ b/docs/content/reference/v3/meta.json@@ -0,0 +1,10 @@+{+ "title": "V3",+ "pages": [+ "index",+ "authentication",+ "rate-limits",+ "errors",+ "api-reference"+ ]+}diff --git a/docs/content/reference/v3/rate-limits.mdx b/docs/content/reference/v3/rate-limits.mdxnew file mode 100644index 000000000..65d06418a--- /dev/null+++ b/docs/content/reference/v3/rate-limits.mdx@@ -0,0 +1,62 @@+---+title: Rate Limits+description: Composio API rate limits by plan, rate limit headers, and best practices+keywords: [API rate limits, rate limiting, throttling, 429 too many requests, API quotas, request limits]+---++Rate limits are enforced **per organization** and reset on a rolling 10-minute window.++## Rate limits by plan++| Plan | Rate Limit | Window |+|------|------------|--------|+| Starter | 20,000 requests | 10 minutes |+| Hobby | 20,000 requests | 10 minutes |+| Growth | 100,000 requests | 10 minutes |+| Enterprise | Unlimited | - |++<Callout>+All authenticated API endpoints share your organization's rate limit. This includes tool execution, connected accounts, triggers, and all other API operations.+</Callout>++## Rate limit headers++API responses include headers to help you track your usage:++| Header | Description |+|--------|-------------|+| `X-RateLimit` | Total requests allowed in the current window |+| `X-RateLimit-Remaining` | Requests remaining in the current window |+| `X-RateLimit-Window-Size` | Window size (e.g., `600s` for 600 seconds) |+| `Retry-After` | Seconds until the window resets (only on 429 responses) |++## Rate limit response++When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:++```json+{+ "message": "Rate limit exceeded. Limit: 100000 requests per 10 minutes"+}+```++## Best practices++1. **Monitor your usage** - Check the `X-RateLimit-Remaining` header to track how close you are to the limit.++2. **Implement backoff** - When you receive a `429`, wait for the duration specified in `Retry-After` before retrying.++3. **Cache responses** - Cache tool definitions and other static data to reduce unnecessary API calls.++## Need higher limits?++If you're hitting rate limits regularly, consider upgrading your plan or [talk to us](https://calendly.com/composiohq/enterprise) to discuss custom limits for your use case.++<Cards>+ <Card title="Errors" href="/reference/v3/errors">+ Understanding API error responses+ </Card>+ <Card title="Pricing" href="https://composio.dev/pricing">+ Compare plans and limits+ </Card>+</Cards>diff --git a/docs/content/toolkits/managed-auth.mdx b/docs/content/toolkits/managed-auth.mdxindex ba6d77b7c..bcbc50891 100644--- a/docs/content/toolkits/managed-auth.mdx+++ b/docs/content/toolkits/managed-auth.mdx@@ -8,7 +8,7 @@ Toolkits with managed auth work out of the box with no OAuth setup. For toolkitsYou can also check programmatically whether a toolkit has managed auth:```bash-curl 'https://backend.composio.dev/api/v3/toolkits/posthog' \+curl 'https://backend.composio.dev/api/v3.1/toolkits/posthog' \-H 'x-api-key: YOUR_API_KEY'```diff --git a/docs/lib/api-version.ts b/docs/lib/api-version.tsnew file mode 100644index 000000000..3906fe002--- /dev/null+++ b/docs/lib/api-version.ts@@ -0,0 +1,16 @@+/**+ * Shared API version detection logic.+ * Centralizes the URL-based version detection used across components and proxy.+ */++export type ApiVersion = '3.1' | '3.0';++/**+ * Detects the API version from a pathname.+ * /reference/v3/ or /reference/v3 → '3.0', everything else → '3.1'+ */+export function detectApiVersion(pathname: string): ApiVersion {+ return pathname.startsWith('/reference/v3/') || pathname === '/reference/v3'+ ? '3.0'+ : '3.1';+}diff --git a/docs/lib/filter-api-version.ts b/docs/lib/filter-api-version.tsnew file mode 100644index 000000000..418b7c69e--- /dev/null+++ b/docs/lib/filter-api-version.ts@@ -0,0 +1,82 @@+/**+ * Filters the combined page tree to show only the selected API version.+ * v3.1 pages are at /reference/{page} and /reference/api-reference/{tag}/{op}+ * v3.0 pages are at /reference/v3/{page} and /reference/v3/api-reference/{tag}/{op}+ *+ * For v3.1: hide the V3 folder entirely.+ * For v3.0: lift V3 folder contents to the top, hide v3.1-only nodes.+ */++interface PageTreeNode {+ type: 'page' | 'folder' | 'separator';+ name?: unknown;+ url?: string;+ children?: PageTreeNode[];+ index?: PageTreeNode;+ [key: string]: unknown;+}++interface PageTreeRoot {+ children: PageTreeNode[];+ [key: string]: unknown;+}++function isV3Node(node: PageTreeNode): boolean {+ if (node.type === 'page' && typeof node.url === 'string') {+ return node.url.startsWith('/reference/v3/') || node.url === '/reference/v3';+ }+ if (node.type === 'folder') {+ if (node.index && isV3Node(node.index)) return true;+ return node.children?.some(isV3Node) ?? false;+ }+ return false;+}++/** Checks if a folder contains v3.1 API reference pages (URLs under /reference/api-reference/). */+function isV31ApiFolder(node: PageTreeNode): boolean {+ if (node.type !== 'folder') return false;+ const hasV31ApiPage = (n: PageTreeNode): boolean => {+ if (n.type === 'page' && typeof n.url === 'string') {+ return n.url.startsWith('/reference/api-reference/');+ }+ if (n.type === 'folder') {+ if (n.index && hasV31ApiPage(n.index)) return true;+ return n.children?.some(hasV31ApiPage) ?? false;+ }+ return false;+ };+ if (node.index && hasV31ApiPage(node.index)) return true;+ return node.children?.some(hasV31ApiPage) ?? false;+}++export function prepareTree<T extends PageTreeRoot>(tree: T, version: string): T {+ const children = tree.children as PageTreeNode[];++ if (version === '3.1') {+ // Just hide the V3 folder+ return {+ ...tree,+ children: children.filter((node) => !isV3Node(node)),+ };+ }++ // v3.0: lift V3 folder contents, keep version-independent folders (SDK Reference, Meta Tools)+ const v3Folder = children.find(+ (node) => node.type === 'folder' && isV3Node(node),+ );++ // Nodes that should appear in both versions (exclude v3 nodes, v3.1 API Reference folder,+ // and top-level pages which are version-specific — both versions have their own copies)+ const sharedNodes = children.filter(+ (node) => node.type !== 'page' && !isV3Node(node) && !isV31ApiFolder(node),+ );++ if (v3Folder?.children) {+ // Include the folder's index page (v3/index.mdx → overview) which fumadocs+ // stores in .index rather than .children+ const indexPage = v3Folder.index ? [v3Folder.index] : [];+ return { ...tree, children: [...indexPage, ...v3Folder.children, ...sharedNodes] };+ }++ return { ...tree, children: [...children.filter(isV3Node), ...sharedNodes] };+}diff --git a/docs/lib/layout.shared.tsx b/docs/lib/layout.shared.tsxindex 3d1acd3df..19a549050 100644--- a/docs/lib/layout.shared.tsx+++ b/docs/lib/layout.shared.tsx@@ -2,6 +2,7 @@ import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';import Image from 'next/image';import { Play } from 'lucide-react';import { SearchAndAskAI, SearchAndAskAIMobile } from '@/components/ask-ai-button';+import { NavVersionSelector } from '@/components/version-selector';// Composio Logo Component with light/dark mode switchingfunction ComposioLogo() {@@ -53,7 +54,7 @@ export function baseOptions(): BaseLayoutProps {active: 'nested-url',},{- text: 'Reference',+ text: <span className="inline-flex items-center gap-1">Reference <NavVersionSelector /></span>,url: '/reference',active: 'nested-url',},diff --git a/docs/lib/openapi.ts b/docs/lib/openapi.tsindex 880a4d1f7..d9d723342 100644--- a/docs/lib/openapi.ts+++ b/docs/lib/openapi.ts@@ -1,10 +1,14 @@import { join } from 'path';import { createOpenAPI } from 'fumadocs-openapi/server';-// Use local filtered spec (generated by scripts/fetch-openapi.ts)-// Run `bun run scripts/fetch-openapi.ts` to update the spec-// Use absolute path to ensure resolution in Vercel serverless functions+// v3.1 (latest) — clean operationIds, default API referenceexport const openapi = createOpenAPI({input: [join(process.cwd(), 'public/openapi.json')],proxyUrl: '/api/proxy',});++// v3.0 — mounted under api-reference/v3/+export const openapiV3 = createOpenAPI({+ input: [join(process.cwd(), 'public/openapi-v3.json')],+ proxyUrl: '/api/proxy',+});diff --git a/docs/lib/source.ts b/docs/lib/source.tsindex fd565dc5e..26ac2d3a3 100644--- a/docs/lib/source.ts+++ b/docs/lib/source.ts@@ -1,33 +1,30 @@import { docs, reference, cookbooks, toolkits, changelog } from 'fumadocs-mdx:collections/server';import { type InferPageType, loader, multiple } from 'fumadocs-core/source';import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';-import { openapi } from './openapi';+import { openapi, openapiV3 } from './openapi';import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';import { getGuardrails } from './llm-guardrails';/*** Transformer to set defaultOpen: true for specific folders in the reference sidebar.- * This is needed because openapiSource doesn't support meta.json files.*/const defaultOpenTransformer = {folder(node: { name: string; defaultOpen?: boolean }, folderPath: string) {- // Set defaultOpen for API Reference and SDK Reference folders- if (folderPath === 'api-reference' || folderPath === 'sdk-reference' || folderPath === 'meta-tools') {+ if (folderPath === 'api-reference' || folderPath === 'sdk-reference' || folderPath === 'meta-tools' || folderPath === 'v3/api-reference') {return { ...node, defaultOpen: true };}return node;},};-// See https://fumadocs.dev/docs/headless/source-api for more infoexport const source = loader({baseUrl: '/docs',source: docs.toFumadocsSource(),plugins: [lucideIconsPlugin()],});-// Combined reference source with MDX pages and OpenAPI-generated pages-// Lazy initialization to avoid top-level await issues in serverless+// One combined reference source with both v3.1 and v3.0 OpenAPI pages.+// v3.1 at api-reference/, v3.0 at api-reference/v3/// eslint-disable-next-line @typescript-eslint/no-explicit-anylet _referenceSource: any = null;// eslint-disable-next-line @typescript-eslint/no-explicit-any@@ -35,22 +32,23 @@ let _openapiPagesPromise: Promise<any> | null = null;async function getOpenapiPages() {if (!_openapiPagesPromise) {- _openapiPagesPromise = openapiSource(openapi, {- groupBy: 'tag',- baseDir: 'api-reference',- });+ _openapiPagesPromise = Promise.all([+ openapiSource(openapi, { groupBy: 'tag', baseDir: 'api-reference' }),+ openapiSource(openapiV3, { groupBy: 'tag', baseDir: 'v3/api-reference' }),+ ]);}return _openapiPagesPromise;}export async function getReferenceSource() {if (!_referenceSource) {- const openapiPages = await getOpenapiPages();+ const [openapiLatest, openapiV3Pages] = await getOpenapiPages();_referenceSource = loader({baseUrl: '/reference',source: multiple({mdx: reference.toFumadocsSource(),- openapi: openapiPages,+ openapi: openapiLatest,+ 'openapi-v3': openapiV3Pages,}),plugins: [lucideIconsPlugin(), openapiPlugin()],pageTree: {@@ -83,9 +81,6 @@ export const toolkitsSource = loader({export const changelogEntries = changelog;-/**- * Generate OG image URL for any page section- */export function getOgImageUrl(_section: string, _slugs: string[], title?: string, _description?: string): string {const encodedTitle = encodeURIComponent(title ?? 'Composio Docs');return `https://og.composio.dev/api/og?title=${encodedTitle}`;@@ -118,67 +113,49 @@ export function mdxToCleanMarkdown(content: string): string {);// Remove Cards wrapper before processing individual Card tags- // (prevents <Cards> from being matched by <Card regex since <Cards starts with <Card)result = result.replace(/<\/?Cards\b[^>]*>/g, '');// Convert Card - handle multiline and various attribute orders- // Self-closing Cards with description attributeresult = result.replace(/<Card\b[\s\S]*?title="([^"]*)"[\s\S]*?href="([^"]*)"[\s\S]*?description="([^"]*)"[\s\S]*?\/>/g,'- [$1]($2): $3');- // Cards with children content (non-self-closing)result = result.replace(/<Card\b[\s\S]*?title="([^"]*)"[\s\S]*?href="([^"]*)"[\s\S]*?>([\s\S]*?)<\/Card>/g,'- [$1]($2): $3');- // Cards with href before titleresult = result.replace(/<Card\b[\s\S]*?href="([^"]*)"[\s\S]*?title="([^"]*)"[\s\S]*?>([\s\S]*?)<\/Card>/g,'- [$2]($1): $3');- // Convert ProviderCard to markdown linkresult = result.replace(/<ProviderCard[\s\S]*?name="([^"]*)"[\s\S]*?href="([^"]*)"[\s\S]*?languages=\{\[([^\]]*)\]\}[\s\S]*?\/>/g,(_, name, href, langs) => `- [${name}](${href}) (${langs.replace(/"/g, '')})`);- // Strip orphaned indentation from converted list items- // (Cards/ProviderCards nested inside wrapper components had JSX indentation that persists after wrapper removal)result = result.replace(/^[ \t]+(- \[)/gm, '$1');- // Convert Tabs/Tab content - keep inner contentresult = result.replace(/<TabsList>[\s\S]*?<\/TabsList>/g, '');result = result.replace(/<TabsTrigger[^>]*>[^<]*<\/TabsTrigger>/g, '');result = result.replace(/<TabsContent[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/TabsContent>/g, '\n**$1:**\n$2');result = result.replace(/<Tab[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/Tab>/g, '\n**$1:**\n$2');- // Convert Steps/Step with StepTitle- // Handle StepTitle with potential whitespace and multiline contentresult = result.replace(/<StepTitle>([\s\S]*?)<\/StepTitle>/g, (_, title) => {- // Clean up the title - remove extra whitespace and any # prefix fumadocs might addconst cleanTitle = title.replace(/^[\s#]*#\s*/, '').replace(/\s+$/, '').trim();return cleanTitle ? `#### ${cleanTitle}` : '';});- // Handle <Step> with ### header pattern (legacy)result = result.replace(/<Step>\s*###\s*(.+)/g, '#### $1');- // Remove Steps wrapper and Step tagsresult = result.replace(/<\/?Steps>/g, '');result = result.replace(/<\/?Step>/g, '');- // Clean up step titles that fumadocs converted to "# title" format- // These appear as "#### # Title" after our processing, fix to "#### Title"result = result.replace(/^(\s*#{1,6})\s*#\s+(.+)$/gm, '$1 $2');- // Clean up any standalone # that fumadocs might leaveresult = result.replace(/^\s*#\s*$/gm, '');- // Convert FrameworkOption to header with framework nameresult = result.replace(/<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g,'\n## $1\n');result = result.replace(/<\/FrameworkOption>/g, '');- // Convert IntegrationTabs — extract label from tabs prop if presentconst tabLabelMap: Record<string, string> = { native: 'Native Tools', mcp: 'MCP' };result = result.replace(/<IntegrationTabs[\s\S]*?tabs=\{\[([\s\S]*?)\]\}[\s\S]*?>/g,@@ -191,64 +168,53 @@ export function mdxToCleanMarkdown(content: string): string {return '\n> Choose your integration type · [Use this guide to decide](/docs/native-tools-vs-mcp)\n';});- // Also handle IntegrationTabs without explicit tabs propresult = result.replace(/<IntegrationTabs(?![^>]*tabs=)[\s\S]*?>/g,'\n> Choose your integration type · [Use this guide to decide](/docs/native-tools-vs-mcp)\n');- // Convert IntegrationContent to labeled sectionresult = result.replace(/<IntegrationContent[\s\S]*?value="([^"]*)"[\s\S]*?>/g,(_, value: string) => `\n### ${tabLabelMap[value] || value}\n`);result = result.replace(/<\/IntegrationContent>/g, '');- // Convert Accordion to collapsible-style textresult = result.replace(/<Accordion[\s\S]*?title="([^"]*)"[\s\S]*?>([\s\S]*?)<\/Accordion>/g,'\n**$1**\n$2');- // Convert Figure to markdown image with captionresult = result.replace(/<Figure[\s\S]*?src="([^"]*)"[\s\S]*?alt="([^"]*)"[\s\S]*?caption="([^"]*)"[\s\S]*?\/>/g,'\n*$3*');- // Figure without captionresult = result.replace(/<Figure[\s\S]*?src="([^"]*)"[\s\S]*?alt="([^"]*)"[\s\S]*?\/>/g,'');- // Convert ToolTypeOption to labeled section (similar to IntegrationContent)result = result.replace(/<ToolTypeOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g,'\n### $1\n');result = result.replace(/<\/ToolTypeOption>/g, '');- // Convert TemplateCard to markdown link with descriptionresult = result.replace(/<TemplateCard[\s\S]*?title="([^"]*)"[\s\S]*?description="([^"]*)"[\s\S]*?href="([^"]*)"[\s\S]*?\/>/g,'- [$1]($3): $2');- // TemplateCard with href before titleresult = result.replace(/<TemplateCard[\s\S]*?href="([^"]*)"[\s\S]*?title="([^"]*)"[\s\S]*?description="([^"]*)"[\s\S]*?\/>/g,'- [$2]($1): $3');- // Convert GlossaryTerm to heading + definitionresult = result.replace(/<GlossaryTerm[\s\S]*?name="([^"]*)"[\s\S]*?>([\s\S]*?)<\/GlossaryTerm>/g,(_, name, content) => `### ${name}\n\n${content.trim()}`);- // Strip PromptBanner and its children (UI-only copy-prompt widget)result = result.replace(/<PromptBanner[\s\S]*?<\/PromptBanner>/g, '');- // Convert AIToolsBanner to plain textresult = result.replace(/<AIToolsBanner\s*\/>/g,'### For AI tools\n\n' +@@ -263,29 +229,16 @@ export function mdxToCleanMarkdown(content: string): string {'- [llms-full.txt](/llms-full.txt) — Complete documentation in one file');- // Convert ConnectClientOption opening tags to headings for LLM outputresult = result.replace(/<ConnectClientOption[^>]*\bname="([^"]*)"[^>]*>/g,(_, name) => `## ${name}\n`);- // 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 conflictsresult = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary|ConnectFlow|ConnectClientOption)[^>]*>/g, '');- // Remove remaining self-closing JSX tags (including those with JSX expressions)result = result.replace(/<[A-Z][a-zA-Z]*[\s\S]*?\/>/g, '');-- // Remove remaining JSX opening/closing tags but keep contentresult = result.replace(/<\/?[A-Z][a-zA-Z]*[^>]*>/g, '');- // Note: lone brace cleanup is done inside the code-block-aware loop below- // to avoid stripping { and } from JSON code blocks.-- // Normalize indentation while preserving markdown structure- // - Code blocks: normalize by stripping common indentation prefix- // - Nested lists/blockquotes: preserve relative indentation- // - Other content: remove excessive leading whitespace from JSX nestingconst lines = result.split('\n');const normalizedLines: string[] = [];let inCodeBlock = false;@@ -293,12 +246,10 @@ export function mdxToCleanMarkdown(content: string): string {const flushCodeBlock = () => {if (codeBlockLines.length > 0) {- // Find minimum indentation (ignoring empty lines)const nonEmptyLines = codeBlockLines.filter(l => l.trim().length > 0);const minIndent = nonEmptyLines.length > 0? Math.min(...nonEmptyLines.map(l => l.match(/^(\s*)/)?.[1]?.length || 0)): 0;- // Strip common indentationfor (const codeLine of codeBlockLines) {normalizedLines.push(codeLine.slice(minIndent));}@@ -309,71 +260,51 @@ export function mdxToCleanMarkdown(content: string): string {for (const line of lines) {if (line.trim().startsWith('```')) {if (inCodeBlock) {- // End of code block - normalize and flushflushCodeBlock();inCodeBlock = false;normalizedLines.push(line.trim());} else {- // Start of code blockinCodeBlock = true;normalizedLines.push(line.trim());}} else if (inCodeBlock) {codeBlockLines.push(line);} else {- // Outside code blocks - smart whitespace handlingconst trimmedLine = line.trimStart();- // Clean up leftover JSX artifacts like lone } or { (only outside code blocks)if (/^\s*[{}]\s*$/.test(line)) {continue;}- // Preserve indentation for markdown list items (but not blockquotes at root level)if (trimmedLine.match(/^[-*+]\s/) || trimmedLine.match(/^\d+\.\s/)) {- // For list items, normalize to 2-space indentation levelsconst leadingSpaces = line.length - trimmedLine.length;const indentLevel = Math.floor(leadingSpaces / 2);- const normalizedIndent = ' '.repeat(Math.min(indentLevel, 4)); // Cap at 4 levels+ const normalizedIndent = ' '.repeat(Math.min(indentLevel, 4));normalizedLines.push(normalizedIndent + trimmedLine);} else {- // For other content (including blockquotes), remove excessive leading whitespacenormalizedLines.push(trimmedLine);}}}- // Handle unclosed code block - flush any remaining contentif (inCodeBlock) {flushCodeBlock();}result = normalizedLines.join('\n');-- // Clean up excessive newlinesresult = result.replace(/\n{3,}/g, '\n\n');-- // Strip twoslash annotations ONLY inside code blocks (used for type-checking, not useful for AI)- // These include: // ---cut---, // @errors, // ^?, // @noErrors, etc.result = stripTwoslashFromCodeBlocks(result);return result.trim();}-/**- * Strip twoslash annotations only from inside code blocks.- * This ensures we don't accidentally modify prose content.- */function stripTwoslashFromCodeBlocks(content: string): string {- // Match code blocks: ```lang ... ```return content.replace(/(```[\w]*\n)([\s\S]*?)(```)/g, (match, open, code, close) => {let cleanCode = code;- // Remove twoslash directivescleanCode = cleanCode.replace(/^\/\/\s*---cut---.*\n?/gm, '');cleanCode = cleanCode.replace(/^\/\/\s*@errors?:.*\n?/gm, '');cleanCode = cleanCode.replace(/^\/\/\s*@noErrors.*\n?/gm, '');cleanCode = cleanCode.replace(/^\/\/\s*@filename:.*\n?/gm, '');cleanCode = cleanCode.replace(/^\/\/\s*@highlight.*\n?/gm, '');- cleanCode = cleanCode.replace(/^\/\/\s*\^[\?\!].*\n?/gm, ''); // ^? and ^! hover annotations- // Clean up resulting empty lines at start of code block+ cleanCode = cleanCode.replace(/^\/\/\s*\^[\?\!].*\n?/gm, '');cleanCode = cleanCode.replace(/^\n+/, '');return open + cleanCode + close;});@@ -382,15 +313,12 @@ function stripTwoslashFromCodeBlocks(content: string): string {export async function getLLMText(page: InferPageType<typeof source>, options?: { includeFooter?: boolean; includeGuardrails?: boolean }) {const includeFooter = options?.includeFooter ?? true;const includeGuardrails = options?.includeGuardrails ?? true;- // Fall back to description if getText is not availableif (typeof page.data.getText !== 'function') {return `# ${page.data.title} (${page.url})${page.data.description || ''}`;}- // Try 'processed' mode first (works in serverless), then 'raw' (works locally)- // Both can fail in different environments, so handle gracefullylet content: string | null = null;try {@@ -410,9 +338,6 @@ ${page.data.description || ''}`;${page.data.description || ''}`;}- // Split content at Mermaid tags, process each segment separately, then rejoin- // with mermaid code blocks. This prevents JSX regexes with [\s\S]*? from- // matching across mermaid boundaries and consuming diagram content.const mermaidRegex = /<Mermaid\s+chart="([\s\S]*?)"\s*\/>/g;const segments: string[] = [];const mermaidCharts: string[] = [];@@ -429,7 +354,6 @@ ${page.data.description || ''}`;const cleanSegments = segments.map(s => mdxToCleanMarkdown(s));let cleanContent = cleanSegments[0];for (let i = 0; i < mermaidCharts.length; i++) {- // Decode HTML entities that fumadocs encodes in JSX attributesconst chart = mermaidCharts[i].replace(/"/g, '"').replace(/'/g, "'").replace(/&/g, '&');cleanContent += `\n\n\`\`\`mermaid\n${chart}\n\`\`\`\n\n${cleanSegments[i + 1]}`;}@@ -446,7 +370,6 @@ ${cleanContent}${footer}${guardrails}`;}export function formatDate(dateStr: string): string {- // Add T12:00 to avoid UTC midnight timezone shiftreturn new Date(`${dateStr}T12:00:00`).toLocaleDateString('en-US', {year: 'numeric',month: 'short',@@ -465,21 +388,18 @@ function validateDateFormat(dateStr: string): void {}export function dateToChangelogUrl(dateStr: string): string {- // Convert "2025-12-29" to "/docs/changelog/2025/12/29"validateDateFormat(dateStr);const [year, month, day] = dateStr.split('-');return `/docs/changelog/${year}/${month}/${day}`;}export function dateToSlug(dateStr: string): string[] {- // Convert "2025-12-29" to ["2025", "12", "29"]validateDateFormat(dateStr);const [year, month, day] = dateStr.split('-');return [year, month, day];}export function slugToDate(slug: string[]): string | null {- // Convert ["2025", "12", "29"] to "2025-12-29"if (slug.length !== 3) return null;const [year, month, day] = slug;return `${year}-${month}-${day}`;diff --git a/docs/lib/use-api-version.ts b/docs/lib/use-api-version.tsnew file mode 100644index 000000000..7063c2d8f--- /dev/null+++ b/docs/lib/use-api-version.ts@@ -0,0 +1,12 @@+'use client';++import { usePathname } from 'next/navigation';+import { detectApiVersion, type ApiVersion } from './api-version';++/**+ * Client hook that returns the current API version based on the URL path.+ */+export function useApiVersion(): ApiVersion {+ const pathname = usePathname();+ return detectApiVersion(pathname);+}diff --git a/docs/mdx-components.tsx b/docs/mdx-components.tsxindex 502da19ac..db0978fd3 100644--- a/docs/mdx-components.tsx+++ b/docs/mdx-components.tsx@@ -24,6 +24,8 @@ import { ManagedAuthList } from '@/components/toolkits/managed-auth-list';import { Mermaid } from '@/components/mermaid';import { AIToolsBanner } from '@/components/ai-tools-banner';import { Glossary, GlossaryTerm } from '@/components/glossary';+import { ApiBaseUrl } from '@/components/api-base-url';+import { ApiEndpointsTable } from '@/components/api-endpoints-table';import {ShieldCheck,Route as RouteIcon,@@ -99,6 +101,8 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {StepTitle,Glossary,GlossaryTerm,+ ApiBaseUrl,+ ApiEndpointsTable,// Lucide iconsShieldCheck,RouteIcon,diff --git a/docs/proxy.ts b/docs/proxy.tsindex a114b7ab7..94b324e6c 100644--- a/docs/proxy.ts+++ b/docs/proxy.ts@@ -11,6 +11,7 @@ function kebabToCamel(str: string): string {* Proxy handles:* 1. Markdown content negotiation for AI agents (Accept: text/markdown)* 2. Redirects for old Fern API reference URLs (kebab-case → camelCase)+ * 3. Sets x-pathname header for 404 logging*/export function proxy(request: NextRequest) {const { pathname } = request.nextUrl;@@ -23,18 +24,24 @@ export function proxy(request: NextRequest) {}// Handle old Fern API reference URLs (kebab-case → camelCase)- // Example: /reference/api-reference/tools/get-tools → /reference/api-reference/tools/getTools- if (pathname.startsWith('/reference/api-reference/')) {- const segments = pathname.split('/');-- // Convert kebab-case segments to camelCase (only operation IDs after index 3)- // Structure: /reference/api-reference/{tag}/{operationId}+ // v3.1: /reference/api-reference/{tag}/{operationId}+ // v3.0: /reference/v3/api-reference/{tag}/{operationId}+ const apiRefPrefix = pathname.startsWith('/reference/v3/api-reference/')+ ? '/reference/v3/api-reference/'+ : pathname.startsWith('/reference/api-reference/')+ ? '/reference/api-reference/'+ : null;++ if (apiRefPrefix) {+ const rest = pathname.slice(apiRefPrefix.length);+ const segments = rest.split('/');+ // segments[0] = tag, segments[1+] = operationId parts — only camelCase the operationIdconst newSegments = segments.map((segment, index) => {- if (index <= 3) return segment; // Keep /reference/api-reference/{tag} as-is+ if (index === 0) return segment; // keep tag as-isreturn kebabToCamel(segment);});- const newPathname = newSegments.join('/');+ const newPathname = apiRefPrefix + newSegments.join('/');if (newPathname !== pathname) {const url = request.nextUrl.clone();url.pathname = newPathname;diff --git a/docs/public/openapi-v3.json b/docs/public/openapi-v3.jsonnew file mode 100644index 000000000..b27df66d2--- /dev/null+++ b/docs/public/openapi-v3.json@@ -0,0 +1,19271 @@+{+ "openapi": "3.0.0",+ "info": {+ "version": "3.0.0",+ "title": "Composio Platform API",+ "description": "",+ "contact": {+ "name": "Composio Support",+ "url": "https://composio.dev/support",+ "email": "[email protected]"+ },+ "license": {+ "name": "Proprietary",+ "url": "https://composio.dev/terms"+ }+ },+ "servers": [+ {+ "url": "https://backend.composio.dev",+ "description": "PRODUCTION API"+ }+ ],+ "tags": [+ {+ "name": "Authentication",+ "description": "Authentication related endpoints"+ },+ {+ "name": "Auth Configs",+ "description": "Authentication configuration management"+ },+ {+ "name": "Connected Accounts",+ "description": "Connected account management"+ },+ {+ "name": "Logs",+ "description": "Logging and monitoring"+ },+ {+ "name": "OpenAPI",+ "description": "OpenAPI specification management"+ },+ {+ "name": "Organization",+ "description": "Organization management"+ },+ {+ "name": "API Keys",+ "description": "API key management"+ },+ {+ "name": "Webhooks",+ "description": "Webhook configuration"+ },+ {+ "name": "Team",+ "description": "Team member management"+ },+ {+ "name": "Toolkits",+ "description": "Toolkit and tool management"+ },+ {+ "name": "Tools",+ "description": "Tool execution endpoints"+ },+ {+ "name": "Recipes",+ "description": "Recipe management and execution. Recipes are reusable code modules that combine multiple tools."+ },+ {+ "name": "Triggers",+ "description": "Trigger management and execution"+ },+ {+ "name": "Payments",+ "description": "Payment and subscription management"+ },+ {+ "name": "Files",+ "description": "File management"+ },+ {+ "name": "MCP",+ "description": "MCP server management"+ },+ {+ "name": "Migration",+ "description": "Endpoints to help with migration from v1 to v3"+ },+ {+ "name": "MCP Partner",+ "description": "MCP partner management"+ },+ {+ "name": "Recipe",+ "description": "Recipe endpoints"+ },+ {+ "name": "Tool Router",+ "description": "(Labs) Tool router endpoints"+ }+ ],+ "components": {+ "securitySchemes": {+ "ApiKeyAuth": {+ "type": "apiKey",+ "in": "header",+ "name": "x-api-key",+ "description": "Project API key authentication"+ },+ "UserApiKeyAuth": {+ "type": "apiKey",+ "in": "header",+ "name": "x-user-api-key",+ "description": "User API key authentication"+ },+ "OrgApiKeyAuth": {+ "type": "apiKey",+ "in": "header",+ "name": "x-org-api-key",+ "description": "Organization API key authentication"+ }+ },+ "schemas": {+ "Error": {+ "type": "object",+ "properties": {+ "error": {+ "type": "object",+ "properties": {+ "message": {+ "type": "string"+ },+ "code": {+ "type": "number"+ },+ "slug": {+ "type": "string"+ },+ "status": {+ "type": "number"+ },+ "request_id": {+ "type": "string"+ },+ "suggested_fix": {+ "type": "string"+ },+ "errors": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "message",+ "code",+ "slug",+ "status"+ ]+ }+ },+ "required": [+ "error"+ ]+ },+ "PatchConnectedAccountBody": {+ "type": "object",+ "properties": {+ "alias": {+ "type": "string",+ "description": "A human-readable alias for this connected account. Pass an empty string to clear the alias. Must be unique per entity and toolkit within the project."+ },+ "connection": {+ "type": "object",+ "properties": {+ "state": {+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "BEARER_TOKEN",+ "API_KEY",+ "BASIC",+ "BASIC_WITH_JWT",+ "GOOGLE_SERVICE_ACCOUNT",+ "SERVICE_ACCOUNT"+ ],+ "description": "The auth scheme of the connected account. Must match the connection's actual auth scheme."+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string",+ "nullable": true+ },+ "your-domain": {+ "type": "string",+ "nullable": true+ },+ "region": {+ "type": "string",+ "nullable": true+ },+ "shop": {+ "type": "string",+ "nullable": true+ },+ "account_url": {+ "type": "string",+ "nullable": true+ },+ "COMPANYDOMAIN": {+ "type": "string",+ "nullable": true+ },+ "extension": {+ "type": "string",+ "nullable": true+ },+ "form_api_base_url": {+ "type": "string",+ "nullable": true+ },+ "instanceEndpoint": {+ "type": "string",+ "nullable": true+ },+ "api_url": {+ "type": "string",+ "nullable": true+ },+ "borneo_dashboard_url": {+ "type": "string",+ "nullable": true+ },+ "proxy_username": {+ "type": "string",+ "nullable": true+ },+ "proxy_password": {+ "type": "string",+ "nullable": true+ },+ "domain": {+ "type": "string",+ "nullable": true+ },+ "version": {+ "type": "string",+ "nullable": true+ },+ "dc": {+ "type": "string",+ "nullable": true+ },+ "site_name": {+ "type": "string",+ "nullable": true+ },+ "instanceName": {+ "type": "string",+ "nullable": true+ },+ "account_id": {+ "type": "string",+ "nullable": true+ },+ "your_server": {+ "type": "string",+ "nullable": true+ },+ "server_location": {+ "type": "string",+ "nullable": true+ },+ "base_url": {+ "type": "string",+ "nullable": true+ },+ "token": {+ "type": "string",+ "nullable": true+ },+ "generic_api_key": {+ "type": "string",+ "nullable": true+ },+ "api_key": {+ "type": "string",+ "nullable": true+ },+ "bearer_token": {+ "type": "string",+ "nullable": true+ },+ "basic_encoded": {+ "type": "string",+ "nullable": true+ },+ "username": {+ "type": "string",+ "nullable": true+ },+ "password": {+ "type": "string",+ "nullable": true+ },+ "credentials_json": {+ "type": "string",+ "nullable": true+ },+ "application_id": {+ "type": "string",+ "nullable": true+ },+ "installation_id": {+ "type": "string",+ "nullable": true+ },+ "private_key": {+ "type": "string",+ "nullable": true+ }+ },+ "additionalProperties": {},+ "description": "Credential fields to update. Only provided fields are changed — omitted fields are preserved. Set a field to null to remove it."+ }+ },+ "required": [+ "authScheme",+ "val"+ ]+ }+ },+ "required": [+ "state"+ ]+ }+ }+ },+ "DeprecatedToolkitInfo": {+ "type": "object",+ "properties": {+ "toolkitId": {+ "type": "string"+ }+ },+ "required": [+ "toolkitId"+ ],+ "description": "Deprecated toolkit ID",+ "deprecated": true,+ "example": {+ "toolkitId": "550e8400-e29b-41d4-a716-446655440000"+ }+ },+ "Tool": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Unique identifier for the tool",+ "example": "GITHUB_CREATE_A_WORKFLOW_DISPATCH_EVENT"+ },+ "name": {+ "type": "string",+ "description": "Human-readable display name of the tool",+ "example": "GitHub Actions"+ },+ "description": {+ "type": "string",+ "description": "Detailed explanation of the tool's functionality and purpose",+ "example": "Automate GitHub workflows including CI/CD, issue management, and release processes"+ },+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Unique identifier of the parent toolkit",+ "example": "github"+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the parent toolkit",+ "example": "GitHub"+ },+ "logo": {+ "type": "string",+ "description": "URL to the toolkit logo image",+ "example": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"+ }+ },+ "required": [+ "slug",+ "name",+ "logo"+ ]+ },+ "input_parameters": {+ "type": "object",+ "additionalProperties": {},+ "description": "Schema definition of required input parameters for the tool",+ "example": {+ "repo_name": {+ "type": "string",+ "description": "GitHub repository name in owner/repo format",+ "required": true,+ "example": "octocat/Hello-World"+ },+ "workflow_id": {+ "type": "string",+ "description": "ID or filename of the workflow to trigger",+ "required": true,+ "example": "main.yml"+ }+ }+ },+ "no_auth": {+ "type": "boolean",+ "description": "Indicates if the tool can be used without authentication",+ "example": false+ },+ "available_versions": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of all available versions for this tool",+ "example": [+ "20250905_00",+ "20250906_00"+ ]+ },+ "version": {+ "type": "string",+ "description": "Current version of the tool",+ "example": "20250905_00"+ },+ "output_parameters": {+ "type": "object",+ "additionalProperties": {},+ "description": "Schema definition of return values from the tool",+ "example": {+ "run_id": {+ "type": "number",+ "description": "ID of the workflow run that was triggered",+ "example": 12345678+ },+ "status": {+ "type": "string",+ "description": "Status of the workflow run",+ "example": "completed",+ "enum": [+ "queued",+ "in_progress",+ "completed",+ "failed"+ ]+ }+ }+ },+ "scopes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of scopes associated with the tool",+ "example": [+ "https://www.googleapis.com/auth/gmail.modify"+ ]+ },+ "scope_requirements": {+ "type": "object",+ "nullable": true,+ "properties": {+ "all_of": {+ "type": "array",+ "items": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "object",+ "properties": {+ "any_of": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1+ }+ },+ "required": [+ "any_of"+ ]+ }+ ]+ }+ }+ },+ "required": [+ "all_of"+ ],+ "description": "Structured scope requirements for the tool. Null means the tool is legacy and only exposes flat scopes.",+ "example": {+ "all_of": [+ "read:user",+ {+ "any_of": [+ "repo",+ "public_repo"+ ]+ }+ ]+ }+ },+ "tags": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of tags associated with the tool for categorization and filtering",+ "example": [+ "ci-cd",+ "github",+ "automation",+ "devops"+ ]+ },+ "human_description": {+ "type": "string",+ "description": "Human-friendly description of the tool, if available",+ "example": "Create a new issue in a GitHub repository"+ },+ "is_deprecated": {+ "type": "boolean",+ "description": "Indicates if this tool is deprecated and may be removed in the future",+ "example": false+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "displayName": {+ "type": "string",+ "description": "The display name of the tool",+ "example": "GitHub Actions"+ },+ "version": {+ "type": "string",+ "description": "Current version identifier of the tool",+ "example": "20250905_00"+ },+ "available_versions": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of all available versions for this tool",+ "example": [+ "20250905_00",+ "20250906_00"+ ]+ },+ "is_deprecated": {+ "type": "boolean",+ "description": "Indicates if this tool is deprecated and may be removed in the future",+ "example": false+ },+ "toolkit": {+ "type": "object",+ "properties": {+ "logo": {+ "type": "string",+ "description": "URL to the toolkit logo image",+ "example": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"+ }+ },+ "required": [+ "logo"+ ]+ }+ },+ "required": [+ "displayName",+ "version",+ "available_versions",+ "is_deprecated",+ "toolkit"+ ]+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "toolkit",+ "input_parameters",+ "no_auth",+ "available_versions",+ "version",+ "output_parameters",+ "scopes",+ "scope_requirements",+ "tags",+ "is_deprecated",+ "deprecated"+ ]+ },+ "ToolsPaginated": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/Tool"+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ },+ "ToolRouterToolkitsListResponse": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Display name of the toolkit"+ },+ "slug": {+ "type": "string",+ "description": "Unique slug identifier"+ },+ "enabled": {+ "type": "boolean",+ "description": "Whether the toolkit is enabled"+ },+ "is_no_auth": {+ "type": "boolean",+ "description": "Whether the toolkit is no-auth"+ },+ "composio_managed_auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Available Composio-managed auth schemes"+ },+ "meta": {+ "type": "object",+ "properties": {+ "logo": {+ "type": "string",+ "format": "uri",+ "description": "URL to the toolkit logo"+ },+ "description": {+ "type": "string",+ "description": "Description of the toolkit"+ }+ },+ "required": [+ "logo",+ "description"+ ],+ "description": "Toolkit metadata"+ },+ "connected_account": {+ "type": "object",+ "nullable": true,+ "properties": {+ "id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "Connected account identifier"+ },+ "user_id": {+ "type": "string",+ "description": "User identifier"+ },+ "status": {+ "type": "string",+ "description": "Connection status"+ },+ "created_at": {+ "type": "string",+ "format": "date-time",+ "description": "Creation timestamp"+ },+ "auth_config": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Auth config identifier"+ },+ "auth_scheme": {+ "type": "string",+ "description": "Authentication scheme type"+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether this is a Composio-managed auth config"+ }+ },+ "required": [+ "id",+ "auth_scheme",+ "is_composio_managed"+ ],+ "description": "Auth config details"+ }+ },+ "required": [+ "id",+ "user_id",+ "status",+ "created_at",+ "auth_config"+ ],+ "description": "Connected account if available"+ }+ },+ "required": [+ "name",+ "slug",+ "enabled",+ "is_no_auth",+ "composio_managed_auth_schemes",+ "meta",+ "connected_account"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ },+ "parameters": {}+ },+ "paths": {+ "/api/v3/auth/session/info": {+ "get": {+ "summary": "Get current user session information",+ "description": "Retrieves detailed information about the current authenticated user session, including project details, organization membership, and API key information if applicable. This endpoint is useful for verifying authentication status and retrieving contextual information about the authenticated user and their access privileges.",+ "tags": [+ "Authentication"+ ],+ "operationId": "getAuthSessionInfo",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Session is valid and active. Returns detailed information about the authenticated user, their project, and organization.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "project": {+ "type": "object",+ "nullable": true,+ "properties": {+ "auto_id": {+ "type": "number",+ "description": "Internal auto-incrementing ID for the project",+ "example": 12345+ },+ "id": {+ "type": "string",+ "description": "UUID identifier for the project",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "org_id": {+ "type": "string",+ "description": "Organization UUID that this project belongs to",+ "example": "550e8400-e29b-41d4-a716-446655440001"+ },+ "name": {+ "type": "string",+ "description": "User-defined name for the project",+ "example": "Production API"+ },+ "email": {+ "type": "string",+ "description": "Email address used for project notifications",+ "example": "[email protected]"+ },+ "nano_id": {+ "type": "string",+ "format": "projectId",+ "description": "Short, URL-friendly unique identifier for the project",+ "example": "proj_abc123xyz456"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when the project was created",+ "example": "2023-05-16T14:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when the project was last modified",+ "example": "2023-05-18T09:15:30.000Z"+ },+ "webhook_url": {+ "type": "string",+ "nullable": true,+ "description": "Endpoint URL for trigger webhook notifications",+ "example": "https://example.com/webhook"+ },+ "event_webhook_url": {+ "type": "string",+ "nullable": true,+ "description": "Endpoint URL for event webhook notifications",+ "example": "https://example.com/events"+ },+ "webhook_secret": {+ "type": "string",+ "nullable": true,+ "description": "Secret used to verify webhook signatures",+ "example": "whsec_a1b2c3d4e5f6g7h8i9j0"+ },+ "triggers_enabled": {+ "type": "boolean",+ "description": "Flag indicating if triggers are enabled for this project",+ "example": true+ },+ "last_subscribed_at": {+ "type": "string",+ "nullable": true,+ "description": "Date and time when the project last subscribed to updates",+ "example": "2023-05-17T10:00:00.000Z"+ },+ "deleted": {+ "type": "boolean",+ "description": "Flag indicating if the project has been deleted",+ "example": false+ },+ "is_new_webhook": {+ "type": "boolean",+ "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",+ "example": true,+ "deprecated": true+ },+ "webhook_version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Version of the webhook configuration",+ "example": "V2"+ },+ "org": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "orgId",+ "description": "Short, URL-friendly unique identifier for the organization",+ "example": "org_abc123xyz456"+ },+ "name": {+ "type": "string",+ "description": "User-defined name for the organization",+ "example": "Acme Corp"+ },+ "plan": {+ "type": "string",+ "description": "Current subscription plan level",+ "example": "BUSINESS"+ }+ },+ "required": [+ "id",+ "name",+ "plan"+ ],+ "description": "Organization details"+ }+ },+ "required": [+ "auto_id",+ "id",+ "org_id",+ "name",+ "email",+ "nano_id",+ "created_at",+ "updated_at",+ "webhook_url",+ "event_webhook_url",+ "webhook_secret",+ "triggers_enabled",+ "last_subscribed_at",+ "deleted",+ "is_new_webhook",+ "webhook_version",+ "org"+ ],+ "description": "Details of the current active project (null if accessing with org-level credentials)"+ },+ "api_key": {+ "type": "object",+ "nullable": true,+ "properties": {+ "auto_id": {+ "type": "number",+ "description": "Internal auto-incrementing ID for the API key",+ "example": 7890+ },+ "id": {+ "type": "string",+ "description": "UUID identifier for the API key",+ "example": "550e8400-e29b-41d4-a716-446655440003"+ },+ "name": {+ "type": "string",+ "description": "User-defined name for the API key",+ "example": "Development Key"+ },+ "project_id": {+ "type": "string",+ "format": "projectId",+ "description": "Short, URL-friendly unique identifier for the associated project",+ "example": "proj_abc123xyz456"+ },+ "org_member_id": {+ "type": "string",+ "description": "UUID identifier for the organization member who owns this API key",+ "example": "550e8400-e29b-41d4-a716-446655440002"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when the API key was created",+ "example": "2023-05-01T10:00:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when the API key was last modified",+ "example": "2023-05-01T10:00:00.000Z"+ },+ "deleted_at": {+ "type": "string",+ "nullable": true,+ "description": "Date and time when the API key was deleted (if applicable)"+ },+ "key": {+ "type": "string",+ "description": "The actual API key value (usually only shown once during creation)",+ "example": "sk_live_abc123xyz456"+ },+ "deleted": {+ "type": "boolean",+ "description": "Flag indicating if the API key has been deleted",+ "example": false+ }+ },+ "required": [+ "auto_id",+ "id",+ "name",+ "project_id",+ "org_member_id",+ "created_at",+ "updated_at",+ "deleted_at",+ "key",+ "deleted"+ ],+ "description": "Details of the API key used for authentication (null if using session auth)"+ },+ "org_member": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID identifier for the organization member",+ "example": "550e8400-e29b-41d4-a716-446655440002"+ },+ "email": {+ "type": "string",+ "description": "Email address of the authenticated user",+ "example": "[email protected]"+ },+ "name": {+ "type": "string",+ "description": "Display name of the authenticated user",+ "example": "John Doe"+ },+ "role": {+ "type": "string",+ "description": "Access role of the authenticated user within the organization",+ "example": "admin"+ }+ },+ "required": [+ "id",+ "email",+ "name",+ "role"+ ],+ "description": "Information about the authenticated user",+ "example": {+ "id": "550e8400-e29b-41d4-a716-446655440002",+ "email": "[email protected]",+ "name": "John Doe",+ "role": "admin"+ }+ }+ },+ "required": [+ "project",+ "api_key",+ "org_member"+ ],+ "description": "Response containing user session information"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The request format may be invalid or missing required parameters.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid or expired.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to access this resource.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The requested project, organization, or member resource could not be found.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/auth_configs": {+ "post": {+ "summary": "Create new authentication configuration",+ "description": "Creates a new auth config for a toolkit, allowing you to use your own OAuth credentials or API keys instead of Composio-managed authentication. This is required when you want to use custom OAuth apps (bring your own client ID/secret) or configure specific authentication parameters for a toolkit.",+ "tags": [+ "Auth Configs"+ ],+ "operationId": "postAuthConfigs",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Toolkit slug to create auth config for"+ }+ },+ "required": [+ "slug"+ ]+ },+ "auth_config": {+ "oneOf": [+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "use_composio_managed_auth"+ ]+ },+ "name": {+ "type": "string",+ "description": "The name of the integration"+ },+ "credentials": {+ "type": "object",+ "properties": {+ "scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "user_scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ }+ },+ "default": {}+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ }+ }+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",+ "x-experimental": true+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "use_custom_auth"+ ]+ },+ "name": {+ "type": "string",+ "description": "The name of the integration"+ },+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "credentials": {+ "type": "object",+ "properties": {+ "scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "user_scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ }+ },+ "default": {}+ },+ "proxy_config": {+ "type": "object",+ "nullable": true,+ "properties": {+ "proxy_url": {+ "type": "string",+ "format": "uri",+ "description": "The url of the auth proxy"+ },+ "proxy_auth_key": {+ "type": "string",+ "description": "The auth key for the auth proxy"+ }+ },+ "required": [+ "proxy_url"+ ]+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ }+ }+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",+ "x-experimental": true+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ }+ },+ "required": [+ "type",+ "authScheme"+ ]+ }+ ],+ "default": {+ "type": "use_composio_managed_auth",+ "credentials": {},+ "restrict_to_following_tools": []+ }+ }+ },+ "required": [+ "toolkit"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Successfully created auth config",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The unique key of the toolkit"+ }+ },+ "required": [+ "slug"+ ]+ },+ "auth_config": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The auth config id of the toolkit (must be a valid auth config id)"+ },+ "auth_scheme": {+ "type": "string",+ "description": "The authentication mode of the toolkit"+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether the auth config is managed by Composio"+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "The tools that the user can use with the auth config"+ }+ },+ "required": [+ "id",+ "auth_scheme",+ "is_composio_managed"+ ]+ }+ },+ "required": [+ "toolkit",+ "auth_config"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "get": {+ "summary": "List authentication configurations with optional filters",+ "description": "Retrieves all auth configs for your project. Auth configs define how users authenticate with external services (OAuth, API keys, etc.). Use filters to find configs for specific toolkits or to distinguish between Composio-managed and custom configurations.",+ "tags": [+ "Auth Configs"+ ],+ "operationId": "getAuthConfigs",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "boolean"+ }+ ],+ "description": "Whether to filter by composio managed auth configs"+ },+ "required": false,+ "description": "Whether to filter by composio managed auth configs",+ "name": "is_composio_managed",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Comma-separated list of toolkit slugs to filter auth configs by",+ "in": "query",+ "name": "toolkit_slug"+ },+ {+ "schema": {+ "type": "string",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_slug instead.",+ "deprecated": true+ },+ "required": false,+ "description": "The app id to filter by",+ "name": "deprecated_app_id",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "DEPRECATED: This parameter will be removed in a future version.",+ "deprecated": true+ },+ "required": false,+ "name": "deprecated_status",+ "in": "query"+ },+ {+ "schema": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "Show disabled auth configs"+ },+ "required": false,+ "description": "Show disabled auth configs",+ "name": "show_disabled",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Search auth configs by name or id"+ },+ "required": false,+ "description": "Search auth configs by name or id",+ "name": "search",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully fetched auth configs",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique ID of the authentication configuration"+ },+ "uuid": {+ "type": "string",+ "description": "The UUID of the authentication configuration (for backward compatibility)"+ },+ "type": {+ "type": "string",+ "enum": [+ "default",+ "custom"+ ],+ "description": "The type of the authentication configuration (custom or default)"+ },+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The unique identifier of the integration app"+ },+ "logo": {+ "type": "string",+ "description": "The URL to the integration app's logo image"+ },+ "auth_guide_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions"+ },+ "auth_hint_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a page where users can obtain or configure credentials"+ }+ },+ "required": [+ "slug",+ "logo"+ ],+ "description": "Information about the associated integration"+ },+ "name": {+ "type": "string",+ "description": "The display name of the authentication configuration"+ },+ "auth_scheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ],+ "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether this authentication configuration is managed by Composio or the user"+ },+ "credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"+ },+ "proxy_config": {+ "type": "object",+ "nullable": true,+ "properties": {+ "proxy_url": {+ "type": "string",+ "format": "uri",+ "description": "The url of the auth proxy"+ },+ "proxy_auth_key": {+ "type": "string",+ "description": "The auth key for the auth proxy"+ }+ },+ "required": [+ "proxy_url"+ ]+ },+ "status": {+ "type": "string",+ "enum": [+ "ENABLED",+ "DISABLED"+ ],+ "description": "Current status of the authentication configuration"+ },+ "created_by": {+ "type": "string",+ "description": "The identifier of the user who created the auth config"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 date-time when the auth config was created"+ },+ "last_updated_at": {+ "type": "string",+ "description": "ISO 8601 date-time when the auth config was last updated"+ },+ "no_of_connections": {+ "type": "number",+ "description": "The number of active connections using this auth config"+ },+ "expected_input_fields": {+ "type": "array",+ "items": {+ "nullable": true,+ "type": "object"+ },+ "description": "Fields expected during connection initialization"+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ },+ "tools_available_for_execution": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."+ }+ }+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",+ "x-experimental": true+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ },+ "deprecated_params": {+ "type": "object",+ "properties": {+ "default_connector_id": {+ "type": "string",+ "nullable": true,+ "description": "Deprecated: Default connector ID"+ },+ "member_uuid": {+ "type": "string",+ "description": "Deprecated: Member UUID"+ },+ "toolkit_id": {+ "type": "string",+ "description": "Deprecated: Toolkit ID"+ },+ "expected_input_fields": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": {}+ },+ "description": "Deprecated: Fields expected during connection initialization"+ }+ },+ "required": [+ "default_connector_id"+ ],+ "description": "DEPRECATED: This parameter will be removed in a future version.",+ "deprecated": true+ }+ },+ "required": [+ "id",+ "uuid",+ "type",+ "toolkit",+ "name",+ "status",+ "no_of_connections",+ "tool_access_config"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/auth_configs/{nanoid}": {+ "get": {+ "summary": "Get single authentication configuration by ID",+ "description": "Retrieves detailed information about a specific authentication configuration using its unique identifier.",+ "tags": [+ "Auth Configs"+ ],+ "operationId": "getAuthConfigsByNanoid",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique identifier of the authentication configuration to retrieve"+ },+ "required": true,+ "description": "The unique identifier of the authentication configuration to retrieve",+ "name": "nanoid",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully fetched auth config",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique ID of the authentication configuration"+ },+ "uuid": {+ "type": "string",+ "description": "The UUID of the authentication configuration (for backward compatibility)"+ },+ "type": {+ "type": "string",+ "enum": [+ "default",+ "custom"+ ],+ "description": "The type of the authentication configuration (custom or default)"+ },+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The unique identifier of the integration app"+ },+ "logo": {+ "type": "string",+ "description": "The URL to the integration app's logo image"+ },+ "auth_guide_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions"+ },+ "auth_hint_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a page where users can obtain or configure credentials"+ }+ },+ "required": [+ "slug",+ "logo"+ ],+ "description": "Information about the associated integration"+ },+ "name": {+ "type": "string",+ "description": "The display name of the authentication configuration"+ },+ "auth_scheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ],+ "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether this authentication configuration is managed by Composio or the user"+ },+ "credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"+ },+ "proxy_config": {+ "type": "object",+ "nullable": true,+ "properties": {+ "proxy_url": {+ "type": "string",+ "format": "uri",+ "description": "The url of the auth proxy"+ },+ "proxy_auth_key": {+ "type": "string",+ "description": "The auth key for the auth proxy"+ }+ },+ "required": [+ "proxy_url"+ ]+ },+ "status": {+ "type": "string",+ "enum": [+ "ENABLED",+ "DISABLED"+ ],+ "description": "Current status of the authentication configuration"+ },+ "created_by": {+ "type": "string",+ "description": "The identifier of the user who created the auth config"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 date-time when the auth config was created"+ },+ "last_updated_at": {+ "type": "string",+ "description": "ISO 8601 date-time when the auth config was last updated"+ },+ "no_of_connections": {+ "type": "number",+ "description": "The number of active connections using this auth config"+ },+ "expected_input_fields": {+ "type": "array",+ "items": {+ "nullable": true,+ "type": "object"+ },+ "description": "Fields expected during connection initialization"+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ },+ "tools_available_for_execution": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."+ }+ }+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",+ "x-experimental": true+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ },+ "deprecated_params": {+ "type": "object",+ "properties": {+ "default_connector_id": {+ "type": "string",+ "nullable": true,+ "description": "Deprecated: Default connector ID"+ },+ "member_uuid": {+ "type": "string",+ "description": "Deprecated: Member UUID"+ },+ "toolkit_id": {+ "type": "string",+ "description": "Deprecated: Toolkit ID"+ },+ "expected_input_fields": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": {}+ },+ "description": "Deprecated: Fields expected during connection initialization"+ }+ },+ "required": [+ "default_connector_id"+ ],+ "description": "DEPRECATED: This parameter will be removed in a future version.",+ "deprecated": true+ }+ },+ "required": [+ "id",+ "uuid",+ "type",+ "toolkit",+ "name",+ "status",+ "no_of_connections",+ "tool_access_config"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid auth config ID format",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication required",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Auth configuration does not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "patch": {+ "summary": "Update an authentication configuration",+ "description": "Modifies an existing authentication configuration with new credentials or other settings. Only specified fields will be updated.",+ "tags": [+ "Auth Configs"+ ],+ "operationId": "patchAuthConfigsByNanoid",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique identifier of the authentication configuration to update"+ },+ "required": true,+ "description": "The unique identifier of the authentication configuration to update",+ "name": "nanoid",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "oneOf": [+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "custom"+ ]+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "description": "The display name of the authentication configuration"+ },+ "credentials": {+ "type": "object",+ "properties": {+ "scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "user_scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ }+ }+ },+ "proxy_config": {+ "type": "object",+ "nullable": true,+ "properties": {+ "proxy_url": {+ "type": "string",+ "format": "uri",+ "description": "The url of the auth proxy"+ },+ "proxy_auth_key": {+ "type": "string",+ "description": "The auth key for the auth proxy"+ }+ },+ "required": [+ "proxy_url"+ ]+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ },+ "tools_available_for_execution": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."+ }+ }+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config."+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "default"+ ]+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "description": "The display name of the authentication configuration"+ },+ "scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "user_scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ },+ "tools_available_for_execution": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."+ }+ }+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config."+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ }+ },+ "required": [+ "type"+ ]+ }+ ]+ },+ "examples": {+ "standardUpdate": {+ "summary": "Standard credential update",+ "value": {+ "auth_config": {+ "credentials": {+ "api_key": "YOUR_NEW_API_KEY",+ "client_secret": "YOUR_NEW_CLIENT_SECRET"+ },+ "restrict_to_following_tools": [+ "GMAIL_SEND_EMAIL",+ "GMAIL_FETCH_EMAILS"+ ]+ }+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully updated auth config",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid input or credentials format",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication required",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Auth configuration does not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "delete": {+ "summary": "Delete an authentication configuration",+ "description": "Soft-deletes an authentication configuration by marking it as deleted in the database. This operation cannot be undone.",+ "tags": [+ "Auth Configs"+ ],+ "operationId": "deleteAuthConfigsByNanoid",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique identifier of the authentication configuration to delete"+ },+ "required": true,+ "description": "The unique identifier of the authentication configuration to delete",+ "name": "nanoid",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully deleted auth config",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid auth config ID format",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication required",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Auth config not found - The specified configuration does not exist or was already deleted",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/auth_configs/{nanoid}/{status}": {+ "patch": {+ "summary": "Enable or disable an authentication configuration",+ "description": "Updates the status of an authentication configuration to either enabled or disabled. Disabled configurations cannot be used for new connections.",+ "tags": [+ "Auth Configs"+ ],+ "operationId": "patchAuthConfigsByNanoidByStatus",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique identifier of the authentication configuration to update"+ },+ "required": true,+ "description": "The unique identifier of the authentication configuration to update",+ "name": "nanoid",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "ENABLED",+ "DISABLED"+ ],+ "description": "The new status to set for the auth configuration"+ },+ "required": true,+ "description": "The new status to set for the auth configuration",+ "name": "status",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully updated auth config status",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid auth config ID or status value",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication required",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Auth configuration does not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/connected_accounts": {+ "get": {+ "summary": "List connected accounts with optional filters",+ "description": "Retrieves all connected accounts for your project. Connected accounts represent authenticated user connections to external services (e.g., a user's Gmail account, Slack workspace). Filter by toolkit, status, user ID, or auth config to find specific connections.",+ "tags": [+ "Connected Accounts"+ ],+ "operationId": "getConnectedAccounts",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "The toolkit slugs of the connected accounts"+ },+ "required": false,+ "description": "The toolkit slugs of the connected accounts",+ "name": "toolkit_slugs",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "description": "The status of the connected account"+ },+ "required": false,+ "description": "The status of the connected account",+ "name": "statuses",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "nullable": true,+ "description": "The cursor to paginate through the connected accounts"+ },+ "required": false,+ "description": "The cursor to paginate through the connected accounts",+ "name": "cursor",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true,+ "description": "The limit of the connected accounts to return"+ },+ "required": false,+ "description": "The limit of the connected accounts to return",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "The user ids of the connected accounts"+ },+ "required": false,+ "description": "The user ids of the connected accounts",+ "name": "user_ids",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "authConfigId"+ },+ "description": "The auth config ids of the connected accounts"+ },+ "required": false,+ "description": "The auth config ids of the connected accounts",+ "name": "auth_config_ids",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "description": "The connected account ids to filter by"+ },+ "required": false,+ "description": "The connected account ids to filter by",+ "name": "connected_account_ids",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "created_at",+ "updated_at"+ ],+ "default": "created_at",+ "description": "The order by of the connected accounts"+ },+ "required": false,+ "description": "The order by of the connected accounts",+ "name": "order_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "asc",+ "desc"+ ],+ "default": "desc",+ "description": "The order direction of the connected accounts"+ },+ "required": false,+ "description": "The order direction of the connected accounts",+ "name": "order_direction",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved connected accounts",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The slug of the toolkit"+ }+ },+ "required": [+ "slug"+ ]+ },+ "auth_config": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The id of the auth config"+ },+ "auth_scheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ],+ "description": "the authScheme is part of the connection state use it there",+ "deprecated": true+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether the auth config is managed by Composio"+ },+ "is_disabled": {+ "type": "boolean",+ "description": "Whether the auth config is disabled"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the auth config"+ }+ },+ "required": [+ "uuid"+ ],+ "deprecated": true+ }+ },+ "required": [+ "id",+ "auth_scheme",+ "is_composio_managed",+ "is_disabled"+ ]+ },+ "id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The id of the connection"+ },+ "word_id": {+ "type": "string",+ "nullable": true,+ "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")"+ },+ "alias": {+ "type": "string",+ "nullable": true,+ "description": "A user-defined alias for the connected account"+ },+ "user_id": {+ "type": "string",+ "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back",+ "deprecated": true+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ],+ "description": "The status of the connection"+ },+ "created_at": {+ "type": "string",+ "description": "The created at of the connection"+ },+ "updated_at": {+ "type": "string",+ "description": "The updated at of the connection"+ },+ "state": {+ "description": "The state of the connection",+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH1",+ "OAUTH2",+ "API_KEY",+ "BASIC",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "CALCOM_AUTH",+ "BILLCOM_AUTH",+ "BASIC_WITH_JWT",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ }+ },+ "required": [+ "status"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "authScheme",+ "val"+ ],+ "additionalProperties": true+ },+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "This is deprecated, use `state` instead",+ "deprecated": true+ },+ "status_reason": {+ "type": "string",+ "nullable": true,+ "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled"+ },+ "is_disabled": {+ "type": "boolean",+ "description": "Whether the connection is disabled"+ },+ "test_request_endpoint": {+ "type": "string",+ "description": "The endpoint to make test request for verification"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "labels": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The labels of the connection"+ },+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the connection"+ }+ },+ "required": [+ "labels",+ "uuid"+ ],+ "deprecated": true+ }+ },+ "required": [+ "toolkit",+ "auth_config",+ "id",+ "word_id",+ "alias",+ "user_id",+ "status",+ "created_at",+ "updated_at",+ "state",+ "data",+ "status_reason",+ "is_disabled"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "post": {+ "summary": "Create a new connected account",+ "description": "Initiates a new connection to an external service for a user. For OAuth-based toolkits, this returns a redirect URL to complete authentication. For API key-based toolkits, provide the credentials directly in the request body. Use the `user_id` field to associate the connection with a specific user in your system.",+ "tags": [+ "Connected Accounts"+ ],+ "operationId": "postConnectedAccounts",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "auth_config": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The auth config id of the app (must be a valid auth config id)"+ }+ },+ "required": [+ "id"+ ]+ },+ "connection": {+ "type": "object",+ "properties": {+ "state": {+ "description": "The state of the connected account",+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH1",+ "OAUTH2",+ "API_KEY",+ "BASIC",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "CALCOM_AUTH",+ "BILLCOM_AUTH",+ "BASIC_WITH_JWT",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ }+ },+ "required": [+ "status"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "authScheme",+ "val"+ ],+ "additionalProperties": true+ },+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use state instead.",+ "deprecated": true+ },+ "user_id": {+ "type": "string",+ "default": "default",+ "description": "The user id of the connected account"+ },+ "alias": {+ "type": "string",+ "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."+ },+ "callback_url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to redirect to after connection completion"+ },+ "redirect_uri": {+ "type": "string",+ "format": "uri",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use callback_url instead.",+ "deprecated": true+ },+ "deprecated_is_v1_rerouted": {+ "type": "boolean",+ "default": false,+ "description": "DEPRECATED: This parameter will be removed in a future version.",+ "deprecated": true+ }+ }+ },+ "validate_credentials": {+ "type": "boolean",+ "default": false,+ "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme",+ "x-experimental": true+ }+ },+ "required": [+ "auth_config",+ "connection"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Successfully created connected account",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The id of the connected account"+ },+ "connectionData": {+ "description": "The connection data of the connected account",+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH1",+ "OAUTH2",+ "API_KEY",+ "BASIC",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "CALCOM_AUTH",+ "BILLCOM_AUTH",+ "BASIC_WITH_JWT",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ }+ },+ "required": [+ "status"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "authScheme",+ "val"+ ],+ "additionalProperties": true+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ],+ "description": "DEPRECATED: This field will be removed in a future version",+ "deprecated": true+ },+ "redirect_url": {+ "type": "string",+ "nullable": true,+ "description": "DEPRECATED: This field will be removed in a future version",+ "deprecated": true+ },+ "redirect_uri": {+ "type": "string",+ "nullable": true,+ "description": "DEPRECATED: This field will be removed in a future version",+ "deprecated": true+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the connected account"+ },+ "authConfigUuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the auth config"+ }+ },+ "required": [+ "uuid",+ "authConfigUuid"+ ],+ "description": "DEPRECATED: This field will be removed in a future version. Please use id and auth_config.id instead.",+ "deprecated": true+ }+ },+ "required": [+ "id",+ "connectionData",+ "status",+ "redirect_url",+ "redirect_uri",+ "deprecated"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/connected_accounts/{nanoid}": {+ "get": {+ "summary": "Get connected account details by ID",+ "description": "Retrieves comprehensive details of a connected account, including authentication configuration, connection status, and all parameters needed for API requests.",+ "tags": [+ "Connected Accounts"+ ],+ "operationId": "getConnectedAccountsByNanoid",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "required": true,+ "description": "The unique identifier (nanoid) of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoid",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved connected account details with all authentication parameters and connection status",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The slug of the toolkit"+ }+ },+ "required": [+ "slug"+ ]+ },+ "auth_config": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The id of the auth config"+ },+ "auth_scheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ],+ "description": "the authScheme is part of the connection state use it there",+ "deprecated": true+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether the auth config is managed by Composio"+ },+ "is_disabled": {+ "type": "boolean",+ "description": "Whether the auth config is disabled"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the auth config"+ }+ },+ "required": [+ "uuid"+ ],+ "deprecated": true+ }+ },+ "required": [+ "id",+ "auth_scheme",+ "is_composio_managed",+ "is_disabled"+ ]+ },+ "id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The id of the connection"+ },+ "word_id": {+ "type": "string",+ "nullable": true,+ "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")"+ },+ "alias": {+ "type": "string",+ "nullable": true,+ "description": "A user-defined alias for the connected account"+ },+ "user_id": {+ "type": "string",+ "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back",+ "deprecated": true+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ],+ "description": "The status of the connection"+ },+ "created_at": {+ "type": "string",+ "description": "The created at of the connection"+ },+ "updated_at": {+ "type": "string",+ "description": "The updated at of the connection"+ },+ "state": {+ "description": "The state of the connection",+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH1",+ "OAUTH2",+ "API_KEY",+ "BASIC",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "CALCOM_AUTH",+ "BILLCOM_AUTH",+ "BASIC_WITH_JWT",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ }+ },+ "required": [+ "status"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "authScheme",+ "val"+ ],+ "additionalProperties": true+ },+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "This is deprecated, use `state` instead",+ "deprecated": true+ },+ "status_reason": {+ "type": "string",+ "nullable": true,+ "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled"+ },+ "is_disabled": {+ "type": "boolean",+ "description": "Whether the connection is disabled"+ },+ "test_request_endpoint": {+ "type": "string",+ "description": "The endpoint to make test request for verification"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "labels": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The labels of the connection"+ },+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the connection"+ }+ },+ "required": [+ "labels",+ "uuid"+ ],+ "deprecated": true+ },+ "params": {+ "type": "object",+ "additionalProperties": {},+ "description": "The initialization data of the connection, including configuration parameters",+ "deprecated": true+ }+ },+ "required": [+ "toolkit",+ "auth_config",+ "id",+ "word_id",+ "alias",+ "user_id",+ "status",+ "created_at",+ "updated_at",+ "state",+ "data",+ "status_reason",+ "is_disabled",+ "params"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid nanoid format or other validation error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Insufficient permissions to access this connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Connected account does not exist or was deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Failed to retrieve connected account details",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "delete": {+ "summary": "Delete a connected account",+ "description": "Soft-deletes a connected account by marking it as deleted in the database. This prevents the account from being used for API calls but preserves the record for audit purposes.",+ "tags": [+ "Connected Accounts"+ ],+ "operationId": "deleteConnectedAccountsByNanoid",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "required": true,+ "description": "The unique identifier (nanoid) of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoid",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully deleted the connected account. The account is marked as deleted but retained in the database for historical purposes.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "description": "Indicates whether the connected account was successfully deleted"+ }+ },+ "required": [+ "success"+ ],+ "description": "Response returned after successfully deleting a connected account",+ "example": {+ "success": true+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid nanoid format or other validation error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Insufficient permissions to delete this connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Connected account not found - The specified account does not exist or has already been deleted",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Failed to delete the connected account due to a server-side issue",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "patch": {+ "summary": "Update a connected account",+ "description": "Update a connected account. Supports updating the alias and/or credentials. Only specified fields will be updated. Set a credential field to null to remove it. Alias must be unique within the same project, entity, and toolkit scope.",+ "tags": [+ "Connected Accounts"+ ],+ "operationId": "patchConnectedAccountsByNanoid",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "required": true,+ "description": "The unique identifier (nanoid) of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoid",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/PatchConnectedAccountBody"+ },+ "examples": {+ "credentials": {+ "summary": "Update credentials",+ "value": {+ "connection": {+ "state": {+ "authScheme": "BEARER_TOKEN",+ "val": {+ "token": "new_access_token"+ }+ }+ }+ }+ },+ "alias": {+ "summary": "Update alias",+ "value": {+ "alias": "work-gmail"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully updated connected account",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "description": "Whether the update was successful"+ },+ "id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The unique identifier of the updated connected account"+ },+ "status": {+ "type": "string",+ "description": "The current status of the connected account after the update (ACTIVE, EXPIRED, INACTIVE, etc.)"+ }+ },+ "required": [+ "success",+ "id",+ "status"+ ],+ "example": {+ "success": true,+ "id": "ca_1a2b3c4d5e6f",+ "status": "ACTIVE"+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid nanoid, duplicate alias, or invalid credential values",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Insufficient permissions to update this connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Connected account does not exist or was deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Failed to update connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/connected_accounts/{nanoId}/status": {+ "patch": {+ "summary": "Enable or disable a connected account",+ "description": "Updates the status of a connected account to either enabled (active) or disabled (inactive). Disabled accounts cannot be used for API calls but remain in the database.",+ "tags": [+ "Connected Accounts"+ ],+ "operationId": "patchConnectedAccountsByNanoIdStatus",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "required": true,+ "description": "The unique identifier of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoId",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "boolean",+ "description": "Set to true to enable the account or false to disable it"+ }+ },+ "required": [+ "enabled"+ ],+ "example": {+ "enabled": true+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully updated the connected account status. If enabled=true, the account status is set to ACTIVE; if enabled=false, the status is set to INACTIVE.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "description": "Indicates whether the connected account status was successfully updated"+ }+ },+ "required": [+ "success"+ ],+ "description": "Response returned after successfully updating a connected account status",+ "example": {+ "success": true+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid nanoid format or invalid request body",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Insufficient permissions to update this connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Connected account not found - The specified account does not exist or has been deleted",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Failed to update the connected account status due to a server-side issue",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/connected_accounts/{nanoid}/refresh": {+ "post": {+ "summary": "Refresh authentication for a connected account",+ "description": "Initiates a new authentication flow for a connected account when credentials have expired or become invalid. This may generate a new authentication URL for OAuth flows or refresh tokens for other auth schemes.",+ "tags": [+ "Connected Accounts"+ ],+ "operationId": "postConnectedAccountsByNanoidRefresh",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "required": true,+ "description": "The unique identifier of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoid",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "format": "uri"+ },+ "required": false,+ "name": "redirect_url",+ "in": "query"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "redirect_url": {+ "type": "string",+ "format": "uri"+ },+ "validate_credentials": {+ "type": "boolean",+ "default": false,+ "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme",+ "x-experimental": true+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully refreshed the connected account authentication. For OAuth flows, a new redirect URL is provided.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "The unique identifier of the connected account"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ],+ "description": "The current status of the connected account (e.g., active, pending, failed)"+ },+ "redirect_url": {+ "type": "string",+ "nullable": true,+ "description": "The URL to which the user should be redirected to complete the authentication process (null for auth schemes that do not require redirection)"+ }+ },+ "required": [+ "id",+ "status",+ "redirect_url"+ ],+ "description": "Response schema for a refreshed connected account authentication",+ "example": {+ "id": "ca_1a2b3c4d5e6f",+ "status": "ACTIVE",+ "redirect_url": "https://app.example.com/oauth/callback"+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid nanoid format or the account cannot be refreshed in its current state",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Insufficient permissions to refresh this connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Connected account does not exist or was deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Failed to refresh the connected account authentication",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/connected_accounts/link": {+ "post": {+ "summary": "Create a new auth link session",+ "description": "Creates a new authentication link session that users can use to connect their accounts",+ "tags": [+ "Connected Accounts"+ ],+ "operationId": "postConnectedAccountsLink",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "auth_config_id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The auth config id to create a link for"+ },+ "user_id": {+ "type": "string",+ "minLength": 1,+ "description": "The user id to create a link for"+ },+ "alias": {+ "type": "string",+ "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."+ },+ "callback_url": {+ "type": "string",+ "description": "The callback url to create a link for"+ },+ "connection_data": {+ "description": "Optional data to pre-fill connection fields with default values",+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ },+ "state_prefix": {+ "type": "string",+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"+ },+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"+ },+ "code_verifier": {+ "type": "string"+ },+ "finalRedirectUri": {+ "type": "string"+ },+ "webhook_signature": {+ "type": "string"+ },+ "access_token": {+ "type": "string"+ },+ "id_token": {+ "type": "string"+ },+ "token_type": {+ "type": "string"+ },+ "refresh_token": {+ "type": "string",+ "nullable": true+ },+ "expires_in": {+ "anyOf": [+ {+ "type": "number"+ },+ {+ "type": "string"+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "scope": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "authed_user": {+ "type": "object",+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {+ "type": "string"+ }+ },+ "description": "for slack user scopes"+ },+ "generic_api_key": {+ "type": "string"+ },+ "api_key": {+ "type": "string"+ },+ "bearer_token": {+ "type": "string"+ },+ "basic_encoded": {+ "type": "string"+ },+ "username": {+ "type": "string"+ },+ "password": {+ "type": "string"+ },+ "token": {+ "type": "string"+ },+ "composio_link_redirect_url": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "sessionId": {+ "type": "string"+ },+ "devKey": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "client_id": {+ "type": "string",+ "description": "Dynamically registered client ID"+ },+ "client_secret": {+ "type": "string",+ "description": "Dynamically registered client secret"+ },+ "client_id_issued_at": {+ "type": "number"+ },+ "client_secret_expires_at": {+ "type": "number"+ },+ "expires_at": {+ "type": "string"+ }+ },+ "additionalProperties": true+ }+ },+ "required": [+ "auth_config_id",+ "user_id"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Successfully created auth link",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "link_token": {+ "type": "string",+ "description": "The generated link token for the auth session"+ },+ "redirect_url": {+ "type": "string",+ "description": "The redirect URI to send users to for authentication"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO timestamp when the link expires"+ },+ "connected_account_id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The connected account ID that was created"+ }+ },+ "required": [+ "link_token",+ "redirect_url",+ "expires_at",+ "connected_account_id"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Auth config not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/org/usage/summary": {+ "get": {+ "summary": "Org usage summary",+ "description": "Aggregated metering usage for the authenticated organization across all projects. Requires ClickHouse logging (`USE_CLICKHOUSE_FOR_LOGS`). Values are summed from raw metering events grouped by `entity_type`.",+ "tags": [+ "Organization"+ ],+ "operationId": "getOrgUsageSummary",+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time."+ },+ "required": false,+ "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time.",+ "name": "start_time",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Exclusive range end (ISO 8601). Defaults to now."+ },+ "required": false,+ "description": "Exclusive range end (ISO 8601). Defaults to now.",+ "name": "end_time",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types."+ },+ "required": false,+ "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types.",+ "name": "entity_types",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Usage aggregates for the organization.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "rows": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "entity_type": {+ "type": "string"+ },+ "unit": {+ "type": "string"+ },+ "total_quantity": {+ "type": "string"+ },+ "event_count": {+ "type": "integer",+ "minimum": 0+ }+ },+ "required": [+ "entity_type",+ "unit",+ "total_quantity",+ "event_count"+ ]+ }+ }+ },+ "required": [+ "rows"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid time range, entity_types, or query parameters.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Authentication required.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Failed to load usage from analytics store or feature configuration.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/org/project/config": {+ "get": {+ "summary": "Get project configuration",+ "description": "Retrieves the current project configuration including 2FA settings.",+ "tags": [+ "Projects"+ ],+ "operationId": "getOrgProjectConfig",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Project configuration retrieved successfully.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "is_2FA_enabled": {+ "type": "boolean"+ },+ "logo_url": {+ "type": "string"+ },+ "display_name": {+ "type": "string"+ },+ "mask_secret_keys_in_connected_account": {+ "type": "boolean"+ },+ "log_visibility_setting": {+ "type": "string",+ "enum": [+ "show_all",+ "dont_store_data"+ ]+ },+ "require_mcp_api_key": {+ "type": "boolean"+ },+ "is_composio_link_enabled_for_managed_auth": {+ "type": "boolean",+ "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."+ },+ "signed_url_file_expiry_in_seconds": {+ "type": "number",+ "minimum": 1,+ "maximum": 86400+ }+ },+ "required": [+ "is_2FA_enabled",+ "mask_secret_keys_in_connected_account",+ "log_visibility_setting"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The project configuration data may be invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Project not found. The specified project does not exist or has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "patch": {+ "summary": "Update project configuration",+ "description": "Updates the project configuration settings.",+ "tags": [+ "Projects"+ ],+ "operationId": "patchOrgProjectConfig",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "is_2FA_enabled": {+ "type": "boolean"+ },+ "logo_url": {+ "type": "string"+ },+ "display_name": {+ "type": "string"+ },+ "mask_secret_keys_in_connected_account": {+ "type": "boolean"+ },+ "log_visibility_setting": {+ "type": "string",+ "enum": [+ "show_all",+ "dont_store_data"+ ]+ },+ "require_mcp_api_key": {+ "type": "boolean"+ },+ "is_composio_link_enabled_for_managed_auth": {+ "type": "boolean",+ "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."+ },+ "signed_url_file_expiry_in_seconds": {+ "type": "number",+ "minimum": 1,+ "maximum": 86400+ }+ }+ },+ "examples": {+ "Enable 2FA": {+ "value": {+ "is_2FA_enabled": true+ }+ },+ "Disable 2FA": {+ "value": {+ "is_2FA_enabled": false+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Project configuration updated successfully.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "is_2FA_enabled": {+ "type": "boolean"+ },+ "logo_url": {+ "type": "string"+ },+ "display_name": {+ "type": "string"+ },+ "mask_secret_keys_in_connected_account": {+ "type": "boolean"+ },+ "log_visibility_setting": {+ "type": "string",+ "enum": [+ "show_all",+ "dont_store_data"+ ]+ },+ "require_mcp_api_key": {+ "type": "boolean"+ },+ "is_composio_link_enabled_for_managed_auth": {+ "type": "boolean",+ "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."+ },+ "signed_url_file_expiry_in_seconds": {+ "type": "number",+ "minimum": 1,+ "maximum": 86400+ }+ },+ "required": [+ "is_2FA_enabled",+ "mask_secret_keys_in_connected_account",+ "log_visibility_setting"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The configuration data may be invalid or missing.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Project not found. The specified project does not exist or has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/org/project/usage/summary": {+ "get": {+ "summary": "Project usage summary",+ "description": "Aggregated metering usage for the authenticated project only. Requires ClickHouse logging (`USE_CLICKHOUSE_FOR_LOGS`). Values are summed from raw metering events grouped by `entity_type`.",+ "tags": [+ "Projects"+ ],+ "operationId": "getOrgProjectUsageSummary",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time."+ },+ "required": false,+ "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time.",+ "name": "start_time",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Exclusive range end (ISO 8601). Defaults to now."+ },+ "required": false,+ "description": "Exclusive range end (ISO 8601). Defaults to now.",+ "name": "end_time",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types."+ },+ "required": false,+ "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types.",+ "name": "entity_types",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Usage aggregates for the project.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "rows": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "entity_type": {+ "type": "string"+ },+ "unit": {+ "type": "string"+ },+ "total_quantity": {+ "type": "string"+ },+ "event_count": {+ "type": "integer",+ "minimum": 0+ }+ },+ "required": [+ "entity_type",+ "unit",+ "total_quantity",+ "event_count"+ ]+ }+ }+ },+ "required": [+ "rows"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid time range, entity_types, or query parameters.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Authentication required.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Failed to load usage from analytics store or feature configuration.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/org/owner/project/new": {+ "post": {+ "summary": "Create a new project",+ "description": "Creates a new project within the authenticated user's organization using the specified name. Projects are isolated environments within your organization, each with their own API keys, webhook configurations, and resources. Use this endpoint to create additional projects for different environments (e.g., development, staging, production) or for separate applications.",+ "tags": [+ "Projects"+ ],+ "operationId": "postOrgOwnerProjectNew",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 3,+ "maxLength": 75,+ "pattern": "^[a-zA-Z0-9_-]+$",+ "description": "A unique name for your project that follows the required format rules",+ "example": "my-awesome-project"+ },+ "should_create_api_key": {+ "type": "boolean",+ "default": false,+ "description": "Whether to create an API key for the project. If true, the API key will be created and returned in the response.",+ "example": false+ },+ "config": {+ "type": "object",+ "properties": {+ "is_2FA_enabled": {+ "type": "boolean"+ },+ "logo_url": {+ "type": "string"+ },+ "display_name": {+ "type": "string"+ },+ "mask_secret_keys_in_connected_account": {+ "type": "boolean"+ },+ "log_visibility_setting": {+ "type": "string",+ "enum": [+ "show_all",+ "dont_store_data"+ ]+ },+ "require_mcp_api_key": {+ "type": "boolean"+ },+ "is_composio_link_enabled_for_managed_auth": {+ "type": "boolean",+ "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."+ },+ "signed_url_file_expiry_in_seconds": {+ "type": "number",+ "minimum": 1,+ "maximum": 86400+ }+ },+ "required": [+ "is_2FA_enabled",+ "mask_secret_keys_in_connected_account",+ "log_visibility_setting"+ ],+ "description": "Configuration for the project"+ }+ },+ "required": [+ "name"+ ]+ },+ "examples": {+ "Simple project": {+ "value": {+ "name": "my_production_api"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Project successfully created. Returns the complete project object with generated IDs, webhook secrets, and configuration.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier for the project",+ "example": "proj_abc123xyz456"+ },+ "name": {+ "type": "string",+ "description": "Name of the project",+ "example": "My Awesome Project"+ },+ "api_key": {+ "type": "string",+ "nullable": true,+ "description": "API key for the project",+ "example": "ak_abc123xyz456"+ }+ },+ "required": [+ "id",+ "api_key"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if the project name format is invalid, too short, or contains invalid characters.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/org/owner/project/list": {+ "get": {+ "summary": "List all projects",+ "description": "Retrieves all projects belonging to the authenticated organization. Projects are returned in descending order of creation date (newest first). This endpoint is useful for displaying project selection in dashboards or for integrations that need to list all available projects.",+ "tags": [+ "Projects"+ ],+ "operationId": "getOrgOwnerProjectList",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Projects retrieved successfully with pagination. Returns an array of projects with pagination info.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier for the project",+ "example": "proj_abc123xyz456"+ },+ "org_id": {+ "type": "string",+ "format": "orgId",+ "description": "Identifier of the organization that owns this project",+ "example": "org_abc123xyz456"+ },+ "name": {+ "type": "string",+ "description": "Name of the project",+ "example": "My Awesome Project"+ },+ "email": {+ "type": "string",+ "description": "Email address associated with the project",+ "example": "[email protected]"+ },+ "created_at": {+ "type": "string",+ "description": "ISO timestamp when the project was created",+ "example": "2023-05-16T14:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO timestamp when the project was last updated",+ "example": "2023-05-18T09:15:30.000Z"+ },+ "webhook_url": {+ "type": "string",+ "nullable": true,+ "format": "uri",+ "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.",+ "example": "https://example.com/webhook",+ "deprecated": true+ },+ "event_webhook_url": {+ "type": "string",+ "nullable": true,+ "format": "uri",+ "description": "DEPRECATED: No longer used.",+ "example": "https://example.com/events",+ "deprecated": true+ },+ "webhook_secret": {+ "type": "string",+ "nullable": true,+ "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.",+ "example": "whsec_abcdef123456789",+ "deprecated": true+ },+ "triggers_enabled": {+ "type": "boolean",+ "description": "Whether triggers are enabled for this project",+ "example": true+ },+ "last_subscribed_at": {+ "type": "string",+ "nullable": true,+ "format": "date-time",+ "description": "ISO timestamp when the project last subscribed to updates",+ "example": "2023-05-17T10:00:00.000Z"+ },+ "is_new_webhook": {+ "type": "boolean",+ "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",+ "example": true,+ "deprecated": true+ },+ "webhook_version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.",+ "example": "V2"+ },+ "deleted": {+ "type": "boolean",+ "description": "Whether this project has been soft-deleted",+ "example": false+ }+ },+ "required": [+ "id",+ "org_id",+ "name",+ "email",+ "created_at",+ "updated_at",+ "webhook_url",+ "event_webhook_url",+ "webhook_secret",+ "webhook_version",+ "deleted"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "data",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if there are invalid query parameters or the request is malformed.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/org/owner/project/{nano_id}": {+ "get": {+ "summary": "Get project details by ID With Org Api key",+ "description": "Retrieves detailed information about a specific project using its unique identifier. This endpoint provides complete project configuration including webhook URLs, creation and update timestamps, and webhook secrets. Use this endpoint to inspect project settings or verify project configuration.",+ "tags": [+ "Projects"+ ],+ "operationId": "getOrgOwnerProjectByNanoId",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier (Nano ID) of the project to retrieve",+ "example": "proj_abc123xyz456"+ },+ "required": true,+ "description": "Unique identifier (Nano ID) of the project to retrieve",+ "name": "nano_id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Project retrieved successfully. Returns a complete project object with all configuration details and associated API keys.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier for the project",+ "example": "proj_abc123xyz456"+ },+ "org_id": {+ "type": "string",+ "format": "orgId",+ "description": "Identifier of the organization that owns this project",+ "example": "org_abc123xyz456"+ },+ "name": {+ "type": "string",+ "description": "Name of the project",+ "example": "My Awesome Project"+ },+ "email": {+ "type": "string",+ "description": "Email address associated with the project",+ "example": "[email protected]"+ },+ "created_at": {+ "type": "string",+ "description": "ISO timestamp when the project was created",+ "example": "2023-05-16T14:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO timestamp when the project was last updated",+ "example": "2023-05-18T09:15:30.000Z"+ },+ "webhook_url": {+ "type": "string",+ "nullable": true,+ "format": "uri",+ "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.",+ "example": "https://example.com/webhook",+ "deprecated": true+ },+ "event_webhook_url": {+ "type": "string",+ "nullable": true,+ "format": "uri",+ "description": "DEPRECATED: No longer used.",+ "example": "https://example.com/events",+ "deprecated": true+ },+ "webhook_secret": {+ "type": "string",+ "nullable": true,+ "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.",+ "example": "whsec_abcdef123456789",+ "deprecated": true+ },+ "triggers_enabled": {+ "type": "boolean",+ "description": "Whether triggers are enabled for this project",+ "example": true+ },+ "last_subscribed_at": {+ "type": "string",+ "nullable": true,+ "format": "date-time",+ "description": "ISO timestamp when the project last subscribed to updates",+ "example": "2023-05-17T10:00:00.000Z"+ },+ "is_new_webhook": {+ "type": "boolean",+ "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",+ "example": true,+ "deprecated": true+ },+ "webhook_version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.",+ "example": "V2"+ },+ "deleted": {+ "type": "boolean",+ "description": "Whether this project has been soft-deleted",+ "example": false+ },+ "api_keys": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Unique identifier for the API key",+ "example": "01H4DKRF5SMP7NQCA3BWT0JYB6"+ },+ "name": {+ "type": "string",+ "description": "User-defined name for the API key",+ "example": "Production Server Key"+ },+ "key": {+ "type": "string",+ "description": "The actual API key value used for authentication",+ "example": "ak_a1b2c3d4e5f6g7h8i9j0"+ },+ "created_at": {+ "type": "string",+ "format": "date-time",+ "description": "ISO 8601 timestamp when the API key was created",+ "example": "2023-07-15T14:30:00.000Z"+ }+ },+ "required": [+ "id",+ "name",+ "key",+ "created_at"+ ]+ },+ "description": "Array of API keys for the project, including their properties"+ }+ },+ "required": [+ "id",+ "org_id",+ "name",+ "email",+ "created_at",+ "updated_at",+ "webhook_url",+ "event_webhook_url",+ "webhook_secret",+ "webhook_version",+ "deleted",+ "api_keys"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if the project ID format is invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The specified project does not exist or you do not have access to it.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "delete": {+ "summary": "Delete a project",+ "description": "Soft-deletes a project within the organization by its unique identifier. When a project is deleted, it is marked as deleted but not immediately removed from the database. This operation affects all resources associated with the project including API keys, webhook configurations, and connected services. This action cannot be undone through the API.",+ "tags": [+ "Projects"+ ],+ "operationId": "deleteOrgOwnerProjectByNanoId",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier (Nano ID) of the project to delete",+ "example": "proj_abc123xyz456"+ },+ "required": true,+ "description": "Unique identifier (Nano ID) of the project to delete",+ "name": "nano_id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Project successfully deleted. The project has been marked as deleted in the system.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "success"+ ],+ "description": "Status indicating successful deletion",+ "example": "success"+ }+ },+ "required": [+ "status"+ ],+ "description": "Response indicating successful project deletion"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The project ID may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. You do not have permission to delete this project.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The specified project does not exist or has already been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/org/owner/project/{nano_id}/regenerate_api_key": {+ "post": {+ "summary": "Delete and generate new API key for project",+ "description": "Generates a new API key for the specified project, invalidating any existing API keys for that project. This operation creates a fresh API key with a new random name and key value. All existing API keys for this project will be marked as deleted.",+ "tags": [+ "Projects"+ ],+ "operationId": "postOrgOwnerProjectByNanoIdRegenerateApiKey",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier (Nano ID) of the project to regenerate API key for",+ "example": "proj_abc123xyz456"+ },+ "required": true,+ "description": "Unique identifier (Nano ID) of the project to regenerate API key for",+ "name": "nano_id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "API key regenerated successfully. Returns the new API key details.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "api_key": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Unique identifier for the API key",+ "example": "01H4DKRF5SMP7NQCA3BWT0JYB6"+ },+ "name": {+ "type": "string",+ "description": "Name of the API key",+ "example": "epic_avatar"+ },+ "key": {+ "type": "string",+ "description": "The newly generated API key value",+ "example": "ak_a1b2c3d4e5f6g7h8i9j0"+ },+ "created_at": {+ "type": "string",+ "description": "ISO timestamp when the API key was created",+ "example": "2023-05-16T14:30:00.000Z"+ }+ },+ "required": [+ "id",+ "name",+ "key",+ "created_at"+ ],+ "description": "The newly generated API key for this project"+ },+ "message": {+ "type": "string",+ "description": "Success message",+ "example": "API key regenerated successfully"+ }+ },+ "required": [+ "api_key",+ "message"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The project ID may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The specified project does not exist or you do not have access to it.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/webhook_subscriptions": {+ "post": {+ "summary": "Create webhook subscription",+ "description": "Creates a webhook subscription for the authenticated project. Only one subscription is allowed per project. The signing secret is returned only on creation.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "postWebhookSubscriptions",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "webhook_url": {+ "type": "string",+ "maxLength": 2048,+ "format": "uri",+ "description": "HTTPS URL to receive webhook events"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1,+ "description": "Array of event types to subscribe to"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "default": "V3",+ "description": "Webhook payload version"+ }+ },+ "required": [+ "webhook_url",+ "enabled_events"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Webhook subscription created",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Unique subscription ID"+ },+ "webhook_url": {+ "type": "string",+ "description": "Webhook destination URL"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Subscribed event types"+ },+ "secret": {+ "type": "string",+ "description": "Signing secret for HMAC verification"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ }+ },+ "required": [+ "id",+ "webhook_url",+ "version",+ "enabled_events",+ "secret",+ "created_at",+ "updated_at"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "Subscription already exists",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "get": {+ "summary": "List webhook subscriptions",+ "description": "Lists all webhook subscriptions for the authenticated project with pagination. Currently limited to one subscription per project.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "getWebhookSubscriptions",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Webhook subscriptions retrieved",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Unique subscription ID"+ },+ "webhook_url": {+ "type": "string",+ "description": "Webhook destination URL"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Subscribed event types"+ },+ "secret": {+ "type": "string",+ "description": "Masked signing secret (full secret only on create/rotate)"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ }+ },+ "required": [+ "id",+ "webhook_url",+ "version",+ "enabled_events",+ "secret",+ "created_at",+ "updated_at"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid pagination",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/webhook_subscriptions/{id}": {+ "get": {+ "summary": "Get webhook subscription",+ "description": "Retrieves a webhook subscription by ID.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "getWebhookSubscriptionsById",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Webhook subscription ID"+ },+ "required": true,+ "description": "Webhook subscription ID",+ "name": "id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Webhook subscription retrieved",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Unique subscription ID"+ },+ "webhook_url": {+ "type": "string",+ "description": "Webhook destination URL"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Subscribed event types"+ },+ "secret": {+ "type": "string",+ "description": "Masked signing secret (full secret only on create/rotate)"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ }+ },+ "required": [+ "id",+ "webhook_url",+ "version",+ "enabled_events",+ "secret",+ "created_at",+ "updated_at"+ ]+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Subscription not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "patch": {+ "summary": "Update webhook subscription",+ "description": "Updates a webhook subscription. At least one field must be provided.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "patchWebhookSubscriptionsById",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Webhook subscription ID"+ },+ "required": true,+ "description": "Webhook subscription ID",+ "name": "id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "webhook_url": {+ "type": "string",+ "maxLength": 2048,+ "format": "uri",+ "description": "HTTPS URL to receive webhook events"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1,+ "description": "Array of event types to subscribe to"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Webhook subscription updated",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Unique subscription ID"+ },+ "webhook_url": {+ "type": "string",+ "description": "Webhook destination URL"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Subscribed event types"+ },+ "secret": {+ "type": "string",+ "description": "Masked signing secret (full secret only on create/rotate)"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ }+ },+ "required": [+ "id",+ "webhook_url",+ "version",+ "enabled_events",+ "secret",+ "created_at",+ "updated_at"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Subscription not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "delete": {+ "summary": "Delete webhook subscription",+ "description": "Permanently deletes a webhook subscription. This action cannot be undone.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "deleteWebhookSubscriptionsById",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Webhook subscription ID"+ },+ "required": true,+ "description": "Webhook subscription ID",+ "name": "id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Webhook subscription deleted",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ }+ },+ "required": [+ "success"+ ]+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Subscription not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/webhook_subscriptions/{id}/rotate_secret": {+ "post": {+ "summary": "Rotate webhook secret",+ "description": "Generates a new signing secret for the webhook subscription. The new secret is returned only in this response.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "postWebhookSubscriptionsByIdRotateSecret",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Webhook subscription ID"+ },+ "required": true,+ "description": "Webhook subscription ID",+ "name": "id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Webhook secret rotated",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Subscription ID"+ },+ "secret": {+ "type": "string",+ "description": "New signing secret"+ }+ },+ "required": [+ "id",+ "secret"+ ]+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Subscription not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/webhook_subscriptions/event_types": {+ "get": {+ "summary": "List available event types",+ "description": "Returns all event types that can be subscribed to, along with their supported webhook versions.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "getWebhookSubscriptionsEventTypes",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Event types retrieved",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "event_type": {+ "type": "string",+ "description": "Event type identifier"+ },+ "description": {+ "type": "string",+ "description": "Human-readable description of the event"+ },+ "supported_versions": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ]+ },+ "description": "Webhook versions that support this event"+ }+ },+ "required": [+ "event_type",+ "description",+ "supported_versions"+ ]+ }+ }+ },+ "required": [+ "items"+ ]+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/toolkits": {+ "get": {+ "summary": "List available toolkits",+ "description": "Retrieves a comprehensive list of toolkits of their latest versions that are available to the authenticated project. Toolkits represent integration points with external services and applications, each containing a collection of tools and triggers. This endpoint supports filtering by category and management type, as well as different sorting options.",+ "tags": [+ "Toolkits"+ ],+ "operationId": "getToolkits",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Category ID or name to filter toolkits by",+ "example": "productivity"+ },+ "required": false,+ "description": "Filter toolkits by category",+ "name": "category",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "composio",+ "all",+ "project"+ ],+ "description": "Entity responsible for managing the toolkits"+ },+ "required": false,+ "description": "Filter toolkits by who manages them",+ "name": "managed_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "usage",+ "alphabetically"+ ],+ "description": "Determines how toolkits should be sorted in the response"+ },+ "required": false,+ "description": "Sort order for returned toolkits",+ "name": "sort_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "Include deprecated toolkits in the response",+ "example": true+ },+ "required": false,+ "description": "Include deprecated toolkits in the response",+ "name": "include_deprecated",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Search query to filter toolkits by name, slug, or description (minimum 3 characters)",+ "example": "gmail"+ },+ "required": false,+ "description": "Search query to filter toolkits by name, slug, or description",+ "name": "search",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Toolkits retrieved successfully. Returns a paginated list of available toolkits with detailed metadata.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "URL-friendly unique identifier for the toolkit",+ "example": "github"+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the toolkit",+ "example": "GitHub"+ },+ "auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods supported by this toolkit",+ "example": [+ "oauth2",+ "api_key"+ ]+ },+ "composio_managed_auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods that Composio manages for this toolkit",+ "example": [+ "oauth2"+ ]+ },+ "is_local_toolkit": {+ "type": "boolean",+ "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",+ "deprecated": true,+ "example": false+ },+ "no_auth": {+ "type": "boolean",+ "description": "When true, this toolkit can be used without authentication",+ "example": false+ },+ "auth_guide_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions for this toolkit",+ "example": "https://composio.dev/auth/github"+ },+ "deprecated": {+ "$ref": "#/components/schemas/DeprecatedToolkitInfo"+ },+ "meta": {+ "type": "object",+ "properties": {+ "created_at": {+ "type": "string",+ "description": "Creation date and time of the toolkit",+ "example": "2023-01-15T09:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Last modification date and time of the toolkit",+ "example": "2023-05-20T14:45:00.000Z"+ },+ "description": {+ "type": "string",+ "description": "Human-readable description explaining the toolkit's purpose and functionality",+ "example": "Integrate with GitHub repositories, issues, pull requests, and more."+ },+ "logo": {+ "type": "string",+ "description": "Image URL for the toolkit's branding",+ "example": "https://assets.composio.dev/logos/github.png"+ },+ "app_url": {+ "type": "string",+ "nullable": true,+ "description": "Link to the toolkit's main application or service website",+ "example": "https://github.com"+ },+ "categories": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Category identifier",+ "example": "developer-tools"+ },+ "name": {+ "type": "string",+ "description": "Human-readable category name",+ "example": "Developer Tools"+ }+ },+ "required": [+ "id",+ "name"+ ]+ },+ "description": "List of categories associated with this toolkit",+ "example": [+ {+ "id": "developer-tools",+ "name": "Developer Tools"+ },+ {+ "id": "productivity",+ "name": "Productivity"+ }+ ]+ },+ "triggers_count": {+ "type": "number",+ "description": "Count of available triggers in this toolkit",+ "example": 5+ },+ "tools_count": {+ "type": "number",+ "description": "Count of available tools in this toolkit",+ "example": 12+ },+ "version": {+ "type": "string",+ "description": "Version of the toolkit",+ "example": "20250905_00"+ }+ },+ "required": [+ "created_at",+ "updated_at",+ "description",+ "logo",+ "categories",+ "triggers_count",+ "tools_count",+ "version"+ ],+ "description": "Additional metadata about the toolkit"+ }+ },+ "required": [+ "slug",+ "name",+ "is_local_toolkit",+ "deprecated",+ "meta"+ ],+ "description": "Detailed information about a toolkit"+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The query parameters may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The toolkits you are looking for do not exist.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/toolkits/categories": {+ "get": {+ "summary": "List toolkit categories",+ "description": "Retrieves a comprehensive list of all available toolkit categories from their latest versions. These categories can be used to filter toolkits by type or purpose when using the toolkit listing endpoint. Categories help organize toolkits into logical groups based on their functionality or industry focus.",+ "tags": [+ "Toolkits"+ ],+ "operationId": "getToolkitsCategories",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved a paginated list of all available toolkit categories with their identifiers and display names.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Display name of the toolkit category",+ "example": "Developer Tools"+ },+ "id": {+ "type": "string",+ "description": "URL-friendly unique identifier for the category, used for filtering toolkits",+ "example": "developer-tools"+ }+ },+ "required": [+ "name",+ "id"+ ],+ "description": "Information about a single toolkit category"+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The request may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The requested resource was not found.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/toolkits/{slug}": {+ "get": {+ "summary": "Get toolkit by slug",+ "description": "Retrieves comprehensive information about a specific toolkit using its unique slug identifier. This endpoint provides detailed metadata, authentication configuration options, and feature counts for the requested toolkit.",+ "tags": [+ "Toolkits"+ ],+ "operationId": "getToolkitsBySlug",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "The unique slug identifier of the toolkit to retrieve",+ "example": "github"+ },+ "required": true,+ "description": "Toolkit slug identifier",+ "name": "slug",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "default": "latest",+ "description": "Version of the toolkit",+ "example": "20250905_00"+ },+ "required": false,+ "description": "Version of the toolkit",+ "name": "version",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved detailed information about the requested toolkit, including authentication options, metadata, and feature counts.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "URL-friendly unique identifier for the toolkit",+ "example": "github"+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the toolkit",+ "example": "GitHub"+ },+ "enabled": {+ "type": "boolean",+ "description": "Indicates if this toolkit is currently enabled and available for use",+ "example": true+ },+ "composio_managed_auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods that Composio manages for this toolkit",+ "example": [+ "oauth2"+ ]+ },+ "is_local_toolkit": {+ "type": "boolean",+ "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",+ "deprecated": true,+ "example": false+ },+ "auth_config_details": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "mode": {+ "type": "string",+ "description": "The type of authentication mode (e.g., oauth2, basic_auth, api_key)",+ "example": "oauth2"+ },+ "fields": {+ "type": "object",+ "properties": {+ "auth_config_creation": {+ "type": "object",+ "properties": {+ "required": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "default": {+ "type": "string",+ "nullable": true+ },+ "type": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "required": {+ "type": "boolean"+ },+ "legacy_template_name": {+ "type": "string"+ }+ },+ "required": [+ "name",+ "displayName",+ "type",+ "description",+ "required"+ ]+ }+ },+ "optional": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "default": {+ "type": "string",+ "nullable": true+ },+ "type": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "required": {+ "type": "boolean"+ },+ "legacy_template_name": {+ "type": "string"+ }+ },+ "required": [+ "name",+ "displayName",+ "type",+ "description",+ "required"+ ]+ }+ }+ },+ "required": [+ "required",+ "optional"+ ],+ "description": "Form fields needed when creating an authentication configuration"+ },+ "connected_account_initiation": {+ "type": "object",+ "properties": {+ "required": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "default": {+ "type": "string",+ "nullable": true+ },+ "type": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "required": {+ "type": "boolean"+ },+ "legacy_template_name": {+ "type": "string"+ }+ },+ "required": [+ "name",+ "displayName",+ "type",+ "description",+ "required"+ ]+ }+ },+ "optional": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "default": {+ "type": "string",+ "nullable": true+ },+ "type": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "required": {+ "type": "boolean"+ },+ "legacy_template_name": {+ "type": "string"+ }+ },+ "required": [+ "name",+ "displayName",+ "type",+ "description",+ "required"+ ]+ }+ }+ },+ "required": [+ "required",+ "optional"+ ],+ "description": "Form fields needed when connecting a user account with this authentication method"+ }+ },+ "required": [+ "auth_config_creation",+ "connected_account_initiation"+ ],+ "description": "Field groups required for different authentication stages"+ },+ "proxy": {+ "type": "object",+ "properties": {+ "base_url": {+ "type": "string",+ "description": "URL to which authentication requests will be proxied",+ "example": "https://auth.example.com/proxy"+ }+ },+ "required": [+ "base_url"+ ],+ "description": "Configuration for proxying authentication requests to external services"+ },+ "name": {+ "type": "string",+ "description": "Display name for this authentication method",+ "example": "OAuth 2.0"+ },+ "auth_hint_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a page where users can obtain or configure credentials for this authentication method",+ "example": "https://github.com/settings/tokens"+ },+ "deprecated_auth_provider_details": {+ "type": "object",+ "properties": {+ "authorization_url": {+ "type": "string"+ },+ "token_url": {+ "type": "string"+ }+ },+ "description": "Authentication URL fields for OAuth 2.0 and OAuth 1.0. We don't recommend using this field for authentication and might break post Aug 31 2025.",+ "deprecated": true+ }+ },+ "required": [+ "mode",+ "fields",+ "name"+ ],+ "description": "Detailed configuration for an authentication method"+ },+ "description": "Complete authentication configuration details for each supported auth method"+ },+ "auth_guide_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions for this toolkit",+ "example": "https://composio.dev/auth/github"+ },+ "base_url": {+ "type": "string",+ "description": "If evaluation of base URL needs some connection info (like shopify), please create the connection and get the base URL from there",+ "example": "https://api.github.com"+ },+ "meta": {+ "type": "object",+ "properties": {+ "created_at": {+ "type": "string",+ "description": "Creation date and time of the toolkit",+ "example": "2023-01-15T09:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Last modification date and time of the toolkit",+ "example": "2023-05-20T14:45:00.000Z"+ },+ "description": {+ "type": "string",+ "description": "Human-readable description explaining the toolkit's purpose and functionality",+ "example": "Integrate with GitHub repositories, issues, pull requests, and more."+ },+ "logo": {+ "type": "string",+ "description": "Image URL for the toolkit's branding",+ "example": "https://assets.composio.dev/logos/github.png"+ },+ "app_url": {+ "type": "string",+ "nullable": true,+ "description": "Link to the toolkit's main application or service website",+ "example": "https://github.com"+ },+ "categories": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Human-readable category name",+ "example": "Developer Tools"+ },+ "slug": {+ "type": "string",+ "description": "URL-friendly identifier for the category",+ "example": "developer-tools"+ }+ },+ "required": [+ "name",+ "slug"+ ]+ },+ "description": "List of categories associated with this toolkit",+ "example": [+ {+ "name": "Developer Tools",+ "slug": "developer-tools"+ },+ {+ "name": "Productivity",+ "slug": "productivity"+ }+ ]+ },+ "triggers_count": {+ "type": "number",+ "description": "Count of available triggers in this toolkit",+ "example": 5+ },+ "tools_count": {+ "type": "number",+ "description": "Count of available tools in this toolkit",+ "example": 12+ },+ "version": {+ "type": "string",+ "description": "Version of the toolkit",+ "example": "20250905_00"+ },+ "available_versions": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Available versions of the toolkit",+ "example": [+ "20250905_00",+ "20250906_00"+ ]+ }+ },+ "required": [+ "created_at",+ "updated_at",+ "description",+ "logo",+ "categories",+ "triggers_count",+ "tools_count",+ "version",+ "available_versions"+ ],+ "description": "Comprehensive metadata for the toolkit including dates, descriptions, and statistics"+ },+ "get_current_user_endpoint": {+ "type": "string",+ "description": "Endpoint to get the current user"+ },+ "get_current_user_endpoint_method": {+ "type": "string",+ "description": "HTTP method to use when calling the get current user endpoint (e.g., GET, POST)",+ "example": "GET"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "toolkitId": {+ "type": "string"+ },+ "getCurrentUserEndpoint": {+ "type": "string"+ },+ "rawProxyInfoByAuthSchemes": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": {}+ }+ }+ },+ "required": [+ "toolkitId",+ "rawProxyInfoByAuthSchemes"+ ]+ }+ },+ "required": [+ "slug",+ "name",+ "enabled",+ "is_local_toolkit",+ "meta",+ "deprecated"+ ],+ "description": "Detailed information about a single toolkit"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The toolkit slug may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The requested toolkit does not exist or is not accessible to the authenticated project.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpect ed error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tools": {+ "get": {+ "summary": "List available tools",+ "description": "Retrieve a paginated list of available tools with comprehensive filtering, sorting and search capabilities. Use query parameters to narrow down results by toolkit, tags, or search terms.",+ "tags": [+ "Tools"+ ],+ "operationId": "getTools",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "The slug of the toolkit to filter by",+ "in": "query",+ "name": "toolkit_slug"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Comma-separated list of specific tool slugs to retrieve (overrides other filters)",+ "in": "query",+ "name": "tool_slugs"+ },+ {+ "schema": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "required": false,+ "description": "Comma-separated list of auth config IDs to filter tools by",+ "in": "query",+ "name": "auth_config_ids"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "true",+ "false"+ ]+ },+ "required": false,+ "description": "Filter to only show important/featured tools (set to \"true\" to enable)",+ "in": "query",+ "name": "important"+ },+ {+ "schema": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "required": false,+ "description": "Filter tools by one or more tags (can be specified multiple times)",+ "in": "query",+ "name": "tags"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Filter tools by one or more scopes (can be specified multiple times)"+ },+ "required": false,+ "description": "Array of scopes to filter tools by)",+ "name": "scopes",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Full-text search query to filter tools by name, slug, or description. Applied as a soft filter on top of other filters.",+ "in": "query",+ "name": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Deprecated: use \"query\" instead. Free-text search query to find tools by name, description, or functionality.",+ "in": "query",+ "name": "search",+ "deprecated": true+ },+ {+ "schema": {+ "type": "boolean",+ "default": true+ },+ "required": false,+ "description": "Include deprecated tools in the response",+ "in": "query",+ "name": "include_deprecated"+ },+ {+ "schema": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object representation of parsed bracket notation"+ }+ ]+ },+ "required": false,+ "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",+ "in": "query",+ "name": "toolkit_versions",+ "examples": {+ "latest_version": {+ "summary": "Latest version for all toolkits",+ "value": "latest"+ },+ "bracket_notation": {+ "summary": "Specific versions using bracket notation",+ "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"+ },+ "null_value": {+ "summary": "No version specified (uses 00000000_00)",+ "value": null+ }+ }+ },+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved tools list with pagination information",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ToolsPaginated"+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid query parameters",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - User does not have permission to access tools",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - The requested resource was not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Too many requests - Rate limit exceeded",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tools/enum": {+ "get": {+ "summary": "Get tool enum list",+ "description": "Retrieve a list of all available tool enumeration values (tool slugs) from latest version of each toolkit. This endpoint returns a comma-separated string of tool slugs that can be used in other API calls.",+ "tags": [+ "Tools"+ ],+ "operationId": "getToolsEnum",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved tool enum list",+ "content": {+ "application/json": {+ "schema": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "JSON string containing all tool enum values from latest version of each toolkit"+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid request parameters",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - User does not have permission to access tool enums",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Tool enum list not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tools/{tool_slug}": {+ "get": {+ "summary": "Get tool by slug",+ "description": "Retrieve detailed information about a specific tool using its slug identifier. This endpoint returns full metadata about a tool including input/output parameters, versions, and toolkit information.",+ "tags": [+ "Tools"+ ],+ "operationId": "getToolsByToolSlug",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string"+ },+ "required": true,+ "description": "The unique slug identifier of the tool",+ "name": "tool_slug",+ "in": "path"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Optional version of the tool to retrieve",+ "name": "version",+ "in": "query"+ },+ {+ "schema": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object representation of parsed bracket notation"+ }+ ]+ },+ "required": false,+ "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",+ "in": "query",+ "name": "toolkit_versions",+ "examples": {+ "latest_version": {+ "summary": "Latest version for all toolkits",+ "value": "latest"+ },+ "bracket_notation": {+ "summary": "Specific versions using bracket notation",+ "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"+ },+ "null_value": {+ "summary": "No version specified (uses 00000000_00)",+ "value": null+ }+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved tool details",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Tool"+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid tool slug format",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Tool with the specified slug does not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/toolkits/multi": {+ "post": {+ "summary": "Fetch multiple toolkits",+ "description": "Retrieves a comprehensive list of toolkits of their latest versions that are available to the authenticated project. Toolkits represent integration points with external services and applications, each containing a collection of tools and triggers. This endpoint supports filtering by category and management type, as well as different sorting options. You can optionally specify a list of toolkit slugs to fetch specific toolkits.",+ "tags": [+ "Toolkits"+ ],+ "operationId": "postToolkitsMulti",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of toolkit slug identifiers to retrieve",+ "example": [+ "github",+ "slack",+ "gmail"+ ]+ },+ "category": {+ "type": "string",+ "description": "Category ID or name to filter toolkits by",+ "example": "productivity"+ },+ "managed_by": {+ "type": "string",+ "enum": [+ "composio",+ "all",+ "project"+ ],+ "description": "Entity responsible for managing the toolkits"+ },+ "sort_by": {+ "type": "string",+ "enum": [+ "usage",+ "alphabetically"+ ],+ "description": "Determines how toolkits should be sorted in the response"+ },+ "limit": {+ "type": "number",+ "nullable": true+ },+ "cursor": {+ "type": "string"+ }+ },+ "description": "Body parameters for filtering and sorting toolkits"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Toolkits retrieved successfully. Returns a paginated list of available toolkits with detailed metadata.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "URL-friendly unique identifier for the toolkit",+ "example": "github"+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the toolkit",+ "example": "GitHub"+ },+ "auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods supported by this toolkit",+ "example": [+ "oauth2",+ "api_key"+ ]+ },+ "composio_managed_auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods that Composio manages for this toolkit",+ "example": [+ "oauth2"+ ]+ },+ "is_local_toolkit": {+ "type": "boolean",+ "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",+ "deprecated": true,+ "example": false+ },+ "no_auth": {+ "type": "boolean",+ "description": "When true, this toolkit can be used without authentication",+ "example": false+ },+ "auth_guide_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions for this toolkit",+ "example": "https://composio.dev/auth/github"+ },+ "deprecated": {+ "$ref": "#/components/schemas/DeprecatedToolkitInfo"+ },+ "meta": {+ "type": "object",+ "properties": {+ "created_at": {+ "type": "string",+ "description": "Creation date and time of the toolkit",+ "example": "2023-01-15T09:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Last modification date and time of the toolkit",+ "example": "2023-05-20T14:45:00.000Z"+ },+ "description": {+ "type": "string",+ "description": "Human-readable description explaining the toolkit's purpose and functionality",+ "example": "Integrate with GitHub repositories, issues, pull requests, and more."+ },+ "logo": {+ "type": "string",+ "description": "Image URL for the toolkit's branding",+ "example": "https://assets.composio.dev/logos/github.png"+ },+ "app_url": {+ "type": "string",+ "nullable": true,+ "description": "Link to the toolkit's main application or service website",+ "example": "https://github.com"+ },+ "categories": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Category identifier",+ "example": "developer-tools"+ },+ "name": {+ "type": "string",+ "description": "Human-readable category name",+ "example": "Developer Tools"+ }+ },+ "required": [+ "id",+ "name"+ ]+ },+ "description": "List of categories associated with this toolkit",+ "example": [+ {+ "id": "developer-tools",+ "name": "Developer Tools"+ },+ {+ "id": "productivity",+ "name": "Productivity"+ }+ ]+ },+ "triggers_count": {+ "type": "number",+ "description": "Count of available triggers in this toolkit",+ "example": 5+ },+ "tools_count": {+ "type": "number",+ "description": "Count of available tools in this toolkit",+ "example": 12+ },+ "version": {+ "type": "string",+ "description": "Version of the toolkit",+ "example": "20250905_00"+ }+ },+ "required": [+ "created_at",+ "updated_at",+ "description",+ "logo",+ "categories",+ "triggers_count",+ "tools_count",+ "version"+ ],+ "description": "Additional metadata about the toolkit"+ }+ },+ "required": [+ "slug",+ "name",+ "is_local_toolkit",+ "deprecated",+ "meta"+ ],+ "description": "Detailed information about a toolkit"+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The query parameters may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The toolkits you are looking for do not exist.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tools/execute/{tool_slug}": {+ "post": {+ "summary": "Execute tool",+ "description": "Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.",+ "tags": [+ "Tools"+ ],+ "operationId": "postToolsExecuteByToolSlug",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string"+ },+ "required": true,+ "description": "The tool slug to execute",+ "name": "tool_slug",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "description": "JSON object containing custom headers to pass to LLM providers (OpenAI, Bedrock, etc.)",+ "example": "{\"x-custom-header\": \"value\", \"authorization\": \"Bearer token\"}"+ },+ "required": false,+ "name": "x-llm-gateway-headers",+ "in": "header"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "connected_account_id": {+ "type": "string",+ "description": "Unique identifier for the connected account to use for authentication",+ "example": "ca_1a2b3c4d5e6f"+ },+ "entity_id": {+ "type": "string",+ "description": "Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations)",+ "example": "repo-123",+ "deprecated": true+ },+ "user_id": {+ "type": "string",+ "description": "User id for multi-user connected accounts (e.g. multiple users, organizations)",+ "example": "user-123"+ },+ "version": {+ "type": "string",+ "description": "Tool version to execute (defaults to \"00000000_00\" if not specified)",+ "example": "latest"+ },+ "custom_auth_params": {+ "type": "object",+ "properties": {+ "base_url": {+ "type": "string",+ "description": "The base URL (root address) what you should use while making http requests to the connected account. For example, for gmail, it would be 'https://gmail.googleapis.com'"+ },+ "parameters": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "The name of the parameter. For example, 'x-api-key', 'Content-Type', etc."+ },+ "in": {+ "type": "string",+ "enum": [+ "query",+ "header"+ ],+ "description": "The location of the parameter. Can be 'query' or 'header'."+ },+ "value": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "number"+ }+ ],+ "description": "The value of the parameter. For example, '1234567890', 'application/json', etc."+ }+ },+ "required": [+ "name",+ "in",+ "value"+ ]+ }+ },+ "body": {+ "type": "object",+ "additionalProperties": {},+ "description": "The body to be sent to the endpoint for authentication. This is a JSON object. Note: This is very rarely needed and is only required by very few apps."+ }+ },+ "description": "Custom authentication parameters for tools that support parameterized authentication",+ "example": {+ "base_url": "https://api.example.com",+ "parameters": [+ {+ "name": "x-api-key",+ "value": "secret-key",+ "in": "header"+ }+ ]+ }+ },+ "custom_connection_data": {+ "description": "Custom connection data for tools that support custom connection data",+ "example": {+ "authScheme": "OAUTH2",+ "toolkitSlug": "github",+ "val": {+ "access_token": "secret-token"+ }+ },+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "DCR_OAUTH",+ "API_KEY",+ "BASIC_WITH_JWT",+ "BASIC",+ "BEARER_TOKEN",+ "OAUTH1",+ "NO_AUTH",+ "SERVICE_ACCOUNT",+ "GOOGLE_SERVICE_ACCOUNT",+ "S2S_OAUTH2"+ ]+ },+ "toolkitSlug": {+ "type": "string"+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "state_prefix": {+ "type": "string",+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"+ },+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"+ },+ "access_token": {+ "type": "string"+ },+ "id_token": {+ "type": "string"+ },+ "token_type": {+ "type": "string"+ },+ "refresh_token": {+ "type": "string",+ "nullable": true+ },+ "expires_in": {+ "anyOf": [+ {+ "type": "number"+ },+ {+ "type": "string"+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "scope": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "webhook_signature": {+ "type": "string"+ },+ "authed_user": {+ "type": "object",+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {+ "type": "string"+ }+ },+ "description": "for slack user scopes"+ },+ "client_id": {+ "type": "string",+ "description": "Dynamically registered client ID"+ },+ "client_secret": {+ "type": "string",+ "description": "Dynamically registered client secret"+ },+ "client_id_issued_at": {+ "type": "number"+ },+ "client_secret_expires_at": {+ "type": "number"+ },+ "generic_api_key": {+ "type": "string"+ },+ "api_key": {+ "type": "string"+ },+ "bearer_token": {+ "type": "string"+ },+ "basic_encoded": {+ "type": "string"+ },+ "username": {+ "type": "string"+ },+ "password": {+ "type": "string"+ },+ "token": {+ "type": "string"+ },+ "oauth_token": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "expires_at": {+ "type": "string"+ }+ },+ "required": [+ "access_token"+ ],+ "additionalProperties": {}+ }+ },+ "required": [+ "authScheme",+ "toolkitSlug",+ "val"+ ],+ "additionalProperties": true+ },+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "description": "Key-value pairs of arguments required by the tool (mutually exclusive with text)",+ "example": {+ "repository": "octocat/Hello-World",+ "workflow_id": "main.yml",+ "ref": "main",+ "inputs": {+ "environment": "production"+ }+ }+ },+ "text": {+ "type": "string",+ "description": "Natural language description of the task to perform (mutually exclusive with arguments)",+ "example": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment"+ },+ "allow_tracing": {+ "type": "boolean",+ "nullable": true,+ "description": "Deprecated. Enable debug tracing for tool execution (useful for debugging)",+ "deprecated": true,+ "example": false+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed action and received response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "Tool execution output data that varies based on the specific tool",+ "example": {+ "run_id": 12345678,+ "status": "queued",+ "created_at": "2023-01-01T12:00:00Z",+ "html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"+ }+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the tool execution was not successful (null if successful)"+ },+ "successful": {+ "type": "boolean",+ "description": "Indicates if the tool execution was successful",+ "example": true+ },+ "session_info": {+ "nullable": true,+ "description": "Optional session information for tools that return session context",+ "example": {+ "session_id": "session-12345",+ "expires_at": "2023-01-01T13:00:00Z"+ },+ "type": "object"+ },+ "log_id": {+ "type": "string",+ "description": "Unique identifier for the execution log (useful for debugging and support)",+ "example": "log_abc123def456"+ }+ },+ "required": [+ "data",+ "error",+ "successful"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid request parameters, missing required arguments, or conflicting parameters",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Tool or connected account not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "408": {+ "description": "Request timeout - Tool execution exceeded the maximum allowed time",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "410": {+ "description": "Gone - Tool has been deprecated and is no longer available",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large - Request or response payload exceeds size limits",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity - Invalid state of the connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Rate limit exceeded - Too many requests to the tool or underlying API",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "502": {+ "description": "Bad gateway - Error communicating with the tool provider API",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "503": {+ "description": "Upstream service unavailable - Tool provider API is currently down or unavailable",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tools/execute/{tool_slug}/input": {+ "post": {+ "summary": "Generate tool inputs from natural language",+ "description": "Uses AI to translate a natural language description into structured arguments for a specific tool. This endpoint is useful when you want to let users describe what they want to do in plain language instead of providing structured parameters.",+ "tags": [+ "Tools"+ ],+ "operationId": "postToolsExecuteByToolSlugInput",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string"+ },+ "required": true,+ "description": "The tool slug to generate inputs for",+ "name": "tool_slug",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "text": {+ "type": "string",+ "description": "Natural language description of what you want to accomplish with this tool",+ "example": "I need to trigger the main workflow in the octocat/Hello-World repository to deploy to production"+ },+ "custom_description": {+ "type": "string",+ "description": "Custom description of the tool to help guide the LLM in generating more accurate inputs",+ "example": "This tool triggers GitHub Actions workflows in a repository. It requires the repository name, workflow ID, and optional input parameters."+ },+ "system_prompt": {+ "type": "string",+ "description": "System prompt to control and guide the behavior of the LLM when generating inputs",+ "example": "You are an expert assistant that generates precise GitHub Actions workflow parameters. Extract exact repository names, workflow IDs, and input values from user descriptions."+ },+ "version": {+ "type": "string",+ "description": "Tool version to use when generating inputs (defaults to \"latest\" if not specified)",+ "example": "latest"+ }+ },+ "required": [+ "text"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully generated structured inputs for the action based on natural language description",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "description": "Key-value pairs of arguments required by the tool to accomplish the described task",+ "example": {+ "repository": "octocat/Hello-World",+ "workflow_id": "main.yml",+ "ref": "main",+ "inputs": {+ "environment": "production"+ }+ }+ },+ "error": {+ "type": "string",+ "description": "Error message if the arguments could not be generated (null if successful)",+ "example": "Unable to determine the repository name from the provided description"+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid input parameters or insufficient description to generate tool arguments",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - The specified tool does not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity - Invalid state of the connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Too many requests - Rate limit exceeded for natural language processing",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - AI processing failed or other server error occurred",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tools/execute/proxy": {+ "post": {+ "summary": "Execute proxy request",+ "description": "Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.",+ "tags": [+ "Tools"+ ],+ "operationId": "postToolsExecuteProxy",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "connected_account_id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The ID of the connected account to use for authentication (if not provided, will use the default account for the project)",+ "example": "ca_1a2b3c4d5e6f"+ },+ "endpoint": {+ "type": "string",+ "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",+ "example": "/api/v1/resources"+ },+ "method": {+ "type": "string",+ "enum": [+ "GET",+ "POST",+ "PUT",+ "DELETE",+ "PATCH",+ "HEAD"+ ],+ "description": "The HTTP method to use for the request",+ "example": "GET"+ },+ "body": {+ "nullable": true,+ "description": "The request body (for POST, PUT, and PATCH requests)",+ "example": {+ "name": "New Resource",+ "description": "This is a new resource"+ },+ "type": "object"+ },+ "binary_body": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "URL to fetch binary content from"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"+ }+ },+ "required": [+ "url"+ ]+ },+ {+ "type": "object",+ "properties": {+ "base64": {+ "type": "string",+ "minLength": 1,+ "description": "Base64-encoded binary data"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"+ }+ },+ "required": [+ "base64"+ ]+ }+ ],+ "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."+ },+ "parameters": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Parameter name",+ "example": "x-api-key"+ },+ "value": {+ "type": "string",+ "description": "Parameter value",+ "example": "abc123def456"+ },+ "type": {+ "type": "string",+ "enum": [+ "header",+ "query"+ ],+ "description": "Parameter type (header or query)",+ "example": "header"+ }+ },+ "required": [+ "name",+ "value",+ "type"+ ]+ },+ "description": "Additional HTTP headers or query parameters to include in the request",+ "example": [+ {+ "name": "x-api-key",+ "value": "abc123def456",+ "type": "header"+ },+ {+ "name": "filter",+ "value": "active",+ "type": "query"+ }+ ]+ },+ "custom_connection_data": {+ "deprecated": true,+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "DCR_OAUTH",+ "API_KEY",+ "BASIC_WITH_JWT",+ "BASIC",+ "BEARER_TOKEN",+ "OAUTH1",+ "NO_AUTH",+ "SERVICE_ACCOUNT",+ "GOOGLE_SERVICE_ACCOUNT",+ "S2S_OAUTH2"+ ]+ },+ "toolkitSlug": {+ "type": "string"+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "state_prefix": {+ "type": "string",+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"+ },+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"+ },+ "access_token": {+ "type": "string"+ },+ "id_token": {+ "type": "string"+ },+ "token_type": {+ "type": "string"+ },+ "refresh_token": {+ "type": "string",+ "nullable": true+ },+ "expires_in": {+ "anyOf": [+ {+ "type": "number"+ },+ {+ "type": "string"+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "scope": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "webhook_signature": {+ "type": "string"+ },+ "authed_user": {+ "type": "object",+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {+ "type": "string"+ }+ },+ "description": "for slack user scopes"+ },+ "client_id": {+ "type": "string",+ "description": "Dynamically registered client ID"+ },+ "client_secret": {+ "type": "string",+ "description": "Dynamically registered client secret"+ },+ "client_id_issued_at": {+ "type": "number"+ },+ "client_secret_expires_at": {+ "type": "number"+ },+ "generic_api_key": {+ "type": "string"+ },+ "api_key": {+ "type": "string"+ },+ "bearer_token": {+ "type": "string"+ },+ "basic_encoded": {+ "type": "string"+ },+ "username": {+ "type": "string"+ },+ "password": {+ "type": "string"+ },+ "token": {+ "type": "string"+ },+ "oauth_token": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "expires_at": {+ "type": "string"+ }+ },+ "required": [+ "access_token"+ ],+ "additionalProperties": {}+ }+ },+ "required": [+ "authScheme",+ "toolkitSlug",+ "val"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "endpoint",+ "method"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed proxy request and received response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "nullable": true,+ "description": "The response data returned from the proxied API",+ "example": {+ "id": "123",+ "name": "Resource Name",+ "created_at": "2023-01-01T00:00:00Z"+ },+ "type": "object"+ },+ "binary_data": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "description": "URL to download binary content"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type of the binary data"+ },+ "size": {+ "type": "number",+ "description": "File size in bytes"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the URL expires"+ }+ },+ "required": [+ "url",+ "content_type",+ "size"+ ],+ "description": "Binary body response data. Present when the response is a binary file."+ },+ "status": {+ "type": "number",+ "description": "The HTTP status code returned from the proxied API",+ "example": 200+ },+ "headers": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "The HTTP headers returned from the proxied API",+ "example": {+ "content-type": "application/json",+ "cache-control": "no-cache",+ "host": "api.example.com"+ }+ }+ },+ "required": [+ "status"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid request parameters or body format",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Connected account does not have permission to access the requested resource",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Resource not found or connected account not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity - Invalid state of the connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Too many requests - Rate limit exceeded on the connected account or proxy service",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "502": {+ "description": "Bad gateway - Error communicating with the upstream API",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "504": {+ "description": "Gateway timeout - Upstream API timed out",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/trigger_instances/{slug}/upsert": {+ "post": {+ "summary": "Create or update a trigger",+ "description": "Creates a new trigger instance or updates an existing one with the same configuration. Triggers listen for events from external services (webhooks or polling) and can invoke your workflows. If a matching trigger already exists and is disabled, it will be re-enabled. Requires a connected account ID to associate the trigger with a specific user connection.",+ "tags": [+ "Triggers"+ ],+ "operationId": "postTriggerInstancesBySlugUpsert",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase)."+ },+ "required": true,+ "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).",+ "name": "slug",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "connectedAuthId": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.",+ "deprecated": true+ },+ "triggerConfig": {+ "type": "object",+ "additionalProperties": {},+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.",+ "deprecated": true+ },+ "connected_account_id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "Connected account nanoid"+ },+ "trigger_config": {+ "type": "object",+ "additionalProperties": {},+ "description": "Trigger configuration"+ },+ "version": {+ "type": "string",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.",+ "deprecated": true,+ "example": "latest"+ },+ "toolkit_versions": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ],+ "description": "Toolkit version specification. Supports \"latest\" string or a record mapping toolkit slugs to specific versions.",+ "example": "latest"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully upserted trigger instance",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "trigger_id": {+ "type": "string",+ "description": "ID of the updated trigger"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "description": "ID of the updated trigger"+ }+ },+ "required": [+ "uuid"+ ]+ }+ },+ "required": [+ "trigger_id",+ "deprecated"+ ]+ }+ }+ }+ },+ "201": {+ "description": "Successfully created trigger instance",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "trigger_id": {+ "type": "string",+ "description": "ID of the updated trigger"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "description": "ID of the updated trigger"+ }+ },+ "required": [+ "uuid"+ ]+ }+ },+ "required": [+ "trigger_id",+ "deprecated"+ ]+ }+ }+ }+ },+ "204": {+ "description": "No content",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Trigger instance not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "408": {+ "description": "Request timeout",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "Conflict",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "410": {+ "description": "Gone",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/trigger_instances/active": {+ "get": {+ "summary": "List active triggers",+ "description": "Retrieves all active trigger instances for your project. Triggers listen for events from connected accounts (e.g., new emails, Slack messages, GitHub commits) and can invoke webhooks or workflows. Use filters to find triggers for specific users, connected accounts, or trigger types.",+ "tags": [+ "Triggers"+ ],+ "operationId": "getTriggerInstancesActive",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Array of user IDs to filter triggers by"+ },+ "required": false,+ "description": "Array of user IDs to filter triggers by",+ "name": "user_ids",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "description": "Array of connected account IDs to filter triggers by"+ },+ "required": false,+ "description": "Array of connected account IDs to filter triggers by",+ "name": "connected_account_ids",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "authConfigId"+ },+ "description": "Array of auth config IDs to filter triggers by"+ },+ "required": false,+ "description": "Array of auth config IDs to filter triggers by",+ "name": "auth_config_ids",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "triggerInstanceId"+ },+ "description": "Array of trigger IDs to filter triggers by"+ },+ "required": false,+ "description": "Array of trigger IDs to filter triggers by",+ "name": "trigger_ids",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Array of trigger names to filter triggers by. Case-insensitive (internally normalized to uppercase)."+ },+ "required": false,+ "description": "Array of trigger names to filter triggers by. Case-insensitive (internally normalized to uppercase).",+ "name": "trigger_names",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "connectedAccountId"+ }+ },+ "required": false,+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_ids instead.",+ "deprecated": true,+ "name": "connectedAccountIds",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "authConfigId"+ }+ },+ "required": false,+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use auth_config_ids instead.",+ "deprecated": true,+ "name": "authConfigIds",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "triggerInstanceId"+ }+ },+ "required": false,+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_ids instead.",+ "deprecated": true,+ "name": "triggerIds",+ "in": "query"+ },+ {+ "schema": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "When set to true, includes disabled triggers in the response."+ },+ "required": false,+ "description": "When set to true, includes disabled triggers in the response.",+ "name": "show_disabled",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ }+ },+ "required": false,+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_names instead.",+ "deprecated": true,+ "name": "triggerNames",+ "in": "query"+ },+ {+ "schema": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "DEPRECATED: Use show_disabled instead"+ },+ "required": false,+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use show_disabled instead.",+ "deprecated": true,+ "name": "showDisabled",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Array of connected account UUIDs to filter triggers by"+ },+ "required": false,+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_ids instead.",+ "deprecated": true,+ "name": "deprecatedConnectedAccountUuids",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Array of auth config UUIDs to filter triggers by"+ },+ "required": false,+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use auth_config_ids instead.",+ "deprecated": true,+ "name": "deprecatedAuthConfigUuids",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved active trigger instances",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "description": "Unique identifier of the trigger instance"+ },+ "id": {+ "type": "string",+ "format": "triggerInstanceId",+ "description": "Nano ID of the trigger instance"+ },+ "connected_account_id": {+ "type": "string",+ "description": "ID of the connected account this trigger is associated with"+ },+ "trigger_name": {+ "type": "string",+ "description": "Name of the trigger"+ },+ "connected_account_uuid": {+ "type": "string",+ "description": "UUID of the connected account this trigger is associated with"+ },+ "user_id": {+ "type": "string",+ "description": "ID of the user this trigger is associated with"+ },+ "trigger_data": {+ "type": "string",+ "description": "Additional data associated with the trigger instance"+ },+ "version": {+ "type": "string",+ "description": "Version of the trigger instance"+ },+ "trigger_config": {+ "type": "object",+ "additionalProperties": {},+ "description": "Configuration for the trigger"+ },+ "state": {+ "type": "object",+ "additionalProperties": {},+ "description": "DEPRECATED: This field exposes internal state and will be removed in a future version.",+ "deprecated": true+ },+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the trigger instance was updated"+ },+ "disabled_at": {+ "type": "string",+ "nullable": true,+ "description": "ISO 8601 timestamp when the trigger instance was disabled, if applicable"+ },+ "disabledAt": {+ "type": "string",+ "nullable": true,+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use disabled_at instead.",+ "deprecated": true+ },+ "connectedAccountId": {+ "type": "string",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.",+ "deprecated": true+ },+ "triggerName": {+ "type": "string",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_name instead.",+ "deprecated": true+ },+ "updatedAt": {+ "type": "string",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use updated_at instead.",+ "deprecated": true+ },+ "triggerConfig": {+ "type": "object",+ "additionalProperties": {},+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.",+ "deprecated": true+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "createdAt": {+ "type": "string",+ "description": "Deprecated created_at for the trigger instance"+ }+ },+ "required": [+ "createdAt"+ ],+ "description": "Deprecated fields for the trigger instance"+ }+ },+ "required": [+ "id",+ "connected_account_id",+ "trigger_name",+ "connected_account_uuid",+ "user_id",+ "version",+ "trigger_config",+ "state",+ "updated_at",+ "disabled_at",+ "disabledAt",+ "connectedAccountId",+ "triggerName",+ "updatedAt",+ "triggerConfig"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/trigger_instances/manage/{triggerId}": {+ "delete": {+ "summary": "Delete a trigger",+ "description": "Permanently deletes a trigger instance. This stops the trigger from listening for events and removes it from your project. Use the PATCH endpoint with status \"disable\" if you want to temporarily pause a trigger instead.",+ "tags": [+ "Triggers"+ ],+ "operationId": "deleteTriggerInstancesManageByTriggerId",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "triggerInstanceId",+ "description": "The ID of the trigger instance to delete"+ },+ "required": true,+ "description": "The ID of the trigger instance to delete",+ "name": "triggerId",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully deleted the trigger instance",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "trigger_id": {+ "type": "string",+ "format": "triggerInstanceId",+ "description": "The ID of the deleted trigger instance"+ }+ },+ "required": [+ "trigger_id"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Trigger instance not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "Trigger instance already deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "410": {+ "description": "Trigger instance already gone",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "patch": {+ "summary": "Enable or disable a trigger",+ "description": "Updates the status of a trigger instance to enable or disable it. Disabling a trigger pauses event listening without deleting the trigger configuration. Re-enabling restores the trigger to its active state. Use this for temporary maintenance or to control trigger execution.",+ "tags": [+ "Triggers"+ ],+ "operationId": "patchTriggerInstancesManageByTriggerId",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "triggerInstanceId",+ "description": "The ID of the trigger instance to update"+ },+ "required": true,+ "description": "The ID of the trigger instance to update",+ "name": "triggerId",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "enable",+ "disable"+ ]+ }+ },+ "required": [+ "status"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully updated trigger status",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "success"+ ],+ "description": "Status of the operation"+ }+ },+ "required": [+ "status"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad Request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Trigger instance not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "Trigger instance already enabled/disabled",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "410": {+ "description": "Trigger instance already gone",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal Server Error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/triggers_types/list/enum": {+ "get": {+ "summary": "List trigger type enums",+ "description": "Retrieves a list of all available trigger type enum values that can be used across the API from latest versions of the toolkit only",+ "tags": [+ "Triggers"+ ],+ "operationId": "getTriggersTypesListEnum",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved trigger enum list",+ "content": {+ "application/json": {+ "schema": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "JSON string containing all trigger enum values"+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/triggers_types/{slug}": {+ "get": {+ "summary": "Get trigger type by slug",+ "description": "Retrieve detailed information about a specific trigger type using its slug identifier",+ "tags": [+ "Triggers"+ ],+ "operationId": "getTriggersTypesBySlug",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "The unique slug identifier for the trigger type. Case-insensitive (internally normalized to uppercase).",+ "example": "SLACK_RECEIVE_MESSAGE"+ },+ "required": true,+ "description": "The unique slug identifier for the trigger type. Case-insensitive (internally normalized to uppercase).",+ "name": "slug",+ "in": "path"+ },+ {+ "schema": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object representation of parsed bracket notation"+ }+ ]+ },+ "required": false,+ "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",+ "in": "query",+ "name": "toolkit_versions",+ "examples": {+ "latest_version": {+ "summary": "Latest version for all toolkits",+ "value": "latest"+ },+ "bracket_notation": {+ "summary": "Specific versions using bracket notation",+ "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"+ },+ "null_value": {+ "summary": "No version specified (uses latest)",+ "value": null+ }+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved trigger type",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Unique identifier for the trigger type",+ "example": "SLACK_RECEIVE_MESSAGE"+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the trigger",+ "example": "New Message in Slack Channel"+ },+ "description": {+ "type": "string",+ "description": "Detailed description of what the trigger does",+ "example": "Triggers when a new message is posted to a Slack channel"+ },+ "instructions": {+ "type": "string",+ "description": "Step-by-step instructions on how to set up and use this trigger"+ },+ "type": {+ "type": "string",+ "enum": [+ "webhook",+ "poll"+ ],+ "description": "The trigger mechanism - either webhook (event-based) or poll (scheduled check)",+ "example": "webhook"+ },+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Unique identifier for the parent toolkit",+ "example": "slack"+ },+ "name": {+ "type": "string",+ "description": "Deprecated: Use slug instead",+ "example": "Slack"+ },+ "logo": {+ "type": "string",+ "description": "Logo of the toolkit",+ "example": "https://example.com/logo.png"+ }+ },+ "required": [+ "slug",+ "name",+ "logo"+ ],+ "description": "Information about the toolkit that provides this trigger"+ },+ "config": {+ "type": "object",+ "additionalProperties": {},+ "description": "Configuration schema required to set up this trigger",+ "example": {+ "channel_id": {+ "type": "string",+ "required": true+ },+ "message_type": {+ "type": "enum",+ "options": [+ "all",+ "direct",+ "channel"+ ]+ }+ }+ },+ "payload": {+ "type": "object",+ "additionalProperties": {},+ "description": "Schema of the data payload this trigger will deliver when it fires",+ "example": {+ "message": {+ "type": "string"+ },+ "sender": {+ "type": "object",+ "properties": {+ "id": "string",+ "name": "string"+ }+ },+ "timestamp": {+ "type": "number"+ }+ }+ },+ "version": {+ "type": "string",+ "description": "Version of the trigger type",+ "example": "20250930_00"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "instructions",+ "type",+ "toolkit",+ "config",+ "payload",+ "version"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/triggers_types": {+ "get": {+ "summary": "List trigger types",+ "description": "Retrieve a list of available trigger types with optional filtering by toolkit. Results are paginated and can be filtered by toolkit.",+ "tags": [+ "Triggers"+ ],+ "operationId": "getTriggersTypes",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Array of toolkit slugs to filter triggers by",+ "example": [+ "slack",+ "github"+ ]+ },+ "required": false,+ "description": "Array of toolkit slugs to filter triggers by",+ "name": "toolkit_slugs",+ "in": "query"+ },+ {+ "schema": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object representation of parsed bracket notation"+ }+ ]+ },+ "required": false,+ "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",+ "in": "query",+ "name": "toolkit_versions",+ "examples": {+ "latest_version": {+ "summary": "Latest version for all toolkits",+ "value": "latest"+ },+ "bracket_notation": {+ "summary": "Specific versions using bracket notation",+ "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"+ },+ "null_value": {+ "summary": "No version specified (uses latest)",+ "value": null+ }+ }+ },+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved triggers",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Unique identifier for the trigger type",+ "example": "SLACK_RECEIVE_MESSAGE"+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the trigger",+ "example": "New Message in Slack Channel"+ },+ "description": {+ "type": "string",+ "description": "Detailed description of what the trigger does",+ "example": "Triggers when a new message is posted to a Slack channel"+ },+ "instructions": {+ "type": "string",+ "description": "Step-by-step instructions on how to set up and use this trigger"+ },+ "type": {+ "type": "string",+ "enum": [+ "webhook",+ "poll"+ ],+ "description": "The trigger mechanism - either webhook (event-based) or poll (scheduled check)",+ "example": "webhook"+ },+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Unique identifier for the parent toolkit",+ "example": "slack"+ },+ "name": {+ "type": "string",+ "description": "Deprecated: Use slug instead",+ "example": "Slack"+ },+ "logo": {+ "type": "string",+ "description": "Logo of the toolkit",+ "example": "https://example.com/logo.png"+ }+ },+ "required": [+ "slug",+ "name",+ "logo"+ ],+ "description": "Information about the toolkit that provides this trigger"+ },+ "config": {+ "type": "object",+ "additionalProperties": {},+ "description": "Configuration schema required to set up this trigger",+ "example": {+ "channel_id": {+ "type": "string",+ "required": true+ },+ "message_type": {+ "type": "enum",+ "options": [+ "all",+ "direct",+ "channel"+ ]+ }+ }+ },+ "payload": {+ "type": "object",+ "additionalProperties": {},+ "description": "Schema of the data payload this trigger will deliver when it fires",+ "example": {+ "message": {+ "type": "string"+ },+ "sender": {+ "type": "object",+ "properties": {+ "id": "string",+ "name": "string"+ }+ },+ "timestamp": {+ "type": "number"+ }+ }+ },+ "version": {+ "type": "string",+ "description": "Version of the trigger type",+ "example": "20250930_00"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "instructions",+ "type",+ "toolkit",+ "config",+ "payload",+ "version"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/mcp/servers": {+ "get": {+ "summary": "List MCP servers with optional filters and pagination",+ "description": "Retrieves a paginated list of MCP servers associated with the authenticated project. Results can be filtered by name, toolkit, or authentication configuration ID. MCP servers are used to provide Model Control Protocol integration points for connecting AI assistants to your applications and services.",+ "tags": [+ "MCP"+ ],+ "operationId": "getMcpServers",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Name substring to filter servers by",+ "example": "github"+ },+ "required": false,+ "description": "Filter MCP servers by name (case-insensitive partial match)",+ "name": "name",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Comma-separated list of toolkit slugs to filter servers by",+ "in": "query",+ "name": "toolkits"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Comma-separated list of auth config IDs to filter servers by",+ "in": "query",+ "name": "auth_config_ids"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "created_at",+ "updated_at"+ ],+ "default": "updated_at",+ "description": "Field to use for ordering the results",+ "example": "updated_at"+ },+ "required": false,+ "description": "Field to order results by",+ "name": "order_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "asc",+ "desc"+ ],+ "default": "desc",+ "description": "Sort direction (ascending or descending)",+ "example": "desc"+ },+ "required": false,+ "description": "Direction of ordering",+ "name": "order_direction",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true,+ "default": 1,+ "description": "Page number to retrieve",+ "example": 1+ },+ "required": false,+ "description": "Page number for pagination (1-based)",+ "name": "page_no",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true,+ "default": 10,+ "description": "Number of servers to return per page",+ "example": 10+ },+ "required": false,+ "description": "Number of items per page (default: 10)",+ "name": "limit",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved MCP servers. Returns a paginated list of server configurations including connection details and command instructions.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID of the MCP server instance",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "name": {+ "type": "string",+ "description": "User-defined descriptive name for this MCP server",+ "example": "GitHub Integration Server"+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "ID references to the auth configurations used by this server",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of tool slugs that this MCP server is allowed to use",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "GITHUB_GET_A_REPOSITORY",+ "GITHUB_LIST_PULL_REQUESTS"+ ]+ },+ "mcp_url": {+ "type": "string",+ "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param",+ "deprecated": true,+ "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john"+ },+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of toolkit slugs that this MCP server is allowed to use",+ "example": [+ "github",+ "jira",+ "slack"+ ]+ },+ "toolkit_icons": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes",+ "example": {+ "github": "https://assets.composio.dev/logos/github.png",+ "jira": "https://assets.composio.dev/logos/jira.png",+ "slack": "https://assets.composio.dev/logos/slack.png"+ }+ },+ "commands": {+ "type": "object",+ "properties": {+ "cursor": {+ "type": "string",+ "description": "Command line instruction for Cursor client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor"+ },+ "claude": {+ "type": "string",+ "description": "Command line instruction for Claude client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude"+ },+ "windsurf": {+ "type": "string",+ "description": "Command line instruction for Windsurf client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf"+ }+ },+ "required": [+ "cursor",+ "claude",+ "windsurf"+ ],+ "description": "Set of command line instructions for connecting various clients to this MCP server",+ "deprecated": true+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when this server configuration was last modified",+ "example": "2023-06-15T14:30:00.000Z"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when this server was initially created",+ "example": "2023-06-10T09:15:00.000Z"+ },+ "server_instance_count": {+ "type": "number",+ "description": "Total count of active user instances connected to this server",+ "example": 5+ },+ "managed_auth_via_composio": {+ "type": "boolean",+ "description": "Whether the MCP server is managed by Composio",+ "example": true+ }+ },+ "required": [+ "id",+ "name",+ "auth_config_ids",+ "allowed_tools",+ "mcp_url",+ "toolkits",+ "toolkit_icons",+ "commands",+ "updated_at",+ "created_at",+ "server_instance_count",+ "managed_auth_via_composio"+ ],+ "description": "MCP server configuration and connection details"+ },+ "description": "Array of MCP server configurations",+ "example": [+ {+ "id": "550e8400-e29b-41d4-a716-446655440000",+ "name": "GitHub Integration Server",+ "auth_config_ids": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ],+ "allowed_tools": [+ "GITHUB_CREATE_AN_ISSUE",+ "GITHUB_GET_A_REPOSITORY"+ ],+ "mcp_url": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john",+ "commands": {+ "cursor": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor",+ "claude": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude",+ "windsurf": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf"+ },+ "toolkits": [+ "github",+ "jira",+ "slack"+ ],+ "toolkit_icons": {+ "github": "https://assets.composio.dev/logos/github.png",+ "jira": "https://assets.composio.dev/logos/jira.png",+ "slack": "https://assets.composio.dev/logos/slack.png"+ },+ "updated_at": "2023-06-15T14:30:00.000Z",+ "created_at": "2023-06-10T09:15:00.000Z",+ "server_instance_count": 5,+ "managed_auth_via_composio": true+ }+ ]+ },+ "total_pages": {+ "type": "number",+ "description": "Total number of pages in the paginated response",+ "example": 5+ },+ "current_page": {+ "type": "number",+ "description": "Current page number being returned",+ "example": 1+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page"+ ],+ "description": "Paginated response containing MCP servers"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The query parameters may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to view MCP servers for this project.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "post": {+ "summary": "Create a new MCP server",+ "description": "Creates a new Model Control Protocol (MCP) server instance for the authenticated project. An MCP server provides a connection point for AI assistants to access your applications and services. The server is configured with specific authentication and tool permissions that determine what actions the connected assistants can perform.",+ "tags": [+ "MCP"+ ],+ "operationId": "postMcpServers",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 4,+ "maxLength": 30,+ "pattern": "^[a-zA-Z0-9- ]+$",+ "description": "Human-readable name to identify this MCP server instance (4-30 characters, alphanumeric, spaces, and hyphens only)",+ "example": "Production GitHub Integration"+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "ID references to existing authentication configurations",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ },+ "no_auth_apps": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of NO_AUTH apps to enable for this MCP server",+ "example": [+ "exa",+ "codeinterpreter",+ "composio",+ "composio_search"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "List of tool slugs that should be allowed for this server. If not provided, all available tools for the authentication configuration will be enabled.",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "GITHUB_GET_A_REPOSITORY",+ "GITHUB_LIST_PULL_REQUESTS"+ ]+ },+ "managed_auth_via_composio": {+ "type": "boolean",+ "description": "Whether the MCP server is managed by Composio"+ }+ },+ "required": [+ "name",+ "auth_config_ids"+ ],+ "description": "Request parameters for creating a new MCP server with specific authentication configuration"+ },+ "examples": {+ "Basic MCP Server": {+ "value": {+ "name": "GitHub Integration Server",+ "auth_config_ids": [+ "ac_1a2b3c4d5e6f"+ ]+ }+ },+ "Server with Limited Tools": {+ "value": {+ "name": "GitHub Issues Only",+ "auth_config_ids": [+ "ac_1a2b3c4d5e6f"+ ],+ "allowed_tools": [+ "GMAIL_ADD_LABEL_TO_EMAIL"+ ]+ }+ },+ "Server with Expiration": {+ "value": {+ "name": "Temporary Integration Server",+ "auth_config_ids": [+ "ac_1a2b3c4d5e6f"+ ]+ }+ }+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "MCP server created successfully. Returns the complete server configuration including connection details and command instructions.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID of the MCP server instance",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "name": {+ "type": "string",+ "description": "User-defined descriptive name for this MCP server",+ "example": "GitHub Integration Server"+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "ID references to the auth configurations used by this server",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of tool slugs that this MCP server is allowed to use",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "GITHUB_GET_A_REPOSITORY",+ "GITHUB_LIST_PULL_REQUESTS"+ ]+ },+ "mcp_url": {+ "type": "string",+ "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param",+ "deprecated": true,+ "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john"+ },+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of toolkit slugs that this MCP server is allowed to use",+ "example": [+ "github",+ "jira",+ "slack"+ ]+ },+ "toolkit_icons": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes",+ "example": {+ "github": "https://assets.composio.dev/logos/github.png",+ "jira": "https://assets.composio.dev/logos/jira.png",+ "slack": "https://assets.composio.dev/logos/slack.png"+ }+ },+ "commands": {+ "type": "object",+ "properties": {+ "cursor": {+ "type": "string",+ "description": "Command line instruction for Cursor client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor"+ },+ "claude": {+ "type": "string",+ "description": "Command line instruction for Claude client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude"+ },+ "windsurf": {+ "type": "string",+ "description": "Command line instruction for Windsurf client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf"+ }+ },+ "required": [+ "cursor",+ "claude",+ "windsurf"+ ],+ "description": "Set of command line instructions for connecting various clients to this MCP server",+ "deprecated": true+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when this server configuration was last modified",+ "example": "2023-06-15T14:30:00.000Z"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when this server was initially created",+ "example": "2023-06-10T09:15:00.000Z"+ },+ "server_instance_count": {+ "type": "number",+ "description": "Total count of active user instances connected to this server",+ "example": 5+ },+ "managed_auth_via_composio": {+ "type": "boolean",+ "description": "Whether the MCP server is managed by Composio",+ "example": true+ }+ },+ "required": [+ "id",+ "name",+ "auth_config_ids",+ "allowed_tools",+ "mcp_url",+ "toolkits",+ "toolkit_icons",+ "commands",+ "updated_at",+ "created_at",+ "server_instance_count",+ "managed_auth_via_composio"+ ],+ "description": "MCP server configuration and connection details"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The request body may be invalid, missing required parameters, or the auth_config_id may not exist.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to create MCP servers for this project.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not Found. The specified auth_config_id does not exist or is not accessible to the authenticated user.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/mcp/servers/custom": {+ "post": {+ "summary": "Create a new custom MCP server with multiple apps",+ "description": "Creates a new Model Control Protocol (MCP) server instance that can integrate with multiple applications or toolkits simultaneously. This endpoint allows you to create a server that can access tools from different applications, making it suitable for complex workflows that span multiple services.",+ "tags": [+ "MCP"+ ],+ "operationId": "postMcpServersCustom",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 4,+ "maxLength": 30,+ "pattern": "^[a-zA-Z0-9- ]+$",+ "description": "Human-readable name to identify this custom MCP server (4-30 characters, alphanumeric, spaces, and hyphens only)",+ "example": "Multi App Integration Server"+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "ID references to existing authentication configurations",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ },+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of application/toolkit identifiers to enable for this server",+ "example": [+ "github",+ "jira",+ "slack"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tool identifiers to enable that aren't part of standard toolkits",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "SLACK_SEND_MESSAGE"+ ]+ },+ "custom_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "DEPRECATED: Use allowed_tools instead. Tool identifiers to enable that aren't part of standard toolkits",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "SLACK_SEND_MESSAGE"+ ]+ },+ "managed_auth_via_composio": {+ "type": "boolean",+ "description": "Whether to manage authentication via Composio"+ }+ },+ "required": [+ "name"+ ],+ "description": "Parameters for creating a new custom MCP server with multiple applications"+ },+ "examples": {+ "Basic Multi-App Server": {+ "value": {+ "name": "Development Integration Server",+ "toolkits": [+ "github",+ "jira"+ ]+ }+ },+ "Advanced Multi-App Server": {+ "value": {+ "name": "Complete Workflow Integration",+ "toolkits": [+ "github",+ "jira",+ "slack"+ ],+ "custom_tools": [+ "SLACK_SEND_MESSAGE"+ ]+ }+ }+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Custom MCP server created successfully. Returns the complete server configuration including connection details and command instructions for all specified applications.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Unique identifier for the newly created custom MCP server",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the custom MCP server",+ "example": "Multi-App Integration Server"+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "ID references to the auth configurations used by this server",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of tool identifiers that are enabled for this server",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "JIRA_GET_ISSUE",+ "SLACK_SEND_MESSAGE",+ "GMAIL_SEND_EMAIL"+ ]+ },+ "mcp_url": {+ "type": "string",+ "description": "URL endpoint for establishing connection to this MCP server",+ "example": "https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john"+ },+ "commands": {+ "type": "object",+ "properties": {+ "cursor": {+ "type": "string",+ "description": "Command line instruction for Cursor client setup",+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john\" --client cursor"+ },+ "claude": {+ "type": "string",+ "description": "Command line instruction for Claude client setup",+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john\" --client claude"+ },+ "windsurf": {+ "type": "string",+ "description": "Command line instruction for Windsurf client setup",+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf"+ }+ },+ "required": [+ "cursor",+ "claude",+ "windsurf"+ ],+ "description": "Set of command line instructions for connecting various clients to this MCP server"+ }+ },+ "required": [+ "id",+ "name",+ "auth_config_ids",+ "allowed_tools",+ "mcp_url",+ "commands"+ ],+ "description": "Response for a successfully created custom MCP server with multiple applications"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The request body may be invalid, missing required parameters, or contain invalid toolkit identifiers.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to create MCP servers for this project.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/mcp/servers/generate": {+ "post": {+ "summary": "Generate MCP URL with custom parameters",+ "description": "Generates a Model Control Protocol (MCP) URL for an existing server with custom query parameters. The URL includes user-specific parameters and configuration flags that control the behavior of the MCP connection.",+ "tags": [+ "MCP"+ ],+ "operationId": "postMcpServersGenerate",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "mcp_server_id": {+ "type": "string",+ "description": "Unique identifier of the MCP server to generate URL for",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "managed_auth_by_composio": {+ "type": "boolean",+ "default": false,+ "description": "Flag indicating if Composio manages authentication",+ "example": true+ },+ "user_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of user identifiers for whom the URL is generated",+ "example": [+ "user_123456",+ "user_789012"+ ]+ },+ "connected_account_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of connected account identifiers",+ "example": [+ "ca_1a2b3c4d5e6f",+ "ca_7g8h9i0j1k2l",+ "ca_3m4n5o6p7q8r"+ ]+ }+ },+ "required": [+ "mcp_server_id"+ ],+ "description": "Request parameters for generating an MCP URL"+ },+ "examples": {+ "Basic URL Generation": {+ "value": {+ "mcp_server_id": "550e8400-e29b-41d4-a716-446655440000",+ "user_ids": [+ "user_123456"+ ],+ "connected_account_ids": [+ "ca_1a2b3c4d5e6f",+ "ca_7g8h9i0j1k2l"+ ]+ }+ },+ "Managed Auth Configuration": {+ "value": {+ "mcp_server_id": "550e8400-e29b-41d4-a716-446655440000",+ "user_ids": [+ "user_123456",+ "user_789012"+ ],+ "connected_account_ids": [+ "ca_1a2b3c4d5e6f",+ "ca_7g8h9i0j1k2l",+ "ca_3m4n5o6p7q8r"+ ]+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully generated MCP URL. Returns the complete URL with all specified query parameters.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "mcp_url": {+ "type": "string",+ "description": "Base MCP URL without any query parameters",+ "example": "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000"+ },+ "connected_account_urls": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of URLs generated for each connected account ID",+ "example": [+ "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000?include_composio_helper_actions=true&connected_account_ids=ca_1a2b3c4d5e6f&user_id=user_123456,user_789012",+ "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000?include_composio_helper_actions=true&connected_account_ids=ca_7g8h9i0j1k2l&user_id=user_123456,user_789012"+ ]+ },+ "user_ids_url": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of URLs generated for each user ID",+ "example": [+ "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000?include_composio_helper_actions=true&connected_account_ids=ca_1a2b3c4d5e6f,ca_7g8h9i0j1k2l&user_id=user_123456",+ "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000?include_composio_helper_actions=true&connected_account_ids=ca_1a2b3c4d5e6f,ca_7g8h9i0j1k2l&user_id=user_789012"+ ]+ }+ },+ "required": [+ "mcp_url",+ "connected_account_urls",+ "user_ids_url"+ ],+ "description": "Response containing the generated MCP URLs"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The request body may be invalid or missing required parameters.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to access this MCP server.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "MCP server not found. No server with the specified ID exists or it has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/mcp/{id}": {+ "get": {+ "summary": "Get MCP server details by ID",+ "description": "Retrieves detailed configuration information for a specific Model Control Protocol (MCP) server. The returned data includes connection details, associated applications, enabled tools, and authentication configuration.",+ "tags": [+ "MCP"+ ],+ "operationId": "getMcpById",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Unique identifier of the MCP server to retrieve, update, or delete",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "required": true,+ "description": "The ID of the MCP server",+ "name": "id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved MCP server. Returns the complete server configuration including connection details, authentication settings, and available tools.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID of the MCP server instance",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "name": {+ "type": "string",+ "description": "User-defined descriptive name for this MCP server",+ "example": "GitHub Integration Server"+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "ID references to the auth configurations used by this server",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of tool slugs that this MCP server is allowed to use",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "GITHUB_GET_A_REPOSITORY",+ "GITHUB_LIST_PULL_REQUESTS"+ ]+ },+ "mcp_url": {+ "type": "string",+ "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param",+ "deprecated": true,+ "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john"+ },+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of toolkit slugs that this MCP server is allowed to use",+ "example": [+ "github",+ "jira",+ "slack"+ ]+ },+ "toolkit_icons": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes",+ "example": {+ "github": "https://assets.composio.dev/logos/github.png",+ "jira": "https://assets.composio.dev/logos/jira.png",+ "slack": "https://assets.composio.dev/logos/slack.png"+ }+ },+ "commands": {+ "type": "object",+ "properties": {+ "cursor": {+ "type": "string",+ "description": "Command line instruction for Cursor client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor"+ },+ "claude": {+ "type": "string",+ "description": "Command line instruction for Claude client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude"+ },+ "windsurf": {+ "type": "string",+ "description": "Command line instruction for Windsurf client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf"+ }+ },+ "required": [+ "cursor",+ "claude",+ "windsurf"+ ],+ "description": "Set of command line instructions for connecting various clients to this MCP server",+ "deprecated": true+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when this server configuration was last modified",+ "example": "2023-06-15T14:30:00.000Z"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when this server was initially created",+ "example": "2023-06-10T09:15:00.000Z"+ },+ "server_instance_count": {+ "type": "number",+ "description": "Total count of active user instances connected to this server",+ "example": 5+ },+ "managed_auth_via_composio": {+ "type": "boolean",+ "description": "Whether the MCP server is managed by Composio",+ "example": true+ },+ "deleted": {+ "type": "boolean",+ "description": "Whether the MCP server is deleted"+ }+ },+ "required": [+ "id",+ "name",+ "auth_config_ids",+ "allowed_tools",+ "mcp_url",+ "toolkits",+ "toolkit_icons",+ "commands",+ "updated_at",+ "created_at",+ "server_instance_count",+ "managed_auth_via_composio",+ "deleted"+ ],+ "description": "MCP server configuration and connection details"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The server ID parameter may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to view this MCP server.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "MCP server not found. No server with the specified ID exists or it has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "patch": {+ "summary": "Update MCP server configuration",+ "description": "Updates the configuration of an existing Model Control Protocol (MCP) server. You can modify the server name, associated applications, and enabled tools. Only the fields included in the request will be updated.",+ "tags": [+ "MCP"+ ],+ "operationId": "patchMcpById",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Unique identifier of the MCP server to retrieve, update, or delete",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "required": true,+ "description": "The ID of the MCP server",+ "name": "id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Human-readable name to identify this MCP server instance (4-30 characters, alphanumeric, spaces, and hyphens only)",+ "example": "Production GitHub Integration"+ },+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of toolkit slugs this server should be configured to work with.",+ "example": [+ "gmail",+ "notion"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of action identifiers that should be enabled for this server",+ "example": [+ "GMAIL_ADD_LABEL_TO_EMAIL"+ ]+ },+ "managed_auth_via_composio": {+ "type": "boolean",+ "description": "Whether the MCP server is managed by Composio",+ "example": true+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of auth config IDs to use for this MCP server.",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ }+ },+ "description": "Parameters for updating an existing MCP server configuration"+ },+ "examples": {+ "Update Server Name": {+ "value": {+ "name": "Updated GitHub Integration Server"+ }+ },+ "Update Single Auth Config": {+ "value": {+ "auth_config_ids": [+ "ac_1a2b3c4d5e6f"+ ],+ "toolkits": [+ "gmail"+ ],+ "allowed_tools": [+ "GMAIL_ADD_LABEL_TO_EMAIL"+ ]+ }+ },+ "Update Multiple Auth Configs": {+ "value": {+ "auth_config_ids": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ],+ "toolkits": [+ "gmail",+ "notion"+ ],+ "allowed_tools": [+ "GMAIL_ADD_LABEL_TO_EMAIL",+ "NOTION_CREATE_NOTION_PAGE"+ ]+ }+ },+ "Update Toolkits Only": {+ "value": {+ "toolkits": [+ "gmail",+ "notion"+ ]+ }+ },+ "Full Update": {+ "value": {+ "name": "Production Multi-App MCP Server",+ "auth_config_ids": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ],+ "toolkits": [+ "gmail",+ "notion"+ ],+ "allowed_tools": [+ "GMAIL_ADD_LABEL_TO_EMAIL",+ "NOTION_CREATE_NOTION_PAGE"+ ]+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully updated MCP server. Returns the complete updated server configuration including connection details, authentication settings, and available tools.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID of the MCP server instance",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "name": {+ "type": "string",+ "description": "User-defined descriptive name for this MCP server",+ "example": "GitHub Integration Server"+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "ID references to the auth configurations used by this server",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of tool slugs that this MCP server is allowed to use",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "GITHUB_GET_A_REPOSITORY",+ "GITHUB_LIST_PULL_REQUESTS"+ ]+ },+ "mcp_url": {+ "type": "string",+ "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param",+ "deprecated": true,+ "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john"+ },+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of toolkit slugs that this MCP server is allowed to use",+ "example": [+ "github",+ "jira",+ "slack"+ ]+ },+ "toolkit_icons": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes",+ "example": {+ "github": "https://assets.composio.dev/logos/github.png",+ "jira": "https://assets.composio.dev/logos/jira.png",+ "slack": "https://assets.composio.dev/logos/slack.png"+ }+ },+ "commands": {+ "type": "object",+ "properties": {+ "cursor": {+ "type": "string",+ "description": "Command line instruction for Cursor client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor"+ },+ "claude": {+ "type": "string",+ "description": "Command line instruction for Claude client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude"+ },+ "windsurf": {+ "type": "string",+ "description": "Command line instruction for Windsurf client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf"+ }+ },+ "required": [+ "cursor",+ "claude",+ "windsurf"+ ],+ "description": "Set of command line instructions for connecting various clients to this MCP server",+ "deprecated": true+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when this server configuration was last modified",+ "example": "2023-06-15T14:30:00.000Z"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when this server was initially created",+ "example": "2023-06-10T09:15:00.000Z"+ },+ "server_instance_count": {+ "type": "number",+ "description": "Total count of active user instances connected to this server",+ "example": 5+ },+ "managed_auth_via_composio": {+ "type": "boolean",+ "description": "Whether the MCP server is managed by Composio",+ "example": true+ },+ "deleted": {+ "type": "boolean",+ "description": "Whether the MCP server is deleted"+ }+ },+ "required": [+ "id",+ "name",+ "auth_config_ids",+ "allowed_tools",+ "mcp_url",+ "toolkits",+ "toolkit_icons",+ "commands",+ "updated_at",+ "created_at",+ "server_instance_count",+ "managed_auth_via_composio",+ "deleted"+ ],+ "description": "MCP server configuration and connection details"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The request parameters may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to update this MCP server.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "MCP server not found. No server with the specified ID exists or it has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "delete": {+ "summary": "Delete an MCP server",+ "description": "Performs a soft delete on a Model Control Protocol (MCP) server, making it unavailable for future use. This operation is reversible in the database but cannot be undone through the API. Any applications or services connected to this server will lose access after deletion.",+ "tags": [+ "MCP"+ ],+ "operationId": "deleteMcpById",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Unique identifier of the MCP server to retrieve, update, or delete",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "required": true,+ "description": "The ID of the MCP server",+ "name": "id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully deleted MCP server. The server has been soft-deleted and is no longer available for use.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Unique identifier of the MCP server to retrieve, update, or delete",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "deleted": {+ "type": "boolean",+ "description": "Indicates whether the MCP server was successfully deleted",+ "example": true+ }+ },+ "required": [+ "id",+ "deleted"+ ],+ "description": "Response indicating the success of the delete operation"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The server ID parameter may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to delete this MCP server.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "MCP server not found. No server with the specified ID exists or it has already been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/mcp/app/{appKey}": {+ "get": {+ "summary": "List MCP servers for a specific app",+ "description": "Retrieves a paginated list of Model Control Protocol (MCP) servers that are configured for a specific application or toolkit. This endpoint allows you to find all MCP server instances that have access to a particular application, such as GitHub, Slack, or Jira.",+ "tags": [+ "MCP"+ ],+ "operationId": "getMcpAppByAppKey",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Toolkit or application slug identifier to filter MCP servers by",+ "example": "github"+ },+ "required": true,+ "description": "The key of the app to find MCP servers for",+ "name": "appKey",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "description": "Name substring to filter servers by",+ "example": "github"+ },+ "required": false,+ "description": "Filter MCP servers by name (case-insensitive partial match)",+ "name": "name",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Comma-separated list of toolkit slugs to filter servers by",+ "in": "query",+ "name": "toolkits"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Comma-separated list of auth config IDs to filter servers by",+ "in": "query",+ "name": "auth_config_ids"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "created_at",+ "updated_at"+ ],+ "default": "updated_at",+ "description": "Field to use for ordering the results",+ "example": "updated_at"+ },+ "required": false,+ "description": "Field to order results by",+ "name": "order_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "asc",+ "desc"+ ],+ "default": "desc",+ "description": "Sort direction (ascending or descending)",+ "example": "desc"+ },+ "required": false,+ "description": "Direction of ordering",+ "name": "order_direction",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true,+ "default": 1,+ "description": "Page number to retrieve",+ "example": 1+ },+ "required": false,+ "description": "Page number for pagination (1-based)",+ "name": "page_no",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true,+ "default": 10,+ "description": "Number of servers to return per page",+ "example": 10+ },+ "required": false,+ "description": "Number of items per page (default: 10)",+ "name": "limit",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved MCP servers for the specified application. Returns a paginated list of server configurations including connection details and command instructions.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID of the MCP server instance",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "name": {+ "type": "string",+ "description": "User-defined descriptive name for this MCP server",+ "example": "GitHub Integration Server"+ },+ "auth_config_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "ID references to the auth configurations used by this server",+ "example": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ]+ },+ "allowed_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of tool slugs that this MCP server is allowed to use",+ "example": [+ "GITHUB_CREATE_AN_ISSUE",+ "GITHUB_GET_A_REPOSITORY",+ "GITHUB_LIST_PULL_REQUESTS"+ ]+ },+ "mcp_url": {+ "type": "string",+ "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param",+ "deprecated": true,+ "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john"+ },+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of toolkit slugs that this MCP server is allowed to use",+ "example": [+ "github",+ "jira",+ "slack"+ ]+ },+ "toolkit_icons": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes",+ "example": {+ "github": "https://assets.composio.dev/logos/github.png",+ "jira": "https://assets.composio.dev/logos/jira.png",+ "slack": "https://assets.composio.dev/logos/slack.png"+ }+ },+ "commands": {+ "type": "object",+ "properties": {+ "cursor": {+ "type": "string",+ "description": "Command line instruction for Cursor client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor"+ },+ "claude": {+ "type": "string",+ "description": "Command line instruction for Claude client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude"+ },+ "windsurf": {+ "type": "string",+ "description": "Command line instruction for Windsurf client setup",+ "deprecated": true,+ "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf"+ }+ },+ "required": [+ "cursor",+ "claude",+ "windsurf"+ ],+ "description": "Set of command line instructions for connecting various clients to this MCP server",+ "deprecated": true+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when this server configuration was last modified",+ "example": "2023-06-15T14:30:00.000Z"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when this server was initially created",+ "example": "2023-06-10T09:15:00.000Z"+ },+ "server_instance_count": {+ "type": "number",+ "description": "Total count of active user instances connected to this server",+ "example": 5+ },+ "managed_auth_via_composio": {+ "type": "boolean",+ "description": "Whether the MCP server is managed by Composio",+ "example": true+ }+ },+ "required": [+ "id",+ "name",+ "auth_config_ids",+ "allowed_tools",+ "mcp_url",+ "toolkits",+ "toolkit_icons",+ "commands",+ "updated_at",+ "created_at",+ "server_instance_count",+ "managed_auth_via_composio"+ ],+ "description": "MCP server configuration and connection details"+ },+ "description": "Array of MCP server configurations",+ "example": [+ {+ "id": "550e8400-e29b-41d4-a716-446655440000",+ "name": "GitHub Integration Server",+ "auth_config_ids": [+ "ac_1a2b3c4d5e6f",+ "ac_7g8h9i0j1k2l"+ ],+ "allowed_tools": [+ "GITHUB_CREATE_AN_ISSUE",+ "GITHUB_GET_A_REPOSITORY"+ ],+ "mcp_url": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john",+ "commands": {+ "cursor": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor",+ "claude": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude",+ "windsurf": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf"+ },+ "toolkits": [+ "github",+ "jira",+ "slack"+ ],+ "toolkit_icons": {+ "github": "https://assets.composio.dev/logos/github.png",+ "jira": "https://assets.composio.dev/logos/jira.png",+ "slack": "https://assets.composio.dev/logos/slack.png"+ },+ "updated_at": "2023-06-15T14:30:00.000Z",+ "created_at": "2023-06-10T09:15:00.000Z",+ "server_instance_count": 5,+ "managed_auth_via_composio": true+ }+ ]+ },+ "total_pages": {+ "type": "number",+ "description": "Total number of pages in the paginated response",+ "example": 5+ },+ "current_page": {+ "type": "number",+ "description": "Current page number being returned",+ "example": 1+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page"+ ],+ "description": "Paginated response containing MCP servers"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The query parameters may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to view MCP servers for this application.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Application not found. No application with the specified key exists.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/mcp/servers/{serverId}/instances": {+ "get": {+ "summary": "List all instances for an MCP server",+ "description": "Retrieves a paginated list of user instances (user IDs) associated with a specific Model Control Protocol (MCP) server. This endpoint supports pagination to handle servers with many instances.",+ "tags": [+ "MCP"+ ],+ "operationId": "getMcpServersByServerIdInstances",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "UUID of the MCP server to list instances for",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "required": true,+ "description": "The ID of the MCP server",+ "name": "serverId",+ "in": "path"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true,+ "default": 1,+ "description": "Page number to retrieve",+ "example": 1+ },+ "required": false,+ "description": "Page number for pagination (1-based)",+ "name": "page_no",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true,+ "default": 20,+ "description": "Number of instances to return per page",+ "example": 20+ },+ "required": false,+ "description": "Number of items per page (default: 20)",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Filter instances by user ID or instance ID (partial match)",+ "example": "user_123"+ },+ "required": false,+ "description": "Search instances by user ID/instance ID",+ "name": "search",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "created_at",+ "updated_at"+ ],+ "default": "updated_at",+ "description": "Field to use for ordering the results",+ "example": "updated_at"+ },+ "required": false,+ "description": "Field to order results by",+ "name": "order_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "asc",+ "desc"+ ],+ "default": "desc",+ "description": "Sort direction (ascending or descending)",+ "example": "desc"+ },+ "required": false,+ "description": "Direction of ordering",+ "name": "order_direction",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved MCP server instances. Returns the list of user IDs associated with this server.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "instances": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID of the instance record",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "instance_id": {+ "type": "string",+ "description": "The instance identifier (same as the user_id)",+ "example": "user_123456"+ },+ "mcp_server_id": {+ "type": "string",+ "description": "UUID of the parent MCP server",+ "example": "660e8400-e29b-41d4-a716-446655440001"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when this instance was created",+ "example": "2023-06-10T09:15:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when this instance was last modified",+ "example": "2023-06-15T14:30:00.000Z"+ }+ },+ "required": [+ "id",+ "instance_id",+ "mcp_server_id",+ "created_at",+ "updated_at"+ ],+ "description": "MCP server instance details"+ },+ "description": "List of instance objects associated with this MCP server for the current page",+ "example": [+ {+ "id": "550e8400-e29b-41d4-a716-446655440000",+ "instance_id": "user_123456",+ "mcp_server_id": "660e8400-e29b-41d4-a716-446655440001",+ "created_at": "2023-06-10T09:15:00.000Z",+ "updated_at": "2023-06-15T14:30:00.000Z"+ }+ ]+ },+ "server_id": {+ "type": "string",+ "description": "UUID of the MCP server",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "server_name": {+ "type": "string",+ "description": "Name of the MCP server",+ "example": "Production GitHub Integration"+ },+ "total_pages": {+ "type": "number",+ "description": "Total number of pages in the paginated response",+ "example": 3+ },+ "current_page": {+ "type": "number",+ "description": "Current page number being returned",+ "example": 1+ }+ },+ "required": [+ "instances",+ "server_id",+ "server_name",+ "total_pages",+ "current_page"+ ],+ "description": "Paginated list of instances for an MCP server"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The server ID parameter may be invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "MCP server not found. No server with the specified ID exists.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ },+ "post": {+ "summary": "Create a new MCP server instance",+ "description": "Creates a new instance for a Model Control Protocol (MCP) server. This endpoint validates that the user has connected accounts for all auth configurations associated with the MCP server before creating the instance.",+ "tags": [+ "MCP"+ ],+ "operationId": "postMcpServersByServerIdInstances",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "UUID of the MCP server to create an instance for",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "required": true,+ "description": "The ID of the MCP server",+ "name": "serverId",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "user_id": {+ "type": "string",+ "minLength": 1,+ "description": "The user ID (entity ID) that will be used as both the user identifier and instance ID",+ "example": "user_123456"+ }+ },+ "required": [+ "user_id"+ ],+ "description": "Parameters for creating a new MCP server instance"+ },+ "examples": {+ "Create Instance": {+ "value": {+ "user_id": "user_123456"+ }+ }+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Successfully created MCP server instance. Returns the created instance details.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID of the instance record",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "instance_id": {+ "type": "string",+ "description": "The instance identifier (same as the user_id)",+ "example": "user_123456"+ },+ "mcp_server_id": {+ "type": "string",+ "description": "UUID of the parent MCP server",+ "example": "660e8400-e29b-41d4-a716-446655440001"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when this instance was created",+ "example": "2023-06-10T09:15:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when this instance was last modified",+ "example": "2023-06-15T14:30:00.000Z"+ }+ },+ "required": [+ "id",+ "instance_id",+ "mcp_server_id",+ "created_at",+ "updated_at"+ ],+ "description": "MCP server instance details"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The request parameters may be invalid or the instance ID already exists.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The user does not have connected accounts for all required auth configurations.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "MCP server not found. No server with the specified ID exists.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "Conflict. An instance with this ID already exists for the server.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/mcp/servers/{serverId}/instances/{instanceId}": {+ "delete": {+ "summary": "Delete an MCP server instance and associated connected accounts",+ "description": "Removes a user instance from the MCP server and deletes all connected accounts for that user that are associated with the auth configurations of this specific MCP server. Connected accounts for other auth configurations are not affected.",+ "tags": [+ "MCP"+ ],+ "operationId": "deleteMcpServersByServerIdInstancesByInstanceId",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "UUID of the MCP server",+ "example": "550e8400-e29b-41d4-a716-446655440000"+ },+ "required": true,+ "description": "The ID of the MCP server",+ "name": "serverId",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "description": "The user ID to remove from this server",+ "example": "user_123456"+ },+ "required": true,+ "description": "The instance ID (user ID) to delete",+ "name": "instanceId",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully deleted MCP server instance and associated connected accounts.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "message": {+ "type": "string"+ },+ "deleted_connected_accounts": {+ "type": "number"+ }+ },+ "required": [+ "message",+ "deleted_connected_accounts"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The request parameters may be invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "MCP server or instance not found.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/files/list": {+ "get": {+ "summary": "List files with optional app and action filters",+ "description": "Retrieves a list of files associated with the authenticated project. Results can be filtered by toolkit and tool slugs.",+ "tags": [+ "Files"+ ],+ "operationId": "getFilesList",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Filter files by app slug. Example: \"file-converter\""+ },+ "required": false,+ "description": "Filter files by app slug. Example: \"file-converter\"",+ "name": "toolkit_slug",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Filter files by action slug. Example: \"convert-to-pdf\""+ },+ "required": false,+ "description": "Filter files by action slug. Example: \"convert-to-pdf\"",+ "name": "tool_slug",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved files",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "toolkit_slug": {+ "type": "string",+ "description": "Slug of the app where this file belongs to. Example: \"file-converter\""+ },+ "tool_slug": {+ "type": "string",+ "description": "Slug of the action where this file belongs to. Example: \"convert-to-pdf\""+ },+ "filename": {+ "type": "string",+ "description": "Name of the original file. Example: \"document.docx\""+ },+ "mimetype": {+ "type": "string",+ "description": "Mime type of the original file. Example: \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\""+ },+ "md5": {+ "type": "string",+ "description": "MD5 hash of the file for integrity verification. Example: \"d41d8cd98f00b204e9800998ecf8427e\""+ }+ },+ "required": [+ "toolkit_slug",+ "tool_slug",+ "filename",+ "mimetype",+ "md5"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/files/upload/request": {+ "post": {+ "summary": "Create presigned URL for request file upload to S3",+ "description": "Generates a presigned URL for uploading a file to S3. This endpoint handles deduplication by checking if a file with the same MD5 hash already exists.",+ "tags": [+ "Files"+ ],+ "operationId": "postFilesUploadRequest",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit_slug": {+ "type": "string",+ "description": "Slug of the app where this file belongs to. Example: \"gmail\", \"slack\", \"github\""+ },+ "tool_slug": {+ "type": "string",+ "description": "Slug of the action where this file belongs to. Example: \"GMAIL_SEND_EMAIL\", \"SLACK_UPLOAD_FILE\""+ },+ "filename": {+ "type": "string",+ "description": "Name of the original file. Example: \"quarterly_report.pdf\""+ },+ "mimetype": {+ "type": "string",+ "description": "Mime type of the original file. Example: \"application/pdf\", \"image/png\""+ },+ "md5": {+ "type": "string",+ "description": "MD5 hash of the file for deduplication and integrity verification. Example: \"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\""+ }+ },+ "required": [+ "toolkit_slug",+ "tool_slug",+ "filename",+ "mimetype",+ "md5"+ ]+ },+ "examples": {+ "Gmail Email Attachment": {+ "value": {+ "toolkit_slug": "gmail",+ "tool_slug": "GMAIL_SEND_EMAIL",+ "filename": "quarterly_report.pdf",+ "mimetype": "application/pdf",+ "md5": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"+ }+ },+ "Slack File Upload": {+ "value": {+ "toolkit_slug": "slack",+ "tool_slug": "SLACK_SEND_MESSAGE",+ "filename": "meeting_notes.docx",+ "mimetype": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",+ "md5": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"+ }+ },+ "GitHub Issue Screenshot": {+ "value": {+ "toolkit_slug": "github",+ "tool_slug": "GITHUB_CREATE_AN_ISSUE",+ "filename": "bug_screenshot.png",+ "mimetype": "image/png",+ "md5": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8"+ }+ },+ "Notion Page Image": {+ "value": {+ "toolkit_slug": "notion",+ "tool_slug": "NOTION_ADD_PAGE_CONTENT",+ "filename": "diagram.svg",+ "mimetype": "image/svg+xml",+ "md5": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"+ }+ },+ "Jira Attachment": {+ "value": {+ "toolkit_slug": "jira",+ "tool_slug": "JIRA_ADD_ATTACHMENT",+ "filename": "error_logs.txt",+ "mimetype": "text/plain",+ "md5": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully created upload URL for request file",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "ID of the request file. Example: \"req_file_9mZn4qR8sXwT\""+ },+ "key": {+ "type": "string",+ "description": "Object storage upload location. Example: \"projects/prj_xyz789/requests/slack/SLACK_UPLOAD_FILE/document_9mZn4q.docx\""+ },+ "new_presigned_url": {+ "type": "string",+ "description": "Presigned URL for upload. Example: \"https://storage.composio.dev/projects/prj_xyz789/requests/slack/document_9mZn4q.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600...\""+ },+ "newPresignedUrl": {+ "type": "string",+ "description": "[DEPRECATED] Use new_presigned_url instead. Presigned URL for upload. Example: \"https://storage.composio.dev/projects/prj_xyz789/requests/slack/document_9mZn4q.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600...\"",+ "deprecated": true+ },+ "type": {+ "type": "string",+ "enum": [+ "new"+ ],+ "description": "[DEPRECATED] Indicates this is a new file that needs to be uploaded",+ "deprecated": true+ },+ "metadata": {+ "type": "object",+ "properties": {+ "storage_backend": {+ "type": "string",+ "enum": [+ "s3",+ "azure_blob_storage"+ ],+ "description": "Storage backend used for the file. If this is azure, use `x-ms-blob-type` header to set the blob type to `BlockBlob` while uploading the file"+ }+ },+ "required": [+ "storage_backend"+ ]+ }+ },+ "required": [+ "id",+ "key",+ "new_presigned_url",+ "newPresignedUrl",+ "type",+ "metadata"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad Request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not Found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "410": {+ "description": "Gone",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Too Many Requests",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal Server Error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not Implemented",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/migration/get-nanoid": {+ "get": {+ "summary": "Get NanoId from UUID",+ "description": "Convert a legacy UUID to its corresponding NanoId for migration purposes. This endpoint facilitates the transition from UUID-based identifiers to the more compact NanoId format used in the v3 API.",+ "tags": [+ "Migration"+ ],+ "operationId": "getMigrationGetNanoid",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "uuid",+ "example": "123e4567-e89b-12d3-a456-426614174000"+ },+ "required": true,+ "description": "The legacy UUID that needs to be converted to a NanoId",+ "name": "uuid",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "CONNECTED_ACCOUNT",+ "AUTH_CONFIG",+ "TRIGGER_INSTANCE"+ ],+ "example": "CONNECTED_ACCOUNT"+ },+ "required": true,+ "description": "The type of resource that the UUID belongs to",+ "name": "type",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Your Composio API key used for authentication",+ "example": "sk_123456789abcdef"+ },+ "required": true,+ "name": "x-api-key",+ "in": "header"+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved NanoId for the given UUID",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "nanoid": {+ "type": "string",+ "minLength": 10,+ "maxLength": 10,+ "description": "The NanoId corresponding to the provided UUID. This is the new identifier that should be used in place of the legacy UUID.",+ "example": "XqXrPalt3v"+ }+ },+ "required": [+ "nanoid"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad Request - Invalid UUID or resource not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Invalid or missing API key",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not Found - The UUID does not correspond to any resource of the specified type",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "410": {+ "description": "Gone - The UUID does not correspond to any resource of the specified type",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error - An unexpected error occurred during processing",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session": {+ "post": {+ "summary": "Create a new tool router session",+ "description": "Creates a new session for the tool router feature. This endpoint initializes a new session with specified toolkits and their authentication configurations. The session provides an isolated environment for testing and managing tool routing logic with scoped MCP server access.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSession",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "user_id": {+ "type": "string",+ "minLength": 1,+ "description": "The identifier of the user who is initiating the session, ideally a unique identifier from your database like a user ID or email address",+ "example": "user_123456789"+ },+ "toolkits": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enable": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Only these specific toolkits will be enabled",+ "example": [+ "gmail",+ "slack",+ "github"+ ]+ }+ },+ "required": [+ "enable"+ ],+ "additionalProperties": false,+ "description": "Enable only specific toolkits (allowlist)"+ },+ {+ "type": "object",+ "properties": {+ "disable": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "These specific toolkits will be disabled",+ "example": [+ "gmail",+ "slack"+ ]+ }+ },+ "required": [+ "disable"+ ],+ "additionalProperties": false,+ "description": "Disable specific toolkits (denylist)"+ }+ ],+ "description": "Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive."+ },+ "auth_configs": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "authConfigId"+ },+ "description": "The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed",+ "example": {+ "gmail": "ac_1a2b3c4d5e6f",+ "slack": "ac_7g8h9i0j1k2l"+ }+ },+ "connected_accounts": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "description": "The connected accounts to use for the session. This will override the default behaviour and use the given connected account when specific toolkits are being executed",+ "example": {+ "github": "ca_3m4n5o6p7q8r"+ }+ },+ "manage_connections": {+ "type": "object",+ "properties": {+ "enable": {+ "type": "boolean",+ "nullable": true,+ "default": true,+ "description": "Whether to enable the connection manager for automatic connection handling. If true, we will provide a tool your agent can use to initiate connections to toolkits if it doesnt exist. If set to false, then you have to manage connections manually.",+ "example": true+ },+ "callback_url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to redirect to after a user completes authentication for a connected account. This allows you to handle the auth callback in your own application.",+ "example": "https://your-app.com/auth/callback"+ },+ "enable_wait_for_connections": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "When true, the COMPOSIO_WAIT_FOR_CONNECTIONS tool is available for agents to poll connection status after sharing auth URLs. Default is false (disabled). May not work reliably with GPT models.",+ "example": false+ },+ "enable_connection_removal": {+ "type": "boolean",+ "nullable": true,+ "default": true,+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected accounts. Default true."+ }+ },+ "default": {+ "enable": true,+ "enable_wait_for_connections": false,+ "enable_connection_removal": true+ },+ "additionalProperties": false,+ "description": "Configuration for connection management settings"+ },+ "tools": {+ "type": "object",+ "additionalProperties": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enable": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Only these specific tools will be available for this toolkit",+ "example": [+ "GMAIL_SEND_EMAIL",+ "GMAIL_FETCH_EMAILS"+ ]+ }+ },+ "required": [+ "enable"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "disable": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "These specific tools will be disabled for this toolkit",+ "example": [+ "SLACK_ADD_EMOJI"+ ]+ }+ },+ "required": [+ "disable"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "tags": {+ "anyOf": [+ {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ }+ },+ {+ "type": "object",+ "properties": {+ "enable": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"+ },+ "disable": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }+ }+ }+ ],+ "description": "MCP tags to filter tools. Array format is treated as enabled list. Object format supports both enabled and disabled lists.",+ "example": {+ "enable": [+ "openWorldHint"+ ],+ "disable": [+ "destructiveHint"+ ]+ }+ }+ },+ "required": [+ "tags"+ ],+ "additionalProperties": false+ }+ ]+ },+ "description": "Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit",+ "example": {+ "gmail": {+ "enable": [+ "GMAIL_SEND_EMAIL",+ "GMAIL_FETCH_EMAILS"+ ]+ },+ "slack": {+ "disable": [+ "SLACK_ADD_EMOJI"+ ]+ },+ "slack_bot": {+ "tags": {+ "enable": [+ "destructiveHint"+ ],+ "disable": [+ "openWorldHint"+ ]+ }+ }+ }+ },+ "tags": {+ "anyOf": [+ {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ }+ },+ {+ "type": "object",+ "properties": {+ "enable": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"+ },+ "disable": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }+ }+ }+ ],+ "description": "Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.",+ "example": {+ "enable": [+ "openWorldHint"+ ],+ "disable": [+ "destructiveHint"+ ]+ }+ },+ "workbench": {+ "type": "object",+ "properties": {+ "enable": {+ "type": "boolean",+ "default": true,+ "description": "Set to false to disable the workbench entirely. When disabled, no code execution tools are available in the session.",+ "example": true+ },+ "enable_proxy_execution": {+ "type": "boolean",+ "default": true,+ "description": "Whether proxy execution is enabled. When enabled, workbench can call URLs and APIs directly.",+ "example": true+ },+ "auto_offload_threshold": {+ "type": "number",+ "minimum": 0,+ "exclusiveMinimum": true,+ "description": "Character threshold for automatic offloading. When workbench response exceeds this threshold, it will be automatically offloaded. Default is picked automatically based on the response size.",+ "example": 20000+ }+ },+ "default": {+ "enable": true,+ "enable_proxy_execution": true+ },+ "additionalProperties": false,+ "description": "Configuration for workbench behavior"+ },+ "multi_account": {+ "type": "object",+ "properties": {+ "enable": {+ "type": "boolean",+ "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration.",+ "example": true+ },+ "max_accounts_per_toolkit": {+ "type": "integer",+ "minimum": 2,+ "maximum": 10,+ "description": "Maximum number of connected accounts allowed per toolkit. Must be between 2 and 10.",+ "example": 5+ },+ "require_explicit_selection": {+ "type": "boolean",+ "description": "When true, the agent must explicitly select which account to use. When false (default), the first/default account is used automatically.",+ "example": false+ }+ },+ "additionalProperties": false,+ "description": "Configure multi-account behavior. When enabled, users can connect multiple accounts per toolkit."+ },+ "experimental": {+ "type": "object",+ "properties": {+ "assistive_prompt_config": {+ "type": "object",+ "properties": {+ "user_timezone": {+ "type": "string",+ "description": "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to customize the system prompt with timezone-aware instructions.",+ "example": "America/New_York"+ }+ },+ "additionalProperties": false,+ "description": "Customize assistive prompt generation (e.g., timezone)."+ },+ "custom_toolkits": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$",+ "description": "Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.",+ "example": "ecommerce"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "Display name shown to the LLM and in search results.",+ "example": "E-Commerce API"+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 2048,+ "description": "Used for BM25 search matching and shown in toolkit connection statuses.",+ "example": "Internal e-commerce API for order management and fulfillment"+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$",+ "description": "Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).",+ "example": "GET_CUSTOMER_ORDERS"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "Human-readable display name",+ "example": "Get Customer Orders"+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120,+ "description": "Used for BM25 search matching and shown to the LLM.",+ "example": "Fetch recent orders for a customer by their email address"+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Must have type: \"object\" and a properties field.",+ "example": {+ "type": "object",+ "properties": {+ "email": {+ "type": "string",+ "description": "Customer email"+ }+ },+ "required": [+ "email"+ ]+ }+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Optional output schema for the tool response."+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema"+ ]+ },+ "minItems": 1,+ "maxItems": 100,+ "description": "Tools in this custom toolkit"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "tools"+ ]+ },+ "description": "Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth."+ },+ "custom_tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$",+ "description": "Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.",+ "example": "GET_IMPORTANT_EMAILS"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "Human-readable display name",+ "example": "Get Important Emails"+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120,+ "description": "Used for BM25 search matching and shown to the LLM.",+ "example": "Fetch emails marked as important from the last 24 hours"+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Must have type: \"object\" and a properties field.",+ "example": {+ "type": "object",+ "properties": {+ "limit": {+ "type": "number",+ "description": "Max results to return"+ }+ }+ }+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "JSON Schema describing tool output (optional)"+ },+ "extends_toolkit": {+ "type": "string",+ "minLength": 1,+ "description": "If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's auth/connection status. If omitted, the tool is standalone (no-auth).",+ "example": "gmail"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema"+ ]+ },+ "description": "Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection."+ }+ },+ "additionalProperties": false,+ "description": "Experimental features - not stable, may be modified or removed in future versions.",+ "x-experimental": true+ }+ },+ "required": [+ "user_id"+ ]+ },+ "examples": {+ "Session with all toolkits": {+ "value": {+ "user_id": "user_123456789"+ }+ },+ "Session with only specific toolkits": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ }+ }+ },+ "Session with only specific toolkits disabled": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "disable": [+ "gmail",+ "slack"+ ]+ }+ }+ },+ "Session with connection manager enabled": {+ "value": {+ "user_id": "user_123456789",+ "manage_connections": {+ "enable": true+ }+ }+ },+ "Session with connection manager and specific toolkits": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ },+ "manage_connections": {+ "enable": true+ }+ }+ },+ "Session with custom callback URL": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "github",+ "slack"+ ]+ },+ "manage_connections": {+ "enable": true,+ "callback_url": "https://your-app.com/auth/callback"+ }+ }+ },+ "Session with workbench configuration": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail"+ ]+ },+ "workbench": {+ "enable_proxy_execution": true,+ "auto_offload_threshold": 10000+ }+ }+ },+ "Session with global tags filter": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ },+ "tags": [+ "readOnlyHint",+ "idempotentHint"+ ]+ }+ },+ "Session with auth config overrides": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ },+ "auth_configs": {+ "gmail": "ac_1a2b3c4d5e6f",+ "slack": "ac_7g8h9i0j1k2l"+ }+ }+ },+ "Session with connected account overrides": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ },+ "connected_accounts": {+ "gmail": "ca_1a2b3c4d5e6f",+ "slack": "ca_7g8h9i0j1k2l"+ }+ }+ },+ "Session with comprehensive configuration": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack",+ "github"+ ]+ },+ "auth_configs": {+ "gmail": "ac_1a2b3c4d5e6f",+ "slack": "ac_7g8h9i0j1k2l"+ },+ "connected_accounts": {+ "github": "ca_3m4n5o6p7q8r"+ },+ "manage_connections": {+ "enable": true,+ "callback_url": "https://your-app.com/auth/callback"+ },+ "tools": {+ "gmail": {+ "enable": [+ "GMAIL_SEND_EMAIL",+ "GMAIL_FETCH_EMAILS"+ ]+ },+ "slack": {+ "disable": [+ "SLACK_ADD_EMOJI"+ ]+ },+ "slack_bot": {+ "tags": [+ "destructiveHint"+ ]+ }+ },+ "tags": [+ "destructiveHint",+ "idempotentHint"+ ],+ "workbench": {+ "enable_proxy_execution": true,+ "auto_offload_threshold": 10000+ }+ }+ },+ "Session with disabled toolkits and global tags": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "disable": [+ "gmail"+ ]+ },+ "tags": [+ "readOnlyHint"+ ]+ }+ }+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Session successfully created. Returns the session ID and MCP server URL for the created session.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "session_id": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The identifier of the session",+ "example": "trs_123456789"+ },+ "mcp": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "http"+ ],+ "description": "The type of the MCP server. Can be http"+ },+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The URL of the MCP server",+ "example": "https://app.composio.dev/tool_router/v3/trs_123456789/mcp"+ }+ },+ "required": [+ "type",+ "url"+ ]+ },+ "tool_router_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of available tools in this session"+ },+ "config": {+ "type": "object",+ "properties": {+ "user_id": {+ "type": "string",+ "description": "User identifier for this session"+ },+ "toolkits": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "enabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "disabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "disabled"+ ],+ "additionalProperties": false+ }+ ],+ "description": "Toolkit configuration - either enabled list or disabled list"+ },+ "auth_configs": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "authConfigId"+ },+ "description": "Auth config overrides per toolkit"+ },+ "connected_accounts": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "description": "Connected account overrides per toolkit"+ },+ "manage_connections": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "boolean",+ "default": true,+ "description": "Whether to enable the connection manager for automatic connection handling"+ },+ "callback_url": {+ "type": "string",+ "format": "uri",+ "description": "Custom callback URL for connected account auth flows"+ },+ "enable_wait_for_connections": {+ "type": "boolean",+ "default": false,+ "description": "Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models."+ },+ "enable_connection_removal": {+ "type": "boolean",+ "default": true,+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS. Default true."+ }+ },+ "description": "Manage connections configuration"+ },+ "tools": {+ "type": "object",+ "additionalProperties": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "enabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "disabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "disabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "tags": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"+ },+ "disabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }+ }+ }+ },+ "required": [+ "tags"+ ],+ "additionalProperties": false+ }+ ]+ },+ "description": "Tool-level configuration per toolkit"+ },+ "tags": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"+ },+ "disabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }+ },+ "description": "MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied."+ },+ "workbench": {+ "type": "object",+ "properties": {+ "enable": {+ "type": "boolean",+ "description": "Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed."+ },+ "proxy_execution_enabled": {+ "type": "boolean",+ "description": "Whether proxy execution is enabled in the workbench"+ },+ "auto_offload_threshold": {+ "type": "number",+ "minimum": 0,+ "exclusiveMinimum": true,+ "description": "Character threshold after which tool execution response are saved to a file in workbench. Default is 20k."+ }+ },+ "default": {+ "enable": true,+ "proxy_execution_enabled": true+ },+ "description": "Workbench configuration"+ }+ },+ "required": [+ "user_id"+ ],+ "description": "The session configuration including user, toolkits, and overrides"+ },+ "experimental": {+ "type": "object",+ "properties": {+ "assistive_prompt": {+ "type": "string",+ "description": "The assistive system prompt for the tool router session"+ },+ "custom_toolkits": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 2048+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "original_slug": {+ "type": "string",+ "description": "Original tool slug as provided by the user"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema",+ "original_slug"+ ]+ }+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "tools"+ ]+ },+ "description": "User-defined custom toolkits with grouped tools (no-auth)"+ },+ "custom_tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "extends_toolkit": {+ "type": "string",+ "minLength": 1+ },+ "original_slug": {+ "type": "string",+ "description": "Original tool slug as provided by the user"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema",+ "original_slug"+ ]+ },+ "description": "Custom tools — standalone or extending Composio toolkits"+ }+ },+ "description": "Experimental features including the generated system prompt. Only returned on session creation, not on GET.",+ "x-experimental": true+ }+ },+ "required": [+ "session_id",+ "mcp",+ "tool_router_tools",+ "config"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if the user_id format is invalid, toolkit names are invalid, or auth_config_id IDs are malformed.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The user is not authorized to create a tool router session.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/execute": {+ "post": {+ "summary": "Execute a tool within a tool router session",+ "description": "Executes a specific tool within a tool router session. The toolkit is automatically inferred from the tool slug. The tool must belong to an allowed toolkit and must not be disabled in the session configuration. This endpoint validates permissions, resolves connected accounts, and executes the tool with the session context.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdExecute",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ },+ {+ "workbench_access_key": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",+ "example": "trs_LX9uJKBinWWr"+ },+ "required": false,+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",+ "name": "session_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "tool_slug": {+ "type": "string",+ "minLength": 1,+ "description": "The unique slug identifier of the tool to execute",+ "example": "GITHUB_CREATE_AN_ISSUE"+ },+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "default": {},+ "description": "The arguments required by the tool",+ "example": {+ "repository": "octocat/Hello-World",+ "workflow_id": "main.yml",+ "ref": "main",+ "inputs": {+ "environment": "production"+ }+ }+ },+ "account": {+ "type": "string",+ "description": "Account identifier to specify which connected account to use. Use the account ID (e.g. \"coup_hurricane_dal_analytical\") or an alias. When omitted with a single account, the default is used. When omitted with multiple accounts, an error lists available accounts.",+ "example": "coup_hurricane_dal_analytical"+ }+ },+ "required": [+ "tool_slug"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed the tool. Returns execution result, logs, and status.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "The data returned by the tool execution",+ "example": {+ "message": "Hello, World!",+ "status": "success"+ }+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the execution failed, null otherwise"+ },+ "log_id": {+ "type": "string",+ "description": "Unique identifier for the execution log",+ "example": "log_abc123xyz"+ }+ },+ "required": [+ "data",+ "error",+ "log_id"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/execute_meta": {+ "post": {+ "summary": "Execute a meta tool within a tool router session",+ "description": "Executes a Composio meta tool (COMPOSIO_*) within a tool router session.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdExecuteMeta",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",+ "example": "trs_LX9uJKBinWWr"+ },+ "required": false,+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",+ "name": "session_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "enum": [+ "COMPOSIO_SEARCH_TOOLS",+ "COMPOSIO_MULTI_EXECUTE_TOOL",+ "COMPOSIO_MANAGE_CONNECTIONS",+ "COMPOSIO_WAIT_FOR_CONNECTIONS",+ "COMPOSIO_REMOTE_WORKBENCH",+ "COMPOSIO_REMOTE_BASH_TOOL",+ "COMPOSIO_GET_TOOL_SCHEMAS",+ "COMPOSIO_UPSERT_RECIPE",+ "COMPOSIO_GET_RECIPE"+ ],+ "description": "The unique slug identifier of the meta tool to execute",+ "example": "COMPOSIO_MANAGE_CONNECTIONS"+ },+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "default": {},+ "description": "The arguments required by the meta tool",+ "example": {+ "toolkits": [+ "github"+ ],+ "reinitiate_all": false+ }+ }+ },+ "required": [+ "slug"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed the meta tool. Returns execution result, logs, and status.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "The data returned by the tool execution",+ "example": {+ "message": "Hello, World!",+ "status": "success"+ }+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the execution failed, null otherwise"+ },+ "log_id": {+ "type": "string",+ "description": "Unique identifier for the execution log",+ "example": "log_abc123xyz"+ }+ },+ "required": [+ "data",+ "error",+ "log_id"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}": {+ "get": {+ "summary": "Get a tool router session by ID",+ "description": "Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "getToolRouterSessionBySessionId",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The session ID returned when creating the session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Session successfully retrieved. Returns the session details including configuration.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "session_id": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The identifier of the session",+ "example": "trs_123456789"+ },+ "mcp": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "http"+ ],+ "description": "The type of the MCP server. Can be http"+ },+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The URL of the MCP server",+ "example": "https://app.composio.dev/tool_router/v3/trs_123456789/mcp"+ }+ },+ "required": [+ "type",+ "url"+ ]+ },+ "tool_router_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of available tools in this session"+ },+ "config": {+ "type": "object",+ "properties": {+ "user_id": {+ "type": "string",+ "description": "User identifier for this session"+ },+ "toolkits": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "enabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "disabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "disabled"+ ],+ "additionalProperties": false+ }+ ],+ "description": "Toolkit configuration - either enabled list or disabled list"+ },+ "auth_configs": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "authConfigId"+ },+ "description": "Auth config overrides per toolkit"+ },+ "connected_accounts": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "description": "Connected account overrides per toolkit"+ },+ "manage_connections": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "boolean",+ "default": true,+ "description": "Whether to enable the connection manager for automatic connection handling"+ },+ "callback_url": {+ "type": "string",+ "format": "uri",+ "description": "Custom callback URL for connected account auth flows"+ },+ "enable_wait_for_connections": {+ "type": "boolean",+ "default": false,+ "description": "Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models."+ },+ "enable_connection_removal": {+ "type": "boolean",+ "default": true,+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS. Default true."+ }+ },+ "description": "Manage connections configuration"+ },+ "tools": {+ "type": "object",+ "additionalProperties": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "enabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "disabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "disabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "tags": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"+ },+ "disabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }+ }+ }+ },+ "required": [+ "tags"+ ],+ "additionalProperties": false+ }+ ]+ },+ "description": "Tool-level configuration per toolkit"+ },+ "tags": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"+ },+ "disabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }+ },+ "description": "MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied."+ },+ "workbench": {+ "type": "object",+ "properties": {+ "enable": {+ "type": "boolean",+ "description": "Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed."+ },+ "proxy_execution_enabled": {+ "type": "boolean",+ "description": "Whether proxy execution is enabled in the workbench"+ },+ "auto_offload_threshold": {+ "type": "number",+ "minimum": 0,+ "exclusiveMinimum": true,+ "description": "Character threshold after which tool execution response are saved to a file in workbench. Default is 20k."+ }+ },+ "default": {+ "enable": true,+ "proxy_execution_enabled": true+ },+ "description": "Workbench configuration"+ }+ },+ "required": [+ "user_id"+ ],+ "description": "The session configuration including user, toolkits, and overrides"+ },+ "experimental": {+ "type": "object",+ "properties": {+ "assistive_prompt": {+ "type": "string",+ "description": "The assistive system prompt for the tool router session"+ },+ "custom_toolkits": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 2048+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "original_slug": {+ "type": "string",+ "description": "Original tool slug as provided by the user"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema",+ "original_slug"+ ]+ }+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "tools"+ ]+ },+ "description": "User-defined custom toolkits with grouped tools (no-auth)"+ },+ "custom_tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "extends_toolkit": {+ "type": "string",+ "minLength": 1+ },+ "original_slug": {+ "type": "string",+ "description": "Original tool slug as provided by the user"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema",+ "original_slug"+ ]+ },+ "description": "Custom tools — standalone or extending Composio toolkits"+ }+ },+ "description": "Experimental features",+ "x-experimental": true+ }+ },+ "required": [+ "session_id",+ "mcp",+ "tool_router_tools",+ "config"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if the session_id format is invalid, please pass this in trs_ prefix format",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The session with the provided ID does not exist or has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/link": {+ "post": {+ "summary": "Create a link session for a toolkit in a tool router session",+ "description": "Initiates an authentication link session for a specific toolkit within a tool router session. Returns a link token and redirect URL that users can use to complete the OAuth flow.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdLink",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The session ID returned when creating the session",+ "example": "trs_LX9uJKBinWWr"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "string",+ "minLength": 1,+ "description": "The unique slug identifier of the toolkit to connect",+ "example": "github"+ },+ "alias": {+ "type": "string",+ "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."+ },+ "callback_url": {+ "type": "string",+ "format": "uri",+ "description": "URL where users will be redirected after completing auth",+ "example": "https://myapp.com/callback"+ }+ },+ "required": [+ "toolkit"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Successfully created link session. Returns link token, redirect URL, and connected account ID.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "link_token": {+ "type": "string",+ "description": "Token used to complete the authentication flow",+ "example": "lt_abc123xyz"+ },+ "redirect_url": {+ "type": "string",+ "format": "uri",+ "description": "The URL where users should be redirected to complete OAuth",+ "example": "https://app.composio.dev/link/lt_abc123xyz"+ },+ "connected_account_id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The unique identifier for the connected account",+ "example": "ca_abc123xyz"+ }+ },+ "required": [+ "link_token",+ "redirect_url",+ "connected_account_id"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if the toolkit slug is invalid, request parameters are malformed, or a connected account is already defined for this toolkit in the session configuration.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The session does not belong to the authenticated user.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The session does not exist, toolkit not found, or no auth config exists for the toolkit.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while creating the link session.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/proxy_execute": {+ "post": {+ "summary": "Execute proxy request within a tool router session",+ "description": "Execute any native API call on a toolkit with authentication automatically injected from Composio. This endpoint proxies HTTP requests to third-party APIs using connected account credentials resolved from the session context. Provide the toolkit slug, API endpoint, and HTTP method — Composio handles authentication injection, abstracting away credential management. Supports all HTTP methods, custom headers/query parameters, and binary request/response bodies.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdProxyExecute",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ },+ {+ "workbench_access_key": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",+ "example": "trs_LX9uJKBinWWr"+ },+ "required": false,+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",+ "name": "session_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit_slug": {+ "type": "string",+ "description": "The slug of the toolkit to use for the request",+ "example": "gmail"+ },+ "endpoint": {+ "type": "string",+ "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",+ "example": "/api/v1/resources"+ },+ "method": {+ "type": "string",+ "enum": [+ "GET",+ "POST",+ "PUT",+ "DELETE",+ "PATCH",+ "HEAD"+ ],+ "description": "The HTTP method to use for the request",+ "example": "GET"+ },+ "body": {+ "nullable": true,+ "description": "The request body (for POST, PUT, and PATCH requests)",+ "example": {+ "name": "New Resource",+ "description": "This is a new resource"+ },+ "type": "object"+ },+ "binary_body": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "URL to fetch binary content from"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"+ }+ },+ "required": [+ "url"+ ]+ },+ {+ "type": "object",+ "properties": {+ "base64": {+ "type": "string",+ "minLength": 1,+ "description": "Base64-encoded binary data"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"+ }+ },+ "required": [+ "base64"+ ]+ }+ ],+ "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."+ },+ "parameters": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Parameter name",+ "example": "x-api-key"+ },+ "value": {+ "type": "string",+ "description": "Parameter value",+ "example": "abc123def456"+ },+ "type": {+ "type": "string",+ "enum": [+ "header",+ "query"+ ],+ "description": "Parameter type (header or query)",+ "example": "header"+ }+ },+ "required": [+ "name",+ "value",+ "type"+ ]+ },+ "description": "Additional HTTP headers or query parameters to include in the request",+ "example": [+ {+ "name": "x-api-key",+ "value": "abc123def456",+ "type": "header"+ },+ {+ "name": "filter",+ "value": "active",+ "type": "query"+ }+ ]+ },+ "custom_connection_data": {+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "DCR_OAUTH",+ "API_KEY",+ "BASIC_WITH_JWT",+ "BASIC",+ "BEARER_TOKEN",+ "OAUTH1",+ "NO_AUTH",+ "SERVICE_ACCOUNT",+ "GOOGLE_SERVICE_ACCOUNT",+ "S2S_OAUTH2"+ ]+ },+ "toolkitSlug": {+ "type": "string"+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "state_prefix": {+ "type": "string",+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"+ },+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"+ },+ "access_token": {+ "type": "string"+ },+ "id_token": {+ "type": "string"+ },+ "token_type": {+ "type": "string"+ },+ "refresh_token": {+ "type": "string",+ "nullable": true+ },+ "expires_in": {+ "anyOf": [+ {+ "type": "number"+ },+ {+ "type": "string"+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "scope": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "webhook_signature": {+ "type": "string"+ },+ "authed_user": {+ "type": "object",+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {+ "type": "string"+ }+ },+ "description": "for slack user scopes"+ },+ "client_id": {+ "type": "string",+ "description": "Dynamically registered client ID"+ },+ "client_secret": {+ "type": "string",+ "description": "Dynamically registered client secret"+ },+ "client_id_issued_at": {+ "type": "number"+ },+ "client_secret_expires_at": {+ "type": "number"+ },+ "generic_api_key": {+ "type": "string"+ },+ "api_key": {+ "type": "string"+ },+ "bearer_token": {+ "type": "string"+ },+ "basic_encoded": {+ "type": "string"+ },+ "username": {+ "type": "string"+ },+ "password": {+ "type": "string"+ },+ "token": {+ "type": "string"+ },+ "oauth_token": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "expires_at": {+ "type": "string"+ }+ },+ "required": [+ "access_token"+ ],+ "additionalProperties": {}+ }+ },+ "required": [+ "authScheme",+ "toolkitSlug",+ "val"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "toolkit_slug",+ "endpoint",+ "method"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed proxy request and received response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "nullable": true,+ "description": "The response data returned from the proxied API",+ "example": {+ "id": "123",+ "name": "Resource Name",+ "created_at": "2023-01-01T00:00:00Z"+ },+ "type": "object"+ },+ "binary_data": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "description": "URL to download binary content"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type of the binary data"+ },+ "size": {+ "type": "number",+ "description": "File size in bytes"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the URL expires"+ }+ },+ "required": [+ "url",+ "content_type",+ "size"+ ],+ "description": "Binary body response data. Present when the response is a binary file."+ },+ "status": {+ "type": "number",+ "description": "The HTTP status code returned from the proxied API",+ "example": 200+ },+ "headers": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "The HTTP headers returned from the proxied API",+ "example": {+ "content-type": "application/json",+ "cache-control": "no-cache"+ }+ }+ },+ "required": [+ "status"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/toolkits": {+ "get": {+ "summary": "Get toolkits for a tool router session",+ "description": "Retrieves a cursor-paginated list of toolkits available in the tool router session. Includes toolkit metadata, composio-managed auth schemes, and connected accounts if available. Optionally filter by specific toolkit slugs.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "getToolRouterSessionBySessionIdToolkits",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The session ID returned when creating the session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 50+ },+ "required": false,+ "description": "Number of items per page, max allowed is 50",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Filter toolkits by specific slugs (comma-separated). Overrides session toolkit configuration if provided.",+ "example": "gmail,slack,github"+ },+ "required": false,+ "description": "Optional comma-separated list of toolkit slugs to filter by. If provided, only these toolkits will be returned, overriding the session configuration.",+ "name": "toolkits",+ "in": "query"+ },+ {+ "schema": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "Whether to filter by connected toolkits. If provided, only connected toolkits will be returned."+ },+ "required": false,+ "description": "Whether to filter by connected toolkits. If provided, only connected toolkits will be returned.",+ "name": "is_connected",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Search query to filter toolkits by name, slug, or description",+ "example": "gmail"+ },+ "required": false,+ "description": "Search query to filter toolkits by name, slug, or description",+ "name": "search",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Toolkits successfully retrieved. Returns a paginated list of toolkits with their metadata and connected accounts.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ToolRouterToolkitsListResponse"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if pagination parameters are invalid or the session_id format is incorrect.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The session does not belong to the authenticated user.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The session with the provided ID does not exist or has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/tools": {+ "get": {+ "summary": "List meta tools with schemas for a tool router session",+ "description": "Returns the meta tools available in a tool router session with their complete schemas. This includes request and response schemas specific to the session context.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "getToolRouterSessionBySessionIdTools",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "Tool router session ID"+ },+ "required": false,+ "description": "Tool router session ID",+ "name": "session_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully retrieved meta tools with their complete schemas.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/Tool"+ },+ "description": "List of tools with their complete schemas"+ }+ },+ "required": [+ "items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/search": {+ "post": {+ "summary": "Search for tools using a query",+ "description": "Search for tools matching a given use case query within a tool router session. Returns matching tool slugs, full tool schemas, toolkit connection statuses, and workflow guidance in a predictable format.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdSearch",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "Tool router session ID (trs_*)",+ "example": "trs_LX9uJKBinWWr"+ },+ "required": true,+ "description": "Tool router session ID (trs_*)",+ "name": "session_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "queries": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "use_case": {+ "type": "string",+ "minLength": 1,+ "description": "The task or use case to search tools for. Provide a detailed description to get the best results.",+ "example": "Send an email to [email protected] with a summary of my last 5 slack messages"+ },+ "known_fields": {+ "type": "string",+ "description": "Known field hints as key:value pairs (e.g., \"channel_name:general, user_email:[email protected]\")",+ "example": "channel_name:general"+ }+ },+ "required": [+ "use_case"+ ]+ },+ "minItems": 1,+ "maxItems": 7,+ "description": "List of search queries to execute in parallel. Up to 7 queries supported.",+ "example": [+ {+ "use_case": "Send a slack message to a channel"+ }+ ]+ },+ "model": {+ "type": "string",+ "description": "Optional model hint for search/planning behavior (e.g., \"gpt-4o\"). Ignored if invalid.",+ "example": "gpt-4o"+ }+ },+ "required": [+ "queries"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed the search. Returns matching tool slugs, schemas, connection statuses, and guidance.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "description": "Whether all searches completed successfully. False if any query failed."+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if any searches failed, null if all succeeded. Format: \"X out of Y searches failed, reasons: <details>\""+ },+ "results": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "index": {+ "type": "number",+ "description": "1-based index of the query in the request"+ },+ "use_case": {+ "type": "string",+ "description": "The use case that was searched"+ },+ "execution_guidance": {+ "type": "string",+ "description": "Guidance message about the search results, particularly when a cached plan is available"+ },+ "difficulty": {+ "type": "string",+ "description": "Task difficulty assessment (e.g., \"easy - Simple single-tool operation with known parameters\")"+ },+ "recommended_plan_steps": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Workflow steps from cached plan (only present when cached plan is available)"+ },+ "known_pitfalls": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Common pitfalls and considerations (only present when cached plan is available)"+ },+ "reference_workbench_snippets": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "description": {+ "type": "string",+ "description": "Description of what the code snippet does"+ },+ "code": {+ "type": "string",+ "description": "Python code snippet for the workbench"+ }+ },+ "required": [+ "description",+ "code"+ ]+ },+ "description": "Reference Python code snippets for processing tool responses in the workbench (only present when cached plan is available)"+ },+ "primary_tool_slugs": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of main tool slugs matching the search criteria"+ },+ "related_tool_slugs": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of related tool slugs that might be useful"+ },+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of unique toolkit slugs used by tools in this query"+ },+ "plan_id": {+ "type": "string",+ "description": "ID of cached plan if available"+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the search for this query failed, null otherwise. Always present for failed queries."+ },+ "memory": {+ "type": "object",+ "additionalProperties": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "description": "Memory data relevant to this query, grouped by app. Only present for non-cached search results."+ }+ },+ "required": [+ "index",+ "use_case",+ "primary_tool_slugs",+ "related_tool_slugs",+ "toolkits"+ ]+ },+ "description": "Per-query search results with tools, reasoning, and memory. One entry per query in request order."+ },+ "toolkit_connection_statuses": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "string",+ "description": "The toolkit slug identifier (e.g., \"gmail\", \"slack\")"+ },+ "description": {+ "type": "string",+ "description": "Description of what the toolkit does and its capabilities"+ },+ "has_active_connection": {+ "type": "boolean",+ "description": "Whether an active connection exists for this toolkit"+ },+ "connection_details": {+ "type": "object",+ "additionalProperties": {},+ "description": "Connection details including auth config and connected account IDs. Only present when has_active_connection is true."+ },+ "current_user_info": {+ "type": "object",+ "additionalProperties": {},+ "description": "Information about the currently connected user (email, name, etc.)"+ },+ "accounts": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Unique identifier for this account"+ },+ "alias": {+ "type": "string",+ "description": "User-assigned alias for this account"+ },+ "user_info": {+ "type": "object",+ "additionalProperties": {},+ "description": "Information about the connected user (email, name, etc.)"+ },+ "status": {+ "type": "string",+ "description": "Connection status (e.g., \"active\")"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp of when the account was connected"+ },+ "is_default": {+ "type": "boolean",+ "description": "Whether this is the default account for the toolkit"+ }+ },+ "required": [+ "id",+ "status",+ "created_at",+ "is_default"+ ]+ },+ "description": "List of connected accounts for this toolkit. Present when multi-account is enabled."+ },+ "account_selection": {+ "type": "string",+ "enum": [+ "required"+ ],+ "description": "When \"required\", the agent must specify which account to use. Present only when multiple accounts exist."+ },+ "status_message": {+ "type": "string",+ "description": "Human-readable message about the connection status and next steps"+ }+ },+ "required": [+ "toolkit",+ "description",+ "has_active_connection",+ "status_message"+ ]+ },+ "description": "Connection status for all toolkits mentioned across all queries, with descriptions merged in."+ },+ "tool_schemas": {+ "type": "object",+ "additionalProperties": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "string",+ "description": "The slug of the toolkit that provides this tool"+ },+ "tool_slug": {+ "type": "string",+ "description": "The slug of the tool"+ },+ "description": {+ "type": "string",+ "description": "Description of the tool"+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Input schema for the tool (only present when hasFullSchema is true)"+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Output/response schema for the tool. Only included when include_output_schemas is true."+ },+ "hasFullSchema": {+ "type": "boolean",+ "description": "Whether the full input_schema is included in this response"+ },+ "schemaRef": {+ "type": "object",+ "properties": {+ "tool": {+ "type": "string",+ "enum": [+ "COMPOSIO_GET_TOOL_SCHEMAS"+ ],+ "description": "Tool to call"+ },+ "args": {+ "type": "object",+ "properties": {+ "tool_slugs": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tool slugs to fetch schemas for"+ }+ },+ "required": [+ "tool_slugs"+ ],+ "description": "Arguments to pass to the tool"+ },+ "message": {+ "type": "string",+ "description": "Instruction message for the LLM"+ }+ },+ "required": [+ "tool",+ "args"+ ],+ "description": "Reference to fetch full schema when hasFullSchema is false"+ }+ },+ "required": [+ "toolkit",+ "tool_slug"+ ]+ },+ "description": "Deduplicated tool definitions keyed by tool_slug for O(1) lookup. Each tool appears once even if used in multiple queries."+ },+ "time_info": {+ "type": "object",+ "properties": {+ "current_time_utc": {+ "type": "string",+ "description": "Current time in ISO format (UTC)"+ },+ "current_time_utc_epoch_seconds": {+ "type": "number",+ "description": "Current time as Unix epoch timestamp in seconds"+ },+ "message": {+ "type": "string",+ "description": "Important message about time handling and timezone considerations"+ }+ },+ "required": [+ "current_time_utc",+ "current_time_utc_epoch_seconds",+ "message"+ ],+ "description": "Time information for the query"+ },+ "session": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Session identifier to be passed to subsequent meta tool calls as session_id."+ },+ "generate_id": {+ "type": "boolean",+ "description": "Whether a fresh session id was generated in this call."+ },+ "instructions": {+ "type": "string",+ "description": "LLM-facing guidance on how to reuse this session id"+ }+ },+ "required": [+ "id",+ "generate_id",+ "instructions"+ ],+ "description": "Session info for correlating meta tool calls"+ },+ "next_steps_guidance": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Combined workflow guidance covering connections, planner, and memory usage. Each element is a step instruction."+ }+ },+ "required": [+ "success",+ "error",+ "results",+ "toolkit_connection_statuses",+ "tool_schemas",+ "time_info",+ "session",+ "next_steps_guidance"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items": {+ "get": {+ "summary": "List files in a session mount",+ "description": "Lists files in a workbench session storage mount with cursor-based pagination. Use the download_url endpoint with the returned mount_relative_path to get a presigned download URL.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "getToolRouterSessionBySessionIdMountsByMountIdItems",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "ID of the storage mount",+ "example": "files"+ },+ "required": true,+ "description": "ID of the storage mount",+ "name": "mount_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "description": "Pagination cursor from the previous response next_cursor field"+ },+ "required": false,+ "description": "Pagination cursor from the previous response next_cursor field",+ "name": "cursor",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "minimum": 1,+ "maximum": 500,+ "default": 100,+ "description": "Maximum number of files to return per page (1-500)"+ },+ "required": false,+ "description": "Maximum number of files to return per page (1-500)",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "Filter results to files under this mount-relative path prefix (e.g. \"data/\" lists only files in the data/ subdirectory)",+ "example": "data/"+ },+ "required": false,+ "description": "Relative path prefix within the mount for filtering",+ "name": "mount_relative_prefix",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Files listed successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "description": "Relative file path within the mount (e.g. \"report.pdf\")"+ },+ "sandbox_mount_prefix": {+ "type": "string",+ "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ },+ "size": {+ "type": "number",+ "description": "File size in bytes"+ },+ "last_modified": {+ "type": "string",+ "description": "ISO 8601 timestamp of last modification"+ }+ },+ "required": [+ "mount_relative_path",+ "sandbox_mount_prefix",+ "size",+ "last_modified"+ ]+ },+ "description": "List of files in the mount"+ },+ "next_cursor": {+ "type": "string",+ "description": "Cursor for the next page of results. If absent, there are no more pages."+ }+ },+ "required": [+ "items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Session or mount not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url": {+ "post": {+ "summary": "Create a presigned download URL for a mount file",+ "description": "Generates a presigned download URL for a file in a workbench session mount. Accepts a relative path within the mount.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdMountsByMountIdDownloadUrl",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "ID of the storage mount",+ "example": "files"+ },+ "required": true,+ "description": "ID of the storage mount",+ "name": "mount_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "minLength": 1,+ "description": "Relative file path within the mount",+ "example": "report.pdf"+ }+ },+ "required": [+ "mount_relative_path"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Download URL created successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "download_url": {+ "type": "string",+ "description": "Presigned download URL for the file"+ },+ "mount_relative_path": {+ "type": "string",+ "description": "Relative file path within the mount (e.g. \"report.pdf\")"+ },+ "sandbox_mount_prefix": {+ "type": "string",+ "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the download URL expires"+ }+ },+ "required": [+ "download_url",+ "mount_relative_path",+ "sandbox_mount_prefix",+ "expires_at"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Session or mount not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url": {+ "post": {+ "summary": "Create a presigned upload URL for a mount file",+ "description": "Generates a presigned upload URL for uploading a file to a workbench session mount. The caller should PUT the file content directly to the returned URL.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdMountsByMountIdUploadUrl",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "ID of the storage mount",+ "example": "files"+ },+ "required": true,+ "description": "ID of the storage mount",+ "name": "mount_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "minLength": 1,+ "description": "Supports subdirectories (e.g. \"data/output.csv\", \"images/charts/chart.png\")",+ "example": "report.pdf"+ },+ "mimetype": {+ "type": "string",+ "minLength": 1,+ "description": "MIME type of the file being uploaded",+ "example": "application/pdf"+ }+ },+ "required": [+ "mount_relative_path"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Upload URL created successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "upload_url": {+ "type": "string",+ "description": "Presigned upload URL — PUT the file content here"+ },+ "mount_relative_path": {+ "type": "string",+ "description": "Relative file path within the mount (e.g. \"report.pdf\")"+ },+ "sandbox_mount_prefix": {+ "type": "string",+ "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the upload URL expires"+ }+ },+ "required": [+ "upload_url",+ "mount_relative_path",+ "sandbox_mount_prefix",+ "expires_at"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Session or mount not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete": {+ "post": {+ "summary": "Delete a file from a session mount",+ "description": "Deletes a file from a workbench session storage mount. S3 delete is idempotent — deleting a non-existent file succeeds silently.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdMountsByMountIdDelete",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "ID of the storage mount",+ "example": "files"+ },+ "required": true,+ "description": "ID of the storage mount",+ "name": "mount_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "minLength": 1,+ "description": "Relative file path within the mount",+ "example": "report.pdf"+ }+ },+ "required": [+ "mount_relative_path"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "File deleted successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "description": "Relative file path that was deleted"+ },+ "sandbox_mount_prefix": {+ "type": "string",+ "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ }+ },+ "required": [+ "mount_relative_path",+ "sandbox_mount_prefix"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Session or mount not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ },+ "/api/v3/toolkits/changelog": {+ "get": {+ "summary": "Get toolkits changelog",+ "description": "Retrieves the last 10 versions changelog for all toolkits. This endpoint provides version history and changelog information for each toolkit.",+ "tags": [+ "Toolkits"+ ],+ "operationId": "getToolkitsChangelog",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Toolkits changelog retrieved successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Toolkit slug"+ },+ "name": {+ "type": "string",+ "description": "Toolkit name"+ },+ "display_name": {+ "type": "string",+ "description": "Toolkit display name"+ },+ "versions": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "version": {+ "type": "string",+ "description": "Version identifier"+ },+ "changelog": {+ "type": "string",+ "description": "Changelog for this version"+ }+ },+ "required": [+ "version",+ "changelog"+ ]+ },+ "description": "Array of version changelogs"+ }+ },+ "required": [+ "slug",+ "name",+ "display_name",+ "versions"+ ]+ },+ "description": "List of toolkits with their changelogs"+ }+ },+ "required": [+ "items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request - invalid parameters",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - authentication required",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - the toolkits you are looking for do not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.0"+ }+ }+ }+}\ No newline at end of filediff --git a/docs/public/openapi.json b/docs/public/openapi.jsonindex 029aaa563..ad2efc49b 100644--- a/docs/public/openapi.json+++ b/docs/public/openapi.json@@ -1,9 +1,9 @@{"openapi": "3.0.0","info": {- "version": "3.0.0",- "title": "Composio Platform API",- "description": "",+ "version": "3.1.0",+ "title": "Composio Platform API v3.1",+ "description": "Composio v3.1 API — all endpoints available under /api/v3.1/. Tool endpoints default to the latest tool version.","contact": {"name": "Composio Support","url": "https://composio.dev/support",@@ -124,242 +124,6 @@}},"schemas": {- "Error": {- "type": "object",- "properties": {- "error": {- "type": "object",- "properties": {- "message": {- "type": "string"- },- "code": {- "type": "number"- },- "slug": {- "type": "string"- },- "status": {- "type": "number"- },- "request_id": {- "type": "string"- },- "suggested_fix": {- "type": "string"- },- "errors": {- "type": "array",- "items": {- "type": "string"- }- }- },- "required": [- "message",- "code",- "slug",- "status"- ]- }- },- "required": [- "error"- ]- },- "PatchConnectedAccountBody": {- "type": "object",- "properties": {- "alias": {- "type": "string",- "description": "A human-readable alias for this connected account. Pass an empty string to clear the alias. Must be unique per entity and toolkit within the project."- },- "connection": {- "type": "object",- "properties": {- "state": {- "type": "object",- "properties": {- "authScheme": {- "type": "string",- "enum": [- "BEARER_TOKEN",- "API_KEY",- "BASIC",- "BASIC_WITH_JWT",- "GOOGLE_SERVICE_ACCOUNT",- "SERVICE_ACCOUNT"- ],- "description": "The auth scheme of the connected account. Must match the connection's actual auth scheme."- },- "val": {- "type": "object",- "properties": {- "subdomain": {- "type": "string",- "nullable": true- },- "your-domain": {- "type": "string",- "nullable": true- },- "region": {- "type": "string",- "nullable": true- },- "shop": {- "type": "string",- "nullable": true- },- "account_url": {- "type": "string",- "nullable": true- },- "COMPANYDOMAIN": {- "type": "string",- "nullable": true- },- "extension": {- "type": "string",- "nullable": true- },- "form_api_base_url": {- "type": "string",- "nullable": true- },- "instanceEndpoint": {- "type": "string",- "nullable": true- },- "api_url": {- "type": "string",- "nullable": true- },- "borneo_dashboard_url": {- "type": "string",- "nullable": true- },- "proxy_username": {- "type": "string",- "nullable": true- },- "proxy_password": {- "type": "string",- "nullable": true- },- "domain": {- "type": "string",- "nullable": true- },- "version": {- "type": "string",- "nullable": true- },- "dc": {- "type": "string",- "nullable": true- },- "site_name": {- "type": "string",- "nullable": true- },- "instanceName": {- "type": "string",- "nullable": true- },- "account_id": {- "type": "string",- "nullable": true- },- "your_server": {- "type": "string",- "nullable": true- },- "server_location": {- "type": "string",- "nullable": true- },- "base_url": {- "type": "string",- "nullable": true- },- "token": {- "type": "string",- "nullable": true- },- "generic_api_key": {- "type": "string",- "nullable": true- },- "api_key": {- "type": "string",- "nullable": true- },- "bearer_token": {- "type": "string",- "nullable": true- },- "basic_encoded": {- "type": "string",- "nullable": true- },- "username": {- "type": "string",- "nullable": true- },- "password": {- "type": "string",- "nullable": true- },- "credentials_json": {- "type": "string",- "nullable": true- },- "application_id": {- "type": "string",- "nullable": true- },- "installation_id": {- "type": "string",- "nullable": true- },- "private_key": {- "type": "string",- "nullable": true- }- },- "additionalProperties": {},- "description": "Credential fields to update. Only provided fields are changed — omitted fields are preserved. Set a field to null to remove it."- }- },- "required": [- "authScheme",- "val"- ]- }- },- "required": [- "state"- ]- }- }- },- "DeprecatedToolkitInfo": {- "type": "object",- "properties": {- "toolkitId": {- "type": "string"- }- },- "required": [- "toolkitId"- ],- "description": "Deprecated toolkit ID",- "deprecated": true,- "example": {- "toolkitId": "550e8400-e29b-41d4-a716-446655440000"- }- },"Tool": {"type": "object","properties": {@@ -644,27 +408,263 @@"total_items"]},- "ToolRouterToolkitsListResponse": {+ "Error": {"type": "object","properties": {- "items": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string",- "description": "Display name of the toolkit"- },- "slug": {- "type": "string",- "description": "Unique slug identifier"- },- "enabled": {- "type": "boolean",- "description": "Whether the toolkit is enabled"- },- "is_no_auth": {+ "error": {+ "type": "object",+ "properties": {+ "message": {+ "type": "string"+ },+ "code": {+ "type": "number"+ },+ "slug": {+ "type": "string"+ },+ "status": {+ "type": "number"+ },+ "request_id": {+ "type": "string"+ },+ "suggested_fix": {+ "type": "string"+ },+ "errors": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "message",+ "code",+ "slug",+ "status"+ ]+ }+ },+ "required": [+ "error"+ ]+ },+ "PatchConnectedAccountBody": {+ "type": "object",+ "properties": {+ "alias": {+ "type": "string",+ "description": "A human-readable alias for this connected account. Pass an empty string to clear the alias. Must be unique per entity and toolkit within the project."+ },+ "connection": {+ "type": "object",+ "properties": {+ "state": {+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "BEARER_TOKEN",+ "API_KEY",+ "BASIC",+ "BASIC_WITH_JWT",+ "GOOGLE_SERVICE_ACCOUNT",+ "SERVICE_ACCOUNT"+ ],+ "description": "The auth scheme of the connected account. Must match the connection's actual auth scheme."+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string",+ "nullable": true+ },+ "your-domain": {+ "type": "string",+ "nullable": true+ },+ "region": {+ "type": "string",+ "nullable": true+ },+ "shop": {+ "type": "string",+ "nullable": true+ },+ "account_url": {+ "type": "string",+ "nullable": true+ },+ "COMPANYDOMAIN": {+ "type": "string",+ "nullable": true+ },+ "extension": {+ "type": "string",+ "nullable": true+ },+ "form_api_base_url": {+ "type": "string",+ "nullable": true+ },+ "instanceEndpoint": {+ "type": "string",+ "nullable": true+ },+ "api_url": {+ "type": "string",+ "nullable": true+ },+ "borneo_dashboard_url": {+ "type": "string",+ "nullable": true+ },+ "proxy_username": {+ "type": "string",+ "nullable": true+ },+ "proxy_password": {+ "type": "string",+ "nullable": true+ },+ "domain": {+ "type": "string",+ "nullable": true+ },+ "version": {+ "type": "string",+ "nullable": true+ },+ "dc": {+ "type": "string",+ "nullable": true+ },+ "site_name": {+ "type": "string",+ "nullable": true+ },+ "instanceName": {+ "type": "string",+ "nullable": true+ },+ "account_id": {+ "type": "string",+ "nullable": true+ },+ "your_server": {+ "type": "string",+ "nullable": true+ },+ "server_location": {+ "type": "string",+ "nullable": true+ },+ "base_url": {+ "type": "string",+ "nullable": true+ },+ "token": {+ "type": "string",+ "nullable": true+ },+ "generic_api_key": {+ "type": "string",+ "nullable": true+ },+ "api_key": {+ "type": "string",+ "nullable": true+ },+ "bearer_token": {+ "type": "string",+ "nullable": true+ },+ "basic_encoded": {+ "type": "string",+ "nullable": true+ },+ "username": {+ "type": "string",+ "nullable": true+ },+ "password": {+ "type": "string",+ "nullable": true+ },+ "credentials_json": {+ "type": "string",+ "nullable": true+ },+ "application_id": {+ "type": "string",+ "nullable": true+ },+ "installation_id": {+ "type": "string",+ "nullable": true+ },+ "private_key": {+ "type": "string",+ "nullable": true+ }+ },+ "additionalProperties": {},+ "description": "Credential fields to update. Only provided fields are changed — omitted fields are preserved. Set a field to null to remove it."+ }+ },+ "required": [+ "authScheme",+ "val"+ ]+ }+ },+ "required": [+ "state"+ ]+ }+ }+ },+ "DeprecatedToolkitInfo": {+ "type": "object",+ "properties": {+ "toolkitId": {+ "type": "string"+ }+ },+ "required": [+ "toolkitId"+ ],+ "description": "Deprecated toolkit ID",+ "deprecated": true,+ "example": {+ "toolkitId": "550e8400-e29b-41d4-a716-446655440000"+ }+ },+ "ToolRouterToolkitsListResponse": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Display name of the toolkit"+ },+ "slug": {+ "type": "string",+ "description": "Unique slug identifier"+ },+ "enabled": {+ "type": "boolean",+ "description": "Whether the toolkit is enabled"+ },+ "is_no_auth": {"type": "boolean","description": "Whether the toolkit is no-auth"},@@ -786,14 +786,14 @@"parameters": {}},"paths": {- "/api/v3/auth/session/info": {+ "/api/v3.1/tools": {"get": {- "summary": "Get current user session information",- "description": "Retrieves detailed information about the current authenticated user session, including project details, organization membership, and API key information if applicable. This endpoint is useful for verifying authentication status and retrieving contextual information about the authenticated user and their access privileges.",+ "summary": "List available tools",+ "description": "Retrieve a paginated list of available tools with comprehensive filtering, sorting and search capabilities. Use query parameters to narrow down results by toolkit, tags, or search terms.","tags": [- "Authentication"+ "Tools"],- "operationId": "getAuthSessionInfo",+ "operationId": "getTools","security": [{"ApiKeyAuth": []@@ -802,279 +802,182 @@"UserApiKeyAuth": []}],+ "parameters": [+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "The slug of the toolkit to filter by",+ "in": "query",+ "name": "toolkit_slug"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Comma-separated list of specific tool slugs to retrieve (overrides other filters)",+ "in": "query",+ "name": "tool_slugs"+ },+ {+ "schema": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "required": false,+ "description": "Comma-separated list of auth config IDs to filter tools by",+ "in": "query",+ "name": "auth_config_ids"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "true",+ "false"+ ]+ },+ "required": false,+ "description": "Filter to only show important/featured tools (set to \"true\" to enable)",+ "in": "query",+ "name": "important"+ },+ {+ "schema": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "required": false,+ "description": "Filter tools by one or more tags (can be specified multiple times)",+ "in": "query",+ "name": "tags"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Filter tools by one or more scopes (can be specified multiple times)"+ },+ "required": false,+ "description": "Array of scopes to filter tools by)",+ "name": "scopes",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Full-text search query to filter tools by name, slug, or description. Applied as a soft filter on top of other filters.",+ "in": "query",+ "name": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Deprecated: use \"query\" instead. Free-text search query to find tools by name, description, or functionality.",+ "in": "query",+ "name": "search",+ "deprecated": true+ },+ {+ "schema": {+ "type": "boolean",+ "default": true+ },+ "required": false,+ "description": "Include deprecated tools in the response",+ "in": "query",+ "name": "include_deprecated"+ },+ {+ "schema": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object representation of parsed bracket notation"+ }+ ]+ },+ "required": false,+ "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",+ "in": "query",+ "name": "toolkit_versions",+ "examples": {+ "latest_version": {+ "summary": "Latest version for all toolkits",+ "value": "latest"+ },+ "bracket_notation": {+ "summary": "Specific versions using bracket notation",+ "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"+ },+ "null_value": {+ "summary": "No version specified (uses 00000000_00)",+ "value": null+ }+ }+ },+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],"responses": {"200": {- "description": "Session is valid and active. Returns detailed information about the authenticated user, their project, and organization.",+ "description": "Successfully retrieved tools list with pagination information","content": {"application/json": {"schema": {- "type": "object",- "properties": {- "project": {- "type": "object",- "nullable": true,- "properties": {- "auto_id": {- "type": "number",- "description": "Internal auto-incrementing ID for the project",- "example": 12345- },- "id": {- "type": "string",- "description": "UUID identifier for the project",- "example": "550e8400-e29b-41d4-a716-446655440000"- },- "org_id": {- "type": "string",- "description": "Organization UUID that this project belongs to",- "example": "550e8400-e29b-41d4-a716-446655440001"- },- "name": {- "type": "string",- "description": "User-defined name for the project",- "example": "Production API"- },- "email": {- "type": "string",- "description": "Email address used for project notifications",- "example": "[email protected]"- },- "nano_id": {- "type": "string",- "format": "projectId",- "description": "Short, URL-friendly unique identifier for the project",- "example": "proj_abc123xyz456"- },- "created_at": {- "type": "string",- "description": "Date and time when the project was created",- "example": "2023-05-16T14:30:00.000Z"- },- "updated_at": {- "type": "string",- "description": "Date and time when the project was last modified",- "example": "2023-05-18T09:15:30.000Z"- },- "webhook_url": {- "type": "string",- "nullable": true,- "description": "Endpoint URL for trigger webhook notifications",- "example": "https://example.com/webhook"- },- "event_webhook_url": {- "type": "string",- "nullable": true,- "description": "Endpoint URL for event webhook notifications",- "example": "https://example.com/events"- },- "webhook_secret": {- "type": "string",- "nullable": true,- "description": "Secret used to verify webhook signatures",- "example": "whsec_a1b2c3d4e5f6g7h8i9j0"- },- "triggers_enabled": {- "type": "boolean",- "description": "Flag indicating if triggers are enabled for this project",- "example": true- },- "last_subscribed_at": {- "type": "string",- "nullable": true,- "description": "Date and time when the project last subscribed to updates",- "example": "2023-05-17T10:00:00.000Z"- },- "deleted": {- "type": "boolean",- "description": "Flag indicating if the project has been deleted",- "example": false- },- "is_new_webhook": {- "type": "boolean",- "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",- "example": true,- "deprecated": true- },- "webhook_version": {- "type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "description": "Version of the webhook configuration",- "example": "V2"- },- "org": {- "type": "object",- "properties": {- "id": {- "type": "string",- "format": "orgId",- "description": "Short, URL-friendly unique identifier for the organization",- "example": "org_abc123xyz456"- },- "name": {- "type": "string",- "description": "User-defined name for the organization",- "example": "Acme Corp"- },- "plan": {- "type": "string",- "description": "Current subscription plan level",- "example": "BUSINESS"- }- },- "required": [- "id",- "name",- "plan"- ],- "description": "Organization details"- }- },- "required": [- "auto_id",- "id",- "org_id",- "name",- "email",- "nano_id",- "created_at",- "updated_at",- "webhook_url",- "event_webhook_url",- "webhook_secret",- "triggers_enabled",- "last_subscribed_at",- "deleted",- "is_new_webhook",- "webhook_version",- "org"- ],- "description": "Details of the current active project (null if accessing with org-level credentials)"- },- "api_key": {- "type": "object",- "nullable": true,- "properties": {- "auto_id": {- "type": "number",- "description": "Internal auto-incrementing ID for the API key",- "example": 7890- },- "id": {- "type": "string",- "description": "UUID identifier for the API key",- "example": "550e8400-e29b-41d4-a716-446655440003"- },- "name": {- "type": "string",- "description": "User-defined name for the API key",- "example": "Development Key"- },- "project_id": {- "type": "string",- "format": "projectId",- "description": "Short, URL-friendly unique identifier for the associated project",- "example": "proj_abc123xyz456"- },- "org_member_id": {- "type": "string",- "description": "UUID identifier for the organization member who owns this API key",- "example": "550e8400-e29b-41d4-a716-446655440002"- },- "created_at": {- "type": "string",- "description": "Date and time when the API key was created",- "example": "2023-05-01T10:00:00.000Z"- },- "updated_at": {- "type": "string",- "description": "Date and time when the API key was last modified",- "example": "2023-05-01T10:00:00.000Z"- },- "deleted_at": {- "type": "string",- "nullable": true,- "description": "Date and time when the API key was deleted (if applicable)"- },- "key": {- "type": "string",- "description": "The actual API key value (usually only shown once during creation)",- "example": "sk_live_abc123xyz456"- },- "deleted": {- "type": "boolean",- "description": "Flag indicating if the API key has been deleted",- "example": false- }- },- "required": [- "auto_id",- "id",- "name",- "project_id",- "org_member_id",- "created_at",- "updated_at",- "deleted_at",- "key",- "deleted"- ],- "description": "Details of the API key used for authentication (null if using session auth)"- },- "org_member": {- "type": "object",- "properties": {- "id": {- "type": "string",- "description": "UUID identifier for the organization member",- "example": "550e8400-e29b-41d4-a716-446655440002"- },- "email": {- "type": "string",- "description": "Email address of the authenticated user",- "example": "[email protected]"- },- "name": {- "type": "string",- "description": "Display name of the authenticated user",- "example": "John Doe"- },- "role": {- "type": "string",- "description": "Access role of the authenticated user within the organization",- "example": "admin"- }- },- "required": [- "id",- "email",- "name",- "role"- ],- "description": "Information about the authenticated user",- "example": {- "id": "550e8400-e29b-41d4-a716-446655440002",- "email": "[email protected]",- "name": "John Doe",- "role": "admin"- }- }- },- "required": [- "project",- "api_key",- "org_member"- ],- "description": "Response containing user session information"+ "$ref": "#/components/schemas/ToolsPaginated"}}}},"400": {- "description": "Bad request. The request format may be invalid or missing required parameters.",+ "description": "Bad request - Invalid query parameters","content": {"application/json": {"schema": {@@ -1084,7 +987,7 @@}},"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid or expired.",+ "description": "Unauthorized - Authentication credentials are missing or invalid","content": {"application/json": {"schema": {@@ -1094,7 +997,7 @@}},"403": {- "description": "Forbidden. The authenticated user does not have permission to access this resource.",+ "description": "Forbidden - User does not have permission to access tools","content": {"application/json": {"schema": {@@ -1104,7 +1007,17 @@}},"404": {- "description": "Not found. The requested project, organization, or member resource could not be found.",+ "description": "Not found - The requested resource was not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Too many requests - Rate limit exceeded","content": {"application/json": {"schema": {@@ -1114,7 +1027,7 @@}},"500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -1123,17 +1036,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/auth_configs": {- "post": {- "summary": "Create new authentication configuration",- "description": "Creates a new auth config for a toolkit, allowing you to use your own OAuth credentials or API keys instead of Composio-managed authentication. This is required when you want to use custom OAuth apps (bring your own client ID/secret) or configure specific authentication parameters for a toolkit.",+ "/api/v3.1/tools/enum": {+ "get": {+ "summary": "Get tool enum list",+ "description": "Retrieve a list of all available tool enumeration values (tool slugs) from latest version of each toolkit. This endpoint returns a comma-separated string of tool slugs that can be used in other API calls.","tags": [- "Auth Configs"+ "Tools"],- "operationId": "postAuthConfigs",+ "operationId": "getToolsEnum","security": [{"ApiKeyAuth": []@@ -1142,305 +1056,33 @@"UserApiKeyAuth": []}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "toolkit": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "Toolkit slug to create auth config for"- }- },- "required": [- "slug"- ]+ "responses": {+ "200": {+ "description": "Successfully retrieved tool enum list",+ "content": {+ "application/json": {+ "schema": {+ "type": "array",+ "items": {+ "type": "string"},- "auth_config": {- "oneOf": [- {- "type": "object",- "properties": {- "type": {- "type": "string",- "enum": [- "use_composio_managed_auth"- ]- },- "name": {- "type": "string",- "description": "The name of the integration"- },- "credentials": {- "type": "object",- "properties": {- "scopes": {- "anyOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"- }- }- ]- },- "user_scopes": {- "anyOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"- }- }- ]- }- },- "default": {}- },- "tool_access_config": {- "type": "object",- "properties": {- "tools_for_connected_account_creation": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."- }- }- },- "restrict_to_following_tools": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "Use tool_access_config instead. This field will be deprecated in the future.",- "deprecated": true- },- "shared_credentials": {- "type": "object",- "additionalProperties": {},- "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",- "x-experimental": true- },- "is_enabled_for_tool_router": {- "type": "boolean",- "description": "Whether this auth config is enabled for tool router"- }- },- "required": [- "type"- ]- },- {- "type": "object",- "properties": {- "type": {- "type": "string",- "enum": [- "use_custom_auth"- ]- },- "name": {- "type": "string",- "description": "The name of the integration"- },- "authScheme": {- "type": "string",- "enum": [- "OAUTH2",- "OAUTH1",- "API_KEY",- "BASIC",- "BILLCOM_AUTH",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "BASIC_WITH_JWT",- "CALCOM_AUTH",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ]- },- "credentials": {- "type": "object",- "properties": {- "scopes": {- "anyOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"- }- }- ]- },- "user_scopes": {- "anyOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"- }- }- ]- }- },- "default": {}- },- "proxy_config": {- "type": "object",- "nullable": true,- "properties": {- "proxy_url": {- "type": "string",- "format": "uri",- "description": "The url of the auth proxy"- },- "proxy_auth_key": {- "type": "string",- "description": "The auth key for the auth proxy"- }- },- "required": [- "proxy_url"- ]- },- "restrict_to_following_tools": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "Use tool_access_config instead. This field will be deprecated in the future.",- "deprecated": true- },- "tool_access_config": {- "type": "object",- "properties": {- "tools_for_connected_account_creation": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."- }- }- },- "shared_credentials": {- "type": "object",- "additionalProperties": {},- "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",- "x-experimental": true- },- "is_enabled_for_tool_router": {- "type": "boolean",- "description": "Whether this auth config is enabled for tool router"- }- },- "required": [- "type",- "authScheme"- ]- }- ],- "default": {- "type": "use_composio_managed_auth",- "credentials": {},- "restrict_to_following_tools": []- }- }- },- "required": [- "toolkit"- ]+ "description": "JSON string containing all tool enum values from latest version of each toolkit"+ }}}- }- },- "responses": {- "201": {- "description": "Successfully created auth config",+ },+ "400": {+ "description": "Bad request - Invalid request parameters","content": {"application/json": {"schema": {- "type": "object",- "properties": {- "toolkit": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "The unique key of the toolkit"- }- },- "required": [- "slug"- ]- },- "auth_config": {- "type": "object",- "properties": {- "id": {- "type": "string",- "format": "authConfigId",- "description": "The auth config id of the toolkit (must be a valid auth config id)"- },- "auth_scheme": {- "type": "string",- "description": "The authentication mode of the toolkit"- },- "is_composio_managed": {- "type": "boolean",- "description": "Whether the auth config is managed by Composio"- },- "restrict_to_following_tools": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "The tools that the user can use with the auth config"- }- },- "required": [- "id",- "auth_scheme",- "is_composio_managed"- ]- }- },- "required": [- "toolkit",- "auth_config"- ]+ "$ref": "#/components/schemas/Error"}}}},- "400": {- "description": "Bad request",+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid","content": {"application/json": {"schema": {@@ -1449,8 +1091,8 @@}}},- "401": {- "description": "Unauthorized",+ "403": {+ "description": "Forbidden - User does not have permission to access tool enums","content": {"application/json": {"schema": {@@ -1460,7 +1102,7 @@}},"404": {- "description": "Not found",+ "description": "Not found - Tool enum list not found","content": {"application/json": {"schema": {@@ -1470,7 +1112,7 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -1479,15 +1121,18 @@}}}- }- },+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/tools/{tool_slug}": {"get": {- "summary": "List authentication configurations with optional filters",- "description": "Retrieves all auth configs for your project. Auth configs define how users authenticate with external services (OAuth, API keys, etc.). Use filters to find configs for specific toolkits or to distinguish between Composio-managed and custom configurations.",+ "summary": "Get tool by slug",+ "description": "Retrieve detailed information about a specific tool using its slug identifier. This endpoint returns full metadata about a tool including input/output parameters, versions, and toolkit information.","tags": [- "Auth Configs"+ "Tools"],- "operationId": "getAuthConfigs",+ "operationId": "getToolsByToolSlug","security": [{"ApiKeyAuth": []@@ -1497,365 +1142,656 @@}],"parameters": [- {- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "boolean"- }- ],- "description": "Whether to filter by composio managed auth configs"- },- "required": false,- "description": "Whether to filter by composio managed auth configs",- "name": "is_composio_managed",- "in": "query"- },{"schema": {"type": "string"},- "required": false,- "description": "Comma-separated list of toolkit slugs to filter auth configs by",- "in": "query",- "name": "toolkit_slug"+ "required": true,+ "description": "The unique slug identifier of the tool",+ "name": "tool_slug",+ "in": "path"},{"schema": {- "type": "string",- "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_slug instead.",- "deprecated": true+ "type": "string"},"required": false,- "description": "The app id to filter by",- "name": "deprecated_app_id",+ "description": "Optional version of the tool to retrieve",+ "name": "version","in": "query"},{"schema": {- "type": "string",- "description": "DEPRECATED: This parameter will be removed in a future version.",- "deprecated": true+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object representation of parsed bracket notation"+ }+ ]},"required": false,- "name": "deprecated_status",- "in": "query"+ "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",+ "in": "query",+ "name": "toolkit_versions",+ "examples": {+ "latest_version": {+ "summary": "Latest version for all toolkits",+ "value": "latest"+ },+ "bracket_notation": {+ "summary": "Specific versions using bracket notation",+ "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"+ },+ "null_value": {+ "summary": "No version specified (uses 00000000_00)",+ "value": null+ }+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved tool details",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Tool"+ }+ }+ }},- {- "schema": {- "type": "boolean",- "nullable": true,- "default": false,- "description": "Show disabled auth configs"- },- "required": false,- "description": "Show disabled auth configs",- "name": "show_disabled",- "in": "query"+ "400": {+ "description": "Bad request - Invalid tool slug format",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Tool with the specified slug does not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }},+ "500": {+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/tools/execute/{tool_slug}": {+ "post": {+ "summary": "Execute tool",+ "description": "Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.",+ "tags": [+ "Tools"+ ],+ "operationId": "postToolsExecuteByToolSlug",+ "security": [{- "schema": {- "type": "string",- "description": "Search auth configs by name or id"- },- "required": false,- "description": "Search auth configs by name or id",- "name": "search",- "in": "query"+ "ApiKeyAuth": []},+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [{"schema": {- "type": "number",- "nullable": true+ "type": "string"},- "required": false,- "description": "Number of items per page, max allowed is 1000",- "name": "limit",- "in": "query"+ "required": true,+ "description": "The tool slug to execute",+ "name": "tool_slug",+ "in": "path"},{"schema": {- "type": "string"+ "type": "string",+ "description": "JSON object containing custom headers to pass to LLM providers (OpenAI, Bedrock, etc.)",+ "example": "{\"x-custom-header\": \"value\", \"authorization\": \"Bearer token\"}"},"required": false,- "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",- "name": "cursor",- "in": "query"+ "name": "x-llm-gateway-headers",+ "in": "header"}],- "responses": {- "200": {- "description": "Successfully fetched auth configs",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "items": {- "type": "array",- "items": {- "type": "object",- "properties": {- "id": {- "type": "string",- "format": "authConfigId",- "description": "The unique ID of the authentication configuration"- },- "uuid": {- "type": "string",- "description": "The UUID of the authentication configuration (for backward compatibility)"- },- "type": {- "type": "string",- "enum": [- "default",- "custom"- ],- "description": "The type of the authentication configuration (custom or default)"- },- "toolkit": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "The unique identifier of the integration app"- },- "logo": {- "type": "string",- "description": "The URL to the integration app's logo image"- },- "auth_guide_url": {- "type": "string",- "nullable": true,- "description": "URL to a guide page with authentication setup instructions"- },- "auth_hint_url": {- "type": "string",- "nullable": true,- "description": "URL to a page where users can obtain or configure credentials"- }- },- "required": [- "slug",- "logo"- ],- "description": "Information about the associated integration"+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "connected_account_id": {+ "type": "string",+ "description": "Unique identifier for the connected account to use for authentication",+ "example": "ca_1a2b3c4d5e6f"+ },+ "entity_id": {+ "type": "string",+ "description": "Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations)",+ "example": "repo-123",+ "deprecated": true+ },+ "user_id": {+ "type": "string",+ "description": "User id for multi-user connected accounts (e.g. multiple users, organizations)",+ "example": "user-123"+ },+ "version": {+ "type": "string",+ "description": "Tool version to execute (defaults to \"00000000_00\" if not specified)",+ "example": "latest"+ },+ "custom_auth_params": {+ "type": "object",+ "properties": {+ "base_url": {+ "type": "string",+ "description": "The base URL (root address) what you should use while making http requests to the connected account. For example, for gmail, it would be 'https://gmail.googleapis.com'"+ },+ "parameters": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "The name of the parameter. For example, 'x-api-key', 'Content-Type', etc."+ },+ "in": {+ "type": "string",+ "enum": [+ "query",+ "header"+ ],+ "description": "The location of the parameter. Can be 'query' or 'header'."+ },+ "value": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "number"+ }+ ],+ "description": "The value of the parameter. For example, '1234567890', 'application/json', etc."+ }},- "name": {- "type": "string",- "description": "The display name of the authentication configuration"+ "required": [+ "name",+ "in",+ "value"+ ]+ }+ },+ "body": {+ "type": "object",+ "additionalProperties": {},+ "description": "The body to be sent to the endpoint for authentication. This is a JSON object. Note: This is very rarely needed and is only required by very few apps."+ }+ },+ "description": "Custom authentication parameters for tools that support parameterized authentication",+ "example": {+ "base_url": "https://api.example.com",+ "parameters": [+ {+ "name": "x-api-key",+ "value": "secret-key",+ "in": "header"+ }+ ]+ }+ },+ "custom_connection_data": {+ "description": "Custom connection data for tools that support custom connection data",+ "example": {+ "authScheme": "OAUTH2",+ "toolkitSlug": "github",+ "val": {+ "access_token": "secret-token"+ }+ },+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "DCR_OAUTH",+ "API_KEY",+ "BASIC_WITH_JWT",+ "BASIC",+ "BEARER_TOKEN",+ "OAUTH1",+ "NO_AUTH",+ "SERVICE_ACCOUNT",+ "GOOGLE_SERVICE_ACCOUNT",+ "S2S_OAUTH2"+ ]+ },+ "toolkitSlug": {+ "type": "string"+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"},- "auth_scheme": {- "type": "string",- "enum": [- "OAUTH2",- "OAUTH1",- "API_KEY",- "BASIC",- "BILLCOM_AUTH",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "BASIC_WITH_JWT",- "CALCOM_AUTH",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ],- "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"+ "your-domain": {+ "type": "string"},- "is_composio_managed": {- "type": "boolean",- "description": "Whether this authentication configuration is managed by Composio or the user"+ "region": {+ "type": "string"},- "credentials": {- "type": "object",- "additionalProperties": {},- "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"+ "shop": {+ "type": "string"},- "proxy_config": {- "type": "object",- "nullable": true,- "properties": {- "proxy_url": {- "type": "string",- "format": "uri",- "description": "The url of the auth proxy"- },- "proxy_auth_key": {- "type": "string",- "description": "The auth key for the auth proxy"- }- },- "required": [- "proxy_url"- ]+ "account_url": {+ "type": "string"},- "status": {- "type": "string",- "enum": [- "ENABLED",- "DISABLED"- ],- "description": "Current status of the authentication configuration"+ "COMPANYDOMAIN": {+ "type": "string"},- "created_by": {- "type": "string",- "description": "The identifier of the user who created the auth config"+ "extension": {+ "type": "string"},- "created_at": {- "type": "string",- "description": "ISO 8601 date-time when the auth config was created"+ "form_api_base_url": {+ "type": "string"},- "last_updated_at": {- "type": "string",- "description": "ISO 8601 date-time when the auth config was last updated"+ "instanceEndpoint": {+ "type": "string"},- "no_of_connections": {- "type": "number",- "description": "The number of active connections using this auth config"+ "api_url": {+ "type": "string"},- "expected_input_fields": {- "type": "array",- "items": {- "nullable": true,- "type": "object"- },- "description": "Fields expected during connection initialization"+ "borneo_dashboard_url": {+ "type": "string"},- "restrict_to_following_tools": {- "type": "array",- "items": {- "type": "string"- },- "description": "Use tool_access_config instead. This field will be deprecated in the future.",- "deprecated": true+ "proxy_username": {+ "type": "string"},- "tool_access_config": {- "type": "object",- "properties": {- "tools_for_connected_account_creation": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."- },- "tools_available_for_execution": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."- }- }+ "proxy_password": {+ "type": "string"},- "shared_credentials": {- "type": "object",- "additionalProperties": {},- "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",- "x-experimental": true+ "domain": {+ "type": "string"},- "is_enabled_for_tool_router": {- "type": "boolean",- "description": "Whether this auth config is enabled for tool router"+ "version": {+ "type": "string"},- "deprecated_params": {- "type": "object",- "properties": {- "default_connector_id": {- "type": "string",- "nullable": true,- "description": "Deprecated: Default connector ID"+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "state_prefix": {+ "type": "string",+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"+ },+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"+ },+ "access_token": {+ "type": "string"+ },+ "id_token": {+ "type": "string"+ },+ "token_type": {+ "type": "string"+ },+ "refresh_token": {+ "type": "string",+ "nullable": true+ },+ "expires_in": {+ "anyOf": [+ {+ "type": "number"},- "member_uuid": {- "type": "string",- "description": "Deprecated: Member UUID"+ {+ "type": "string"},- "toolkit_id": {- "type": "string",- "description": "Deprecated: Toolkit ID"+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "scope": {+ "anyOf": [+ {+ "type": "string"},- "expected_input_fields": {+ {"type": "array","items": {- "type": "object",- "additionalProperties": {}- },- "description": "Deprecated: Fields expected during connection initialization"+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "webhook_signature": {+ "type": "string"+ },+ "authed_user": {+ "type": "object",+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {+ "type": "string"}},- "required": [- "default_connector_id"- ],- "description": "DEPRECATED: This parameter will be removed in a future version.",- "deprecated": true+ "description": "for slack user scopes"+ },+ "client_id": {+ "type": "string",+ "description": "Dynamically registered client ID"+ },+ "client_secret": {+ "type": "string",+ "description": "Dynamically registered client secret"+ },+ "client_id_issued_at": {+ "type": "number"+ },+ "client_secret_expires_at": {+ "type": "number"+ },+ "generic_api_key": {+ "type": "string"+ },+ "api_key": {+ "type": "string"+ },+ "bearer_token": {+ "type": "string"+ },+ "basic_encoded": {+ "type": "string"+ },+ "username": {+ "type": "string"+ },+ "password": {+ "type": "string"+ },+ "token": {+ "type": "string"+ },+ "oauth_token": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "expires_at": {+ "type": "string"}},"required": [- "id",- "uuid",- "type",- "toolkit",- "name",- "status",- "no_of_connections",- "tool_access_config"- ]+ "access_token"+ ],+ "additionalProperties": {}}},- "next_cursor": {- "type": "string",- "nullable": true- },- "total_pages": {- "type": "number"- },- "current_page": {- "type": "number"- },- "total_items": {- "type": "number"+ "required": [+ "authScheme",+ "toolkitSlug",+ "val"+ ],+ "additionalProperties": true+ },+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "description": "Key-value pairs of arguments required by the tool (mutually exclusive with text)",+ "example": {+ "repository": "octocat/Hello-World",+ "workflow_id": "main.yml",+ "ref": "main",+ "inputs": {+ "environment": "production"+ }}},- "required": [- "items",- "total_pages",- "current_page",- "total_items"- ]- }- }- }- },- "400": {- "description": "Bad request",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"+ "text": {+ "type": "string",+ "description": "Natural language description of the task to perform (mutually exclusive with arguments)",+ "example": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment"+ },+ "allow_tracing": {+ "type": "boolean",+ "nullable": true,+ "description": "Deprecated. Enable debug tracing for tool execution (useful for debugging)",+ "deprecated": true,+ "example": false+ }}}}- },- "401": {- "description": "Unauthorized",+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed action and received response","content": {"application/json": {"schema": {- "$ref": "#/components/schemas/Error"- }- }+ "type": "object",+ "properties": {+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "Tool execution output data that varies based on the specific tool",+ "example": {+ "run_id": 12345678,+ "status": "queued",+ "created_at": "2023-01-01T12:00:00Z",+ "html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"+ }+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the tool execution was not successful (null if successful)"+ },+ "successful": {+ "type": "boolean",+ "description": "Indicates if the tool execution was successful",+ "example": true+ },+ "session_info": {+ "nullable": true,+ "description": "Optional session information for tools that return session context",+ "example": {+ "session_id": "session-12345",+ "expires_at": "2023-01-01T13:00:00Z"+ },+ "type": "object"+ },+ "log_id": {+ "type": "string",+ "description": "Unique identifier for the execution log (useful for debugging and support)",+ "example": "log_abc123def456"+ }+ },+ "required": [+ "data",+ "error",+ "successful"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid request parameters, missing required arguments, or conflicting parameters",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }}},"404": {- "description": "Not found",+ "description": "Not found - Tool or connected account not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "408": {+ "description": "Request timeout - Tool execution exceeded the maximum allowed time",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "410": {+ "description": "Gone - Tool has been deprecated and is no longer available",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large - Request or response payload exceeds size limits",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity - Invalid state of the connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Rate limit exceeded - Too many requests to the tool or underlying API","content": {"application/json": {"schema": {@@ -1865,7 +1801,37 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error - Something went wrong on the server",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "502": {+ "description": "Bad gateway - Error communicating with the tool provider API",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "503": {+ "description": "Upstream service unavailable - Tool provider API is currently down or unavailable","content": {"application/json": {"schema": {@@ -1874,17 +1840,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/auth_configs/{nanoid}": {- "get": {- "summary": "Get single authentication configuration by ID",- "description": "Retrieves detailed information about a specific authentication configuration using its unique identifier.",+ "/api/v3.1/tools/execute/{tool_slug}/input": {+ "post": {+ "summary": "Generate tool inputs from natural language",+ "description": "Uses AI to translate a natural language description into structured arguments for a specific tool. This endpoint is useful when you want to let users describe what they want to do in plain language instead of providing structured parameters.","tags": [- "Auth Configs"+ "Tools"],- "operationId": "getAuthConfigsByNanoid",+ "operationId": "postToolsExecuteByToolSlugInput","security": [{"ApiKeyAuth": []@@ -1896,239 +1863,81 @@"parameters": [{"schema": {- "type": "string",- "format": "authConfigId",- "description": "The unique identifier of the authentication configuration to retrieve"+ "type": "string"},"required": true,- "description": "The unique identifier of the authentication configuration to retrieve",- "name": "nanoid",+ "description": "The tool slug to generate inputs for",+ "name": "tool_slug","in": "path"}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "text": {+ "type": "string",+ "description": "Natural language description of what you want to accomplish with this tool",+ "example": "I need to trigger the main workflow in the octocat/Hello-World repository to deploy to production"+ },+ "custom_description": {+ "type": "string",+ "description": "Custom description of the tool to help guide the LLM in generating more accurate inputs",+ "example": "This tool triggers GitHub Actions workflows in a repository. It requires the repository name, workflow ID, and optional input parameters."+ },+ "system_prompt": {+ "type": "string",+ "description": "System prompt to control and guide the behavior of the LLM when generating inputs",+ "example": "You are an expert assistant that generates precise GitHub Actions workflow parameters. Extract exact repository names, workflow IDs, and input values from user descriptions."+ },+ "version": {+ "type": "string",+ "description": "Tool version to use when generating inputs (defaults to \"latest\" if not specified)",+ "example": "latest"+ }+ },+ "required": [+ "text"+ ]+ }+ }+ }+ },"responses": {"200": {- "description": "Successfully fetched auth config",+ "description": "Successfully generated structured inputs for the action based on natural language description","content": {"application/json": {"schema": {"type": "object","properties": {- "id": {- "type": "string",- "format": "authConfigId",- "description": "The unique ID of the authentication configuration"- },- "uuid": {- "type": "string",- "description": "The UUID of the authentication configuration (for backward compatibility)"+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "description": "Key-value pairs of arguments required by the tool to accomplish the described task",+ "example": {+ "repository": "octocat/Hello-World",+ "workflow_id": "main.yml",+ "ref": "main",+ "inputs": {+ "environment": "production"+ }+ }},- "type": {+ "error": {"type": "string",- "enum": [- "default",- "custom"- ],- "description": "The type of the authentication configuration (custom or default)"- },- "toolkit": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "The unique identifier of the integration app"- },- "logo": {- "type": "string",- "description": "The URL to the integration app's logo image"- },- "auth_guide_url": {- "type": "string",- "nullable": true,- "description": "URL to a guide page with authentication setup instructions"- },- "auth_hint_url": {- "type": "string",- "nullable": true,- "description": "URL to a page where users can obtain or configure credentials"- }- },- "required": [- "slug",- "logo"- ],- "description": "Information about the associated integration"- },- "name": {- "type": "string",- "description": "The display name of the authentication configuration"- },- "auth_scheme": {- "type": "string",- "enum": [- "OAUTH2",- "OAUTH1",- "API_KEY",- "BASIC",- "BILLCOM_AUTH",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "BASIC_WITH_JWT",- "CALCOM_AUTH",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ],- "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"- },- "is_composio_managed": {- "type": "boolean",- "description": "Whether this authentication configuration is managed by Composio or the user"- },- "credentials": {- "type": "object",- "additionalProperties": {},- "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"- },- "proxy_config": {- "type": "object",- "nullable": true,- "properties": {- "proxy_url": {- "type": "string",- "format": "uri",- "description": "The url of the auth proxy"- },- "proxy_auth_key": {- "type": "string",- "description": "The auth key for the auth proxy"- }- },- "required": [- "proxy_url"- ]- },- "status": {- "type": "string",- "enum": [- "ENABLED",- "DISABLED"- ],- "description": "Current status of the authentication configuration"- },- "created_by": {- "type": "string",- "description": "The identifier of the user who created the auth config"- },- "created_at": {- "type": "string",- "description": "ISO 8601 date-time when the auth config was created"- },- "last_updated_at": {- "type": "string",- "description": "ISO 8601 date-time when the auth config was last updated"- },- "no_of_connections": {- "type": "number",- "description": "The number of active connections using this auth config"- },- "expected_input_fields": {- "type": "array",- "items": {- "nullable": true,- "type": "object"- },- "description": "Fields expected during connection initialization"- },- "restrict_to_following_tools": {- "type": "array",- "items": {- "type": "string"- },- "description": "Use tool_access_config instead. This field will be deprecated in the future.",- "deprecated": true- },- "tool_access_config": {- "type": "object",- "properties": {- "tools_for_connected_account_creation": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."- },- "tools_available_for_execution": {- "type": "array",- "items": {- "type": "string"- },- "default": [],- "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."- }- }- },- "shared_credentials": {- "type": "object",- "additionalProperties": {},- "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",- "x-experimental": true- },- "is_enabled_for_tool_router": {- "type": "boolean",- "description": "Whether this auth config is enabled for tool router"- },- "deprecated_params": {- "type": "object",- "properties": {- "default_connector_id": {- "type": "string",- "nullable": true,- "description": "Deprecated: Default connector ID"- },- "member_uuid": {- "type": "string",- "description": "Deprecated: Member UUID"- },- "toolkit_id": {- "type": "string",- "description": "Deprecated: Toolkit ID"- },- "expected_input_fields": {- "type": "array",- "items": {- "type": "object",- "additionalProperties": {}- },- "description": "Deprecated: Fields expected during connection initialization"- }- },- "required": [- "default_connector_id"- ],- "description": "DEPRECATED: This parameter will be removed in a future version.",- "deprecated": true+ "description": "Error message if the arguments could not be generated (null if successful)",+ "example": "Unable to determine the repository name from the provided description"}- },- "required": [- "id",- "uuid",- "type",- "toolkit",- "name",- "status",- "no_of_connections",- "tool_access_config"- ]+ }}}}},"400": {- "description": "Bad request - Invalid auth config ID format",+ "description": "Bad request - Invalid input parameters or insufficient description to generate tool arguments","content": {"application/json": {"schema": {@@ -2138,7 +1947,7 @@}},"401": {- "description": "Unauthorized - Authentication required",+ "description": "Unauthorized - Authentication credentials are missing or invalid","content": {"application/json": {"schema": {@@ -2148,7 +1957,27 @@}},"404": {- "description": "Not found - Auth configuration does not exist",+ "description": "Not found - The specified tool does not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity - Invalid state of the connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Too many requests - Rate limit exceeded for natural language processing","content": {"application/json": {"schema": {@@ -2158,7 +1987,7 @@}},"500": {- "description": "Internal server error - Something went wrong on the server",+ "description": "Internal server error - AI processing failed or other server error occurred","content": {"application/json": {"schema": {@@ -2167,15 +1996,18 @@}}}- }- },- "patch": {- "summary": "Update an authentication configuration",- "description": "Modifies an existing authentication configuration with new credentials or other settings. Only specified fields will be updated.",+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/tools/execute/proxy": {+ "post": {+ "summary": "Execute proxy request",+ "description": "Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.","tags": [- "Auth Configs"+ "Tools"],- "operationId": "patchAuthConfigsByNanoid",+ "operationId": "postToolsExecuteProxy","security": [{"ApiKeyAuth": []@@ -2184,275 +2016,452 @@"UserApiKeyAuth": []}],- "parameters": [- {- "schema": {- "type": "string",- "format": "authConfigId",- "description": "The unique identifier of the authentication configuration to update"- },- "required": true,- "description": "The unique identifier of the authentication configuration to update",- "name": "nanoid",- "in": "path"- }- ],"requestBody": {"content": {"application/json": {"schema": {- "oneOf": [- {- "type": "object",- "properties": {- "type": {- "type": "string",- "enum": [- "custom"- ]- },- "name": {- "type": "string",- "minLength": 1,- "description": "The display name of the authentication configuration"- },- "credentials": {- "type": "object",- "properties": {- "scopes": {- "anyOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"- }- }- ]- },- "user_scopes": {- "anyOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"- }- }- ]- }- }- },- "proxy_config": {+ "type": "object",+ "properties": {+ "connected_account_id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The ID of the connected account to use for authentication (if not provided, will use the default account for the project)",+ "example": "ca_1a2b3c4d5e6f"+ },+ "endpoint": {+ "type": "string",+ "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",+ "example": "/api/v1/resources"+ },+ "method": {+ "type": "string",+ "enum": [+ "GET",+ "POST",+ "PUT",+ "DELETE",+ "PATCH",+ "HEAD"+ ],+ "description": "The HTTP method to use for the request",+ "example": "GET"+ },+ "body": {+ "nullable": true,+ "description": "The request body (for POST, PUT, and PATCH requests)",+ "example": {+ "name": "New Resource",+ "description": "This is a new resource"+ },+ "type": "object"+ },+ "binary_body": {+ "anyOf": [+ {"type": "object",- "nullable": true,"properties": {- "proxy_url": {+ "url": {"type": "string","format": "uri",- "description": "The url of the auth proxy"+ "description": "URL to fetch binary content from"},- "proxy_auth_key": {+ "content_type": {"type": "string",- "description": "The auth key for the auth proxy"+ "description": "Content-Type header to use for the request"}},"required": [- "proxy_url"+ "url"]},- "restrict_to_following_tools": {- "type": "array",- "items": {- "type": "string"- },- "description": "Use tool_access_config instead. This field will be deprecated in the future.",- "deprecated": true- },- "tool_access_config": {+ {"type": "object","properties": {- "tools_for_connected_account_creation": {- "type": "array",- "items": {- "type": "string"- },- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ "base64": {+ "type": "string",+ "minLength": 1,+ "description": "Base64-encoded binary data"},- "tools_available_for_execution": {- "type": "array",- "items": {- "type": "string"- },- "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"}+ },+ "required": [+ "base64"+ ]+ }+ ],+ "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."+ },+ "parameters": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Parameter name",+ "example": "x-api-key"+ },+ "value": {+ "type": "string",+ "description": "Parameter value",+ "example": "abc123def456"+ },+ "type": {+ "type": "string",+ "enum": [+ "header",+ "query"+ ],+ "description": "Parameter type (header or query)",+ "example": "header"}},- "shared_credentials": {- "type": "object",- "additionalProperties": {},- "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config."+ "required": [+ "name",+ "value",+ "type"+ ]+ },+ "description": "Additional HTTP headers or query parameters to include in the request",+ "example": [+ {+ "name": "x-api-key",+ "value": "abc123def456",+ "type": "header"},- "is_enabled_for_tool_router": {- "type": "boolean",- "description": "Whether this auth config is enabled for tool router"+ {+ "name": "filter",+ "value": "active",+ "type": "query"}- },- "required": [- "type"]},- {+ "custom_connection_data": {+ "deprecated": true,"type": "object","properties": {- "type": {+ "authScheme": {"type": "string","enum": [- "default"+ "OAUTH2",+ "DCR_OAUTH",+ "API_KEY",+ "BASIC_WITH_JWT",+ "BASIC",+ "BEARER_TOKEN",+ "OAUTH1",+ "NO_AUTH",+ "SERVICE_ACCOUNT",+ "GOOGLE_SERVICE_ACCOUNT",+ "S2S_OAUTH2"]},- "name": {- "type": "string",- "minLength": 1,- "description": "The display name of the authentication configuration"+ "toolkitSlug": {+ "type": "string"},- "scopes": {- "anyOf": [- {+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {"type": "string"},- {- "type": "array",- "items": {- "type": "string"- }- }- ]- },- "user_scopes": {- "anyOf": [- {+ "your-domain": {"type": "string"},- {- "type": "array",- "items": {- "type": "string"- }- }- ]- },- "restrict_to_following_tools": {- "type": "array",- "items": {- "type": "string"- },- "description": "Use tool_access_config instead. This field will be deprecated in the future.",- "deprecated": true- },- "tool_access_config": {- "type": "object",- "properties": {- "tools_for_connected_account_creation": {- "type": "array",- "items": {- "type": "string"- },- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ "region": {+ "type": "string"},- "tools_available_for_execution": {- "type": "array",- "items": {- "type": "string"- },- "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."- }- }- },- "shared_credentials": {- "type": "object",- "additionalProperties": {},- "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config."- },- "is_enabled_for_tool_router": {- "type": "boolean",- "description": "Whether this auth config is enabled for tool router"- }- },- "required": [- "type"- ]- }- ]- },- "examples": {- "standardUpdate": {- "summary": "Standard credential update",- "value": {- "auth_config": {- "credentials": {- "api_key": "YOUR_NEW_API_KEY",- "client_secret": "YOUR_NEW_CLIENT_SECRET"- },- "restrict_to_following_tools": [- "GMAIL_SEND_EMAIL",- "GMAIL_FETCH_EMAILS"- ]- }+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "state_prefix": {+ "type": "string",+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"+ },+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"+ },+ "access_token": {+ "type": "string"+ },+ "id_token": {+ "type": "string"+ },+ "token_type": {+ "type": "string"+ },+ "refresh_token": {+ "type": "string",+ "nullable": true+ },+ "expires_in": {+ "anyOf": [+ {+ "type": "number"+ },+ {+ "type": "string"+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "scope": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "webhook_signature": {+ "type": "string"+ },+ "authed_user": {+ "type": "object",+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {+ "type": "string"+ }+ },+ "description": "for slack user scopes"+ },+ "client_id": {+ "type": "string",+ "description": "Dynamically registered client ID"+ },+ "client_secret": {+ "type": "string",+ "description": "Dynamically registered client secret"+ },+ "client_id_issued_at": {+ "type": "number"+ },+ "client_secret_expires_at": {+ "type": "number"+ },+ "generic_api_key": {+ "type": "string"+ },+ "api_key": {+ "type": "string"+ },+ "bearer_token": {+ "type": "string"+ },+ "basic_encoded": {+ "type": "string"+ },+ "username": {+ "type": "string"+ },+ "password": {+ "type": "string"+ },+ "token": {+ "type": "string"+ },+ "oauth_token": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "expires_at": {+ "type": "string"+ }+ },+ "required": [+ "access_token"+ ],+ "additionalProperties": {}+ }+ },+ "required": [+ "authScheme",+ "toolkitSlug",+ "val"+ ],+ "additionalProperties": true}- }+ },+ "required": [+ "endpoint",+ "method"+ ]}}}},"responses": {"200": {- "description": "Successfully updated auth config",+ "description": "Successfully executed proxy request and received response","content": {"application/json": {"schema": {"type": "object",- "properties": {}- }- }- }- },- "400": {- "description": "Bad request - Invalid input or credentials format",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized - Authentication required",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found - Auth configuration does not exist",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"+ "properties": {+ "data": {+ "nullable": true,+ "description": "The response data returned from the proxied API",+ "example": {+ "id": "123",+ "name": "Resource Name",+ "created_at": "2023-01-01T00:00:00Z"+ },+ "type": "object"+ },+ "binary_data": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "description": "URL to download binary content"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type of the binary data"+ },+ "size": {+ "type": "number",+ "description": "File size in bytes"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the URL expires"+ }+ },+ "required": [+ "url",+ "content_type",+ "size"+ ],+ "description": "Binary body response data. Present when the response is a binary file."+ },+ "status": {+ "type": "number",+ "description": "The HTTP status code returned from the proxied API",+ "example": 200+ },+ "headers": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "The HTTP headers returned from the proxied API",+ "example": {+ "content-type": "application/json",+ "cache-control": "no-cache",+ "host": "api.example.com"+ }+ }+ },+ "required": [+ "status"+ ]}}}},- "500": {- "description": "Internal server error - Something went wrong on the server",+ "400": {+ "description": "Bad request - Invalid request parameters or body format","content": {"application/json": {"schema": {@@ -2460,51 +2469,9 @@}}}- }- }- },- "delete": {- "summary": "Delete an authentication configuration",- "description": "Soft-deletes an authentication configuration by marking it as deleted in the database. This operation cannot be undone.",- "tags": [- "Auth Configs"- ],- "operationId": "deleteAuthConfigsByNanoid",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "format": "authConfigId",- "description": "The unique identifier of the authentication configuration to delete"- },- "required": true,- "description": "The unique identifier of the authentication configuration to delete",- "name": "nanoid",- "in": "path"- }- ],- "responses": {- "200": {- "description": "Successfully deleted auth config",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {}- }- }- }},- "400": {- "description": "Bad request - Invalid auth config ID format",+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid","content": {"application/json": {"schema": {@@ -2513,8 +2480,8 @@}}},- "401": {- "description": "Unauthorized - Authentication required",+ "403": {+ "description": "Forbidden - Connected account does not have permission to access the requested resource","content": {"application/json": {"schema": {@@ -2524,18 +2491,17 @@}},"404": {- "description": "Auth config not found - The specified configuration does not exist or was already deleted",+ "description": "Not found - Resource not found or connected account not found","content": {"application/json": {"schema": {- "type": "object",- "properties": {}+ "$ref": "#/components/schemas/Error"}}}},- "500": {- "description": "Internal server error - Something went wrong on the server",+ "422": {+ "description": "Unprocessable entity - Invalid state of the connected account","content": {"application/json": {"schema": {@@ -2543,67 +2509,19 @@}}}- }- }- }- },- "/api/v3/auth_configs/{nanoid}/{status}": {- "patch": {- "summary": "Enable or disable an authentication configuration",- "description": "Updates the status of an authentication configuration to either enabled or disabled. Disabled configurations cannot be used for new connections.",- "tags": [- "Auth Configs"- ],- "operationId": "patchAuthConfigsByNanoidByStatus",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "format": "authConfigId",- "description": "The unique identifier of the authentication configuration to update"- },- "required": true,- "description": "The unique identifier of the authentication configuration to update",- "name": "nanoid",- "in": "path"},- {- "schema": {- "type": "string",- "enum": [- "ENABLED",- "DISABLED"- ],- "description": "The new status to set for the auth configuration"- },- "required": true,- "description": "The new status to set for the auth configuration",- "name": "status",- "in": "path"- }- ],- "responses": {- "200": {- "description": "Successfully updated auth config status",+ "429": {+ "description": "Too many requests - Rate limit exceeded on the connected account or proxy service","content": {"application/json": {"schema": {- "type": "object",- "properties": {}+ "$ref": "#/components/schemas/Error"}}}},- "400": {- "description": "Bad request - Invalid auth config ID or status value",+ "500": {+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -2612,8 +2530,8 @@}}},- "401": {- "description": "Unauthorized - Authentication required",+ "501": {+ "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme","content": {"application/json": {"schema": {@@ -2622,8 +2540,8 @@}}},- "404": {- "description": "Not found - Auth configuration does not exist",+ "502": {+ "description": "Bad gateway - Error communicating with the upstream API","content": {"application/json": {"schema": {@@ -2632,8 +2550,8 @@}}},- "500": {- "description": "Internal server error - Something went wrong on the server",+ "504": {+ "description": "Gateway timeout - Upstream API timed out","content": {"application/json": {"schema": {@@ -2642,17 +2560,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/connected_accounts": {- "get": {- "summary": "List connected accounts with optional filters",- "description": "Retrieves all connected accounts for your project. Connected accounts represent authenticated user connections to external services (e.g., a user's Gmail account, Slack workspace). Filter by toolkit, status, user ID, or auth config to find specific connections.",+ "/api/v3.1/tools/scopes/required": {+ "post": {+ "summary": "Get required scopes for tools",+ "description": "Resolves required scopes for the specified tools at a given toolkit version. All requested tools must belong to the same toolkit. Returns the flat scope union plus per-tool structured scope requirements when available.","tags": [- "Connected Accounts"+ "Tools"],- "operationId": "getConnectedAccounts",+ "operationId": "postToolsScopesRequired","security": [{"ApiKeyAuth": []@@ -2661,498 +2580,120 @@"UserApiKeyAuth": []}],- "parameters": [- {- "schema": {- "type": "array",- "nullable": true,- "items": {- "type": "string"- },- "description": "The toolkit slugs of the connected accounts"- },- "required": false,- "description": "The toolkit slugs of the connected accounts",- "name": "toolkit_slugs",- "in": "query"- },- {- "schema": {- "type": "array",- "nullable": true,- "items": {- "type": "string",- "enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1,+ "description": "Tool slugs to resolve scopes for. All tools must belong to the same toolkit.",+ "example": [+ "GMAIL_FETCH_EMAILS",+ "GMAIL_SEND_EMAIL"+ ]+ },+ "version": {+ "type": "string",+ "description": "Toolkit version to resolve scopes against for the requested toolkit. Defaults to the pinned HTTP version when omitted.",+ "example": "latest"+ }+ },+ "required": [+ "tools"]- },- "description": "The status of the connected account"- },- "required": false,- "description": "The status of the connected account",- "name": "statuses",- "in": "query"- },- {- "schema": {- "type": "string",- "nullable": true,- "description": "The cursor to paginate through the connected accounts"- },- "required": false,- "description": "The cursor to paginate through the connected accounts",- "name": "cursor",- "in": "query"- },- {- "schema": {- "type": "number",- "nullable": true,- "description": "The limit of the connected accounts to return"- },- "required": false,- "description": "The limit of the connected accounts to return",- "name": "limit",- "in": "query"- },- {- "schema": {- "type": "array",- "nullable": true,- "items": {- "type": "string"- },- "description": "The user ids of the connected accounts"- },- "required": false,- "description": "The user ids of the connected accounts",- "name": "user_ids",- "in": "query"- },- {- "schema": {- "type": "array",- "nullable": true,- "items": {- "type": "string",- "format": "authConfigId"- },- "description": "The auth config ids of the connected accounts"- },- "required": false,- "description": "The auth config ids of the connected accounts",- "name": "auth_config_ids",- "in": "query"- },- {- "schema": {- "type": "array",- "nullable": true,- "items": {- "type": "string",- "format": "connectedAccountId"- },- "description": "The connected account ids to filter by"- },- "required": false,- "description": "The connected account ids to filter by",- "name": "connected_account_ids",- "in": "query"- },- {- "schema": {- "type": "string",- "enum": [- "created_at",- "updated_at"- ],- "default": "created_at",- "description": "The order by of the connected accounts"- },- "required": false,- "description": "The order by of the connected accounts",- "name": "order_by",- "in": "query"- },- {- "schema": {- "type": "string",- "enum": [- "asc",- "desc"- ],- "default": "desc",- "description": "The order direction of the connected accounts"- },- "required": false,- "description": "The order direction of the connected accounts",- "name": "order_direction",- "in": "query"+ }+ }}- ],+ },"responses": {"200": {- "description": "Successfully retrieved connected accounts",+ "description": "Successfully retrieved scopes for the specified tools","content": {"application/json": {"schema": {"type": "object","properties": {- "items": {+ "scopes_required": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "A combined list of all unique scopes required by the specified tools",+ "example": [+ "channels:read",+ "chat:write",+ "https://www.googleapis.com/auth/gmail.modify",+ "repo",+ "user:email"+ ]+ },+ "per_tool_requirements": {"type": "array","items": {"type": "object","properties": {- "toolkit": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "The slug of the toolkit"- }- },- "required": [- "slug"- ]+ "tool": {+ "type": "string"},- "auth_config": {+ "scope_requirements": {"type": "object",+ "nullable": true,"properties": {- "id": {- "type": "string",- "format": "authConfigId",- "description": "The id of the auth config"- },- "auth_scheme": {- "type": "string",- "enum": [- "OAUTH2",- "OAUTH1",- "API_KEY",- "BASIC",- "BILLCOM_AUTH",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "BASIC_WITH_JWT",- "CALCOM_AUTH",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ],- "description": "the authScheme is part of the connection state use it there",- "deprecated": true- },- "is_composio_managed": {- "type": "boolean",- "description": "Whether the auth config is managed by Composio"- },- "is_disabled": {- "type": "boolean",- "description": "Whether the auth config is disabled"- },- "deprecated": {- "type": "object",- "properties": {- "uuid": {- "type": "string",- "format": "uuid",- "description": "The uuid of the auth config"- }- },- "required": [- "uuid"- ],- "deprecated": true+ "all_of": {+ "type": "array",+ "items": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "object",+ "properties": {+ "any_of": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1+ }+ },+ "required": [+ "any_of"+ ]+ }+ ]+ }}},"required": [- "id",- "auth_scheme",- "is_composio_managed",- "is_disabled"+ "all_of"]- },- "id": {- "type": "string",- "format": "connectedAccountId",- "description": "The id of the connection"- },- "word_id": {- "type": "string",- "nullable": true,- "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")"- },- "alias": {- "type": "string",- "nullable": true,- "description": "A user-defined alias for the connected account"- },- "user_id": {- "type": "string",- "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back",- "deprecated": true- },- "status": {- "type": "string",- "enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"- ],- "description": "The status of the connection"- },- "created_at": {- "type": "string",- "description": "The created at of the connection"- },- "updated_at": {- "type": "string",- "description": "The updated at of the connection"- },- "state": {- "description": "The state of the connection",- "type": "object",- "properties": {- "authScheme": {- "type": "string",- "enum": [- "OAUTH1",- "OAUTH2",- "API_KEY",- "BASIC",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "CALCOM_AUTH",- "BILLCOM_AUTH",- "BASIC_WITH_JWT",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ]- },- "val": {- "type": "object",- "properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"- },- "COMPANYDOMAIN": {- "type": "string"- },- "extension": {- "type": "string"- },- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"- },- "domain": {- "type": "string"- },- "version": {- "type": "string"- },- "dc": {- "type": "string"- },- "site_name": {- "type": "string"- },- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"- },- "status": {- "type": "string",- "enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"- ]- },- "oauth_token": {- "type": "string"- },- "authUri": {- "type": "string"- },- "oauth_token_secret": {- "type": "string"- },- "redirectUrl": {- "type": "string"- },- "callbackUrl": {- "type": "string"- },- "oauth_verifier": {- "type": "string"- },- "consumer_key": {- "type": "string"- },- "callback_url": {- "type": "string"- },- "error": {- "type": "string"- },- "error_description": {- "type": "string"- },- "expired_at": {- "type": "string"- }- },- "required": [- "status"- ],- "additionalProperties": true- }- },- "required": [- "authScheme",- "val"- ],- "additionalProperties": true- },- "data": {- "type": "object",- "additionalProperties": {},- "description": "This is deprecated, use `state` instead",- "deprecated": true- },- "status_reason": {- "type": "string",- "nullable": true,- "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled"- },- "is_disabled": {- "type": "boolean",- "description": "Whether the connection is disabled"- },- "test_request_endpoint": {- "type": "string",- "description": "The endpoint to make test request for verification"- },- "deprecated": {- "type": "object",- "properties": {- "labels": {- "type": "array",- "items": {- "type": "string"- },- "description": "The labels of the connection"- },- "uuid": {- "type": "string",- "format": "uuid",- "description": "The uuid of the connection"- }- },- "required": [- "labels",- "uuid"- ],- "deprecated": true}},"required": [- "toolkit",- "auth_config",- "id",- "word_id",- "alias",- "user_id",- "status",- "created_at",- "updated_at",- "state",- "data",- "status_reason",- "is_disabled"+ "tool",+ "scope_requirements"]- }- },- "next_cursor": {- "type": "string",- "nullable": true- },- "total_pages": {- "type": "number"- },- "current_page": {- "type": "number"- },- "total_items": {- "type": "number"+ },+ "description": "Per-tool structured scope requirements. Null scope_requirements marks unmigrated legacy tools."}},"required": [- "items",- "total_pages",- "current_page",- "total_items"+ "scopes_required",+ "per_tool_requirements"]}}}},"400": {- "description": "Bad request",+ "description": "Bad request - Invalid body parameters or tools from different toolkits","content": {"application/json": {"schema": {@@ -3162,7 +2703,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized - Authentication credentials are missing or invalid","content": {"application/json": {"schema": {@@ -3172,17 +2713,7 @@}},"404": {- "description": "Not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "422": {- "description": "Unprocessable entity",+ "description": "Not found - One or more tools could not be resolved for the requested version","content": {"application/json": {"schema": {@@ -3192,7 +2723,7 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -3201,15 +2732,18 @@}}}- }- },- "post": {- "summary": "Create a new connected account",- "description": "Initiates a new connection to an external service for a user. For OAuth-based toolkits, this returns a redirect URL to complete authentication. For API key-based toolkits, provide the credentials directly in the request body. Use the `user_id` field to associate the connection with a specific user in your system.",+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/auth/session/info": {+ "get": {+ "summary": "Get current user session information",+ "description": "Retrieves detailed information about the current authenticated user session, including project details, organization membership, and API key information if applicable. This endpoint is useful for verifying authentication status and retrieving contextual information about the authenticated user and their access privileges.","tags": [- "Connected Accounts"+ "Authentication"],- "operationId": "postConnectedAccounts",+ "operationId": "getAuthSessionInfo","security": [{"ApiKeyAuth": []@@ -3218,449 +2752,279 @@"UserApiKeyAuth": []}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "auth_config": {- "type": "object",- "properties": {- "id": {- "type": "string",- "format": "authConfigId",- "description": "The auth config id of the app (must be a valid auth config id)"- }- },- "required": [- "id"- ]- },- "connection": {- "type": "object",- "properties": {- "state": {- "description": "The state of the connected account",- "type": "object",- "properties": {- "authScheme": {- "type": "string",- "enum": [- "OAUTH1",- "OAUTH2",- "API_KEY",- "BASIC",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "CALCOM_AUTH",- "BILLCOM_AUTH",- "BASIC_WITH_JWT",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ]- },- "val": {- "type": "object",- "properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"- },- "COMPANYDOMAIN": {- "type": "string"- },- "extension": {- "type": "string"- },- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"- },- "domain": {- "type": "string"- },- "version": {- "type": "string"- },- "dc": {- "type": "string"- },- "site_name": {- "type": "string"- },- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"- },- "status": {- "type": "string",- "enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"- ]- },- "oauth_token": {- "type": "string"- },- "authUri": {- "type": "string"- },- "oauth_token_secret": {- "type": "string"- },- "redirectUrl": {- "type": "string"- },- "callbackUrl": {- "type": "string"- },- "oauth_verifier": {- "type": "string"- },- "consumer_key": {- "type": "string"- },- "callback_url": {- "type": "string"- },- "error": {- "type": "string"- },- "error_description": {- "type": "string"- },- "expired_at": {- "type": "string"- }- },- "required": [- "status"- ],- "additionalProperties": true- }- },- "required": [- "authScheme",- "val"- ],- "additionalProperties": true- },- "data": {- "type": "object",- "additionalProperties": {},- "description": "DEPRECATED: This parameter will be removed in a future version. Please use state instead.",- "deprecated": true- },- "user_id": {- "type": "string",- "default": "default",- "description": "The user id of the connected account"- },- "alias": {- "type": "string",- "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."- },- "callback_url": {- "type": "string",- "format": "uri",- "description": "The URL to redirect to after connection completion"- },- "redirect_uri": {- "type": "string",- "format": "uri",- "description": "DEPRECATED: This parameter will be removed in a future version. Please use callback_url instead.",- "deprecated": true- },- "deprecated_is_v1_rerouted": {- "type": "boolean",- "default": false,- "description": "DEPRECATED: This parameter will be removed in a future version.",- "deprecated": true- }- }- },- "validate_credentials": {- "type": "boolean",- "default": false,- "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme",- "x-experimental": true- }- },- "required": [- "auth_config",- "connection"- ]- }- }- }- },"responses": {- "201": {- "description": "Successfully created connected account",+ "200": {+ "description": "Session is valid and active. Returns detailed information about the authenticated user, their project, and organization.","content": {"application/json": {"schema": {"type": "object","properties": {- "id": {- "type": "string",- "format": "connectedAccountId",- "description": "The id of the connected account"- },- "connectionData": {- "description": "The connection data of the connected account",+ "project": {"type": "object",+ "nullable": true,"properties": {- "authScheme": {+ "auto_id": {+ "type": "number",+ "description": "Internal auto-incrementing ID for the project",+ "example": 12345+ },+ "id": {"type": "string",- "enum": [- "OAUTH1",- "OAUTH2",- "API_KEY",- "BASIC",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "CALCOM_AUTH",- "BILLCOM_AUTH",- "BASIC_WITH_JWT",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ]+ "description": "UUID identifier for the project",+ "example": "550e8400-e29b-41d4-a716-446655440000"},- "val": {- "type": "object",- "properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"- },- "COMPANYDOMAIN": {- "type": "string"- },- "extension": {- "type": "string"- },- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"- },- "domain": {- "type": "string"- },- "version": {- "type": "string"- },- "dc": {- "type": "string"- },- "site_name": {- "type": "string"- },- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"- },- "status": {+ "org_id": {+ "type": "string",+ "description": "Organization UUID that this project belongs to",+ "example": "550e8400-e29b-41d4-a716-446655440001"+ },+ "name": {+ "type": "string",+ "description": "User-defined name for the project",+ "example": "Production API"+ },+ "email": {+ "type": "string",+ "description": "Email address used for project notifications",+ "example": "[email protected]"+ },+ "nano_id": {+ "type": "string",+ "format": "projectId",+ "description": "Short, URL-friendly unique identifier for the project",+ "example": "proj_abc123xyz456"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when the project was created",+ "example": "2023-05-16T14:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when the project was last modified",+ "example": "2023-05-18T09:15:30.000Z"+ },+ "webhook_url": {+ "type": "string",+ "nullable": true,+ "description": "Endpoint URL for trigger webhook notifications",+ "example": "https://example.com/webhook"+ },+ "event_webhook_url": {+ "type": "string",+ "nullable": true,+ "description": "Endpoint URL for event webhook notifications",+ "example": "https://example.com/events"+ },+ "webhook_secret": {+ "type": "string",+ "nullable": true,+ "description": "Secret used to verify webhook signatures",+ "example": "whsec_a1b2c3d4e5f6g7h8i9j0"+ },+ "triggers_enabled": {+ "type": "boolean",+ "description": "Flag indicating if triggers are enabled for this project",+ "example": true+ },+ "last_subscribed_at": {+ "type": "string",+ "nullable": true,+ "description": "Date and time when the project last subscribed to updates",+ "example": "2023-05-17T10:00:00.000Z"+ },+ "deleted": {+ "type": "boolean",+ "description": "Flag indicating if the project has been deleted",+ "example": false+ },+ "is_new_webhook": {+ "type": "boolean",+ "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",+ "example": true,+ "deprecated": true+ },+ "webhook_version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Version of the webhook configuration",+ "example": "V2"+ },+ "org": {+ "type": "object",+ "properties": {+ "id": {"type": "string",- "enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"- ]- },- "oauth_token": {- "type": "string"- },- "authUri": {- "type": "string"- },- "oauth_token_secret": {- "type": "string"- },- "redirectUrl": {- "type": "string"- },- "callbackUrl": {- "type": "string"- },- "oauth_verifier": {- "type": "string"- },- "consumer_key": {- "type": "string"- },- "callback_url": {- "type": "string"- },- "error": {- "type": "string"+ "format": "orgId",+ "description": "Short, URL-friendly unique identifier for the organization",+ "example": "org_abc123xyz456"},- "error_description": {- "type": "string"+ "name": {+ "type": "string",+ "description": "User-defined name for the organization",+ "example": "Acme Corp"},- "expired_at": {- "type": "string"+ "plan": {+ "type": "string",+ "description": "Current subscription plan level",+ "example": "BUSINESS"}},"required": [- "status"+ "id",+ "name",+ "plan"],- "additionalProperties": true+ "description": "Organization details"}},"required": [- "authScheme",- "val"- ],- "additionalProperties": true- },- "status": {- "type": "string",- "enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"+ "auto_id",+ "id",+ "org_id",+ "name",+ "email",+ "nano_id",+ "created_at",+ "updated_at",+ "webhook_url",+ "event_webhook_url",+ "webhook_secret",+ "triggers_enabled",+ "last_subscribed_at",+ "deleted",+ "is_new_webhook",+ "webhook_version",+ "org"],- "description": "DEPRECATED: This field will be removed in a future version",- "deprecated": true- },- "redirect_url": {- "type": "string",- "nullable": true,- "description": "DEPRECATED: This field will be removed in a future version",- "deprecated": true- },- "redirect_uri": {- "type": "string",- "nullable": true,- "description": "DEPRECATED: This field will be removed in a future version",- "deprecated": true+ "description": "Details of the current active project (null if accessing with org-level credentials)"},- "deprecated": {+ "api_key": {"type": "object",+ "nullable": true,"properties": {- "uuid": {+ "auto_id": {+ "type": "number",+ "description": "Internal auto-incrementing ID for the API key",+ "example": 7890+ },+ "id": {"type": "string",- "format": "uuid",- "description": "The uuid of the connected account"+ "description": "UUID identifier for the API key",+ "example": "550e8400-e29b-41d4-a716-446655440003"},- "authConfigUuid": {+ "name": {"type": "string",- "format": "uuid",- "description": "The uuid of the auth config"- }- },- "required": [- "uuid",- "authConfigUuid"- ],- "description": "DEPRECATED: This field will be removed in a future version. Please use id and auth_config.id instead.",- "deprecated": true+ "description": "User-defined name for the API key",+ "example": "Development Key"+ },+ "project_id": {+ "type": "string",+ "format": "projectId",+ "description": "Short, URL-friendly unique identifier for the associated project",+ "example": "proj_abc123xyz456"+ },+ "org_member_id": {+ "type": "string",+ "description": "UUID identifier for the organization member who owns this API key",+ "example": "550e8400-e29b-41d4-a716-446655440002"+ },+ "created_at": {+ "type": "string",+ "description": "Date and time when the API key was created",+ "example": "2023-05-01T10:00:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Date and time when the API key was last modified",+ "example": "2023-05-01T10:00:00.000Z"+ },+ "deleted_at": {+ "type": "string",+ "nullable": true,+ "description": "Date and time when the API key was deleted (if applicable)"+ },+ "key": {+ "type": "string",+ "description": "The actual API key value (usually only shown once during creation)",+ "example": "sk_live_abc123xyz456"+ },+ "deleted": {+ "type": "boolean",+ "description": "Flag indicating if the API key has been deleted",+ "example": false+ }+ },+ "required": [+ "auto_id",+ "id",+ "name",+ "project_id",+ "org_member_id",+ "created_at",+ "updated_at",+ "deleted_at",+ "key",+ "deleted"+ ],+ "description": "Details of the API key used for authentication (null if using session auth)"+ },+ "org_member": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "UUID identifier for the organization member",+ "example": "550e8400-e29b-41d4-a716-446655440002"+ },+ "email": {+ "type": "string",+ "description": "Email address of the authenticated user",+ "example": "[email protected]"+ },+ "name": {+ "type": "string",+ "description": "Display name of the authenticated user",+ "example": "John Doe"+ },+ "role": {+ "type": "string",+ "description": "Access role of the authenticated user within the organization",+ "example": "admin"+ }+ },+ "required": [+ "id",+ "email",+ "name",+ "role"+ ],+ "description": "Information about the authenticated user",+ "example": {+ "id": "550e8400-e29b-41d4-a716-446655440002",+ "email": "[email protected]",+ "name": "John Doe",+ "role": "admin"+ }}},"required": [- "id",- "connectionData",- "status",- "redirect_url",- "redirect_uri",- "deprecated"- ]+ "project",+ "api_key",+ "org_member"+ ],+ "description": "Response containing user session information"}}}},"400": {- "description": "Bad request",+ "description": "Bad request. The request format may be invalid or missing required parameters.","content": {"application/json": {"schema": {@@ -3670,7 +3034,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid or expired.","content": {"application/json": {"schema": {@@ -3679,8 +3043,8 @@}}},- "404": {- "description": "Not found",+ "403": {+ "description": "Forbidden. The authenticated user does not have permission to access this resource.","content": {"application/json": {"schema": {@@ -3689,8 +3053,8 @@}}},- "500": {- "description": "Internal server error",+ "404": {+ "description": "Not found. The requested project, organization, or member resource could not be found.","content": {"application/json": {"schema": {@@ -3699,8 +3063,8 @@}}},- "501": {- "description": "Not implemented",+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.","content": {"application/json": {"schema": {@@ -3709,17 +3073,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/connected_accounts/{nanoid}": {- "get": {- "summary": "Get connected account details by ID",- "description": "Retrieves comprehensive details of a connected account, including authentication configuration, connection status, and all parameters needed for API requests.",+ "/api/v3.1/auth_configs": {+ "post": {+ "summary": "Create new authentication configuration",+ "description": "Creates a new auth config for a toolkit, allowing you to use your own OAuth credentials or API keys instead of Composio-managed authentication. This is required when you want to use custom OAuth apps (bring your own client ID/secret) or configure specific authentication parameters for a toolkit.","tags": [- "Connected Accounts"+ "Auth Configs"],- "operationId": "getConnectedAccountsByNanoid",+ "operationId": "postAuthConfigs","security": [{"ApiKeyAuth": []@@ -3728,357 +3093,305 @@"UserApiKeyAuth": []}],- "parameters": [- {- "schema": {- "type": "string",- "format": "connectedAccountId"- },- "required": true,- "description": "The unique identifier (nanoid) of the connected account",- "example": "ca_1a2b3c4d5e6f",- "name": "nanoid",- "in": "path"- }- ],- "responses": {- "200": {- "description": "Successfully retrieved connected account details with all authentication parameters and connection status",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "toolkit": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "The slug of the toolkit"- }- },- "required": [- "slug"- ]+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Toolkit slug to create auth config for"+ }},- "auth_config": {- "type": "object",- "properties": {- "id": {- "type": "string",- "format": "authConfigId",- "description": "The id of the auth config"- },- "auth_scheme": {- "type": "string",- "enum": [- "OAUTH2",- "OAUTH1",- "API_KEY",- "BASIC",- "BILLCOM_AUTH",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "BASIC_WITH_JWT",- "CALCOM_AUTH",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ],- "description": "the authScheme is part of the connection state use it there",- "deprecated": true- },- "is_composio_managed": {- "type": "boolean",- "description": "Whether the auth config is managed by Composio"- },- "is_disabled": {- "type": "boolean",- "description": "Whether the auth config is disabled"- },- "deprecated": {- "type": "object",- "properties": {- "uuid": {- "type": "string",- "format": "uuid",- "description": "The uuid of the auth config"- }+ "required": [+ "slug"+ ]+ },+ "auth_config": {+ "oneOf": [+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "use_composio_managed_auth"+ ]},- "required": [- "uuid"- ],- "deprecated": true- }- },- "required": [- "id",- "auth_scheme",- "is_composio_managed",- "is_disabled"- ]- },- "id": {- "type": "string",- "format": "connectedAccountId",- "description": "The id of the connection"- },- "word_id": {- "type": "string",- "nullable": true,- "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")"- },- "alias": {- "type": "string",- "nullable": true,- "description": "A user-defined alias for the connected account"- },- "user_id": {- "type": "string",- "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back",- "deprecated": true- },- "status": {- "type": "string",- "enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"- ],- "description": "The status of the connection"- },- "created_at": {- "type": "string",- "description": "The created at of the connection"- },- "updated_at": {- "type": "string",- "description": "The updated at of the connection"- },- "state": {- "description": "The state of the connection",- "type": "object",- "properties": {- "authScheme": {- "type": "string",- "enum": [- "OAUTH1",- "OAUTH2",- "API_KEY",- "BASIC",- "BEARER_TOKEN",- "GOOGLE_SERVICE_ACCOUNT",- "NO_AUTH",- "CALCOM_AUTH",- "BILLCOM_AUTH",- "BASIC_WITH_JWT",- "SERVICE_ACCOUNT",- "SAML",- "DCR_OAUTH",- "S2S_OAUTH2"- ]- },- "val": {- "type": "object",- "properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"- },- "COMPANYDOMAIN": {- "type": "string"- },- "extension": {- "type": "string"- },- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"+ "name": {+ "type": "string",+ "description": "The name of the integration"+ },+ "credentials": {+ "type": "object",+ "properties": {+ "scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "user_scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ }},- "domain": {+ "default": {}+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ }+ }+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {"type": "string"},- "version": {- "type": "string"+ "default": [],+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",+ "x-experimental": true+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "use_custom_auth"+ ]+ },+ "name": {+ "type": "string",+ "description": "The name of the integration"+ },+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "credentials": {+ "type": "object",+ "properties": {+ "scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "user_scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ }},- "dc": {- "type": "string"+ "default": {}+ },+ "proxy_config": {+ "type": "object",+ "nullable": true,+ "properties": {+ "proxy_url": {+ "type": "string",+ "format": "uri",+ "description": "The url of the auth proxy"+ },+ "proxy_auth_key": {+ "type": "string",+ "description": "The auth key for the auth proxy"+ }},- "site_name": {+ "required": [+ "proxy_url"+ ]+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {"type": "string"},- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"- },- "status": {- "type": "string",- "enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"- ]- },- "oauth_token": {- "type": "string"- },- "authUri": {- "type": "string"- },- "oauth_token_secret": {- "type": "string"- },- "redirectUrl": {- "type": "string"- },- "callbackUrl": {- "type": "string"- },- "oauth_verifier": {- "type": "string"- },- "consumer_key": {- "type": "string"- },- "callback_url": {- "type": "string"- },- "error": {- "type": "string"- },- "error_description": {- "type": "string"- },- "expired_at": {- "type": "string"+ "default": [],+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ }}},- "required": [- "status"- ],- "additionalProperties": true+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",+ "x-experimental": true+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ }+ },+ "required": [+ "type",+ "authScheme"+ ]+ }+ ],+ "default": {+ "type": "use_composio_managed_auth",+ "credentials": {},+ "restrict_to_following_tools": []+ }+ }+ },+ "required": [+ "toolkit"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Successfully created auth config",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The unique key of the toolkit"}},"required": [- "authScheme",- "val"- ],- "additionalProperties": true- },- "data": {- "type": "object",- "additionalProperties": {},- "description": "This is deprecated, use `state` instead",- "deprecated": true- },- "status_reason": {- "type": "string",- "nullable": true,- "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled"- },- "is_disabled": {- "type": "boolean",- "description": "Whether the connection is disabled"- },- "test_request_endpoint": {- "type": "string",- "description": "The endpoint to make test request for verification"+ "slug"+ ]},- "deprecated": {+ "auth_config": {"type": "object","properties": {- "labels": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The auth config id of the toolkit (must be a valid auth config id)"+ },+ "auth_scheme": {+ "type": "string",+ "description": "The authentication mode of the toolkit"+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether the auth config is managed by Composio"+ },+ "restrict_to_following_tools": {"type": "array","items": {"type": "string"},- "description": "The labels of the connection"- },- "uuid": {- "type": "string",- "format": "uuid",- "description": "The uuid of the connection"+ "default": [],+ "description": "The tools that the user can use with the auth config"}},"required": [- "labels",- "uuid"- ],- "deprecated": true- },- "params": {- "type": "object",- "additionalProperties": {},- "description": "The initialization data of the connection, including configuration parameters",- "deprecated": true+ "id",+ "auth_scheme",+ "is_composio_managed"+ ]}},"required": ["toolkit",- "auth_config",- "id",- "word_id",- "alias",- "user_id",- "status",- "created_at",- "updated_at",- "state",- "data",- "status_reason",- "is_disabled",- "params"+ "auth_config"]}}}},"400": {- "description": "Bad request - Invalid nanoid format or other validation error",+ "description": "Bad request","content": {"application/json": {"schema": {@@ -4088,17 +3401,7 @@}},"401": {- "description": "Unauthorized - Authentication failed",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden - Insufficient permissions to access this connected account",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -4108,7 +3411,7 @@}},"404": {- "description": "Not found - Connected account does not exist or was deleted",+ "description": "Not found","content": {"application/json": {"schema": {@@ -4118,17 +3421,7 @@}},"500": {- "description": "Internal server error - Failed to retrieve connected account details",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "501": {- "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -4137,15 +3430,16 @@}}}- }+ },+ "x-api-version": "3.1"},- "delete": {- "summary": "Delete a connected account",- "description": "Soft-deletes a connected account by marking it as deleted in the database. This prevents the account from being used for API calls but preserves the record for audit purposes.",+ "get": {+ "summary": "List authentication configurations with optional filters",+ "description": "Retrieves all auth configs for your project. Auth configs define how users authenticate with external services (OAuth, API keys, etc.). Use filters to find configs for specific toolkits or to distinguish between Composio-managed and custom configurations.","tags": [- "Connected Accounts"+ "Auth Configs"],- "operationId": "deleteConnectedAccountsByNanoid",+ "operationId": "getAuthConfigs","security": [{"ApiKeyAuth": []@@ -4157,316 +3451,343 @@"parameters": [{"schema": {- "type": "string",- "format": "connectedAccountId"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "boolean"+ }+ ],+ "description": "Whether to filter by composio managed auth configs"},- "required": true,- "description": "The unique identifier (nanoid) of the connected account",- "example": "ca_1a2b3c4d5e6f",- "name": "nanoid",- "in": "path"- }- ],- "responses": {- "200": {- "description": "Successfully deleted the connected account. The account is marked as deleted but retained in the database for historical purposes.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "success": {- "type": "boolean",- "description": "Indicates whether the connected account was successfully deleted"- }- },- "required": [- "success"- ],- "description": "Response returned after successfully deleting a connected account",- "example": {- "success": true- }- }- }- }+ "required": false,+ "description": "Whether to filter by composio managed auth configs",+ "name": "is_composio_managed",+ "in": "query"},- "400": {- "description": "Bad request - Invalid nanoid format or other validation error",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Comma-separated list of toolkit slugs to filter auth configs by",+ "in": "query",+ "name": "toolkit_slug"},- "401": {- "description": "Unauthorized - Authentication failed",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }+ {+ "schema": {+ "type": "string",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_slug instead.",+ "deprecated": true+ },+ "required": false,+ "description": "The app id to filter by",+ "name": "deprecated_app_id",+ "in": "query"},- "403": {- "description": "Forbidden - Insufficient permissions to delete this connected account",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }+ {+ "schema": {+ "type": "string",+ "description": "DEPRECATED: This parameter will be removed in a future version.",+ "deprecated": true+ },+ "required": false,+ "name": "deprecated_status",+ "in": "query"},- "404": {- "description": "Connected account not found - The specified account does not exist or has already been deleted",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {}- }- }- }+ {+ "schema": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "Show disabled auth configs"+ },+ "required": false,+ "description": "Show disabled auth configs",+ "name": "show_disabled",+ "in": "query"},- "500": {- "description": "Internal server error - Failed to delete the connected account due to a server-side issue",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- },- "patch": {- "summary": "Update a connected account",- "description": "Update a connected account. Supports updating the alias and/or credentials. Only specified fields will be updated. Set a credential field to null to remove it. Alias must be unique within the same project, entity, and toolkit scope.",- "tags": [- "Connected Accounts"- ],- "operationId": "patchConnectedAccountsByNanoid",- "security": [{- "ApiKeyAuth": []+ "schema": {+ "type": "string",+ "description": "Search auth configs by name or id"+ },+ "required": false,+ "description": "Search auth configs by name or id",+ "name": "search",+ "in": "query"},{- "UserApiKeyAuth": []- }- ],- "parameters": [+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },{"schema": {- "type": "string",- "format": "connectedAccountId"+ "type": "string"},- "required": true,- "description": "The unique identifier (nanoid) of the connected account",- "example": "ca_1a2b3c4d5e6f",- "name": "nanoid",- "in": "path"+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/PatchConnectedAccountBody"- },- "examples": {- "credentials": {- "summary": "Update credentials",- "value": {- "connection": {- "state": {- "authScheme": "BEARER_TOKEN",- "val": {- "token": "new_access_token"- }- }- }- }- },- "alias": {- "summary": "Update alias",- "value": {- "alias": "work-gmail"- }- }- }- }- }- },"responses": {"200": {- "description": "Successfully updated connected account",+ "description": "Successfully fetched auth configs","content": {"application/json": {"schema": {"type": "object","properties": {- "success": {- "type": "boolean",- "description": "Whether the update was successful"- },- "id": {- "type": "string",- "format": "connectedAccountId",- "description": "The unique identifier of the updated connected account"- },- "status": {- "type": "string",- "description": "The current status of the connected account after the update (ACTIVE, EXPIRED, INACTIVE, etc.)"- }- },- "required": [- "success",- "id",- "status"- ],- "example": {- "success": true,- "id": "ca_1a2b3c4d5e6f",- "status": "ACTIVE"- }- }- }- }- },- "400": {- "description": "Bad request - Invalid nanoid, duplicate alias, or invalid credential values",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized - Authentication failed",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden - Insufficient permissions to update this connected account",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found - Connected account does not exist or was deleted",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique ID of the authentication configuration"+ },+ "uuid": {+ "type": "string",+ "description": "The UUID of the authentication configuration (for backward compatibility)"+ },+ "type": {+ "type": "string",+ "enum": [+ "default",+ "custom"+ ],+ "description": "The type of the authentication configuration (custom or default)"+ },+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The unique identifier of the integration app"+ },+ "logo": {+ "type": "string",+ "description": "The URL to the integration app's logo image"+ },+ "auth_guide_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions"+ },+ "auth_hint_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a page where users can obtain or configure credentials"+ }+ },+ "required": [+ "slug",+ "logo"+ ],+ "description": "Information about the associated integration"+ },+ "name": {+ "type": "string",+ "description": "The display name of the authentication configuration"+ },+ "auth_scheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ],+ "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether this authentication configuration is managed by Composio or the user"+ },+ "credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"+ },+ "proxy_config": {+ "type": "object",+ "nullable": true,+ "properties": {+ "proxy_url": {+ "type": "string",+ "format": "uri",+ "description": "The url of the auth proxy"+ },+ "proxy_auth_key": {+ "type": "string",+ "description": "The auth key for the auth proxy"+ }+ },+ "required": [+ "proxy_url"+ ]+ },+ "status": {+ "type": "string",+ "enum": [+ "ENABLED",+ "DISABLED"+ ],+ "description": "Current status of the authentication configuration"+ },+ "created_by": {+ "type": "string",+ "description": "The identifier of the user who created the auth config"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 date-time when the auth config was created"+ },+ "last_updated_at": {+ "type": "string",+ "description": "ISO 8601 date-time when the auth config was last updated"+ },+ "no_of_connections": {+ "type": "number",+ "description": "The number of active connections using this auth config"+ },+ "expected_input_fields": {+ "type": "array",+ "items": {+ "nullable": true,+ "type": "object"+ },+ "description": "Fields expected during connection initialization"+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ },+ "tools_available_for_execution": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."+ }+ }+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",+ "x-experimental": true+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ },+ "deprecated_params": {+ "type": "object",+ "properties": {+ "default_connector_id": {+ "type": "string",+ "nullable": true,+ "description": "Deprecated: Default connector ID"+ },+ "member_uuid": {+ "type": "string",+ "description": "Deprecated: Member UUID"+ },+ "toolkit_id": {+ "type": "string",+ "description": "Deprecated: Toolkit ID"+ },+ "expected_input_fields": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": {}+ },+ "description": "Deprecated: Fields expected during connection initialization"+ }+ },+ "required": [+ "default_connector_id"+ ],+ "description": "DEPRECATED: This parameter will be removed in a future version.",+ "deprecated": true+ }+ },+ "required": [+ "id",+ "uuid",+ "type",+ "toolkit",+ "name",+ "status",+ "no_of_connections",+ "tool_access_config"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }}},- "500": {- "description": "Internal server error - Failed to update connected account",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },- "/api/v3/connected_accounts/{nanoId}/status": {- "patch": {- "summary": "Enable or disable a connected account",- "description": "Updates the status of a connected account to either enabled (active) or disabled (inactive). Disabled accounts cannot be used for API calls but remain in the database.",- "tags": [- "Connected Accounts"- ],- "operationId": "patchConnectedAccountsByNanoIdStatus",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "format": "connectedAccountId"- },- "required": true,- "description": "The unique identifier of the connected account",- "example": "ca_1a2b3c4d5e6f",- "name": "nanoId",- "in": "path"- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "enabled": {- "type": "boolean",- "description": "Set to true to enable the account or false to disable it"- }- },- "required": [- "enabled"- ],- "example": {- "enabled": true- }- }- }- }- },- "responses": {- "200": {- "description": "Successfully updated the connected account status. If enabled=true, the account status is set to ACTIVE; if enabled=false, the status is set to INACTIVE.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "success": {- "type": "boolean",- "description": "Indicates whether the connected account status was successfully updated"- }- },- "required": [- "success"- ],- "description": "Response returned after successfully updating a connected account status",- "example": {- "success": true- }- }- }- }- },- "400": {- "description": "Bad request - Invalid nanoid format or invalid request body",+ "400": {+ "description": "Bad request","content": {"application/json": {"schema": {@@ -4476,17 +3797,7 @@}},"401": {- "description": "Unauthorized - Authentication failed",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden - Insufficient permissions to update this connected account",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -4496,18 +3807,17 @@}},"404": {- "description": "Connected account not found - The specified account does not exist or has been deleted",+ "description": "Not found","content": {"application/json": {"schema": {- "type": "object",- "properties": {}+ "$ref": "#/components/schemas/Error"}}}},"500": {- "description": "Internal server error - Failed to update the connected account status due to a server-side issue",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -4516,17 +3826,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/connected_accounts/{nanoid}/refresh": {- "post": {- "summary": "Refresh authentication for a connected account",- "description": "Initiates a new authentication flow for a connected account when credentials have expired or become invalid. This may generate a new authentication URL for OAuth flows or refresh tokens for other auth schemes.",+ "/api/v3.1/auth_configs/{nanoid}": {+ "get": {+ "summary": "Get single authentication configuration by ID",+ "description": "Retrieves detailed information about a specific authentication configuration using its unique identifier.","tags": [- "Connected Accounts"+ "Auth Configs"],- "operationId": "postConnectedAccountsByNanoidRefresh",+ "operationId": "getAuthConfigsByNanoid","security": [{"ApiKeyAuth": []@@ -4539,48 +3850,18 @@{"schema": {"type": "string",- "format": "connectedAccountId"+ "format": "authConfigId",+ "description": "The unique identifier of the authentication configuration to retrieve"},"required": true,- "description": "The unique identifier of the connected account",- "example": "ca_1a2b3c4d5e6f",+ "description": "The unique identifier of the authentication configuration to retrieve","name": "nanoid","in": "path"- },- {- "schema": {- "type": "string",- "format": "uri"- },- "required": false,- "name": "redirect_url",- "in": "query"}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "redirect_url": {- "type": "string",- "format": "uri"- },- "validate_credentials": {- "type": "boolean",- "default": false,- "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme",- "x-experimental": true- }- }- }- }- }- },"responses": {"200": {- "description": "Successfully refreshed the connected account authentication. For OAuth flows, a new redirect URL is provided.",+ "description": "Successfully fetched auth config","content": {"application/json": {"schema": {@@ -4588,63 +3869,219 @@"properties": {"id": {"type": "string",- "description": "The unique identifier of the connected account"+ "format": "authConfigId",+ "description": "The unique ID of the authentication configuration"},- "status": {+ "uuid": {+ "type": "string",+ "description": "The UUID of the authentication configuration (for backward compatibility)"+ },+ "type": {"type": "string","enum": [- "INITIALIZING",- "INITIATED",- "ACTIVE",- "FAILED",- "EXPIRED",- "INACTIVE"+ "default",+ "custom"],- "description": "The current status of the connected account (e.g., active, pending, failed)"+ "description": "The type of the authentication configuration (custom or default)"},- "redirect_url": {+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The unique identifier of the integration app"+ },+ "logo": {+ "type": "string",+ "description": "The URL to the integration app's logo image"+ },+ "auth_guide_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions"+ },+ "auth_hint_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a page where users can obtain or configure credentials"+ }+ },+ "required": [+ "slug",+ "logo"+ ],+ "description": "Information about the associated integration"+ },+ "name": {+ "type": "string",+ "description": "The display name of the authentication configuration"+ },+ "auth_scheme": {"type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ],+ "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether this authentication configuration is managed by Composio or the user"+ },+ "credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"+ },+ "proxy_config": {+ "type": "object","nullable": true,- "description": "The URL to which the user should be redirected to complete the authentication process (null for auth schemes that do not require redirection)"- }- },- "required": [- "id",- "status",- "redirect_url"- ],- "description": "Response schema for a refreshed connected account authentication",- "example": {- "id": "ca_1a2b3c4d5e6f",- "status": "ACTIVE",- "redirect_url": "https://app.example.com/oauth/callback"- }- }- }- }- },- "400": {- "description": "Bad request - Invalid nanoid format or the account cannot be refreshed in its current state",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized - Authentication failed",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"+ "properties": {+ "proxy_url": {+ "type": "string",+ "format": "uri",+ "description": "The url of the auth proxy"+ },+ "proxy_auth_key": {+ "type": "string",+ "description": "The auth key for the auth proxy"+ }+ },+ "required": [+ "proxy_url"+ ]+ },+ "status": {+ "type": "string",+ "enum": [+ "ENABLED",+ "DISABLED"+ ],+ "description": "Current status of the authentication configuration"+ },+ "created_by": {+ "type": "string",+ "description": "The identifier of the user who created the auth config"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 date-time when the auth config was created"+ },+ "last_updated_at": {+ "type": "string",+ "description": "ISO 8601 date-time when the auth config was last updated"+ },+ "no_of_connections": {+ "type": "number",+ "description": "The number of active connections using this auth config"+ },+ "expected_input_fields": {+ "type": "array",+ "items": {+ "nullable": true,+ "type": "object"+ },+ "description": "Fields expected during connection initialization"+ },+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ },+ "tools_available_for_execution": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": [],+ "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."+ }+ }+ },+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",+ "x-experimental": true+ },+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ },+ "deprecated_params": {+ "type": "object",+ "properties": {+ "default_connector_id": {+ "type": "string",+ "nullable": true,+ "description": "Deprecated: Default connector ID"+ },+ "member_uuid": {+ "type": "string",+ "description": "Deprecated: Member UUID"+ },+ "toolkit_id": {+ "type": "string",+ "description": "Deprecated: Toolkit ID"+ },+ "expected_input_fields": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": {}+ },+ "description": "Deprecated: Fields expected during connection initialization"+ }+ },+ "required": [+ "default_connector_id"+ ],+ "description": "DEPRECATED: This parameter will be removed in a future version.",+ "deprecated": true+ }+ },+ "required": [+ "id",+ "uuid",+ "type",+ "toolkit",+ "name",+ "status",+ "no_of_connections",+ "tool_access_config"+ ]}}}},- "403": {- "description": "Forbidden - Insufficient permissions to refresh this connected account",+ "400": {+ "description": "Bad request - Invalid auth config ID format","content": {"application/json": {"schema": {@@ -4653,8 +4090,8 @@}}},- "404": {- "description": "Not found - Connected account does not exist or was deleted",+ "401": {+ "description": "Unauthorized - Authentication required","content": {"application/json": {"schema": {@@ -4663,8 +4100,8 @@}}},- "500": {- "description": "Internal server error - Failed to refresh the connected account authentication",+ "404": {+ "description": "Not found - Auth configuration does not exist","content": {"application/json": {"schema": {@@ -4673,8 +4110,8 @@}}},- "501": {- "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",+ "500": {+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -4683,17 +4120,16 @@}}}- }- }- },- "/api/v3/connected_accounts/link": {- "post": {- "summary": "Create a new auth link session",- "description": "Creates a new authentication link session that users can use to connect their accounts",+ },+ "x-api-version": "3.1"+ },+ "patch": {+ "summary": "Update an authentication configuration",+ "description": "Modifies an existing authentication configuration with new credentials or other settings. Only specified fields will be updated.","tags": [- "Connected Accounts"+ "Auth Configs"],- "operationId": "postConnectedAccountsLink",+ "operationId": "patchAuthConfigsByNanoid","security": [{"ApiKeyAuth": []@@ -4702,179 +4138,156 @@"UserApiKeyAuth": []}],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique identifier of the authentication configuration to update"+ },+ "required": true,+ "description": "The unique identifier of the authentication configuration to update",+ "name": "nanoid",+ "in": "path"+ }+ ],"requestBody": {"content": {"application/json": {"schema": {- "type": "object",- "properties": {- "auth_config_id": {- "type": "string",- "format": "authConfigId",- "description": "The auth config id to create a link for"- },- "user_id": {- "type": "string",- "minLength": 1,- "description": "The user id to create a link for"- },- "alias": {- "type": "string",- "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."- },- "callback_url": {- "type": "string",- "description": "The callback url to create a link for"- },- "connection_data": {- "description": "Optional data to pre-fill connection fields with default values",+ "oneOf": [+ {"type": "object","properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"+ "type": {+ "type": "string",+ "enum": [+ "custom"+ ]},- "COMPANYDOMAIN": {- "type": "string"+ "name": {+ "type": "string",+ "minLength": 1,+ "description": "The display name of the authentication configuration"},- "extension": {- "type": "string"+ "credentials": {+ "type": "object",+ "properties": {+ "scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "user_scopes": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ }+ }},- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"- },- "domain": {- "type": "string"- },- "version": {- "type": "string"- },- "dc": {- "type": "string"- },- "site_name": {- "type": "string"- },- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"- },- "oauth_token": {- "type": "string"- },- "authUri": {- "type": "string"- },- "oauth_token_secret": {- "type": "string"- },- "redirectUrl": {- "type": "string"- },- "callbackUrl": {- "type": "string"- },- "oauth_verifier": {- "type": "string"- },- "consumer_key": {- "type": "string"- },- "callback_url": {- "type": "string"- },- "error": {- "type": "string"+ "proxy_config": {+ "type": "object",+ "nullable": true,+ "properties": {+ "proxy_url": {+ "type": "string",+ "format": "uri",+ "description": "The url of the auth proxy"+ },+ "proxy_auth_key": {+ "type": "string",+ "description": "The auth key for the auth proxy"+ }+ },+ "required": [+ "proxy_url"+ ]},- "error_description": {- "type": "string"+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true},- "expired_at": {- "type": "string"+ "tool_access_config": {+ "type": "object",+ "properties": {+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."+ },+ "tools_available_for_execution": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."+ }+ }},- "state_prefix": {- "type": "string",- "maxLength": 40,- "description": "The oauth2 state prefix for the connection"+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config."},- "long_redirect_url": {+ "is_enabled_for_tool_router": {"type": "boolean",- "description": "Whether to return the redirect url without shortening"- },- "code_verifier": {- "type": "string"- },- "finalRedirectUri": {- "type": "string"- },- "webhook_signature": {- "type": "string"- },- "access_token": {- "type": "string"- },- "id_token": {- "type": "string"- },- "token_type": {- "type": "string"+ "description": "Whether this auth config is enabled for tool router"+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "default"+ ]},- "refresh_token": {+ "name": {"type": "string",- "nullable": true+ "minLength": 1,+ "description": "The display name of the authentication configuration"},- "expires_in": {+ "scopes": {"anyOf": [- {- "type": "number"- },{"type": "string"},{- "nullable": true,- "type": "object"+ "type": "array",+ "items": {+ "type": "string"+ }}]},- "scope": {+ "user_scopes": {"anyOf": [{"type": "string"@@ -4884,134 +4297,86 @@"items": {"type": "string"}- },- {- "nullable": true,- "type": "object"}]},- "authed_user": {+ "restrict_to_following_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Use tool_access_config instead. This field will be deprecated in the future.",+ "deprecated": true+ },+ "tool_access_config": {"type": "object","properties": {- "access_token": {- "type": "string"+ "tools_for_connected_account_creation": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."},- "scope": {- "type": "string"+ "tools_available_for_execution": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."}- },- "description": "for slack user scopes"- },- "generic_api_key": {- "type": "string"- },- "api_key": {- "type": "string"- },- "bearer_token": {- "type": "string"- },- "basic_encoded": {- "type": "string"- },- "username": {- "type": "string"- },- "password": {- "type": "string"+ }},- "token": {- "type": "string"+ "shared_credentials": {+ "type": "object",+ "additionalProperties": {},+ "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config."},- "composio_link_redirect_url": {- "type": "string"+ "is_enabled_for_tool_router": {+ "type": "boolean",+ "description": "Whether this auth config is enabled for tool router"+ }+ },+ "required": [+ "type"+ ]+ }+ ]+ },+ "examples": {+ "standardUpdate": {+ "summary": "Standard credential update",+ "value": {+ "auth_config": {+ "credentials": {+ "api_key": "YOUR_NEW_API_KEY",+ "client_secret": "YOUR_NEW_CLIENT_SECRET"},- "credentials_json": {- "type": "string"- },- "sessionId": {- "type": "string"- },- "devKey": {- "type": "string"- },- "application_id": {- "type": "string"- },- "installation_id": {- "type": "string"- },- "private_key": {- "type": "string"- },- "client_id": {- "type": "string",- "description": "Dynamically registered client ID"- },- "client_secret": {- "type": "string",- "description": "Dynamically registered client secret"- },- "client_id_issued_at": {- "type": "number"- },- "client_secret_expires_at": {- "type": "number"- },- "expires_at": {- "type": "string"- }- },- "additionalProperties": true+ "restrict_to_following_tools": [+ "GMAIL_SEND_EMAIL",+ "GMAIL_FETCH_EMAILS"+ ]+ }}- },- "required": [- "auth_config_id",- "user_id"- ]+ }}}}},"responses": {- "201": {- "description": "Successfully created auth link",+ "200": {+ "description": "Successfully updated auth config","content": {"application/json": {"schema": {"type": "object",- "properties": {- "link_token": {- "type": "string",- "description": "The generated link token for the auth session"- },- "redirect_url": {- "type": "string",- "description": "The redirect URI to send users to for authentication"- },- "expires_at": {- "type": "string",- "description": "ISO timestamp when the link expires"- },- "connected_account_id": {- "type": "string",- "format": "connectedAccountId",- "description": "The connected account ID that was created"- }- },- "required": [- "link_token",- "redirect_url",- "expires_at",- "connected_account_id"- ]+ "properties": {}}}}},"400": {- "description": "Bad request",+ "description": "Bad request - Invalid input or credentials format","content": {"application/json": {"schema": {@@ -5021,7 +4386,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized - Authentication required","content": {"application/json": {"schema": {@@ -5031,17 +4396,7 @@}},"404": {- "description": "Auth config not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "422": {- "description": "Unprocessable entity",+ "description": "Not found - Auth configuration does not exist","content": {"application/json": {"schema": {@@ -5051,17 +4406,7 @@}},"500": {- "description": "Internal server error",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "501": {- "description": "Not implemented",+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -5070,98 +4415,51 @@}}}- }- }- },- "/api/v3/org/usage/summary": {- "get": {- "summary": "Org usage summary",- "description": "Aggregated metering usage for the authenticated organization across all projects. Requires ClickHouse logging (`USE_CLICKHOUSE_FOR_LOGS`). Values are summed from raw metering events grouped by `entity_type`.",+ },+ "x-api-version": "3.1"+ },+ "delete": {+ "summary": "Delete an authentication configuration",+ "description": "Soft-deletes an authentication configuration by marking it as deleted in the database. This operation cannot be undone.","tags": [- "Organization"+ "Auth Configs"],- "operationId": "getOrgUsageSummary",- "parameters": [+ "operationId": "deleteAuthConfigsByNanoid",+ "security": [{- "schema": {- "type": "string",- "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time."- },- "required": false,- "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time.",- "name": "start_time",- "in": "query"+ "ApiKeyAuth": []},{- "schema": {- "type": "string",- "description": "Exclusive range end (ISO 8601). Defaults to now."- },- "required": false,- "description": "Exclusive range end (ISO 8601). Defaults to now.",- "name": "end_time",- "in": "query"- },+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [{"schema": {- "type": "array",- "nullable": true,- "items": {- "type": "string"- },- "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types."+ "type": "string",+ "format": "authConfigId",+ "description": "The unique identifier of the authentication configuration to delete"},- "required": false,- "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types.",- "name": "entity_types",- "in": "query"+ "required": true,+ "description": "The unique identifier of the authentication configuration to delete",+ "name": "nanoid",+ "in": "path"}],"responses": {"200": {- "description": "Usage aggregates for the organization.",+ "description": "Successfully deleted auth config","content": {"application/json": {"schema": {"type": "object",- "properties": {- "rows": {- "type": "array",- "items": {- "type": "object",- "properties": {- "entity_type": {- "type": "string"- },- "unit": {- "type": "string"- },- "total_quantity": {- "type": "string"- },- "event_count": {- "type": "integer",- "minimum": 0- }- },- "required": [- "entity_type",- "unit",- "total_quantity",- "event_count"- ]- }- }- },- "required": [- "rows"- ]+ "properties": {}}}}},"400": {- "description": "Invalid time range, entity_types, or query parameters.",+ "description": "Bad request - Invalid auth config ID format","content": {"application/json": {"schema": {@@ -5171,7 +4469,7 @@}},"401": {- "description": "Authentication required.",+ "description": "Unauthorized - Authentication required","content": {"application/json": {"schema": {@@ -5180,18 +4478,19 @@}}},- "403": {- "description": "Forbidden.",+ "404": {+ "description": "Auth config not found - The specified configuration does not exist or was already deleted","content": {"application/json": {"schema": {- "$ref": "#/components/schemas/Error"+ "type": "object",+ "properties": {}}}}},"500": {- "description": "Failed to load usage from analytics store or feature configuration.",+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -5200,17 +4499,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/org/project/config": {- "get": {- "summary": "Get project configuration",- "description": "Retrieves the current project configuration including 2FA settings.",+ "/api/v3.1/auth_configs/{nanoid}/{status}": {+ "patch": {+ "summary": "Enable or disable an authentication configuration",+ "description": "Updates the status of an authentication configuration to either enabled or disabled. Disabled configurations cannot be used for new connections.","tags": [- "Projects"+ "Auth Configs"],- "operationId": "getOrgProjectConfig",+ "operationId": "patchAuthConfigsByNanoidByStatus","security": [{"ApiKeyAuth": []@@ -5219,57 +4519,47 @@"UserApiKeyAuth": []}],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "authConfigId",+ "description": "The unique identifier of the authentication configuration to update"+ },+ "required": true,+ "description": "The unique identifier of the authentication configuration to update",+ "name": "nanoid",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "ENABLED",+ "DISABLED"+ ],+ "description": "The new status to set for the auth configuration"+ },+ "required": true,+ "description": "The new status to set for the auth configuration",+ "name": "status",+ "in": "path"+ }+ ],"responses": {"200": {- "description": "Project configuration retrieved successfully.",+ "description": "Successfully updated auth config status","content": {"application/json": {"schema": {"type": "object",- "properties": {- "is_2FA_enabled": {- "type": "boolean"- },- "logo_url": {- "type": "string"- },- "display_name": {- "type": "string"- },- "mask_secret_keys_in_connected_account": {- "type": "boolean"- },- "log_visibility_setting": {- "type": "string",- "enum": [- "show_all",- "dont_store_data"- ]- },- "require_mcp_api_key": {- "type": "boolean"- },- "is_composio_link_enabled_for_managed_auth": {- "type": "boolean",- "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."- },- "signed_url_file_expiry_in_seconds": {- "type": "number",- "minimum": 1,- "maximum": 86400- }- },- "required": [- "is_2FA_enabled",- "mask_secret_keys_in_connected_account",- "log_visibility_setting"- ]+ "properties": {}}}}},"400": {- "description": "Bad request. The project configuration data may be invalid.",+ "description": "Bad request - Invalid auth config ID or status value","content": {"application/json": {"schema": {@@ -5279,7 +4569,7 @@}},"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "description": "Unauthorized - Authentication required","content": {"application/json": {"schema": {@@ -5289,7 +4579,7 @@}},"404": {- "description": "Project not found. The specified project does not exist or has been deleted.",+ "description": "Not found - Auth configuration does not exist","content": {"application/json": {"schema": {@@ -5299,7 +4589,7 @@}},"500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -5308,177 +4598,18 @@}}}- }- },- "patch": {- "summary": "Update project configuration",- "description": "Updates the project configuration settings.",- "tags": [- "Projects"- ],- "operationId": "patchOrgProjectConfig",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "is_2FA_enabled": {- "type": "boolean"- },- "logo_url": {- "type": "string"- },- "display_name": {- "type": "string"- },- "mask_secret_keys_in_connected_account": {- "type": "boolean"- },- "log_visibility_setting": {- "type": "string",- "enum": [- "show_all",- "dont_store_data"- ]- },- "require_mcp_api_key": {- "type": "boolean"- },- "is_composio_link_enabled_for_managed_auth": {- "type": "boolean",- "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."- },- "signed_url_file_expiry_in_seconds": {- "type": "number",- "minimum": 1,- "maximum": 86400- }- }- },- "examples": {- "Enable 2FA": {- "value": {- "is_2FA_enabled": true- }- },- "Disable 2FA": {- "value": {- "is_2FA_enabled": false- }- }- }- }- }},- "responses": {- "200": {- "description": "Project configuration updated successfully.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "is_2FA_enabled": {- "type": "boolean"- },- "logo_url": {- "type": "string"- },- "display_name": {- "type": "string"- },- "mask_secret_keys_in_connected_account": {- "type": "boolean"- },- "log_visibility_setting": {- "type": "string",- "enum": [- "show_all",- "dont_store_data"- ]- },- "require_mcp_api_key": {- "type": "boolean"- },- "is_composio_link_enabled_for_managed_auth": {- "type": "boolean",- "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."- },- "signed_url_file_expiry_in_seconds": {- "type": "number",- "minimum": 1,- "maximum": 86400- }- },- "required": [- "is_2FA_enabled",- "mask_secret_keys_in_connected_account",- "log_visibility_setting"- ]- }- }- }- },- "400": {- "description": "Bad request. The configuration data may be invalid or missing.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Project not found. The specified project does not exist or has been deleted.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }+ "x-api-version": "3.1"}},- "/api/v3/org/project/usage/summary": {+ "/api/v3.1/connected_accounts": {"get": {- "summary": "Project usage summary",- "description": "Aggregated metering usage for the authenticated project only. Requires ClickHouse logging (`USE_CLICKHOUSE_FOR_LOGS`). Values are summed from raw metering events grouped by `entity_type`.",+ "summary": "List connected accounts with optional filters",+ "description": "Retrieves all connected accounts for your project. Connected accounts represent authenticated user connections to external services (e.g., a user's Gmail account, Slack workspace). Filter by toolkit, status, user ID, or auth config to find specific connections.","tags": [- "Projects"+ "Connected Accounts"],- "operationId": "getOrgProjectUsageSummary",+ "operationId": "getConnectedAccounts","security": [{"ApiKeyAuth": []@@ -5490,430 +4621,466 @@"parameters": [{"schema": {- "type": "string",- "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time."+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "The toolkit slugs of the connected accounts"},"required": false,- "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time.",- "name": "start_time",+ "description": "The toolkit slugs of the connected accounts",+ "name": "toolkit_slugs","in": "query"},{"schema": {- "type": "string",- "description": "Exclusive range end (ISO 8601). Defaults to now."+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "description": "The status of the connected account"},"required": false,- "description": "Exclusive range end (ISO 8601). Defaults to now.",- "name": "end_time",+ "description": "The status of the connected account",+ "name": "statuses","in": "query"},{"schema": {- "type": "array",+ "type": "string","nullable": true,- "items": {- "type": "string"- },- "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types."+ "description": "The cursor to paginate through the connected accounts"},"required": false,- "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types.",- "name": "entity_types",+ "description": "The cursor to paginate through the connected accounts",+ "name": "cursor","in": "query"- }- ],- "responses": {- "200": {- "description": "Usage aggregates for the project.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "rows": {- "type": "array",- "items": {- "type": "object",- "properties": {- "entity_type": {- "type": "string"- },- "unit": {- "type": "string"- },- "total_quantity": {- "type": "string"- },- "event_count": {- "type": "integer",- "minimum": 0- }- },- "required": [- "entity_type",- "unit",- "total_quantity",- "event_count"- ]- }- }- },- "required": [- "rows"- ]- }- }- }},- "400": {- "description": "Invalid time range, entity_types, or query parameters.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }+ {+ "schema": {+ "type": "number",+ "nullable": true,+ "description": "The limit of the connected accounts to return"+ },+ "required": false,+ "description": "The limit of the connected accounts to return",+ "name": "limit",+ "in": "query"},- "401": {- "description": "Authentication required.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "The user ids of the connected accounts"+ },+ "required": false,+ "description": "The user ids of the connected accounts",+ "name": "user_ids",+ "in": "query"},- "403": {- "description": "Forbidden.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "authConfigId"+ },+ "description": "The auth config ids of the connected accounts"+ },+ "required": false,+ "description": "The auth config ids of the connected accounts",+ "name": "auth_config_ids",+ "in": "query"},- "500": {- "description": "Failed to load usage from analytics store or feature configuration.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },- "/api/v3/org/owner/project/new": {- "post": {- "summary": "Create a new project",- "description": "Creates a new project within the authenticated user's organization using the specified name. Projects are isolated environments within your organization, each with their own API keys, webhook configurations, and resources. Use this endpoint to create additional projects for different environments (e.g., development, staging, production) or for separate applications.",- "tags": [- "Projects"- ],- "operationId": "postOrgOwnerProjectNew",- "security": [{- "OrgApiKeyAuth": []- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "name": {- "type": "string",- "minLength": 3,- "maxLength": 75,- "pattern": "^[a-zA-Z0-9_-]+$",- "description": "A unique name for your project that follows the required format rules",- "example": "my-awesome-project"- },- "should_create_api_key": {- "type": "boolean",- "default": false,- "description": "Whether to create an API key for the project. If true, the API key will be created and returned in the response.",- "example": false- },- "config": {- "type": "object",- "properties": {- "is_2FA_enabled": {- "type": "boolean"- },- "logo_url": {- "type": "string"- },- "display_name": {- "type": "string"- },- "mask_secret_keys_in_connected_account": {- "type": "boolean"- },- "log_visibility_setting": {- "type": "string",- "enum": [- "show_all",- "dont_store_data"- ]- },- "require_mcp_api_key": {- "type": "boolean"- },- "is_composio_link_enabled_for_managed_auth": {- "type": "boolean",- "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."- },- "signed_url_file_expiry_in_seconds": {- "type": "number",- "minimum": 1,- "maximum": 86400- }- },- "required": [- "is_2FA_enabled",- "mask_secret_keys_in_connected_account",- "log_visibility_setting"- ],- "description": "Configuration for the project"- }- },- "required": [- "name"- ]+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string",+ "format": "connectedAccountId"},- "examples": {- "Simple project": {- "value": {- "name": "my_production_api"- }- }- }- }+ "description": "The connected account ids to filter by"+ },+ "required": false,+ "description": "The connected account ids to filter by",+ "name": "connected_account_ids",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "created_at",+ "updated_at"+ ],+ "default": "created_at",+ "description": "The order by of the connected accounts"+ },+ "required": false,+ "description": "The order by of the connected accounts",+ "name": "order_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "asc",+ "desc"+ ],+ "default": "desc",+ "description": "The order direction of the connected accounts"+ },+ "required": false,+ "description": "The order direction of the connected accounts",+ "name": "order_direction",+ "in": "query"}- },+ ],"responses": {"200": {- "description": "Project successfully created. Returns the complete project object with generated IDs, webhook secrets, and configuration.",+ "description": "Successfully retrieved connected accounts","content": {"application/json": {"schema": {"type": "object","properties": {- "id": {- "type": "string",- "format": "projectId",- "description": "Unique identifier for the project",- "example": "proj_abc123xyz456"- },- "name": {- "type": "string",- "description": "Name of the project",- "example": "My Awesome Project"- },- "api_key": {- "type": "string",- "nullable": true,- "description": "API key for the project",- "example": "ak_abc123xyz456"- }- },- "required": [- "id",- "api_key"- ]- }- }- }- },- "400": {- "description": "Bad request. This may occur if the project name format is invalid, too short, or contains invalid characters.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },- "/api/v3/org/owner/project/list": {- "get": {- "summary": "List all projects",- "description": "Retrieves all projects belonging to the authenticated organization. Projects are returned in descending order of creation date (newest first). This endpoint is useful for displaying project selection in dashboards or for integrations that need to list all available projects.",- "tags": [- "Projects"- ],- "operationId": "getOrgOwnerProjectList",- "security": [- {- "OrgApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "number",- "nullable": true- },- "required": false,- "description": "Number of items per page, max allowed is 1000",- "name": "limit",- "in": "query"- },- {- "schema": {- "type": "string"- },- "required": false,- "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",- "name": "cursor",- "in": "query"- }- ],- "responses": {- "200": {- "description": "Projects retrieved successfully with pagination. Returns an array of projects with pagination info.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "data": {+ "items": {"type": "array","items": {"type": "object","properties": {- "id": {- "type": "string",- "format": "projectId",- "description": "Unique identifier for the project",- "example": "proj_abc123xyz456"- },- "org_id": {- "type": "string",- "format": "orgId",- "description": "Identifier of the organization that owns this project",- "example": "org_abc123xyz456"- },- "name": {- "type": "string",- "description": "Name of the project",- "example": "My Awesome Project"- },- "email": {- "type": "string",- "description": "Email address associated with the project",- "example": "[email protected]"+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The slug of the toolkit"+ }+ },+ "required": [+ "slug"+ ]},- "created_at": {- "type": "string",- "description": "ISO timestamp when the project was created",- "example": "2023-05-16T14:30:00.000Z"+ "auth_config": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The id of the auth config"+ },+ "auth_scheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ],+ "description": "the authScheme is part of the connection state use it there",+ "deprecated": true+ },+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether the auth config is managed by Composio"+ },+ "is_disabled": {+ "type": "boolean",+ "description": "Whether the auth config is disabled"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the auth config"+ }+ },+ "required": [+ "uuid"+ ],+ "deprecated": true+ }+ },+ "required": [+ "id",+ "auth_scheme",+ "is_composio_managed",+ "is_disabled"+ ]},- "updated_at": {+ "id": {"type": "string",- "description": "ISO timestamp when the project was last updated",- "example": "2023-05-18T09:15:30.000Z"+ "format": "connectedAccountId",+ "description": "The id of the connection"},- "webhook_url": {+ "word_id": {"type": "string","nullable": true,- "format": "uri",- "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.",- "example": "https://example.com/webhook",- "deprecated": true+ "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")"},- "event_webhook_url": {+ "alias": {"type": "string","nullable": true,- "format": "uri",- "description": "DEPRECATED: No longer used.",- "example": "https://example.com/events",- "deprecated": true+ "description": "A user-defined alias for the connected account"},- "webhook_secret": {+ "user_id": {"type": "string",- "nullable": true,- "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.",- "example": "whsec_abcdef123456789",+ "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back","deprecated": true},- "triggers_enabled": {- "type": "boolean",- "description": "Whether triggers are enabled for this project",- "example": true- },- "last_subscribed_at": {+ "status": {"type": "string",- "nullable": true,- "format": "date-time",- "description": "ISO timestamp when the project last subscribed to updates",- "example": "2023-05-17T10:00:00.000Z"+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ],+ "description": "The status of the connection"},- "is_new_webhook": {- "type": "boolean",- "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",- "example": true,- "deprecated": true+ "created_at": {+ "type": "string",+ "description": "The created at of the connection"},- "webhook_version": {+ "updated_at": {"type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "description": "Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.",- "example": "V2"+ "description": "The updated at of the connection"},- "deleted": {- "type": "boolean",- "description": "Whether this project has been soft-deleted",- "example": false+ "state": {+ "description": "The state of the connection",+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH1",+ "OAUTH2",+ "API_KEY",+ "BASIC",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "CALCOM_AUTH",+ "BILLCOM_AUTH",+ "BASIC_WITH_JWT",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ }+ },+ "required": [+ "status"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "authScheme",+ "val"+ ],+ "additionalProperties": true+ },+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "This is deprecated, use `state` instead",+ "deprecated": true+ },+ "status_reason": {+ "type": "string",+ "nullable": true,+ "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled"+ },+ "is_disabled": {+ "type": "boolean",+ "description": "Whether the connection is disabled"+ },+ "test_request_endpoint": {+ "type": "string",+ "description": "The endpoint to make test request for verification"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "labels": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The labels of the connection"+ },+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the connection"+ }+ },+ "required": [+ "labels",+ "uuid"+ ],+ "deprecated": true}},"required": [+ "toolkit",+ "auth_config","id",- "org_id",- "name",- "email",+ "word_id",+ "alias",+ "user_id",+ "status","created_at","updated_at",- "webhook_url",- "event_webhook_url",- "webhook_secret",- "webhook_version",- "deleted"+ "state",+ "data",+ "status_reason",+ "is_disabled"]}},@@ -5932,7 +5099,7 @@}},"required": [- "data",+ "items","total_pages","current_page","total_items"@@ -5942,7 +5109,7 @@}},"400": {- "description": "Bad request. This may occur if there are invalid query parameters or the request is malformed.",+ "description": "Bad request","content": {"application/json": {"schema": {@@ -5952,7 +5119,27 @@}},"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity","content": {"application/json": {"schema": {@@ -5962,7 +5149,7 @@}},"500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -5971,39 +5158,247 @@}}}- }- }- },- "/api/v3/org/owner/project/{nano_id}": {- "get": {- "summary": "Get project details by ID With Org Api key",- "description": "Retrieves detailed information about a specific project using its unique identifier. This endpoint provides complete project configuration including webhook URLs, creation and update timestamps, and webhook secrets. Use this endpoint to inspect project settings or verify project configuration.",+ },+ "x-api-version": "3.1"+ },+ "post": {+ "summary": "Create a new connected account",+ "description": "Initiates a new connection to an external service for a user. For OAuth-based toolkits, this returns a redirect URL to complete authentication. For API key-based toolkits, provide the credentials directly in the request body. Use the `user_id` field to associate the connection with a specific user in your system.","tags": [- "Projects"+ "Connected Accounts"],- "operationId": "getOrgOwnerProjectByNanoId",+ "operationId": "postConnectedAccounts","security": [{- "OrgApiKeyAuth": []+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []}],- "parameters": [- {- "schema": {- "type": "string",- "format": "projectId",- "description": "Unique identifier (Nano ID) of the project to retrieve",- "example": "proj_abc123xyz456"- },- "required": true,- "description": "Unique identifier (Nano ID) of the project to retrieve",- "name": "nano_id",- "in": "path"+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "auth_config": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The auth config id of the app (must be a valid auth config id)"+ }+ },+ "required": [+ "id"+ ]+ },+ "connection": {+ "type": "object",+ "properties": {+ "state": {+ "description": "The state of the connected account",+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH1",+ "OAUTH2",+ "API_KEY",+ "BASIC",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "CALCOM_AUTH",+ "BILLCOM_AUTH",+ "BASIC_WITH_JWT",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ }+ },+ "required": [+ "status"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "authScheme",+ "val"+ ],+ "additionalProperties": true+ },+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use state instead.",+ "deprecated": true+ },+ "user_id": {+ "type": "string",+ "default": "default",+ "description": "The user id of the connected account"+ },+ "alias": {+ "type": "string",+ "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."+ },+ "callback_url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to redirect to after connection completion"+ },+ "redirect_uri": {+ "type": "string",+ "format": "uri",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use callback_url instead.",+ "deprecated": true+ },+ "deprecated_is_v1_rerouted": {+ "type": "boolean",+ "default": false,+ "description": "DEPRECATED: This parameter will be removed in a future version.",+ "deprecated": true+ }+ }+ },+ "validate_credentials": {+ "type": "boolean",+ "default": false,+ "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme",+ "x-experimental": true+ }+ },+ "required": [+ "auth_config",+ "connection"+ ]+ }+ }}- ],+ },"responses": {- "200": {- "description": "Project retrieved successfully. Returns a complete project object with all configuration details and associated API keys.",+ "201": {+ "description": "Successfully created connected account","content": {"application/json": {"schema": {@@ -6011,149 +5406,219 @@"properties": {"id": {"type": "string",- "format": "projectId",- "description": "Unique identifier for the project",- "example": "proj_abc123xyz456"- },- "org_id": {- "type": "string",- "format": "orgId",- "description": "Identifier of the organization that owns this project",- "example": "org_abc123xyz456"- },- "name": {- "type": "string",- "description": "Name of the project",- "example": "My Awesome Project"- },- "email": {- "type": "string",- "description": "Email address associated with the project",- "example": "[email protected]"+ "format": "connectedAccountId",+ "description": "The id of the connected account"},- "created_at": {- "type": "string",- "description": "ISO timestamp when the project was created",- "example": "2023-05-16T14:30:00.000Z"- },- "updated_at": {- "type": "string",- "description": "ISO timestamp when the project was last updated",- "example": "2023-05-18T09:15:30.000Z"- },- "webhook_url": {- "type": "string",- "nullable": true,- "format": "uri",- "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.",- "example": "https://example.com/webhook",- "deprecated": true+ "connectionData": {+ "description": "The connection data of the connected account",+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH1",+ "OAUTH2",+ "API_KEY",+ "BASIC",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "CALCOM_AUTH",+ "BILLCOM_AUTH",+ "BASIC_WITH_JWT",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"+ },+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ }+ },+ "required": [+ "status"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "authScheme",+ "val"+ ],+ "additionalProperties": true},- "event_webhook_url": {+ "status": {"type": "string",- "nullable": true,- "format": "uri",- "description": "DEPRECATED: No longer used.",- "example": "https://example.com/events",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ],+ "description": "DEPRECATED: This field will be removed in a future version","deprecated": true},- "webhook_secret": {+ "redirect_url": {"type": "string","nullable": true,- "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.",- "example": "whsec_abcdef123456789",+ "description": "DEPRECATED: This field will be removed in a future version","deprecated": true},- "triggers_enabled": {- "type": "boolean",- "description": "Whether triggers are enabled for this project",- "example": true- },- "last_subscribed_at": {+ "redirect_uri": {"type": "string","nullable": true,- "format": "date-time",- "description": "ISO timestamp when the project last subscribed to updates",- "example": "2023-05-17T10:00:00.000Z"- },- "is_new_webhook": {- "type": "boolean",- "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",- "example": true,+ "description": "DEPRECATED: This field will be removed in a future version","deprecated": true},- "webhook_version": {- "type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "description": "Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.",- "example": "V2"- },- "deleted": {- "type": "boolean",- "description": "Whether this project has been soft-deleted",- "example": false- },- "api_keys": {- "type": "array",- "items": {- "type": "object",- "properties": {- "id": {- "type": "string",- "description": "Unique identifier for the API key",- "example": "01H4DKRF5SMP7NQCA3BWT0JYB6"- },- "name": {- "type": "string",- "description": "User-defined name for the API key",- "example": "Production Server Key"- },- "key": {- "type": "string",- "description": "The actual API key value used for authentication",- "example": "ak_a1b2c3d4e5f6g7h8i9j0"- },- "created_at": {- "type": "string",- "format": "date-time",- "description": "ISO 8601 timestamp when the API key was created",- "example": "2023-07-15T14:30:00.000Z"- }+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the connected account"},- "required": [- "id",- "name",- "key",- "created_at"- ]- },- "description": "Array of API keys for the project, including their properties"+ "authConfigUuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the auth config"+ }+ },+ "required": [+ "uuid",+ "authConfigUuid"+ ],+ "description": "DEPRECATED: This field will be removed in a future version. Please use id and auth_config.id instead.",+ "deprecated": true}},"required": ["id",- "org_id",- "name",- "email",- "created_at",- "updated_at",- "webhook_url",- "event_webhook_url",- "webhook_secret",- "webhook_version",- "deleted",- "api_keys"+ "connectionData",+ "status",+ "redirect_url",+ "redirect_uri",+ "deprecated"]}}}},"400": {- "description": "Bad request. This may occur if the project ID format is invalid.",+ "description": "Bad request","content": {"application/json": {"schema": {@@ -6163,7 +5628,7 @@}},"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -6173,7 +5638,7 @@}},"404": {- "description": "Not found. The specified project does not exist or you do not have access to it.",+ "description": "Not found","content": {"application/json": {"schema": {@@ -6183,100 +5648,7 @@}},"500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- },- "delete": {- "summary": "Delete a project",- "description": "Soft-deletes a project within the organization by its unique identifier. When a project is deleted, it is marked as deleted but not immediately removed from the database. This operation affects all resources associated with the project including API keys, webhook configurations, and connected services. This action cannot be undone through the API.",- "tags": [- "Projects"- ],- "operationId": "deleteOrgOwnerProjectByNanoId",- "security": [- {- "OrgApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "format": "projectId",- "description": "Unique identifier (Nano ID) of the project to delete",- "example": "proj_abc123xyz456"- },- "required": true,- "description": "Unique identifier (Nano ID) of the project to delete",- "name": "nano_id",- "in": "path"- }- ],- "responses": {- "200": {- "description": "Project successfully deleted. The project has been marked as deleted in the system.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "status": {- "type": "string",- "enum": [- "success"- ],- "description": "Status indicating successful deletion",- "example": "success"- }- },- "required": [- "status"- ],- "description": "Response indicating successful project deletion"- }- }- }- },- "400": {- "description": "Bad request. The project ID may be invalid or in an incorrect format.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden. You do not have permission to delete this project.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found. The specified project does not exist or has already been deleted.",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -6285,8 +5657,8 @@}}},- "500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",+ "501": {+ "description": "Not implemented","content": {"application/json": {"schema": {@@ -6295,413 +5667,377 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/org/owner/project/{nano_id}/regenerate_api_key": {- "post": {- "summary": "Delete and generate new API key for project",- "description": "Generates a new API key for the specified project, invalidating any existing API keys for that project. This operation creates a fresh API key with a new random name and key value. All existing API keys for this project will be marked as deleted.",+ "/api/v3.1/connected_accounts/{nanoid}": {+ "get": {+ "summary": "Get connected account details by ID",+ "description": "Retrieves comprehensive details of a connected account, including authentication configuration, connection status, and all parameters needed for API requests.","tags": [- "Projects"+ "Connected Accounts"],- "operationId": "postOrgOwnerProjectByNanoIdRegenerateApiKey",+ "operationId": "getConnectedAccountsByNanoid","security": [{- "OrgApiKeyAuth": []+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []}],"parameters": [{"schema": {"type": "string",- "format": "projectId",- "description": "Unique identifier (Nano ID) of the project to regenerate API key for",- "example": "proj_abc123xyz456"+ "format": "connectedAccountId"},"required": true,- "description": "Unique identifier (Nano ID) of the project to regenerate API key for",- "name": "nano_id",+ "description": "The unique identifier (nanoid) of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoid","in": "path"}],"responses": {"200": {- "description": "API key regenerated successfully. Returns the new API key details.",+ "description": "Successfully retrieved connected account details with all authentication parameters and connection status","content": {"application/json": {"schema": {"type": "object","properties": {- "api_key": {+ "toolkit": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "The slug of the toolkit"+ }+ },+ "required": [+ "slug"+ ]+ },+ "auth_config": {"type": "object","properties": {"id": {"type": "string",- "description": "Unique identifier for the API key",- "example": "01H4DKRF5SMP7NQCA3BWT0JYB6"+ "format": "authConfigId",+ "description": "The id of the auth config"},- "name": {+ "auth_scheme": {"type": "string",- "description": "Name of the API key",- "example": "epic_avatar"+ "enum": [+ "OAUTH2",+ "OAUTH1",+ "API_KEY",+ "BASIC",+ "BILLCOM_AUTH",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "BASIC_WITH_JWT",+ "CALCOM_AUTH",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ],+ "description": "the authScheme is part of the connection state use it there",+ "deprecated": true},- "key": {- "type": "string",- "description": "The newly generated API key value",- "example": "ak_a1b2c3d4e5f6g7h8i9j0"+ "is_composio_managed": {+ "type": "boolean",+ "description": "Whether the auth config is managed by Composio"},- "created_at": {- "type": "string",- "description": "ISO timestamp when the API key was created",- "example": "2023-05-16T14:30:00.000Z"+ "is_disabled": {+ "type": "boolean",+ "description": "Whether the auth config is disabled"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the auth config"+ }+ },+ "required": [+ "uuid"+ ],+ "deprecated": true}},"required": ["id",- "name",- "key",- "created_at"- ],- "description": "The newly generated API key for this project"+ "auth_scheme",+ "is_composio_managed",+ "is_disabled"+ ]},- "message": {+ "id": {"type": "string",- "description": "Success message",- "example": "API key regenerated successfully"- }- },- "required": [- "api_key",- "message"- ]- }- }- }- },- "400": {- "description": "Bad request. The project ID may be invalid or in an incorrect format.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found. The specified project does not exist or you do not have access to it.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },- "/api/v3/webhook_subscriptions": {- "post": {- "summary": "Create webhook subscription",- "description": "Creates a webhook subscription for the authenticated project. Only one subscription is allowed per project. The signing secret is returned only on creation.",- "tags": [- "Webhooks"- ],- "operationId": "postWebhookSubscriptions",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "webhook_url": {- "type": "string",- "maxLength": 2048,- "format": "uri",- "description": "HTTPS URL to receive webhook events"- },- "enabled_events": {- "type": "array",- "items": {- "type": "string"+ "format": "connectedAccountId",+ "description": "The id of the connection"},- "minItems": 1,- "description": "Array of event types to subscribe to"- },- "version": {- "type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "default": "V3",- "description": "Webhook payload version"- }- },- "required": [- "webhook_url",- "enabled_events"- ]- }- }- }- },- "responses": {- "201": {- "description": "Webhook subscription created",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "id": {+ "word_id": {"type": "string",- "format": "webhookSubscriptionId",- "description": "Unique subscription ID"+ "nullable": true,+ "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")"},- "webhook_url": {+ "alias": {"type": "string",- "description": "Webhook destination URL"+ "nullable": true,+ "description": "A user-defined alias for the connected account"},- "version": {+ "user_id": {"type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "description": "Webhook payload version"- },- "enabled_events": {- "type": "array",- "items": {- "type": "string"- },- "description": "Subscribed event types"+ "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back",+ "deprecated": true},- "secret": {+ "status": {"type": "string",- "description": "Signing secret for HMAC verification"+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ],+ "description": "The status of the connection"},"created_at": {"type": "string",- "description": "ISO 8601 timestamp"+ "description": "The created at of the connection"},"updated_at": {"type": "string",- "description": "ISO 8601 timestamp"- }- },- "required": [- "id",- "webhook_url",- "version",- "enabled_events",- "secret",- "created_at",- "updated_at"- ]- }- }- }- },- "400": {- "description": "Invalid request",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "409": {- "description": "Subscription already exists",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- },- "get": {- "summary": "List webhook subscriptions",- "description": "Lists all webhook subscriptions for the authenticated project with pagination. Currently limited to one subscription per project.",- "tags": [- "Webhooks"- ],- "operationId": "getWebhookSubscriptions",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "number",- "nullable": true- },- "required": false,- "description": "Number of items per page, max allowed is 1000",- "name": "limit",- "in": "query"- },- {- "schema": {- "type": "string"- },- "required": false,- "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",- "name": "cursor",- "in": "query"- }- ],- "responses": {- "200": {- "description": "Webhook subscriptions retrieved",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "items": {- "type": "array",- "items": {- "type": "object",- "properties": {- "id": {- "type": "string",- "format": "webhookSubscriptionId",- "description": "Unique subscription ID"- },- "webhook_url": {- "type": "string",- "description": "Webhook destination URL"- },- "version": {- "type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "description": "Webhook payload version"- },- "enabled_events": {- "type": "array",- "items": {+ "description": "The updated at of the connection"+ },+ "state": {+ "description": "The state of the connection",+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH1",+ "OAUTH2",+ "API_KEY",+ "BASIC",+ "BEARER_TOKEN",+ "GOOGLE_SERVICE_ACCOUNT",+ "NO_AUTH",+ "CALCOM_AUTH",+ "BILLCOM_AUTH",+ "BASIC_WITH_JWT",+ "SERVICE_ACCOUNT",+ "SAML",+ "DCR_OAUTH",+ "S2S_OAUTH2"+ ]+ },+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {"type": "string"},- "description": "Subscribed event types"- },- "secret": {- "type": "string",- "description": "Masked signing secret (full secret only on create/rotate)"- },- "created_at": {- "type": "string",- "description": "ISO 8601 timestamp"+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ]+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ }},- "updated_at": {- "type": "string",- "description": "ISO 8601 timestamp"- }- },- "required": [- "id",- "webhook_url",- "version",- "enabled_events",- "secret",- "created_at",- "updated_at"- ]- }+ "required": [+ "status"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "authScheme",+ "val"+ ],+ "additionalProperties": true},- "next_cursor": {+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "This is deprecated, use `state` instead",+ "deprecated": true+ },+ "status_reason": {"type": "string",- "nullable": true+ "nullable": true,+ "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled"},- "total_pages": {- "type": "number"+ "is_disabled": {+ "type": "boolean",+ "description": "Whether the connection is disabled"},- "current_page": {- "type": "number"+ "test_request_endpoint": {+ "type": "string",+ "description": "The endpoint to make test request for verification"},- "total_items": {- "type": "number"+ "deprecated": {+ "type": "object",+ "properties": {+ "labels": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The labels of the connection"+ },+ "uuid": {+ "type": "string",+ "format": "uuid",+ "description": "The uuid of the connection"+ }+ },+ "required": [+ "labels",+ "uuid"+ ],+ "deprecated": true+ },+ "params": {+ "type": "object",+ "additionalProperties": {},+ "description": "The initialization data of the connection, including configuration parameters",+ "deprecated": true}},"required": [- "items",- "total_pages",- "current_page",- "total_items"+ "toolkit",+ "auth_config",+ "id",+ "word_id",+ "alias",+ "user_id",+ "status",+ "created_at",+ "updated_at",+ "state",+ "data",+ "status_reason",+ "is_disabled",+ "params"]}}}},"400": {- "description": "Invalid pagination",+ "description": "Bad request - Invalid nanoid format or other validation error","content": {"application/json": {"schema": {@@ -6711,7 +6047,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized - Authentication failed","content": {"application/json": {"schema": {@@ -6720,8 +6056,8 @@}}},- "500": {- "description": "Internal server error",+ "403": {+ "description": "Forbidden - Insufficient permissions to access this connected account","content": {"application/json": {"schema": {@@ -6729,100 +6065,9 @@}}}- }- }- }- },- "/api/v3/webhook_subscriptions/{id}": {- "get": {- "summary": "Get webhook subscription",- "description": "Retrieves a webhook subscription by ID.",- "tags": [- "Webhooks"- ],- "operationId": "getWebhookSubscriptionsById",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "format": "webhookSubscriptionId",- "description": "Webhook subscription ID"- },- "required": true,- "description": "Webhook subscription ID",- "name": "id",- "in": "path"- }- ],- "responses": {- "200": {- "description": "Webhook subscription retrieved",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "id": {- "type": "string",- "format": "webhookSubscriptionId",- "description": "Unique subscription ID"- },- "webhook_url": {- "type": "string",- "description": "Webhook destination URL"- },- "version": {- "type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "description": "Webhook payload version"- },- "enabled_events": {- "type": "array",- "items": {- "type": "string"- },- "description": "Subscribed event types"- },- "secret": {- "type": "string",- "description": "Masked signing secret (full secret only on create/rotate)"- },- "created_at": {- "type": "string",- "description": "ISO 8601 timestamp"- },- "updated_at": {- "type": "string",- "description": "ISO 8601 timestamp"- }- },- "required": [- "id",- "webhook_url",- "version",- "enabled_events",- "secret",- "created_at",- "updated_at"- ]- }- }- }},- "401": {- "description": "Unauthorized",+ "404": {+ "description": "Not found - Connected account does not exist or was deleted","content": {"application/json": {"schema": {@@ -6831,8 +6076,8 @@}}},- "404": {- "description": "Subscription not found",+ "500": {+ "description": "Internal server error - Failed to retrieve connected account details","content": {"application/json": {"schema": {@@ -6841,8 +6086,8 @@}}},- "500": {- "description": "Internal server error",+ "501": {+ "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme","content": {"application/json": {"schema": {@@ -6851,15 +6096,16 @@}}}- }+ },+ "x-api-version": "3.1"},- "patch": {- "summary": "Update webhook subscription",- "description": "Updates a webhook subscription. At least one field must be provided.",+ "delete": {+ "summary": "Delete a connected account",+ "description": "Soft-deletes a connected account by marking it as deleted in the database. This prevents the account from being used for API calls but preserves the record for audit purposes.","tags": [- "Webhooks"+ "Connected Accounts"],- "operationId": "patchWebhookSubscriptionsById",+ "operationId": "deleteConnectedAccountsByNanoid","security": [{"ApiKeyAuth": []@@ -6872,110 +6118,41 @@{"schema": {"type": "string",- "format": "webhookSubscriptionId",- "description": "Webhook subscription ID"+ "format": "connectedAccountId"},"required": true,- "description": "Webhook subscription ID",- "name": "id",+ "description": "The unique identifier (nanoid) of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoid","in": "path"}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "webhook_url": {- "type": "string",- "maxLength": 2048,- "format": "uri",- "description": "HTTPS URL to receive webhook events"- },- "enabled_events": {- "type": "array",- "items": {- "type": "string"- },- "minItems": 1,- "description": "Array of event types to subscribe to"- },- "version": {- "type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "description": "Webhook payload version"- }- }- }- }- }- },"responses": {"200": {- "description": "Webhook subscription updated",+ "description": "Successfully deleted the connected account. The account is marked as deleted but retained in the database for historical purposes.","content": {"application/json": {"schema": {"type": "object","properties": {- "id": {- "type": "string",- "format": "webhookSubscriptionId",- "description": "Unique subscription ID"- },- "webhook_url": {- "type": "string",- "description": "Webhook destination URL"- },- "version": {- "type": "string",- "enum": [- "V1",- "V2",- "V3"- ],- "description": "Webhook payload version"- },- "enabled_events": {- "type": "array",- "items": {- "type": "string"- },- "description": "Subscribed event types"- },- "secret": {- "type": "string",- "description": "Masked signing secret (full secret only on create/rotate)"- },- "created_at": {- "type": "string",- "description": "ISO 8601 timestamp"- },- "updated_at": {- "type": "string",- "description": "ISO 8601 timestamp"+ "success": {+ "type": "boolean",+ "description": "Indicates whether the connected account was successfully deleted"}},"required": [- "id",- "webhook_url",- "version",- "enabled_events",- "secret",- "created_at",- "updated_at"- ]+ "success"+ ],+ "description": "Response returned after successfully deleting a connected account",+ "example": {+ "success": true+ }}}}},"400": {- "description": "Invalid request",+ "description": "Bad request - Invalid nanoid format or other validation error","content": {"application/json": {"schema": {@@ -6985,7 +6162,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized - Authentication failed","content": {"application/json": {"schema": {@@ -6994,8 +6171,8 @@}}},- "404": {- "description": "Subscription not found",+ "403": {+ "description": "Forbidden - Insufficient permissions to delete this connected account","content": {"application/json": {"schema": {@@ -7004,8 +6181,19 @@}}},+ "404": {+ "description": "Connected account not found - The specified account does not exist or has already been deleted",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}+ }+ }+ }+ },"500": {- "description": "Internal server error",+ "description": "Internal server error - Failed to delete the connected account due to a server-side issue","content": {"application/json": {"schema": {@@ -7014,15 +6202,16 @@}}}- }+ },+ "x-api-version": "3.1"},- "delete": {- "summary": "Delete webhook subscription",- "description": "Permanently deletes a webhook subscription. This action cannot be undone.",+ "patch": {+ "summary": "Update a connected account",+ "description": "Update a connected account. Supports updating the alias and/or credentials. Only specified fields will be updated. Set a credential field to null to remove it. Alias must be unique within the same project, entity, and toolkit scope.","tags": [- "Webhooks"+ "Connected Accounts"],- "operationId": "deleteWebhookSubscriptionsById",+ "operationId": "patchConnectedAccountsByNanoid","security": [{"ApiKeyAuth": []@@ -7035,36 +6224,103 @@{"schema": {"type": "string",- "format": "webhookSubscriptionId",- "description": "Webhook subscription ID"+ "format": "connectedAccountId"},"required": true,- "description": "Webhook subscription ID",- "name": "id",+ "description": "The unique identifier (nanoid) of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoid","in": "path"}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/PatchConnectedAccountBody"+ },+ "examples": {+ "credentials": {+ "summary": "Update credentials",+ "value": {+ "connection": {+ "state": {+ "authScheme": "BEARER_TOKEN",+ "val": {+ "token": "new_access_token"+ }+ }+ }+ }+ },+ "alias": {+ "summary": "Update alias",+ "value": {+ "alias": "work-gmail"+ }+ }+ }+ }+ }+ },"responses": {"200": {- "description": "Webhook subscription deleted",+ "description": "Successfully updated connected account","content": {"application/json": {"schema": {"type": "object","properties": {"success": {- "type": "boolean"+ "type": "boolean",+ "description": "Whether the update was successful"+ },+ "id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The unique identifier of the updated connected account"+ },+ "status": {+ "type": "string",+ "description": "The current status of the connected account after the update (ACTIVE, EXPIRED, INACTIVE, etc.)"}},"required": [- "success"- ]+ "success",+ "id",+ "status"+ ],+ "example": {+ "success": true,+ "id": "ca_1a2b3c4d5e6f",+ "status": "ACTIVE"+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid nanoid, duplicate alias, or invalid credential values",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"}}}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized - Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden - Insufficient permissions to update this connected account","content": {"application/json": {"schema": {@@ -7074,7 +6330,7 @@}},"404": {- "description": "Subscription not found",+ "description": "Not found - Connected account does not exist or was deleted","content": {"application/json": {"schema": {@@ -7084,7 +6340,7 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error - Failed to update connected account","content": {"application/json": {"schema": {@@ -7093,17 +6349,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/webhook_subscriptions/{id}/rotate_secret": {- "post": {- "summary": "Rotate webhook secret",- "description": "Generates a new signing secret for the webhook subscription. The new secret is returned only in this response.",+ "/api/v3.1/connected_accounts/{nanoId}/status": {+ "patch": {+ "summary": "Enable or disable a connected account",+ "description": "Updates the status of a connected account to either enabled (active) or disabled (inactive). Disabled accounts cannot be used for API calls but remain in the database.","tags": [- "Webhooks"+ "Connected Accounts"],- "operationId": "postWebhookSubscriptionsByIdRotateSecret",+ "operationId": "patchConnectedAccountsByNanoIdStatus","security": [{"ApiKeyAuth": []@@ -7116,43 +6373,62 @@{"schema": {"type": "string",- "format": "webhookSubscriptionId",- "description": "Webhook subscription ID"+ "format": "connectedAccountId"},"required": true,- "description": "Webhook subscription ID",- "name": "id",+ "description": "The unique identifier of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoId","in": "path"}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "boolean",+ "description": "Set to true to enable the account or false to disable it"+ }+ },+ "required": [+ "enabled"+ ],+ "example": {+ "enabled": true+ }+ }+ }+ }+ },"responses": {"200": {- "description": "Webhook secret rotated",+ "description": "Successfully updated the connected account status. If enabled=true, the account status is set to ACTIVE; if enabled=false, the status is set to INACTIVE.","content": {"application/json": {"schema": {"type": "object","properties": {- "id": {- "type": "string",- "format": "webhookSubscriptionId",- "description": "Subscription ID"- },- "secret": {- "type": "string",- "description": "New signing secret"+ "success": {+ "type": "boolean",+ "description": "Indicates whether the connected account status was successfully updated"}},"required": [- "id",- "secret"- ]+ "success"+ ],+ "description": "Response returned after successfully updating a connected account status",+ "example": {+ "success": true+ }}}}},- "401": {- "description": "Unauthorized",+ "400": {+ "description": "Bad request - Invalid nanoid format or invalid request body","content": {"application/json": {"schema": {@@ -7161,8 +6437,8 @@}}},- "404": {- "description": "Subscription not found",+ "401": {+ "description": "Unauthorized - Authentication failed","content": {"application/json": {"schema": {@@ -7171,8 +6447,8 @@}}},- "500": {- "description": "Internal server error",+ "403": {+ "description": "Forbidden - Insufficient permissions to update this connected account","content": {"application/json": {"schema": {@@ -7180,87 +6456,20 @@}}}- }- }- }- },- "/api/v3/webhook_subscriptions/event_types": {- "get": {- "summary": "List available event types",- "description": "Returns all event types that can be subscribed to, along with their supported webhook versions.",- "tags": [- "Webhooks"- ],- "operationId": "getWebhookSubscriptionsEventTypes",- "security": [- {- "ApiKeyAuth": []},- {- "UserApiKeyAuth": []- }- ],- "responses": {- "200": {- "description": "Event types retrieved",+ "404": {+ "description": "Connected account not found - The specified account does not exist or has been deleted","content": {"application/json": {"schema": {"type": "object",- "properties": {- "items": {- "type": "array",- "items": {- "type": "object",- "properties": {- "event_type": {- "type": "string",- "description": "Event type identifier"- },- "description": {- "type": "string",- "description": "Human-readable description of the event"- },- "supported_versions": {- "type": "array",- "items": {- "type": "string",- "enum": [- "V1",- "V2",- "V3"- ]- },- "description": "Webhook versions that support this event"- }- },- "required": [- "event_type",- "description",- "supported_versions"- ]- }- }- },- "required": [- "items"- ]- }- }- }- },- "401": {- "description": "Unauthorized",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"+ "properties": {}}}}},"500": {- "description": "Internal server error",+ "description": "Internal server error - Failed to update the connected account status due to a server-side issue","content": {"application/json": {"schema": {@@ -7269,17 +6478,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/toolkits": {- "get": {- "summary": "List available toolkits",- "description": "Retrieves a comprehensive list of toolkits of their latest versions that are available to the authenticated project. Toolkits represent integration points with external services and applications, each containing a collection of tools and triggers. This endpoint supports filtering by category and management type, as well as different sorting options.",+ "/api/v3.1/connected_accounts/{nanoid}/refresh": {+ "post": {+ "summary": "Refresh authentication for a connected account",+ "description": "Initiates a new authentication flow for a connected account when credentials have expired or become invalid. This may generate a new authentication URL for OAuth flows or refresh tokens for other auth schemes.","tags": [- "Toolkits"+ "Connected Accounts"],- "operationId": "getToolkits",+ "operationId": "postConnectedAccountsByNanoidRefresh","security": [{"ApiKeyAuth": []@@ -7292,278 +6502,92 @@{"schema": {"type": "string",- "description": "Category ID or name to filter toolkits by",- "example": "productivity"+ "format": "connectedAccountId"},- "required": false,- "description": "Filter toolkits by category",- "name": "category",- "in": "query"- },- {- "schema": {- "type": "string",- "enum": [- "composio",- "all",- "project"- ],- "description": "Entity responsible for managing the toolkits"- },- "required": false,- "description": "Filter toolkits by who manages them",- "name": "managed_by",- "in": "query"- },- {- "schema": {- "type": "string",- "enum": [- "usage",- "alphabetically"- ],- "description": "Determines how toolkits should be sorted in the response"- },- "required": false,- "description": "Sort order for returned toolkits",- "name": "sort_by",- "in": "query"- },- {- "schema": {- "type": "boolean",- "nullable": true,- "default": false,- "description": "Include deprecated toolkits in the response",- "example": true- },- "required": false,- "description": "Include deprecated toolkits in the response",- "name": "include_deprecated",- "in": "query"+ "required": true,+ "description": "The unique identifier of the connected account",+ "example": "ca_1a2b3c4d5e6f",+ "name": "nanoid",+ "in": "path"},{"schema": {"type": "string",- "description": "Search query to filter toolkits by name, slug, or description (minimum 3 characters)",- "example": "gmail"- },- "required": false,- "description": "Search query to filter toolkits by name, slug, or description",- "name": "search",- "in": "query"- },- {- "schema": {- "type": "number",- "nullable": true- },- "required": false,- "description": "Number of items per page, max allowed is 1000",- "name": "limit",- "in": "query"- },- {- "schema": {- "type": "string"+ "format": "uri"},"required": false,- "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",- "name": "cursor",+ "name": "redirect_url","in": "query"}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "redirect_url": {+ "type": "string",+ "format": "uri"+ },+ "validate_credentials": {+ "type": "boolean",+ "default": false,+ "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme",+ "x-experimental": true+ }+ }+ }+ }+ }+ },"responses": {"200": {- "description": "Toolkits retrieved successfully. Returns a paginated list of available toolkits with detailed metadata.",+ "description": "Successfully refreshed the connected account authentication. For OAuth flows, a new redirect URL is provided.","content": {"application/json": {"schema": {"type": "object","properties": {- "items": {- "type": "array",- "items": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "URL-friendly unique identifier for the toolkit",- "example": "github"- },- "name": {- "type": "string",- "description": "Human-readable name of the toolkit",- "example": "GitHub"- },- "auth_schemes": {- "type": "array",- "items": {- "type": "string"- },- "description": "List of authentication methods supported by this toolkit",- "example": [- "oauth2",- "api_key"- ]- },- "composio_managed_auth_schemes": {- "type": "array",- "items": {- "type": "string"- },- "description": "List of authentication methods that Composio manages for this toolkit",- "example": [- "oauth2"- ]- },- "is_local_toolkit": {- "type": "boolean",- "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",- "deprecated": true,- "example": false- },- "no_auth": {- "type": "boolean",- "description": "When true, this toolkit can be used without authentication",- "example": false- },- "auth_guide_url": {- "type": "string",- "nullable": true,- "description": "URL to a guide page with authentication setup instructions for this toolkit",- "example": "https://composio.dev/auth/github"- },- "deprecated": {- "$ref": "#/components/schemas/DeprecatedToolkitInfo"- },- "meta": {- "type": "object",- "properties": {- "created_at": {- "type": "string",- "description": "Creation date and time of the toolkit",- "example": "2023-01-15T09:30:00.000Z"- },- "updated_at": {- "type": "string",- "description": "Last modification date and time of the toolkit",- "example": "2023-05-20T14:45:00.000Z"- },- "description": {- "type": "string",- "description": "Human-readable description explaining the toolkit's purpose and functionality",- "example": "Integrate with GitHub repositories, issues, pull requests, and more."- },- "logo": {- "type": "string",- "description": "Image URL for the toolkit's branding",- "example": "https://assets.composio.dev/logos/github.png"- },- "app_url": {- "type": "string",- "nullable": true,- "description": "Link to the toolkit's main application or service website",- "example": "https://github.com"- },- "categories": {- "type": "array",- "items": {- "type": "object",- "properties": {- "id": {- "type": "string",- "description": "Category identifier",- "example": "developer-tools"- },- "name": {- "type": "string",- "description": "Human-readable category name",- "example": "Developer Tools"- }- },- "required": [- "id",- "name"- ]- },- "description": "List of categories associated with this toolkit",- "example": [- {- "id": "developer-tools",- "name": "Developer Tools"- },- {- "id": "productivity",- "name": "Productivity"- }- ]- },- "triggers_count": {- "type": "number",- "description": "Count of available triggers in this toolkit",- "example": 5- },- "tools_count": {- "type": "number",- "description": "Count of available tools in this toolkit",- "example": 12- },- "version": {- "type": "string",- "description": "Version of the toolkit",- "example": "20250905_00"- }- },- "required": [- "created_at",- "updated_at",- "description",- "logo",- "categories",- "triggers_count",- "tools_count",- "version"- ],- "description": "Additional metadata about the toolkit"- }- },- "required": [- "slug",- "name",- "is_local_toolkit",- "deprecated",- "meta"- ],- "description": "Detailed information about a toolkit"- }- },- "next_cursor": {+ "id": {"type": "string",- "nullable": true- },- "total_pages": {- "type": "number"+ "description": "The unique identifier of the connected account"},- "current_page": {- "type": "number"+ "status": {+ "type": "string",+ "enum": [+ "INITIALIZING",+ "INITIATED",+ "ACTIVE",+ "FAILED",+ "EXPIRED",+ "INACTIVE"+ ],+ "description": "The current status of the connected account (e.g., active, pending, failed)"},- "total_items": {- "type": "number"+ "redirect_url": {+ "type": "string",+ "nullable": true,+ "description": "The URL to which the user should be redirected to complete the authentication process (null for auth schemes that do not require redirection)"}},"required": [- "items",- "total_pages",- "current_page",- "total_items"- ]+ "id",+ "status",+ "redirect_url"+ ],+ "description": "Response schema for a refreshed connected account authentication",+ "example": {+ "id": "ca_1a2b3c4d5e6f",+ "status": "ACTIVE",+ "redirect_url": "https://app.example.com/oauth/callback"+ }}}}},"400": {- "description": "Bad request. The query parameters may be invalid or in an incorrect format.",+ "description": "Bad request - Invalid nanoid format or the account cannot be refreshed in its current state","content": {"application/json": {"schema": {@@ -7573,27 +6597,7 @@}},"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found. The toolkits you are looking for do not exist.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",+ "description": "Unauthorized - Authentication failed","content": {"application/json": {"schema": {@@ -7601,83 +6605,9 @@}}}- }- }- }- },- "/api/v3/toolkits/categories": {- "get": {- "summary": "List toolkit categories",- "description": "Retrieves a comprehensive list of all available toolkit categories from their latest versions. These categories can be used to filter toolkits by type or purpose when using the toolkit listing endpoint. Categories help organize toolkits into logical groups based on their functionality or industry focus.",- "tags": [- "Toolkits"- ],- "operationId": "getToolkitsCategories",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "responses": {- "200": {- "description": "Successfully retrieved a paginated list of all available toolkit categories with their identifiers and display names.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "items": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string",- "description": "Display name of the toolkit category",- "example": "Developer Tools"- },- "id": {- "type": "string",- "description": "URL-friendly unique identifier for the category, used for filtering toolkits",- "example": "developer-tools"- }- },- "required": [- "name",- "id"- ],- "description": "Information about a single toolkit category"- }- },- "next_cursor": {- "type": "string",- "nullable": true- },- "total_pages": {- "type": "number"- },- "current_page": {- "type": "number"- },- "total_items": {- "type": "number"- }- },- "required": [- "items",- "total_pages",- "current_page",- "total_items"- ]- }- }- }},- "400": {- "description": "Bad request. The request may be invalid or in an incorrect format.",+ "403": {+ "description": "Forbidden - Insufficient permissions to refresh this connected account","content": {"application/json": {"schema": {@@ -7686,8 +6616,8 @@}}},- "401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "404": {+ "description": "Not found - Connected account does not exist or was deleted","content": {"application/json": {"schema": {@@ -7696,8 +6626,8 @@}}},- "404": {- "description": "Not found. The requested resource was not found.",+ "500": {+ "description": "Internal server error - Failed to refresh the connected account authentication","content": {"application/json": {"schema": {@@ -7706,8 +6636,8 @@}}},- "500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",+ "501": {+ "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme","content": {"application/json": {"schema": {@@ -7716,17 +6646,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/toolkits/{slug}": {- "get": {- "summary": "Get toolkit by slug",- "description": "Retrieves comprehensive information about a specific toolkit using its unique slug identifier. This endpoint provides detailed metadata, authentication configuration options, and feature counts for the requested toolkit.",+ "/api/v3.1/connected_accounts/link": {+ "post": {+ "summary": "Create a new auth link session",+ "description": "Creates a new authentication link session that users can use to connect their accounts","tags": [- "Toolkits"+ "Connected Accounts"],- "operationId": "getToolkitsBySlug",+ "operationId": "postConnectedAccountsLink","security": [{"ApiKeyAuth": []@@ -7735,476 +6666,2139 @@"UserApiKeyAuth": []}],- "parameters": [- {- "schema": {- "type": "string",- "description": "The unique slug identifier of the toolkit to retrieve",- "example": "github"- },- "required": true,- "description": "Toolkit slug identifier",- "name": "slug",- "in": "path"- },- {- "schema": {- "type": "string",- "default": "latest",- "description": "Version of the toolkit",- "example": "20250905_00"- },- "required": false,- "description": "Version of the toolkit",- "name": "version",- "in": "query"- }- ],- "responses": {- "200": {- "description": "Successfully retrieved detailed information about the requested toolkit, including authentication options, metadata, and feature counts.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "URL-friendly unique identifier for the toolkit",- "example": "github"- },- "name": {- "type": "string",- "description": "Human-readable name of the toolkit",- "example": "GitHub"- },- "enabled": {- "type": "boolean",- "description": "Indicates if this toolkit is currently enabled and available for use",- "example": true- },- "composio_managed_auth_schemes": {- "type": "array",- "items": {+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "auth_config_id": {+ "type": "string",+ "format": "authConfigId",+ "description": "The auth config id to create a link for"+ },+ "user_id": {+ "type": "string",+ "minLength": 1,+ "description": "The user id to create a link for"+ },+ "alias": {+ "type": "string",+ "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."+ },+ "callback_url": {+ "type": "string",+ "description": "The callback url to create a link for"+ },+ "connection_data": {+ "description": "Optional data to pre-fill connection fields with default values",+ "type": "object",+ "properties": {+ "subdomain": {"type": "string"},- "description": "List of authentication methods that Composio manages for this toolkit",- "example": [- "oauth2"- ]- },- "is_local_toolkit": {- "type": "boolean",- "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",- "deprecated": true,- "example": false- },- "auth_config_details": {- "type": "array",- "items": {- "type": "object",- "properties": {- "mode": {+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "oauth_token": {+ "type": "string"+ },+ "authUri": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callbackUrl": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "error": {+ "type": "string"+ },+ "error_description": {+ "type": "string"+ },+ "expired_at": {+ "type": "string"+ },+ "state_prefix": {+ "type": "string",+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"+ },+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"+ },+ "code_verifier": {+ "type": "string"+ },+ "finalRedirectUri": {+ "type": "string"+ },+ "webhook_signature": {+ "type": "string"+ },+ "access_token": {+ "type": "string"+ },+ "id_token": {+ "type": "string"+ },+ "token_type": {+ "type": "string"+ },+ "refresh_token": {+ "type": "string",+ "nullable": true+ },+ "expires_in": {+ "anyOf": [+ {+ "type": "number"+ },+ {+ "type": "string"+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "scope": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "authed_user": {+ "type": "object",+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {+ "type": "string"+ }+ },+ "description": "for slack user scopes"+ },+ "generic_api_key": {+ "type": "string"+ },+ "api_key": {+ "type": "string"+ },+ "bearer_token": {+ "type": "string"+ },+ "basic_encoded": {+ "type": "string"+ },+ "username": {+ "type": "string"+ },+ "password": {+ "type": "string"+ },+ "token": {+ "type": "string"+ },+ "composio_link_redirect_url": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "sessionId": {+ "type": "string"+ },+ "devKey": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "client_id": {+ "type": "string",+ "description": "Dynamically registered client ID"+ },+ "client_secret": {+ "type": "string",+ "description": "Dynamically registered client secret"+ },+ "client_id_issued_at": {+ "type": "number"+ },+ "client_secret_expires_at": {+ "type": "number"+ },+ "expires_at": {+ "type": "string"+ }+ },+ "additionalProperties": true+ }+ },+ "required": [+ "auth_config_id",+ "user_id"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Successfully created auth link",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "link_token": {+ "type": "string",+ "description": "The generated link token for the auth session"+ },+ "redirect_url": {+ "type": "string",+ "description": "The redirect URI to send users to for authentication"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO timestamp when the link expires"+ },+ "connected_account_id": {+ "type": "string",+ "format": "connectedAccountId",+ "description": "The connected account ID that was created"+ }+ },+ "required": [+ "link_token",+ "redirect_url",+ "expires_at",+ "connected_account_id"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Auth config not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/org/usage/summary": {+ "get": {+ "summary": "Org usage summary",+ "description": "Aggregated metering usage for the authenticated organization across all projects. Requires ClickHouse logging (`USE_CLICKHOUSE_FOR_LOGS`). Values are summed from raw metering events grouped by `entity_type`.",+ "tags": [+ "Organization"+ ],+ "operationId": "getOrgUsageSummary",+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time."+ },+ "required": false,+ "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time.",+ "name": "start_time",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Exclusive range end (ISO 8601). Defaults to now."+ },+ "required": false,+ "description": "Exclusive range end (ISO 8601). Defaults to now.",+ "name": "end_time",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types."+ },+ "required": false,+ "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types.",+ "name": "entity_types",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Usage aggregates for the organization.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "rows": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "entity_type": {+ "type": "string"+ },+ "unit": {+ "type": "string"+ },+ "total_quantity": {+ "type": "string"+ },+ "event_count": {+ "type": "integer",+ "minimum": 0+ }+ },+ "required": [+ "entity_type",+ "unit",+ "total_quantity",+ "event_count"+ ]+ }+ }+ },+ "required": [+ "rows"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid time range, entity_types, or query parameters.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Authentication required.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Failed to load usage from analytics store or feature configuration.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/org/project/config": {+ "get": {+ "summary": "Get project configuration",+ "description": "Retrieves the current project configuration including 2FA settings.",+ "tags": [+ "Projects"+ ],+ "operationId": "getOrgProjectConfig",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Project configuration retrieved successfully.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "is_2FA_enabled": {+ "type": "boolean"+ },+ "logo_url": {+ "type": "string"+ },+ "display_name": {+ "type": "string"+ },+ "mask_secret_keys_in_connected_account": {+ "type": "boolean"+ },+ "log_visibility_setting": {+ "type": "string",+ "enum": [+ "show_all",+ "dont_store_data"+ ]+ },+ "require_mcp_api_key": {+ "type": "boolean"+ },+ "is_composio_link_enabled_for_managed_auth": {+ "type": "boolean",+ "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."+ },+ "signed_url_file_expiry_in_seconds": {+ "type": "number",+ "minimum": 1,+ "maximum": 86400+ }+ },+ "required": [+ "is_2FA_enabled",+ "mask_secret_keys_in_connected_account",+ "log_visibility_setting"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The project configuration data may be invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Project not found. The specified project does not exist or has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ },+ "patch": {+ "summary": "Update project configuration",+ "description": "Updates the project configuration settings.",+ "tags": [+ "Projects"+ ],+ "operationId": "patchOrgProjectConfig",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "is_2FA_enabled": {+ "type": "boolean"+ },+ "logo_url": {+ "type": "string"+ },+ "display_name": {+ "type": "string"+ },+ "mask_secret_keys_in_connected_account": {+ "type": "boolean"+ },+ "log_visibility_setting": {+ "type": "string",+ "enum": [+ "show_all",+ "dont_store_data"+ ]+ },+ "require_mcp_api_key": {+ "type": "boolean"+ },+ "is_composio_link_enabled_for_managed_auth": {+ "type": "boolean",+ "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."+ },+ "signed_url_file_expiry_in_seconds": {+ "type": "number",+ "minimum": 1,+ "maximum": 86400+ }+ }+ },+ "examples": {+ "Enable 2FA": {+ "value": {+ "is_2FA_enabled": true+ }+ },+ "Disable 2FA": {+ "value": {+ "is_2FA_enabled": false+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Project configuration updated successfully.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "is_2FA_enabled": {+ "type": "boolean"+ },+ "logo_url": {+ "type": "string"+ },+ "display_name": {+ "type": "string"+ },+ "mask_secret_keys_in_connected_account": {+ "type": "boolean"+ },+ "log_visibility_setting": {+ "type": "string",+ "enum": [+ "show_all",+ "dont_store_data"+ ]+ },+ "require_mcp_api_key": {+ "type": "boolean"+ },+ "is_composio_link_enabled_for_managed_auth": {+ "type": "boolean",+ "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."+ },+ "signed_url_file_expiry_in_seconds": {+ "type": "number",+ "minimum": 1,+ "maximum": 86400+ }+ },+ "required": [+ "is_2FA_enabled",+ "mask_secret_keys_in_connected_account",+ "log_visibility_setting"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The configuration data may be invalid or missing.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Project not found. The specified project does not exist or has been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/org/project/usage/summary": {+ "get": {+ "summary": "Project usage summary",+ "description": "Aggregated metering usage for the authenticated project only. Requires ClickHouse logging (`USE_CLICKHOUSE_FOR_LOGS`). Values are summed from raw metering events grouped by `entity_type`.",+ "tags": [+ "Projects"+ ],+ "operationId": "getOrgProjectUsageSummary",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time."+ },+ "required": false,+ "description": "Inclusive range start (ISO 8601). Defaults to 30 days before end_time.",+ "name": "start_time",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Exclusive range end (ISO 8601). Defaults to now."+ },+ "required": false,+ "description": "Exclusive range end (ISO 8601). Defaults to now.",+ "name": "end_time",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types."+ },+ "required": false,+ "description": "Filter to these metering entity types (comma-separated or repeated query keys). Omit for all types.",+ "name": "entity_types",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Usage aggregates for the project.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "rows": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "entity_type": {+ "type": "string"+ },+ "unit": {+ "type": "string"+ },+ "total_quantity": {+ "type": "string"+ },+ "event_count": {+ "type": "integer",+ "minimum": 0+ }+ },+ "required": [+ "entity_type",+ "unit",+ "total_quantity",+ "event_count"+ ]+ }+ }+ },+ "required": [+ "rows"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid time range, entity_types, or query parameters.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Authentication required.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Failed to load usage from analytics store or feature configuration.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/org/owner/project/new": {+ "post": {+ "summary": "Create a new project",+ "description": "Creates a new project within the authenticated user's organization using the specified name. Projects are isolated environments within your organization, each with their own API keys, webhook configurations, and resources. Use this endpoint to create additional projects for different environments (e.g., development, staging, production) or for separate applications.",+ "tags": [+ "Projects"+ ],+ "operationId": "postOrgOwnerProjectNew",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 3,+ "maxLength": 75,+ "pattern": "^[a-zA-Z0-9_-]+$",+ "description": "A unique name for your project that follows the required format rules",+ "example": "my-awesome-project"+ },+ "should_create_api_key": {+ "type": "boolean",+ "default": false,+ "description": "Whether to create an API key for the project. If true, the API key will be created and returned in the response.",+ "example": false+ },+ "config": {+ "type": "object",+ "properties": {+ "is_2FA_enabled": {+ "type": "boolean"+ },+ "logo_url": {+ "type": "string"+ },+ "display_name": {+ "type": "string"+ },+ "mask_secret_keys_in_connected_account": {+ "type": "boolean"+ },+ "log_visibility_setting": {+ "type": "string",+ "enum": [+ "show_all",+ "dont_store_data"+ ]+ },+ "require_mcp_api_key": {+ "type": "boolean"+ },+ "is_composio_link_enabled_for_managed_auth": {+ "type": "boolean",+ "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key."+ },+ "signed_url_file_expiry_in_seconds": {+ "type": "number",+ "minimum": 1,+ "maximum": 86400+ }+ },+ "required": [+ "is_2FA_enabled",+ "mask_secret_keys_in_connected_account",+ "log_visibility_setting"+ ],+ "description": "Configuration for the project"+ }+ },+ "required": [+ "name"+ ]+ },+ "examples": {+ "Simple project": {+ "value": {+ "name": "my_production_api"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Project successfully created. Returns the complete project object with generated IDs, webhook secrets, and configuration.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier for the project",+ "example": "proj_abc123xyz456"+ },+ "name": {+ "type": "string",+ "description": "Name of the project",+ "example": "My Awesome Project"+ },+ "api_key": {+ "type": "string",+ "nullable": true,+ "description": "API key for the project",+ "example": "ak_abc123xyz456"+ }+ },+ "required": [+ "id",+ "api_key"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if the project name format is invalid, too short, or contains invalid characters.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/org/owner/project/list": {+ "get": {+ "summary": "List all projects",+ "description": "Retrieves all projects belonging to the authenticated organization. Projects are returned in descending order of creation date (newest first). This endpoint is useful for displaying project selection in dashboards or for integrations that need to list all available projects.",+ "tags": [+ "Projects"+ ],+ "operationId": "getOrgOwnerProjectList",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Projects retrieved successfully with pagination. Returns an array of projects with pagination info.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier for the project",+ "example": "proj_abc123xyz456"+ },+ "org_id": {+ "type": "string",+ "format": "orgId",+ "description": "Identifier of the organization that owns this project",+ "example": "org_abc123xyz456"+ },+ "name": {+ "type": "string",+ "description": "Name of the project",+ "example": "My Awesome Project"+ },+ "email": {+ "type": "string",+ "description": "Email address associated with the project",+ "example": "[email protected]"+ },+ "created_at": {+ "type": "string",+ "description": "ISO timestamp when the project was created",+ "example": "2023-05-16T14:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO timestamp when the project was last updated",+ "example": "2023-05-18T09:15:30.000Z"+ },+ "webhook_url": {+ "type": "string",+ "nullable": true,+ "format": "uri",+ "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.",+ "example": "https://example.com/webhook",+ "deprecated": true+ },+ "event_webhook_url": {+ "type": "string",+ "nullable": true,+ "format": "uri",+ "description": "DEPRECATED: No longer used.",+ "example": "https://example.com/events",+ "deprecated": true+ },+ "webhook_secret": {+ "type": "string",+ "nullable": true,+ "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.",+ "example": "whsec_abcdef123456789",+ "deprecated": true+ },+ "triggers_enabled": {+ "type": "boolean",+ "description": "Whether triggers are enabled for this project",+ "example": true+ },+ "last_subscribed_at": {+ "type": "string",+ "nullable": true,+ "format": "date-time",+ "description": "ISO timestamp when the project last subscribed to updates",+ "example": "2023-05-17T10:00:00.000Z"+ },+ "is_new_webhook": {+ "type": "boolean",+ "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",+ "example": true,+ "deprecated": true+ },+ "webhook_version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.",+ "example": "V2"+ },+ "deleted": {+ "type": "boolean",+ "description": "Whether this project has been soft-deleted",+ "example": false+ }+ },+ "required": [+ "id",+ "org_id",+ "name",+ "email",+ "created_at",+ "updated_at",+ "webhook_url",+ "event_webhook_url",+ "webhook_secret",+ "webhook_version",+ "deleted"+ ]+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "data",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if there are invalid query parameters or the request is malformed.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/org/owner/project/{nano_id}": {+ "get": {+ "summary": "Get project details by ID With Org Api key",+ "description": "Retrieves detailed information about a specific project using its unique identifier. This endpoint provides complete project configuration including webhook URLs, creation and update timestamps, and webhook secrets. Use this endpoint to inspect project settings or verify project configuration.",+ "tags": [+ "Projects"+ ],+ "operationId": "getOrgOwnerProjectByNanoId",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier (Nano ID) of the project to retrieve",+ "example": "proj_abc123xyz456"+ },+ "required": true,+ "description": "Unique identifier (Nano ID) of the project to retrieve",+ "name": "nano_id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Project retrieved successfully. Returns a complete project object with all configuration details and associated API keys.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier for the project",+ "example": "proj_abc123xyz456"+ },+ "org_id": {+ "type": "string",+ "format": "orgId",+ "description": "Identifier of the organization that owns this project",+ "example": "org_abc123xyz456"+ },+ "name": {+ "type": "string",+ "description": "Name of the project",+ "example": "My Awesome Project"+ },+ "email": {+ "type": "string",+ "description": "Email address associated with the project",+ "example": "[email protected]"+ },+ "created_at": {+ "type": "string",+ "description": "ISO timestamp when the project was created",+ "example": "2023-05-16T14:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO timestamp when the project was last updated",+ "example": "2023-05-18T09:15:30.000Z"+ },+ "webhook_url": {+ "type": "string",+ "nullable": true,+ "format": "uri",+ "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.",+ "example": "https://example.com/webhook",+ "deprecated": true+ },+ "event_webhook_url": {+ "type": "string",+ "nullable": true,+ "format": "uri",+ "description": "DEPRECATED: No longer used.",+ "example": "https://example.com/events",+ "deprecated": true+ },+ "webhook_secret": {+ "type": "string",+ "nullable": true,+ "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.",+ "example": "whsec_abcdef123456789",+ "deprecated": true+ },+ "triggers_enabled": {+ "type": "boolean",+ "description": "Whether triggers are enabled for this project",+ "example": true+ },+ "last_subscribed_at": {+ "type": "string",+ "nullable": true,+ "format": "date-time",+ "description": "ISO timestamp when the project last subscribed to updates",+ "example": "2023-05-17T10:00:00.000Z"+ },+ "is_new_webhook": {+ "type": "boolean",+ "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",+ "example": true,+ "deprecated": true+ },+ "webhook_version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.",+ "example": "V2"+ },+ "deleted": {+ "type": "boolean",+ "description": "Whether this project has been soft-deleted",+ "example": false+ },+ "api_keys": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Unique identifier for the API key",+ "example": "01H4DKRF5SMP7NQCA3BWT0JYB6"+ },+ "name": {+ "type": "string",+ "description": "User-defined name for the API key",+ "example": "Production Server Key"+ },+ "key": {+ "type": "string",+ "description": "The actual API key value used for authentication",+ "example": "ak_a1b2c3d4e5f6g7h8i9j0"+ },+ "created_at": {+ "type": "string",+ "format": "date-time",+ "description": "ISO 8601 timestamp when the API key was created",+ "example": "2023-07-15T14:30:00.000Z"+ }+ },+ "required": [+ "id",+ "name",+ "key",+ "created_at"+ ]+ },+ "description": "Array of API keys for the project, including their properties"+ }+ },+ "required": [+ "id",+ "org_id",+ "name",+ "email",+ "created_at",+ "updated_at",+ "webhook_url",+ "event_webhook_url",+ "webhook_secret",+ "webhook_version",+ "deleted",+ "api_keys"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if the project ID format is invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The specified project does not exist or you do not have access to it.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ },+ "delete": {+ "summary": "Delete a project",+ "description": "Soft-deletes a project within the organization by its unique identifier. When a project is deleted, it is marked as deleted but not immediately removed from the database. This operation affects all resources associated with the project including API keys, webhook configurations, and connected services. This action cannot be undone through the API.",+ "tags": [+ "Projects"+ ],+ "operationId": "deleteOrgOwnerProjectByNanoId",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier (Nano ID) of the project to delete",+ "example": "proj_abc123xyz456"+ },+ "required": true,+ "description": "Unique identifier (Nano ID) of the project to delete",+ "name": "nano_id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Project successfully deleted. The project has been marked as deleted in the system.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "success"+ ],+ "description": "Status indicating successful deletion",+ "example": "success"+ }+ },+ "required": [+ "status"+ ],+ "description": "Response indicating successful project deletion"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The project ID may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. You do not have permission to delete this project.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The specified project does not exist or has already been deleted.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/org/owner/project/{nano_id}/regenerate_api_key": {+ "post": {+ "summary": "Delete and generate new API key for project",+ "description": "Generates a new API key for the specified project, invalidating any existing API keys for that project. This operation creates a fresh API key with a new random name and key value. All existing API keys for this project will be marked as deleted.",+ "tags": [+ "Projects"+ ],+ "operationId": "postOrgOwnerProjectByNanoIdRegenerateApiKey",+ "security": [+ {+ "OrgApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "projectId",+ "description": "Unique identifier (Nano ID) of the project to regenerate API key for",+ "example": "proj_abc123xyz456"+ },+ "required": true,+ "description": "Unique identifier (Nano ID) of the project to regenerate API key for",+ "name": "nano_id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "API key regenerated successfully. Returns the new API key details.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "api_key": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Unique identifier for the API key",+ "example": "01H4DKRF5SMP7NQCA3BWT0JYB6"+ },+ "name": {+ "type": "string",+ "description": "Name of the API key",+ "example": "epic_avatar"+ },+ "key": {+ "type": "string",+ "description": "The newly generated API key value",+ "example": "ak_a1b2c3d4e5f6g7h8i9j0"+ },+ "created_at": {+ "type": "string",+ "description": "ISO timestamp when the API key was created",+ "example": "2023-05-16T14:30:00.000Z"+ }+ },+ "required": [+ "id",+ "name",+ "key",+ "created_at"+ ],+ "description": "The newly generated API key for this project"+ },+ "message": {+ "type": "string",+ "description": "Success message",+ "example": "API key regenerated successfully"+ }+ },+ "required": [+ "api_key",+ "message"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. The project ID may be invalid or in an incorrect format.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found. The specified project does not exist or you do not have access to it.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/webhook_subscriptions": {+ "post": {+ "summary": "Create webhook subscription",+ "description": "Creates a webhook subscription for the authenticated project. Only one subscription is allowed per project. The signing secret is returned only on creation.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "postWebhookSubscriptions",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "webhook_url": {+ "type": "string",+ "maxLength": 2048,+ "format": "uri",+ "description": "HTTPS URL to receive webhook events"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1,+ "description": "Array of event types to subscribe to"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "default": "V3",+ "description": "Webhook payload version"+ }+ },+ "required": [+ "webhook_url",+ "enabled_events"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Webhook subscription created",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Unique subscription ID"+ },+ "webhook_url": {+ "type": "string",+ "description": "Webhook destination URL"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Subscribed event types"+ },+ "secret": {+ "type": "string",+ "description": "Signing secret for HMAC verification"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ }+ },+ "required": [+ "id",+ "webhook_url",+ "version",+ "enabled_events",+ "secret",+ "created_at",+ "updated_at"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "Subscription already exists",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ },+ "get": {+ "summary": "List webhook subscriptions",+ "description": "Lists all webhook subscriptions for the authenticated project with pagination. Currently limited to one subscription per project.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "getWebhookSubscriptions",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Webhook subscriptions retrieved",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {"type": "string",- "description": "The type of authentication mode (e.g., oauth2, basic_auth, api_key)",- "example": "oauth2"+ "format": "webhookSubscriptionId",+ "description": "Unique subscription ID"},- "fields": {- "type": "object",- "properties": {- "auth_config_creation": {- "type": "object",- "properties": {- "required": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string"- },- "displayName": {- "type": "string"- },- "default": {- "type": "string",- "nullable": true- },- "type": {- "type": "string"- },- "description": {- "type": "string"- },- "required": {- "type": "boolean"- },- "legacy_template_name": {- "type": "string"- }- },- "required": [- "name",- "displayName",- "type",- "description",- "required"- ]- }- },- "optional": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string"- },- "displayName": {- "type": "string"- },- "default": {- "type": "string",- "nullable": true- },- "type": {- "type": "string"- },- "description": {- "type": "string"- },- "required": {- "type": "boolean"- },- "legacy_template_name": {- "type": "string"- }- },- "required": [- "name",- "displayName",- "type",- "description",- "required"- ]- }- }- },- "required": [- "required",- "optional"- ],- "description": "Form fields needed when creating an authentication configuration"- },- "connected_account_initiation": {- "type": "object",- "properties": {- "required": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string"- },- "displayName": {- "type": "string"- },- "default": {- "type": "string",- "nullable": true- },- "type": {- "type": "string"- },- "description": {- "type": "string"- },- "required": {- "type": "boolean"- },- "legacy_template_name": {- "type": "string"- }- },- "required": [- "name",- "displayName",- "type",- "description",- "required"- ]- }- },- "optional": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string"- },- "displayName": {- "type": "string"- },- "default": {- "type": "string",- "nullable": true- },- "type": {- "type": "string"- },- "description": {- "type": "string"- },- "required": {- "type": "boolean"- },- "legacy_template_name": {- "type": "string"- }- },- "required": [- "name",- "displayName",- "type",- "description",- "required"- ]- }- }- },- "required": [- "required",- "optional"- ],- "description": "Form fields needed when connecting a user account with this authentication method"- }- },- "required": [- "auth_config_creation",- "connected_account_initiation"+ "webhook_url": {+ "type": "string",+ "description": "Webhook destination URL"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"],- "description": "Field groups required for different authentication stages"+ "description": "Webhook payload version"},- "proxy": {- "type": "object",- "properties": {- "base_url": {- "type": "string",- "description": "URL to which authentication requests will be proxied",- "example": "https://auth.example.com/proxy"- }+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"},- "required": [- "base_url"- ],- "description": "Configuration for proxying authentication requests to external services"+ "description": "Subscribed event types"},- "name": {+ "secret": {"type": "string",- "description": "Display name for this authentication method",- "example": "OAuth 2.0"+ "description": "Masked signing secret (full secret only on create/rotate)"},- "auth_hint_url": {+ "created_at": {"type": "string",- "nullable": true,- "description": "URL to a page where users can obtain or configure credentials for this authentication method",- "example": "https://github.com/settings/tokens"+ "description": "ISO 8601 timestamp"},- "deprecated_auth_provider_details": {- "type": "object",- "properties": {- "authorization_url": {- "type": "string"- },- "token_url": {- "type": "string"- }- },- "description": "Authentication URL fields for OAuth 2.0 and OAuth 1.0. We don't recommend using this field for authentication and might break post Aug 31 2025.",- "deprecated": true+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"}},"required": [- "mode",- "fields",- "name"- ],- "description": "Detailed configuration for an authentication method"- },- "description": "Complete authentication configuration details for each supported auth method"+ "id",+ "webhook_url",+ "version",+ "enabled_events",+ "secret",+ "created_at",+ "updated_at"+ ]+ }},- "auth_guide_url": {+ "next_cursor": {"type": "string",- "nullable": true,- "description": "URL to a guide page with authentication setup instructions for this toolkit",- "example": "https://composio.dev/auth/github"+ "nullable": true},- "base_url": {- "type": "string",- "description": "If evaluation of base URL needs some connection info (like shopify), please create the connection and get the base URL from there",- "example": "https://api.github.com"+ "total_pages": {+ "type": "number"},- "meta": {- "type": "object",- "properties": {- "created_at": {- "type": "string",- "description": "Creation date and time of the toolkit",- "example": "2023-01-15T09:30:00.000Z"- },- "updated_at": {- "type": "string",- "description": "Last modification date and time of the toolkit",- "example": "2023-05-20T14:45:00.000Z"- },- "description": {- "type": "string",- "description": "Human-readable description explaining the toolkit's purpose and functionality",- "example": "Integrate with GitHub repositories, issues, pull requests, and more."- },- "logo": {- "type": "string",- "description": "Image URL for the toolkit's branding",- "example": "https://assets.composio.dev/logos/github.png"- },- "app_url": {- "type": "string",- "nullable": true,- "description": "Link to the toolkit's main application or service website",- "example": "https://github.com"- },- "categories": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string",- "description": "Human-readable category name",- "example": "Developer Tools"- },- "slug": {- "type": "string",- "description": "URL-friendly identifier for the category",- "example": "developer-tools"- }- },- "required": [- "name",- "slug"- ]- },- "description": "List of categories associated with this toolkit",- "example": [- {- "name": "Developer Tools",- "slug": "developer-tools"- },- {- "name": "Productivity",- "slug": "productivity"- }- ]- },- "triggers_count": {- "type": "number",- "description": "Count of available triggers in this toolkit",- "example": 5- },- "tools_count": {- "type": "number",- "description": "Count of available tools in this toolkit",- "example": 12- },- "version": {- "type": "string",- "description": "Version of the toolkit",- "example": "20250905_00"- },- "available_versions": {- "type": "array",- "items": {- "type": "string"- },- "description": "Available versions of the toolkit",- "example": [- "20250905_00",- "20250906_00"- ]- }- },- "required": [- "created_at",- "updated_at",- "description",- "logo",- "categories",- "triggers_count",- "tools_count",- "version",- "available_versions"- ],- "description": "Comprehensive metadata for the toolkit including dates, descriptions, and statistics"+ "current_page": {+ "type": "number"},- "get_current_user_endpoint": {+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid pagination",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/webhook_subscriptions/{id}": {+ "get": {+ "summary": "Get webhook subscription",+ "description": "Retrieves a webhook subscription by ID.",+ "tags": [+ "Webhooks"+ ],+ "operationId": "getWebhookSubscriptionsById",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Webhook subscription ID"+ },+ "required": true,+ "description": "Webhook subscription ID",+ "name": "id",+ "in": "path"+ }+ ],+ "responses": {+ "200": {+ "description": "Webhook subscription retrieved",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "id": {"type": "string",- "description": "Endpoint to get the current user"+ "format": "webhookSubscriptionId",+ "description": "Unique subscription ID"},- "get_current_user_endpoint_method": {+ "webhook_url": {"type": "string",- "description": "HTTP method to use when calling the get current user endpoint (e.g., GET, POST)",- "example": "GET"+ "description": "Webhook destination URL"},- "deprecated": {- "type": "object",- "properties": {- "toolkitId": {- "type": "string"- },- "getCurrentUserEndpoint": {- "type": "string"- },- "rawProxyInfoByAuthSchemes": {- "type": "array",- "items": {- "type": "object",- "additionalProperties": {}- }- }+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"},- "required": [- "toolkitId",- "rawProxyInfoByAuthSchemes"- ]+ "description": "Subscribed event types"+ },+ "secret": {+ "type": "string",+ "description": "Masked signing secret (full secret only on create/rotate)"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"}},"required": [- "slug",- "name",- "enabled",- "is_local_toolkit",- "meta",- "deprecated"- ],- "description": "Detailed information about a single toolkit"- }- }- }- },- "400": {- "description": "Bad request. The toolkit slug may be invalid or in an incorrect format.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"+ "id",+ "webhook_url",+ "version",+ "enabled_events",+ "secret",+ "created_at",+ "updated_at"+ ]}}}},"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -8214,7 +8808,7 @@}},"404": {- "description": "Not found. The requested toolkit does not exist or is not accessible to the authenticated project.",+ "description": "Subscription not found","content": {"application/json": {"schema": {@@ -8224,7 +8818,7 @@}},"500": {- "description": "Internal server error. An unexpect ed error occurred while processing the request.",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -8233,17 +8827,16 @@}}}- }- }- },- "/api/v3/tools": {- "get": {- "summary": "List available tools",- "description": "Retrieve a paginated list of available tools with comprehensive filtering, sorting and search capabilities. Use query parameters to narrow down results by toolkit, tags, or search terms.",+ },+ "x-api-version": "3.1"+ },+ "patch": {+ "summary": "Update webhook subscription",+ "description": "Updates a webhook subscription. At least one field must be provided.","tags": [- "Tools"+ "Webhooks"],- "operationId": "getTools",+ "operationId": "patchWebhookSubscriptionsById","security": [{"ApiKeyAuth": []@@ -8253,201 +8846,113 @@}],"parameters": [- {- "schema": {- "type": "string"- },- "required": false,- "description": "The slug of the toolkit to filter by",- "in": "query",- "name": "toolkit_slug"- },- {- "schema": {- "type": "string"- },- "required": false,- "description": "Comma-separated list of specific tool slugs to retrieve (overrides other filters)",- "in": "query",- "name": "tool_slugs"- },- {- "schema": {- "oneOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"- }- }- ]- },- "required": false,- "description": "Comma-separated list of auth config IDs to filter tools by",- "in": "query",- "name": "auth_config_ids"- },{"schema": {"type": "string",- "enum": [- "true",- "false"- ]- },- "required": false,- "description": "Filter to only show important/featured tools (set to \"true\" to enable)",- "in": "query",- "name": "important"- },- {- "schema": {- "type": "array",- "items": {- "type": "string"- }- },- "required": false,- "description": "Filter tools by one or more tags (can be specified multiple times)",- "in": "query",- "name": "tags"- },- {- "schema": {- "type": "array",- "nullable": true,- "items": {- "type": "string"- },- "description": "Filter tools by one or more scopes (can be specified multiple times)"- },- "required": false,- "description": "Array of scopes to filter tools by)",- "name": "scopes",- "in": "query"- },- {- "schema": {- "type": "string"- },- "required": false,- "description": "Full-text search query to filter tools by name, slug, or description. Applied as a soft filter on top of other filters.",- "in": "query",- "name": "query"- },- {- "schema": {- "type": "string"- },- "required": false,- "description": "Deprecated: use \"query\" instead. Free-text search query to find tools by name, description, or functionality.",- "in": "query",- "name": "search",- "deprecated": true- },- {- "schema": {- "type": "boolean",- "default": true- },- "required": false,- "description": "Include deprecated tools in the response",- "in": "query",- "name": "include_deprecated"- },- {- "schema": {- "oneOf": [- {- "type": "null"- },- {- "type": "string"- },- {- "type": "object",- "additionalProperties": {- "type": "string"- },- "description": "Object representation of parsed bracket notation"- }- ]- },- "required": false,- "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",- "in": "query",- "name": "toolkit_versions",- "examples": {- "latest_version": {- "summary": "Latest version for all toolkits",- "value": "latest"- },- "bracket_notation": {- "summary": "Specific versions using bracket notation",- "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"- },- "null_value": {- "summary": "No version specified (uses 00000000_00)",- "value": null- }- }- },- {- "schema": {- "type": "number",- "nullable": true- },- "required": false,- "description": "Number of items per page, max allowed is 1000",- "name": "limit",- "in": "query"- },- {- "schema": {- "type": "string"+ "format": "webhookSubscriptionId",+ "description": "Webhook subscription ID"},- "required": false,- "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",- "name": "cursor",- "in": "query"+ "required": true,+ "description": "Webhook subscription ID",+ "name": "id",+ "in": "path"}],- "responses": {- "200": {- "description": "Successfully retrieved tools list with pagination information",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/ToolsPaginated"- }- }- }- },- "400": {- "description": "Bad request - Invalid query parameters",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "webhook_url": {+ "type": "string",+ "maxLength": 2048,+ "format": "uri",+ "description": "HTTPS URL to receive webhook events"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1,+ "description": "Array of event types to subscribe to"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ }}}}- },- "401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",+ }+ },+ "responses": {+ "200": {+ "description": "Webhook subscription updated","content": {"application/json": {"schema": {- "$ref": "#/components/schemas/Error"+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Unique subscription ID"+ },+ "webhook_url": {+ "type": "string",+ "description": "Webhook destination URL"+ },+ "version": {+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ],+ "description": "Webhook payload version"+ },+ "enabled_events": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Subscribed event types"+ },+ "secret": {+ "type": "string",+ "description": "Masked signing secret (full secret only on create/rotate)"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ },+ "updated_at": {+ "type": "string",+ "description": "ISO 8601 timestamp"+ }+ },+ "required": [+ "id",+ "webhook_url",+ "version",+ "enabled_events",+ "secret",+ "created_at",+ "updated_at"+ ]}}}},- "403": {- "description": "Forbidden - User does not have permission to access tools",+ "400": {+ "description": "Invalid request","content": {"application/json": {"schema": {@@ -8456,8 +8961,8 @@}}},- "404": {- "description": "Not found - The requested resource was not found",+ "401": {+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -8466,8 +8971,8 @@}}},- "429": {- "description": "Too many requests - Rate limit exceeded",+ "404": {+ "description": "Subscription not found","content": {"application/json": {"schema": {@@ -8477,7 +8982,7 @@}},"500": {- "description": "Internal server error - Something went wrong on the server",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -8486,17 +8991,16 @@}}}- }- }- },- "/api/v3/tools/enum": {- "get": {- "summary": "Get tool enum list",- "description": "Retrieve a list of all available tool enumeration values (tool slugs) from latest version of each toolkit. This endpoint returns a comma-separated string of tool slugs that can be used in other API calls.",+ },+ "x-api-version": "3.1"+ },+ "delete": {+ "summary": "Delete webhook subscription",+ "description": "Permanently deletes a webhook subscription. This action cannot be undone.","tags": [- "Tools"+ "Webhooks"],- "operationId": "getToolsEnum",+ "operationId": "deleteWebhookSubscriptionsById","security": [{"ApiKeyAuth": []@@ -8505,43 +9009,40 @@"UserApiKeyAuth": []}],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Webhook subscription ID"+ },+ "required": true,+ "description": "Webhook subscription ID",+ "name": "id",+ "in": "path"+ }+ ],"responses": {"200": {- "description": "Successfully retrieved tool enum list",+ "description": "Webhook subscription deleted","content": {"application/json": {"schema": {- "type": "array",- "items": {- "type": "string"+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ }},- "description": "JSON string containing all tool enum values from latest version of each toolkit"- }- }- }- },- "400": {- "description": "Bad request - Invalid request parameters",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"+ "required": [+ "success"+ ]}}}},"401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden - User does not have permission to access tool enums",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -8551,7 +9052,7 @@}},"404": {- "description": "Not found - Tool enum list not found",+ "description": "Subscription not found","content": {"application/json": {"schema": {@@ -8561,7 +9062,7 @@}},"500": {- "description": "Internal server error - Something went wrong on the server",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -8570,17 +9071,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tools/{tool_slug}": {- "get": {- "summary": "Get tool by slug",- "description": "Retrieve detailed information about a specific tool using its slug identifier. This endpoint returns full metadata about a tool including input/output parameters, versions, and toolkit information.",+ "/api/v3.1/webhook_subscriptions/{id}/rotate_secret": {+ "post": {+ "summary": "Rotate webhook secret",+ "description": "Generates a new signing secret for the webhook subscription. The new secret is returned only in this response.","tags": [- "Tools"+ "Webhooks"],- "operationId": "getToolsByToolSlug",+ "operationId": "postWebhookSubscriptionsByIdRotateSecret","security": [{"ApiKeyAuth": []@@ -8592,83 +9094,44 @@"parameters": [{"schema": {- "type": "string"+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Webhook subscription ID"},"required": true,- "description": "The unique slug identifier of the tool",- "name": "tool_slug",+ "description": "Webhook subscription ID",+ "name": "id","in": "path"- },- {- "schema": {- "type": "string"- },- "required": false,- "description": "Optional version of the tool to retrieve",- "name": "version",- "in": "query"- },- {- "schema": {- "oneOf": [- {- "type": "null"- },- {- "type": "string"- },- {- "type": "object",- "additionalProperties": {- "type": "string"- },- "description": "Object representation of parsed bracket notation"- }- ]- },- "required": false,- "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",- "in": "query",- "name": "toolkit_versions",- "examples": {- "latest_version": {- "summary": "Latest version for all toolkits",- "value": "latest"- },- "bracket_notation": {- "summary": "Specific versions using bracket notation",- "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"- },- "null_value": {- "summary": "No version specified (uses 00000000_00)",- "value": null- }- }}],"responses": {"200": {- "description": "Successfully retrieved tool details",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Tool"- }- }- }- },- "400": {- "description": "Bad request - Invalid tool slug format",+ "description": "Webhook secret rotated","content": {"application/json": {"schema": {- "$ref": "#/components/schemas/Error"+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "webhookSubscriptionId",+ "description": "Subscription ID"+ },+ "secret": {+ "type": "string",+ "description": "New signing secret"+ }+ },+ "required": [+ "id",+ "secret"+ ]}}}},"401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -8678,7 +9141,7 @@}},"404": {- "description": "Not found - Tool with the specified slug does not exist",+ "description": "Subscription not found","content": {"application/json": {"schema": {@@ -8688,7 +9151,7 @@}},"500": {- "description": "Internal server error - Something went wrong on the server",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -8697,17 +9160,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/toolkits/multi": {- "post": {- "summary": "Fetch multiple toolkits",- "description": "Retrieves a comprehensive list of toolkits of their latest versions that are available to the authenticated project. Toolkits represent integration points with external services and applications, each containing a collection of tools and triggers. This endpoint supports filtering by category and management type, as well as different sorting options. You can optionally specify a list of toolkit slugs to fetch specific toolkits.",+ "/api/v3.1/webhook_subscriptions/event_types": {+ "get": {+ "summary": "List available event types",+ "description": "Returns all event types that can be subscribed to, along with their supported webhook versions.","tags": [- "Toolkits"+ "Webhooks"],- "operationId": "postToolkitsMulti",+ "operationId": "getWebhookSubscriptionsEventTypes","security": [{"ApiKeyAuth": []@@ -8716,62 +9180,9 @@"UserApiKeyAuth": []}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "toolkits": {- "type": "array",- "items": {- "type": "string"- },- "description": "Array of toolkit slug identifiers to retrieve",- "example": [- "github",- "slack",- "gmail"- ]- },- "category": {- "type": "string",- "description": "Category ID or name to filter toolkits by",- "example": "productivity"- },- "managed_by": {- "type": "string",- "enum": [- "composio",- "all",- "project"- ],- "description": "Entity responsible for managing the toolkits"- },- "sort_by": {- "type": "string",- "enum": [- "usage",- "alphabetically"- ],- "description": "Determines how toolkits should be sorted in the response"- },- "limit": {- "type": "number",- "nullable": true- },- "cursor": {- "type": "string"- }- },- "description": "Body parameters for filtering and sorting toolkits"- }- }- }- },"responses": {"200": {- "description": "Toolkits retrieved successfully. Returns a paginated list of available toolkits with detailed metadata.",+ "description": "Event types retrieved","content": {"application/json": {"schema": {@@ -8782,204 +9193,44 @@"items": {"type": "object","properties": {- "slug": {+ "event_type": {"type": "string",- "description": "URL-friendly unique identifier for the toolkit",- "example": "github"+ "description": "Event type identifier"},- "name": {+ "description": {"type": "string",- "description": "Human-readable name of the toolkit",- "example": "GitHub"- },- "auth_schemes": {- "type": "array",- "items": {- "type": "string"- },- "description": "List of authentication methods supported by this toolkit",- "example": [- "oauth2",- "api_key"- ]+ "description": "Human-readable description of the event"},- "composio_managed_auth_schemes": {+ "supported_versions": {"type": "array","items": {- "type": "string"- },- "description": "List of authentication methods that Composio manages for this toolkit",- "example": [- "oauth2"- ]- },- "is_local_toolkit": {- "type": "boolean",- "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",- "deprecated": true,- "example": false- },- "no_auth": {- "type": "boolean",- "description": "When true, this toolkit can be used without authentication",- "example": false- },- "auth_guide_url": {- "type": "string",- "nullable": true,- "description": "URL to a guide page with authentication setup instructions for this toolkit",- "example": "https://composio.dev/auth/github"- },- "deprecated": {- "$ref": "#/components/schemas/DeprecatedToolkitInfo"- },- "meta": {- "type": "object",- "properties": {- "created_at": {- "type": "string",- "description": "Creation date and time of the toolkit",- "example": "2023-01-15T09:30:00.000Z"- },- "updated_at": {- "type": "string",- "description": "Last modification date and time of the toolkit",- "example": "2023-05-20T14:45:00.000Z"- },- "description": {- "type": "string",- "description": "Human-readable description explaining the toolkit's purpose and functionality",- "example": "Integrate with GitHub repositories, issues, pull requests, and more."- },- "logo": {- "type": "string",- "description": "Image URL for the toolkit's branding",- "example": "https://assets.composio.dev/logos/github.png"- },- "app_url": {- "type": "string",- "nullable": true,- "description": "Link to the toolkit's main application or service website",- "example": "https://github.com"- },- "categories": {- "type": "array",- "items": {- "type": "object",- "properties": {- "id": {- "type": "string",- "description": "Category identifier",- "example": "developer-tools"- },- "name": {- "type": "string",- "description": "Human-readable category name",- "example": "Developer Tools"- }- },- "required": [- "id",- "name"- ]- },- "description": "List of categories associated with this toolkit",- "example": [- {- "id": "developer-tools",- "name": "Developer Tools"- },- {- "id": "productivity",- "name": "Productivity"- }- ]- },- "triggers_count": {- "type": "number",- "description": "Count of available triggers in this toolkit",- "example": 5- },- "tools_count": {- "type": "number",- "description": "Count of available tools in this toolkit",- "example": 12- },- "version": {- "type": "string",- "description": "Version of the toolkit",- "example": "20250905_00"- }+ "type": "string",+ "enum": [+ "V1",+ "V2",+ "V3"+ ]},- "required": [- "created_at",- "updated_at",- "description",- "logo",- "categories",- "triggers_count",- "tools_count",- "version"- ],- "description": "Additional metadata about the toolkit"+ "description": "Webhook versions that support this event"}},"required": [- "slug",- "name",- "is_local_toolkit",- "deprecated",- "meta"- ],- "description": "Detailed information about a toolkit"+ "event_type",+ "description",+ "supported_versions"+ ]}- },- "next_cursor": {- "type": "string",- "nullable": true- },- "total_pages": {- "type": "number"- },- "current_page": {- "type": "number"- },- "total_items": {- "type": "number"}},"required": [- "items",- "total_pages",- "current_page",- "total_items"+ "items"]}}}},- "400": {- "description": "Bad request. The query parameters may be invalid or in an incorrect format.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found. The toolkits you are looking for do not exist.",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -8989,7 +9240,7 @@}},"500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -8998,17 +9249,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tools/execute/{tool_slug}": {- "post": {- "summary": "Execute tool",- "description": "Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.",+ "/api/v3.1/toolkits": {+ "get": {+ "summary": "List available toolkits",+ "description": "Retrieves a comprehensive list of toolkits of their latest versions that are available to the authenticated project. Toolkits represent integration points with external services and applications, each containing a collection of tools and triggers. This endpoint supports filtering by category and management type, as well as different sorting options.","tags": [- "Tools"+ "Toolkits"],- "operationId": "postToolsExecuteByToolSlug",+ "operationId": "getToolkits","security": [{"ApiKeyAuth": []@@ -9020,446 +9272,279 @@"parameters": [{"schema": {- "type": "string"+ "type": "string",+ "description": "Category ID or name to filter toolkits by",+ "example": "productivity"},- "required": true,- "description": "The tool slug to execute",- "name": "tool_slug",- "in": "path"+ "required": false,+ "description": "Filter toolkits by category",+ "name": "category",+ "in": "query"},{"schema": {"type": "string",- "description": "JSON object containing custom headers to pass to LLM providers (OpenAI, Bedrock, etc.)",- "example": "{\"x-custom-header\": \"value\", \"authorization\": \"Bearer token\"}"+ "enum": [+ "composio",+ "all",+ "project"+ ],+ "description": "Entity responsible for managing the toolkits"},"required": false,- "name": "x-llm-gateway-headers",- "in": "header"- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "connected_account_id": {- "type": "string",- "description": "Unique identifier for the connected account to use for authentication",- "example": "ca_1a2b3c4d5e6f"- },- "entity_id": {- "type": "string",- "description": "Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations)",- "example": "repo-123",- "deprecated": true- },- "user_id": {- "type": "string",- "description": "User id for multi-user connected accounts (e.g. multiple users, organizations)",- "example": "user-123"- },- "version": {- "type": "string",- "description": "Tool version to execute (defaults to \"00000000_00\" if not specified)",- "example": "latest"- },- "custom_auth_params": {- "type": "object",- "properties": {- "base_url": {- "type": "string",- "description": "The base URL (root address) what you should use while making http requests to the connected account. For example, for gmail, it would be 'https://gmail.googleapis.com'"- },- "parameters": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string",- "description": "The name of the parameter. For example, 'x-api-key', 'Content-Type', etc."- },- "in": {- "type": "string",- "enum": [- "query",- "header"- ],- "description": "The location of the parameter. Can be 'query' or 'header'."- },- "value": {- "anyOf": [- {- "type": "string"- },- {- "type": "number"- }- ],- "description": "The value of the parameter. For example, '1234567890', 'application/json', etc."- }- },- "required": [- "name",- "in",- "value"- ]- }- },- "body": {- "type": "object",- "additionalProperties": {},- "description": "The body to be sent to the endpoint for authentication. This is a JSON object. Note: This is very rarely needed and is only required by very few apps."- }- },- "description": "Custom authentication parameters for tools that support parameterized authentication",- "example": {- "base_url": "https://api.example.com",- "parameters": [- {- "name": "x-api-key",- "value": "secret-key",- "in": "header"- }- ]- }- },- "custom_connection_data": {- "description": "Custom connection data for tools that support custom connection data",- "example": {- "authScheme": "OAUTH2",- "toolkitSlug": "github",- "val": {- "access_token": "secret-token"- }- },- "type": "object",- "properties": {- "authScheme": {- "type": "string",- "enum": [- "OAUTH2",- "DCR_OAUTH",- "API_KEY",- "BASIC_WITH_JWT",- "BASIC",- "BEARER_TOKEN",- "OAUTH1",- "NO_AUTH",- "SERVICE_ACCOUNT",- "GOOGLE_SERVICE_ACCOUNT",- "S2S_OAUTH2"- ]- },- "toolkitSlug": {- "type": "string"- },- "val": {- "type": "object",- "properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"- },- "COMPANYDOMAIN": {- "type": "string"- },- "extension": {- "type": "string"- },- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"- },- "domain": {- "type": "string"- },- "version": {- "type": "string"- },- "dc": {- "type": "string"- },- "site_name": {- "type": "string"- },- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"+ "description": "Filter toolkits by who manages them",+ "name": "managed_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "enum": [+ "usage",+ "alphabetically"+ ],+ "description": "Determines how toolkits should be sorted in the response"+ },+ "required": false,+ "description": "Sort order for returned toolkits",+ "name": "sort_by",+ "in": "query"+ },+ {+ "schema": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "Include deprecated toolkits in the response",+ "example": true+ },+ "required": false,+ "description": "Include deprecated toolkits in the response",+ "name": "include_deprecated",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Search query to filter toolkits by name, slug, or description (minimum 3 characters)",+ "example": "gmail"+ },+ "required": false,+ "description": "Search query to filter toolkits by name, slug, or description",+ "name": "search",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "nullable": true+ },+ "required": false,+ "description": "Number of items per page, max allowed is 1000",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Toolkits retrieved successfully. Returns a paginated list of available toolkits with detailed metadata.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "URL-friendly unique identifier for the toolkit",+ "example": "github"},- "state_prefix": {+ "name": {"type": "string",- "maxLength": 40,- "description": "The oauth2 state prefix for the connection"+ "description": "Human-readable name of the toolkit",+ "example": "GitHub"},- "long_redirect_url": {- "type": "boolean",- "description": "Whether to return the redirect url without shortening"+ "auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods supported by this toolkit",+ "example": [+ "oauth2",+ "api_key"+ ]},- "access_token": {- "type": "string"+ "composio_managed_auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods that Composio manages for this toolkit",+ "example": [+ "oauth2"+ ]},- "id_token": {- "type": "string"+ "is_local_toolkit": {+ "type": "boolean",+ "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",+ "deprecated": true,+ "example": false},- "token_type": {- "type": "string"+ "no_auth": {+ "type": "boolean",+ "description": "When true, this toolkit can be used without authentication",+ "example": false},- "refresh_token": {+ "auth_guide_url": {"type": "string",- "nullable": true+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions for this toolkit",+ "example": "https://composio.dev/auth/github"},- "expires_in": {- "anyOf": [- {- "type": "number"+ "deprecated": {+ "$ref": "#/components/schemas/DeprecatedToolkitInfo"+ },+ "meta": {+ "type": "object",+ "properties": {+ "created_at": {+ "type": "string",+ "description": "Creation date and time of the toolkit",+ "example": "2023-01-15T09:30:00.000Z"},- {- "type": "string"+ "updated_at": {+ "type": "string",+ "description": "Last modification date and time of the toolkit",+ "example": "2023-05-20T14:45:00.000Z"},- {+ "description": {+ "type": "string",+ "description": "Human-readable description explaining the toolkit's purpose and functionality",+ "example": "Integrate with GitHub repositories, issues, pull requests, and more."+ },+ "logo": {+ "type": "string",+ "description": "Image URL for the toolkit's branding",+ "example": "https://assets.composio.dev/logos/github.png"+ },+ "app_url": {+ "type": "string","nullable": true,- "type": "object"- }- ]- },- "scope": {- "anyOf": [- {- "type": "string"+ "description": "Link to the toolkit's main application or service website",+ "example": "https://github.com"},- {+ "categories": {"type": "array","items": {- "type": "string"- }- },- {- "nullable": true,- "type": "object"- }- ]- },- "webhook_signature": {- "type": "string"- },- "authed_user": {- "type": "object",- "properties": {- "access_token": {- "type": "string"+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Category identifier",+ "example": "developer-tools"+ },+ "name": {+ "type": "string",+ "description": "Human-readable category name",+ "example": "Developer Tools"+ }+ },+ "required": [+ "id",+ "name"+ ]+ },+ "description": "List of categories associated with this toolkit",+ "example": [+ {+ "id": "developer-tools",+ "name": "Developer Tools"+ },+ {+ "id": "productivity",+ "name": "Productivity"+ }+ ]},- "scope": {- "type": "string"- }- },- "description": "for slack user scopes"- },- "client_id": {- "type": "string",- "description": "Dynamically registered client ID"- },- "client_secret": {- "type": "string",- "description": "Dynamically registered client secret"- },- "client_id_issued_at": {- "type": "number"- },- "client_secret_expires_at": {- "type": "number"- },- "generic_api_key": {- "type": "string"- },- "api_key": {- "type": "string"- },- "bearer_token": {- "type": "string"- },- "basic_encoded": {- "type": "string"- },- "username": {- "type": "string"- },- "password": {- "type": "string"- },- "token": {- "type": "string"- },- "oauth_token": {- "type": "string"- },- "oauth_token_secret": {- "type": "string"- },- "oauth_verifier": {- "type": "string"- },- "consumer_key": {- "type": "string"- },- "redirectUrl": {- "type": "string"- },- "callback_url": {- "type": "string"- },- "application_id": {- "type": "string"- },- "installation_id": {- "type": "string"- },- "private_key": {- "type": "string"- },- "credentials_json": {- "type": "string"- },- "expires_at": {- "type": "string"+ "triggers_count": {+ "type": "number",+ "description": "Count of available triggers in this toolkit",+ "example": 5+ },+ "tools_count": {+ "type": "number",+ "description": "Count of available tools in this toolkit",+ "example": 12+ },+ "version": {+ "type": "string",+ "description": "Version of the toolkit",+ "example": "20250905_00"+ }+ },+ "required": [+ "created_at",+ "updated_at",+ "description",+ "logo",+ "categories",+ "triggers_count",+ "tools_count",+ "version"+ ],+ "description": "Additional metadata about the toolkit"}},"required": [- "access_token"+ "slug",+ "name",+ "is_local_toolkit",+ "deprecated",+ "meta"],- "additionalProperties": {}- }- },- "required": [- "authScheme",- "toolkitSlug",- "val"- ],- "additionalProperties": true- },- "arguments": {- "type": "object",- "additionalProperties": {},- "description": "Key-value pairs of arguments required by the tool (mutually exclusive with text)",- "example": {- "repository": "octocat/Hello-World",- "workflow_id": "main.yml",- "ref": "main",- "inputs": {- "environment": "production"- }- }- },- "text": {- "type": "string",- "description": "Natural language description of the task to perform (mutually exclusive with arguments)",- "example": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment"- },- "allow_tracing": {- "type": "boolean",- "nullable": true,- "description": "Deprecated. Enable debug tracing for tool execution (useful for debugging)",- "deprecated": true,- "example": false- }- }- }- }- }- },- "responses": {- "200": {- "description": "Successfully executed action and received response",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "data": {- "type": "object",- "additionalProperties": {},- "description": "Tool execution output data that varies based on the specific tool",- "example": {- "run_id": 12345678,- "status": "queued",- "created_at": "2023-01-01T12:00:00Z",- "html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"+ "description": "Detailed information about a toolkit"}},- "error": {+ "next_cursor": {"type": "string",- "nullable": true,- "description": "Error message if the tool execution was not successful (null if successful)"+ "nullable": true},- "successful": {- "type": "boolean",- "description": "Indicates if the tool execution was successful",- "example": true+ "total_pages": {+ "type": "number"},- "session_info": {- "nullable": true,- "description": "Optional session information for tools that return session context",- "example": {- "session_id": "session-12345",- "expires_at": "2023-01-01T13:00:00Z"- },- "type": "object"+ "current_page": {+ "type": "number"},- "log_id": {- "type": "string",- "description": "Unique identifier for the execution log (useful for debugging and support)",- "example": "log_abc123def456"+ "total_items": {+ "type": "number"}},"required": [- "data",- "error",- "successful"+ "items",+ "total_pages",+ "current_page",+ "total_items"]}}}},"400": {- "description": "Bad request - Invalid request parameters, missing required arguments, or conflicting parameters",+ "description": "Bad request. The query parameters may be invalid or in an incorrect format.","content": {"application/json": {"schema": {@@ -9469,17 +9554,7 @@}},"401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource",+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.","content": {"application/json": {"schema": {@@ -9489,37 +9564,7 @@}},"404": {- "description": "Not found - Tool or connected account not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "408": {- "description": "Request timeout - Tool execution exceeded the maximum allowed time",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "410": {- "description": "Gone - Tool has been deprecated and is no longer available",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "413": {- "description": "Payload too large - Request or response payload exceeds size limits",+ "description": "Not found. The toolkits you are looking for do not exist.","content": {"application/json": {"schema": {@@ -9528,8 +9573,8 @@}}},- "422": {- "description": "Unprocessable entity - Invalid state of the connected account",+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.","content": {"application/json": {"schema": {@@ -9537,19 +9582,84 @@}}}+ }+ },+ "x-api-version": "3.1"+ }+ },+ "/api/v3.1/toolkits/categories": {+ "get": {+ "summary": "List toolkit categories",+ "description": "Retrieves a comprehensive list of all available toolkit categories from their latest versions. These categories can be used to filter toolkits by type or purpose when using the toolkit listing endpoint. Categories help organize toolkits into logical groups based on their functionality or industry focus.",+ "tags": [+ "Toolkits"+ ],+ "operationId": "getToolkitsCategories",+ "security": [+ {+ "ApiKeyAuth": []},- "429": {- "description": "Rate limit exceeded - Too many requests to the tool or underlying API",+ {+ "UserApiKeyAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved a paginated list of all available toolkit categories with their identifiers and display names.","content": {"application/json": {"schema": {- "$ref": "#/components/schemas/Error"+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Display name of the toolkit category",+ "example": "Developer Tools"+ },+ "id": {+ "type": "string",+ "description": "URL-friendly unique identifier for the category, used for filtering toolkits",+ "example": "developer-tools"+ }+ },+ "required": [+ "name",+ "id"+ ],+ "description": "Information about a single toolkit category"+ }+ },+ "next_cursor": {+ "type": "string",+ "nullable": true+ },+ "total_pages": {+ "type": "number"+ },+ "current_page": {+ "type": "number"+ },+ "total_items": {+ "type": "number"+ }+ },+ "required": [+ "items",+ "total_pages",+ "current_page",+ "total_items"+ ]}}}},- "500": {- "description": "Internal server error - Something went wrong on the server",+ "400": {+ "description": "Bad request. The request may be invalid or in an incorrect format.","content": {"application/json": {"schema": {@@ -9558,8 +9668,8 @@}}},- "501": {- "description": "Not implemented",+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.","content": {"application/json": {"schema": {@@ -9568,8 +9678,8 @@}}},- "502": {- "description": "Bad gateway - Error communicating with the tool provider API",+ "404": {+ "description": "Not found. The requested resource was not found.","content": {"application/json": {"schema": {@@ -9578,8 +9688,8 @@}}},- "503": {- "description": "Upstream service unavailable - Tool provider API is currently down or unavailable",+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.","content": {"application/json": {"schema": {@@ -9588,17 +9698,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tools/execute/{tool_slug}/input": {- "post": {- "summary": "Generate tool inputs from natural language",- "description": "Uses AI to translate a natural language description into structured arguments for a specific tool. This endpoint is useful when you want to let users describe what they want to do in plain language instead of providing structured parameters.",+ "/api/v3.1/toolkits/{slug}": {+ "get": {+ "summary": "Get toolkit by slug",+ "description": "Retrieves comprehensive information about a specific toolkit using its unique slug identifier. This endpoint provides detailed metadata, authentication configuration options, and feature counts for the requested toolkit.","tags": [- "Tools"+ "Toolkits"],- "operationId": "postToolsExecuteByToolSlugInput",+ "operationId": "getToolkitsBySlug","security": [{"ApiKeyAuth": []@@ -9610,101 +9721,463 @@"parameters": [{"schema": {- "type": "string"+ "type": "string",+ "description": "The unique slug identifier of the toolkit to retrieve",+ "example": "github"},"required": true,- "description": "The tool slug to generate inputs for",- "name": "tool_slug",+ "description": "Toolkit slug identifier",+ "name": "slug","in": "path"+ },+ {+ "schema": {+ "type": "string",+ "default": "latest",+ "description": "Version of the toolkit",+ "example": "20250905_00"+ },+ "required": false,+ "description": "Version of the toolkit",+ "name": "version",+ "in": "query"}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "text": {- "type": "string",- "description": "Natural language description of what you want to accomplish with this tool",- "example": "I need to trigger the main workflow in the octocat/Hello-World repository to deploy to production"- },- "custom_description": {- "type": "string",- "description": "Custom description of the tool to help guide the LLM in generating more accurate inputs",- "example": "This tool triggers GitHub Actions workflows in a repository. It requires the repository name, workflow ID, and optional input parameters."- },- "system_prompt": {- "type": "string",- "description": "System prompt to control and guide the behavior of the LLM when generating inputs",- "example": "You are an expert assistant that generates precise GitHub Actions workflow parameters. Extract exact repository names, workflow IDs, and input values from user descriptions."- },- "version": {- "type": "string",- "description": "Tool version to use when generating inputs (defaults to \"latest\" if not specified)",- "example": "latest"- }- },- "required": [- "text"- ]- }- }- }- },"responses": {"200": {- "description": "Successfully generated structured inputs for the action based on natural language description",+ "description": "Successfully retrieved detailed information about the requested toolkit, including authentication options, metadata, and feature counts.","content": {"application/json": {"schema": {"type": "object","properties": {- "arguments": {+ "slug": {+ "type": "string",+ "description": "URL-friendly unique identifier for the toolkit",+ "example": "github"+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the toolkit",+ "example": "GitHub"+ },+ "enabled": {+ "type": "boolean",+ "description": "Indicates if this toolkit is currently enabled and available for use",+ "example": true+ },+ "composio_managed_auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods that Composio manages for this toolkit",+ "example": [+ "oauth2"+ ]+ },+ "is_local_toolkit": {+ "type": "boolean",+ "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",+ "deprecated": true,+ "example": false+ },+ "auth_config_details": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "mode": {+ "type": "string",+ "description": "The type of authentication mode (e.g., oauth2, basic_auth, api_key)",+ "example": "oauth2"+ },+ "fields": {+ "type": "object",+ "properties": {+ "auth_config_creation": {+ "type": "object",+ "properties": {+ "required": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "default": {+ "type": "string",+ "nullable": true+ },+ "type": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "required": {+ "type": "boolean"+ },+ "legacy_template_name": {+ "type": "string"+ }+ },+ "required": [+ "name",+ "displayName",+ "type",+ "description",+ "required"+ ]+ }+ },+ "optional": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "default": {+ "type": "string",+ "nullable": true+ },+ "type": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "required": {+ "type": "boolean"+ },+ "legacy_template_name": {+ "type": "string"+ }+ },+ "required": [+ "name",+ "displayName",+ "type",+ "description",+ "required"+ ]+ }+ }+ },+ "required": [+ "required",+ "optional"+ ],+ "description": "Form fields needed when creating an authentication configuration"+ },+ "connected_account_initiation": {+ "type": "object",+ "properties": {+ "required": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "default": {+ "type": "string",+ "nullable": true+ },+ "type": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "required": {+ "type": "boolean"+ },+ "legacy_template_name": {+ "type": "string"+ }+ },+ "required": [+ "name",+ "displayName",+ "type",+ "description",+ "required"+ ]+ }+ },+ "optional": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayName": {+ "type": "string"+ },+ "default": {+ "type": "string",+ "nullable": true+ },+ "type": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "required": {+ "type": "boolean"+ },+ "legacy_template_name": {+ "type": "string"+ }+ },+ "required": [+ "name",+ "displayName",+ "type",+ "description",+ "required"+ ]+ }+ }+ },+ "required": [+ "required",+ "optional"+ ],+ "description": "Form fields needed when connecting a user account with this authentication method"+ }+ },+ "required": [+ "auth_config_creation",+ "connected_account_initiation"+ ],+ "description": "Field groups required for different authentication stages"+ },+ "proxy": {+ "type": "object",+ "properties": {+ "base_url": {+ "type": "string",+ "description": "URL to which authentication requests will be proxied",+ "example": "https://auth.example.com/proxy"+ }+ },+ "required": [+ "base_url"+ ],+ "description": "Configuration for proxying authentication requests to external services"+ },+ "name": {+ "type": "string",+ "description": "Display name for this authentication method",+ "example": "OAuth 2.0"+ },+ "auth_hint_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a page where users can obtain or configure credentials for this authentication method",+ "example": "https://github.com/settings/tokens"+ },+ "deprecated_auth_provider_details": {+ "type": "object",+ "properties": {+ "authorization_url": {+ "type": "string"+ },+ "token_url": {+ "type": "string"+ }+ },+ "description": "Authentication URL fields for OAuth 2.0 and OAuth 1.0. We don't recommend using this field for authentication and might break post Aug 31 2025.",+ "deprecated": true+ }+ },+ "required": [+ "mode",+ "fields",+ "name"+ ],+ "description": "Detailed configuration for an authentication method"+ },+ "description": "Complete authentication configuration details for each supported auth method"+ },+ "auth_guide_url": {+ "type": "string",+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions for this toolkit",+ "example": "https://composio.dev/auth/github"+ },+ "base_url": {+ "type": "string",+ "description": "If evaluation of base URL needs some connection info (like shopify), please create the connection and get the base URL from there",+ "example": "https://api.github.com"+ },+ "meta": {"type": "object",- "additionalProperties": {},- "description": "Key-value pairs of arguments required by the tool to accomplish the described task",- "example": {- "repository": "octocat/Hello-World",- "workflow_id": "main.yml",- "ref": "main",- "inputs": {- "environment": "production"+ "properties": {+ "created_at": {+ "type": "string",+ "description": "Creation date and time of the toolkit",+ "example": "2023-01-15T09:30:00.000Z"+ },+ "updated_at": {+ "type": "string",+ "description": "Last modification date and time of the toolkit",+ "example": "2023-05-20T14:45:00.000Z"+ },+ "description": {+ "type": "string",+ "description": "Human-readable description explaining the toolkit's purpose and functionality",+ "example": "Integrate with GitHub repositories, issues, pull requests, and more."+ },+ "logo": {+ "type": "string",+ "description": "Image URL for the toolkit's branding",+ "example": "https://assets.composio.dev/logos/github.png"+ },+ "app_url": {+ "type": "string",+ "nullable": true,+ "description": "Link to the toolkit's main application or service website",+ "example": "https://github.com"+ },+ "categories": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Human-readable category name",+ "example": "Developer Tools"+ },+ "slug": {+ "type": "string",+ "description": "URL-friendly identifier for the category",+ "example": "developer-tools"+ }+ },+ "required": [+ "name",+ "slug"+ ]+ },+ "description": "List of categories associated with this toolkit",+ "example": [+ {+ "name": "Developer Tools",+ "slug": "developer-tools"+ },+ {+ "name": "Productivity",+ "slug": "productivity"+ }+ ]+ },+ "triggers_count": {+ "type": "number",+ "description": "Count of available triggers in this toolkit",+ "example": 5+ },+ "tools_count": {+ "type": "number",+ "description": "Count of available tools in this toolkit",+ "example": 12+ },+ "version": {+ "type": "string",+ "description": "Version of the toolkit",+ "example": "20250905_00"+ },+ "available_versions": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Available versions of the toolkit",+ "example": [+ "20250905_00",+ "20250906_00"+ ]}- }+ },+ "required": [+ "created_at",+ "updated_at",+ "description",+ "logo",+ "categories",+ "triggers_count",+ "tools_count",+ "version",+ "available_versions"+ ],+ "description": "Comprehensive metadata for the toolkit including dates, descriptions, and statistics"},- "error": {+ "get_current_user_endpoint": {"type": "string",- "description": "Error message if the arguments could not be generated (null if successful)",- "example": "Unable to determine the repository name from the provided description"- }- }- }- }- }- },- "400": {- "description": "Bad request - Invalid input parameters or insufficient description to generate tool arguments",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"+ "description": "Endpoint to get the current user"+ },+ "get_current_user_endpoint_method": {+ "type": "string",+ "description": "HTTP method to use when calling the get current user endpoint (e.g., GET, POST)",+ "example": "GET"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "toolkitId": {+ "type": "string"+ },+ "getCurrentUserEndpoint": {+ "type": "string"+ },+ "rawProxyInfoByAuthSchemes": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": {}+ }+ }+ },+ "required": [+ "toolkitId",+ "rawProxyInfoByAuthSchemes"+ ]+ }+ },+ "required": [+ "slug",+ "name",+ "enabled",+ "is_local_toolkit",+ "meta",+ "deprecated"+ ],+ "description": "Detailed information about a single toolkit"}}}},- "404": {- "description": "Not found - The specified tool does not exist",+ "400": {+ "description": "Bad request. The toolkit slug may be invalid or in an incorrect format.","content": {"application/json": {"schema": {@@ -9713,8 +10186,8 @@}}},- "422": {- "description": "Unprocessable entity - Invalid state of the connected account",+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.","content": {"application/json": {"schema": {@@ -9723,8 +10196,8 @@}}},- "429": {- "description": "Too many requests - Rate limit exceeded for natural language processing",+ "404": {+ "description": "Not found. The requested toolkit does not exist or is not accessible to the authenticated project.","content": {"application/json": {"schema": {@@ -9734,7 +10207,7 @@}},"500": {- "description": "Internal server error - AI processing failed or other server error occurred",+ "description": "Internal server error. An unexpect ed error occurred while processing the request.","content": {"application/json": {"schema": {@@ -9743,17 +10216,18 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tools/execute/proxy": {+ "/api/v3.1/toolkits/multi": {"post": {- "summary": "Execute proxy request",- "description": "Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.",+ "summary": "Fetch multiple toolkits",+ "description": "Retrieves a comprehensive list of toolkits of their latest versions that are available to the authenticated project. Toolkits represent integration points with external services and applications, each containing a collection of tools and triggers. This endpoint supports filtering by category and management type, as well as different sorting options. You can optionally specify a list of toolkit slugs to fetch specific toolkits.","tags": [- "Tools"+ "Toolkits"],- "operationId": "postToolsExecuteProxy",+ "operationId": "postToolkitsMulti","security": [{"ApiKeyAuth": []@@ -9768,446 +10242,244 @@"schema": {"type": "object","properties": {- "connected_account_id": {- "type": "string",- "format": "connectedAccountId",- "description": "The ID of the connected account to use for authentication (if not provided, will use the default account for the project)",- "example": "ca_1a2b3c4d5e6f"+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Array of toolkit slug identifiers to retrieve",+ "example": [+ "github",+ "slack",+ "gmail"+ ]},- "endpoint": {+ "category": {"type": "string",- "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",- "example": "/api/v1/resources"+ "description": "Category ID or name to filter toolkits by",+ "example": "productivity"},- "method": {+ "managed_by": {"type": "string","enum": [- "GET",- "POST",- "PUT",- "DELETE",- "PATCH",- "HEAD"- ],- "description": "The HTTP method to use for the request",- "example": "GET"- },- "body": {- "nullable": true,- "description": "The request body (for POST, PUT, and PATCH requests)",- "example": {- "name": "New Resource",- "description": "This is a new resource"- },- "type": "object"- },- "binary_body": {- "anyOf": [- {- "type": "object",- "properties": {- "url": {- "type": "string",- "format": "uri",- "description": "URL to fetch binary content from"- },- "content_type": {- "type": "string",- "description": "Content-Type header to use for the request"- }- },- "required": [- "url"- ]- },- {- "type": "object",- "properties": {- "base64": {- "type": "string",- "minLength": 1,- "description": "Base64-encoded binary data"- },- "content_type": {- "type": "string",- "description": "Content-Type header to use for the request"- }- },- "required": [- "base64"- ]- }+ "composio",+ "all",+ "project"],- "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."- },- "parameters": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string",- "description": "Parameter name",- "example": "x-api-key"- },- "value": {- "type": "string",- "description": "Parameter value",- "example": "abc123def456"- },- "type": {- "type": "string",- "enum": [- "header",- "query"- ],- "description": "Parameter type (header or query)",- "example": "header"- }- },- "required": [- "name",- "value",- "type"- ]- },- "description": "Additional HTTP headers or query parameters to include in the request",- "example": [- {- "name": "x-api-key",- "value": "abc123def456",- "type": "header"- },- {- "name": "filter",- "value": "active",- "type": "query"- }- ]+ "description": "Entity responsible for managing the toolkits"},- "custom_connection_data": {- "deprecated": true,- "type": "object",- "properties": {- "authScheme": {- "type": "string",- "enum": [- "OAUTH2",- "DCR_OAUTH",- "API_KEY",- "BASIC_WITH_JWT",- "BASIC",- "BEARER_TOKEN",- "OAUTH1",- "NO_AUTH",- "SERVICE_ACCOUNT",- "GOOGLE_SERVICE_ACCOUNT",- "S2S_OAUTH2"- ]- },- "toolkitSlug": {- "type": "string"- },- "val": {- "type": "object",- "properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"- },- "COMPANYDOMAIN": {- "type": "string"- },- "extension": {- "type": "string"- },- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"- },- "domain": {- "type": "string"- },- "version": {- "type": "string"- },- "dc": {- "type": "string"- },- "site_name": {- "type": "string"- },- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"+ "sort_by": {+ "type": "string",+ "enum": [+ "usage",+ "alphabetically"+ ],+ "description": "Determines how toolkits should be sorted in the response"+ },+ "limit": {+ "type": "number",+ "nullable": true+ },+ "cursor": {+ "type": "string"+ }+ },+ "description": "Body parameters for filtering and sorting toolkits"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Toolkits retrieved successfully. Returns a paginated list of available toolkits with detailed metadata.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "URL-friendly unique identifier for the toolkit",+ "example": "github"},- "state_prefix": {+ "name": {"type": "string",- "maxLength": 40,- "description": "The oauth2 state prefix for the connection"+ "description": "Human-readable name of the toolkit",+ "example": "GitHub"},- "long_redirect_url": {- "type": "boolean",- "description": "Whether to return the redirect url without shortening"+ "auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods supported by this toolkit",+ "example": [+ "oauth2",+ "api_key"+ ]},- "access_token": {- "type": "string"+ "composio_managed_auth_schemes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of authentication methods that Composio manages for this toolkit",+ "example": [+ "oauth2"+ ]},- "id_token": {- "type": "string"+ "is_local_toolkit": {+ "type": "boolean",+ "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.",+ "deprecated": true,+ "example": false},- "token_type": {- "type": "string"+ "no_auth": {+ "type": "boolean",+ "description": "When true, this toolkit can be used without authentication",+ "example": false},- "refresh_token": {+ "auth_guide_url": {"type": "string",- "nullable": true+ "nullable": true,+ "description": "URL to a guide page with authentication setup instructions for this toolkit",+ "example": "https://composio.dev/auth/github"},- "expires_in": {- "anyOf": [- {- "type": "number"+ "deprecated": {+ "$ref": "#/components/schemas/DeprecatedToolkitInfo"+ },+ "meta": {+ "type": "object",+ "properties": {+ "created_at": {+ "type": "string",+ "description": "Creation date and time of the toolkit",+ "example": "2023-01-15T09:30:00.000Z"},- {- "type": "string"+ "updated_at": {+ "type": "string",+ "description": "Last modification date and time of the toolkit",+ "example": "2023-05-20T14:45:00.000Z"},- {+ "description": {+ "type": "string",+ "description": "Human-readable description explaining the toolkit's purpose and functionality",+ "example": "Integrate with GitHub repositories, issues, pull requests, and more."+ },+ "logo": {+ "type": "string",+ "description": "Image URL for the toolkit's branding",+ "example": "https://assets.composio.dev/logos/github.png"+ },+ "app_url": {+ "type": "string","nullable": true,- "type": "object"- }- ]- },- "scope": {- "anyOf": [- {- "type": "string"+ "description": "Link to the toolkit's main application or service website",+ "example": "https://github.com"},- {+ "categories": {"type": "array","items": {- "type": "string"- }+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Category identifier",+ "example": "developer-tools"+ },+ "name": {+ "type": "string",+ "description": "Human-readable category name",+ "example": "Developer Tools"+ }+ },+ "required": [+ "id",+ "name"+ ]+ },+ "description": "List of categories associated with this toolkit",+ "example": [+ {+ "id": "developer-tools",+ "name": "Developer Tools"+ },+ {+ "id": "productivity",+ "name": "Productivity"+ }+ ]},- {- "nullable": true,- "type": "object"- }- ]- },- "webhook_signature": {- "type": "string"- },- "authed_user": {- "type": "object",- "properties": {- "access_token": {- "type": "string"+ "triggers_count": {+ "type": "number",+ "description": "Count of available triggers in this toolkit",+ "example": 5},- "scope": {- "type": "string"- }- },- "description": "for slack user scopes"- },- "client_id": {- "type": "string",- "description": "Dynamically registered client ID"- },- "client_secret": {- "type": "string",- "description": "Dynamically registered client secret"- },- "client_id_issued_at": {- "type": "number"- },- "client_secret_expires_at": {- "type": "number"- },- "generic_api_key": {- "type": "string"- },- "api_key": {- "type": "string"- },- "bearer_token": {- "type": "string"- },- "basic_encoded": {- "type": "string"- },- "username": {- "type": "string"- },- "password": {- "type": "string"- },- "token": {- "type": "string"- },- "oauth_token": {- "type": "string"- },- "oauth_token_secret": {- "type": "string"- },- "oauth_verifier": {- "type": "string"- },- "consumer_key": {- "type": "string"- },- "redirectUrl": {- "type": "string"- },- "callback_url": {- "type": "string"- },- "application_id": {- "type": "string"- },- "installation_id": {- "type": "string"- },- "private_key": {- "type": "string"- },- "credentials_json": {- "type": "string"- },- "expires_at": {- "type": "string"+ "tools_count": {+ "type": "number",+ "description": "Count of available tools in this toolkit",+ "example": 12+ },+ "version": {+ "type": "string",+ "description": "Version of the toolkit",+ "example": "20250905_00"+ }+ },+ "required": [+ "created_at",+ "updated_at",+ "description",+ "logo",+ "categories",+ "triggers_count",+ "tools_count",+ "version"+ ],+ "description": "Additional metadata about the toolkit"}},"required": [- "access_token"+ "slug",+ "name",+ "is_local_toolkit",+ "deprecated",+ "meta"],- "additionalProperties": {}+ "description": "Detailed information about a toolkit"}},- "required": [- "authScheme",- "toolkitSlug",- "val"- ],- "additionalProperties": true- }- },- "required": [- "endpoint",- "method"- ]- }- }- }- },- "responses": {- "200": {- "description": "Successfully executed proxy request and received response",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "data": {- "nullable": true,- "description": "The response data returned from the proxied API",- "example": {- "id": "123",- "name": "Resource Name",- "created_at": "2023-01-01T00:00:00Z"- },- "type": "object"+ "next_cursor": {+ "type": "string",+ "nullable": true},- "binary_data": {- "type": "object",- "properties": {- "url": {- "type": "string",- "description": "URL to download binary content"- },- "content_type": {- "type": "string",- "description": "Content-Type of the binary data"- },- "size": {- "type": "number",- "description": "File size in bytes"- },- "expires_at": {- "type": "string",- "description": "ISO 8601 timestamp when the URL expires"- }- },- "required": [- "url",- "content_type",- "size"- ],- "description": "Binary body response data. Present when the response is a binary file."+ "total_pages": {+ "type": "number"},- "status": {- "type": "number",- "description": "The HTTP status code returned from the proxied API",- "example": 200+ "current_page": {+ "type": "number"},- "headers": {- "type": "object",- "additionalProperties": {- "type": "string"- },- "description": "The HTTP headers returned from the proxied API",- "example": {- "content-type": "application/json",- "cache-control": "no-cache",- "host": "api.example.com"- }+ "total_items": {+ "type": "number"}},"required": [- "status"+ "items",+ "total_pages",+ "current_page",+ "total_items"]}}}},"400": {- "description": "Bad request - Invalid request parameters or body format",+ "description": "Bad request. The query parameters may be invalid or in an incorrect format.","content": {"application/json": {"schema": {@@ -10217,17 +10489,7 @@}},"401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden - Connected account does not have permission to access the requested resource",+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.","content": {"application/json": {"schema": {@@ -10237,27 +10499,7 @@}},"404": {- "description": "Not found - Resource not found or connected account not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "422": {- "description": "Unprocessable entity - Invalid state of the connected account",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "429": {- "description": "Too many requests - Rate limit exceeded on the connected account or proxy service",+ "description": "Not found. The toolkits you are looking for do not exist.","content": {"application/json": {"schema": {@@ -10267,37 +10509,7 @@}},"500": {- "description": "Internal server error - Something went wrong on the server",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "501": {- "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "502": {- "description": "Bad gateway - Error communicating with the upstream API",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "504": {- "description": "Gateway timeout - Upstream API timed out",+ "description": "Internal server error. An unexpected error occurred while processing the request.","content": {"application/json": {"schema": {@@ -10306,10 +10518,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/trigger_instances/{slug}/upsert": {+ "/api/v3.1/trigger_instances/{slug}/upsert": {"post": {"summary": "Create or update a trigger","description": "Creates a new trigger instance or updates an existing one with the same configuration. Triggers listen for events from external services (webhooks or polling) and can invoke your workflows. If a matching trigger already exists and is disabled, it will be re-enabled. Requires a connected account ID to associate the trigger with a specific user connection.",@@ -10561,10 +10774,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/trigger_instances/active": {+ "/api/v3.1/trigger_instances/active": {"get": {"summary": "List active triggers","description": "Retrieves all active trigger instances for your project. Triggers listen for events from connected accounts (e.g., new emails, Slack messages, GitHub commits) and can invoke webhooks or workflows. Use filters to find triggers for specific users, connected accounts, or trigger types.",@@ -10968,10 +11182,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/trigger_instances/manage/{triggerId}": {+ "/api/v3.1/trigger_instances/manage/{triggerId}": {"delete": {"summary": "Delete a trigger","description": "Permanently deletes a trigger instance. This stops the trigger from listening for events and removes it from your project. Use the PATCH endpoint with status \"disable\" if you want to temporarily pause a trigger instead.",@@ -11081,7 +11296,8 @@}}}- }+ },+ "x-api-version": "3.1"},"patch": {"summary": "Enable or disable a trigger",@@ -11225,10 +11441,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/triggers_types/list/enum": {+ "/api/v3.1/triggers_types/list/enum": {"get": {"summary": "List trigger type enums","description": "Retrieves a list of all available trigger type enum values that can be used across the API from latest versions of the toolkit only",@@ -11299,10 +11516,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/triggers_types/{slug}": {+ "/api/v3.1/triggers_types/{slug}": {"get": {"summary": "Get trigger type by slug","description": "Retrieve detailed information about a specific trigger type using its slug identifier",@@ -11530,10 +11748,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/triggers_types": {+ "/api/v3.1/triggers_types": {"get": {"summary": "List trigger types","description": "Retrieve a list of available trigger types with optional filtering by toolkit. Results are paginated and can be filtered by toolkit.",@@ -11814,10 +12033,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/mcp/servers": {+ "/api/v3.1/mcp/servers": {"get": {"summary": "List MCP servers with optional filters and pagination","description": "Retrieves a paginated list of MCP servers associated with the authenticated project. Results can be filtered by name, toolkit, or authentication configuration ID. MCP servers are used to provide Model Control Protocol integration points for connecting AI assistants to your applications and services.",@@ -12162,7 +12382,8 @@}}}- }+ },+ "x-api-version": "3.1"},"post": {"summary": "Create a new MCP server",@@ -12464,10 +12685,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/mcp/servers/custom": {+ "/api/v3.1/mcp/servers/custom": {"post": {"summary": "Create a new custom MCP server with multiple apps","description": "Creates a new Model Control Protocol (MCP) server instance that can integrate with multiple applications or toolkits simultaneously. This endpoint allows you to create a server that can access tools from different applications, making it suitable for complex workflows that span multiple services.",@@ -12706,10 +12928,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/mcp/servers/generate": {+ "/api/v3.1/mcp/servers/generate": {"post": {"summary": "Generate MCP URL with custom parameters","description": "Generates a Model Control Protocol (MCP) URL for an existing server with custom query parameters. The URL includes user-specific parameters and configuration flags that control the behavior of the MCP connection.",@@ -12898,10 +13121,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/mcp/{id}": {+ "/api/v3.1/mcp/{id}": {"get": {"summary": "Get MCP server details by ID","description": "Retrieves detailed configuration information for a specific Model Control Protocol (MCP) server. The returned data includes connection details, associated applications, enabled tools, and authentication configuration.",@@ -13126,7 +13350,8 @@}}}- }+ },+ "x-api-version": "3.1"},"patch": {"summary": "Update MCP server configuration",@@ -13467,7 +13692,8 @@}}}- }+ },+ "x-api-version": "3.1"},"delete": {"summary": "Delete an MCP server",@@ -13576,10 +13802,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/mcp/app/{appKey}": {+ "/api/v3.1/mcp/app/{appKey}": {"get": {"summary": "List MCP servers for a specific app","description": "Retrieves a paginated list of Model Control Protocol (MCP) servers that are configured for a specific application or toolkit. This endpoint allows you to find all MCP server instances that have access to a particular application, such as GitHub, Slack, or Jira.",@@ -13945,10 +14172,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/mcp/servers/{serverId}/instances": {+ "/api/v3.1/mcp/servers/{serverId}/instances": {"get": {"summary": "List all instances for an MCP server","description": "Retrieves a paginated list of user instances (user IDs) associated with a specific Model Control Protocol (MCP) server. This endpoint supports pagination to handle servers with many instances.",@@ -14178,7 +14406,8 @@}}}- }+ },+ "x-api-version": "3.1"},"post": {"summary": "Create a new MCP server instance",@@ -14342,10 +14571,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/mcp/servers/{serverId}/instances/{instanceId}": {+ "/api/v3.1/mcp/servers/{serverId}/instances/{instanceId}": {"delete": {"summary": "Delete an MCP server instance and associated connected accounts","description": "Removes a user instance from the MCP server and deletes all connected accounts for that user that are associated with the auth configurations of this specific MCP server. Connected accounts for other auth configurations are not affected.",@@ -14448,10 +14678,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/files/list": {+ "/api/v3.1/files/list": {"get": {"summary": "List files with optional app and action filters","description": "Retrieves a list of files associated with the authenticated project. Results can be filtered by toolkit and tool slugs.",@@ -14615,10 +14846,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/files/upload/request": {+ "/api/v3.1/files/upload/request": {"post": {"summary": "Create presigned URL for request file upload to S3","description": "Generates a presigned URL for uploading a file to S3. This endpoint handles deduplication by checking if a file with the same MD5 hash already exists.",@@ -14861,10 +15093,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/migration/get-nanoid": {+ "/api/v3.1/migration/get-nanoid": {"get": {"summary": "Get NanoId from UUID","description": "Convert a legacy UUID to its corresponding NanoId for migration purposes. This endpoint facilitates the transition from UUID-based identifiers to the more compact NanoId format used in the v3 API.",@@ -14991,10 +15224,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session": {+ "/api/v3.1/tool_router/session": {"post": {"summary": "Create a new tool router session","description": "Creates a new session for the tool router feature. This endpoint initializes a new session with specified toolkits and their authentication configurations. The session provides an isolated environment for testing and managing tool routing logic with scoped MCP server access.",@@ -16194,10 +16428,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/execute": {+ "/api/v3.1/tool_router/session/{session_id}/execute": {"post": {"summary": "Execute a tool within a tool router session","description": "Executes a specific tool within a tool router session. The toolkit is automatically inferred from the tool slug. The tool must belong to an allowed toolkit and must not be disabled in the session configuration. This endpoint validates permissions, resolves connected accounts, and executes the tool with the session context.",@@ -16366,10 +16601,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/execute_meta": {+ "/api/v3.1/tool_router/session/{session_id}/execute_meta": {"post": {"summary": "Execute a meta tool within a tool router session","description": "Executes a Composio meta tool (COMPOSIO_*) within a tool router session.",@@ -16538,10 +16774,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}": {+ "/api/v3.1/tool_router/session/{session_id}": {"get": {"summary": "Get a tool router session by ID","description": "Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.",@@ -17017,10 +17254,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/link": {+ "/api/v3.1/tool_router/session/{session_id}/link": {"post": {"summary": "Create a link session for a toolkit in a tool router session","description": "Initiates an authentication link session for a specific toolkit within a tool router session. Returns a link token and redirect URL that users can use to complete the OAuth flow.",@@ -17165,10 +17403,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/proxy_execute": {+ "/api/v3.1/tool_router/session/{session_id}/proxy_execute": {"post": {"summary": "Execute proxy request within a tool router session","description": "Execute any native API call on a toolkit with authentication automatically injected from Composio. This endpoint proxies HTTP requests to third-party APIs using connected account credentials resolved from the session context. Provide the toolkit slug, API endpoint, and HTTP method — Composio handles authentication injection, abstracting away credential management. Supports all HTTP methods, custom headers/query parameters, and binary request/response bodies.",@@ -17703,10 +17942,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/toolkits": {+ "/api/v3.1/tool_router/session/{session_id}/toolkits": {"get": {"summary": "Get toolkits for a tool router session","description": "Retrieves a cursor-paginated list of toolkits available in the tool router session. Includes toolkit metadata, composio-managed auth schemes, and connected accounts if available. Optionally filter by specific toolkit slugs.",@@ -17855,10 +18095,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/tools": {+ "/api/v3.1/tool_router/session/{session_id}/tools": {"get": {"summary": "List meta tools with schemas for a tool router session","description": "Returns the meta tools available in a tool router session with their complete schemas. This includes request and response schemas specific to the session context.",@@ -17980,10 +18221,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/search": {+ "/api/v3.1/tool_router/session/{session_id}/search": {"post": {"summary": "Search for tools using a query","description": "Search for tools matching a given use case query within a tool router session. Returns matching tool slugs, full tool schemas, toolkit connection statuses, and workflow guidance in a predictable format.",@@ -18478,10 +18720,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items": {+ "/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/items": {"get": {"summary": "List files in a session mount","description": "Lists files in a workbench session storage mount with cursor-based pagination. Use the download_url endpoint with the returned mount_relative_path to get a presigned download URL.",@@ -18649,10 +18892,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url": {+ "/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/download_url": {"post": {"summary": "Create a presigned download URL for a mount file","description": "Generates a presigned download URL for a file in a workbench session mount. Accepts a relative path within the mount.",@@ -18789,10 +19033,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url": {+ "/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/upload_url": {"post": {"summary": "Create a presigned upload URL for a mount file","description": "Generates a presigned upload URL for uploading a file to a workbench session mount. The caller should PUT the file content directly to the returned URL.",@@ -18935,10 +19180,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete": {+ "/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/delete": {"post": {"summary": "Delete a file from a session mount","description": "Deletes a file from a workbench session storage mount. S3 delete is idempotent — deleting a non-existent file succeeds silently.",@@ -19065,10 +19311,11 @@}}}- }+ },+ "x-api-version": "3.1"}},- "/api/v3/toolkits/changelog": {+ "/api/v3.1/toolkits/changelog": {"get": {"summary": "Get toolkits changelog","description": "Retrieves the last 10 versions changelog for all toolkits. This endpoint provides version history and changelog information for each toolkit.",@@ -19188,7 +19435,8 @@}}}- }+ },+ "x-api-version": "3.1"}}}diff --git a/docs/scripts/fetch-openapi.mjs b/docs/scripts/fetch-openapi.mjsindex 7d9c436b9..d24921bf7 100644--- a/docs/scripts/fetch-openapi.mjs+++ b/docs/scripts/fetch-openapi.mjs@@ -1,6 +1,8 @@/**- * Fetches and filters the OpenAPI spec for fumadocs- * Mirrors the filtering done in fern/apis/openapi-overrides.yml+ * Fetches and filters the OpenAPI specs for fumadocs.+ * Outputs two separate spec files:+ * - public/openapi.json (v3.1 — latest, clean operationIds)+ * - public/openapi-v3.json (v3.0)** Run: bun run scripts/fetch-openapi.mjs*/@@ -9,7 +11,8 @@ import { writeFileSync } from 'node:fs';import { fileURLToPath } from 'node:url';import { dirname, join } from 'node:path';-const OPENAPI_URL = process.env.OPENAPI_SPEC_URL || 'https://backend.composio.dev/api/v3/openapi.json';+const OPENAPI_V3_URL = process.env.OPENAPI_SPEC_URL || 'https://backend.composio.dev/api/v3/openapi.json';+const OPENAPI_V31_URL = process.env.OPENAPI_V31_SPEC_URL || 'https://backend.composio.dev/api/v3.1/openapi.json';// Tags to ignore (internal/admin)const IGNORED_TAGS = [@@ -20,25 +23,26 @@ const IGNORED_TAGS = ['x-internal',];-async function fetchAndFilterSpec() {- console.log(`Fetching OpenAPI spec from ${OPENAPI_URL}...`);-- const response = await fetch(OPENAPI_URL);+async function fetchSpec(url) {+ console.log(`Fetching OpenAPI spec from ${url}...`);+ const response = await fetch(url);if (!response.ok) {- throw new Error(`Failed to fetch: ${response.status}`);+ throw new Error(`Failed to fetch ${url}: ${response.status}`);}+ return response.json();+}- const spec = await response.json();-- // Filter paths+/**+ * Filter paths: remove ignored/internal tags, keep first tag only.+ */+function filterPaths(paths) {const filteredPaths = {};let removedCount = 0;- for (const [path, methods] of Object.entries(spec.paths)) {+ for (const [path, methods] of Object.entries(paths)) {const filteredMethods = {};for (const [method, operation] of Object.entries(methods)) {- // Skip if all tags are ignoredconst tags = operation.tags || [];const hasValidTag = tags.some(tag => !IGNORED_TAGS.includes(tag));@@ -47,13 +51,11 @@ async function fetchAndFilterSpec() {continue;}- // Skip if marked as internal (property or tag)if (operation['x-internal'] === true || tags.includes('x-internal')) {removedCount++;continue;}- // Keep only the first tag to avoid duplicates in sidebarif (tags.length > 1) {operation.tags = [tags[0]];}@@ -66,32 +68,27 @@ async function fetchAndFilterSpec() {}}- // For endpoints that exist under multiple API versions (e.g. /api/v3/ and /api/v3.1/),- // only keep the latest version to avoid duplicate sidebar entries.- const versionedPaths = new Map();- for (const path of Object.keys(filteredPaths)) {- const match = path.match(/^\/api\/v([\d.]+)\/(.+)$/);- if (!match) continue;- const [, version, rest] = match;- if (!versionedPaths.has(rest)) versionedPaths.set(rest, []);- versionedPaths.get(rest).push({ version, fullPath: path });- }+ return { filteredPaths, removedCount };+}- let versionDedupCount = 0;- for (const entries of versionedPaths.values()) {- if (entries.length <= 1) continue;- entries.sort((a, b) => parseFloat(b.version) - parseFloat(a.version));- for (const entry of entries.slice(1)) {- delete filteredPaths[entry.fullPath];- versionDedupCount++;+/**+ * Strip version prefixes from operationIds (e.g. getV3_1Tools → getTools).+ */+function cleanOperationIds(paths) {+ for (const methods of Object.values(paths)) {+ for (const operation of Object.values(methods)) {+ if (operation.operationId) {+ // Remove V3_1, V3_0, etc. prefixes from operationId+ operation.operationId = operation.operationId.replace(/V\d+_\d+/g, '');+ }}}- if (versionDedupCount > 0) {- console.log(`Removed ${versionDedupCount} endpoints superseded by newer API versions`);- }-- spec.paths = filteredPaths;+}+/**+ * Post-process a spec: remove CookieAuth, normalize unions, fix nullable.+ */+function postProcessSpec(spec) {// Filter tags listif (spec.tags) {spec.tags = spec.tags.filter(tag => !IGNORED_TAGS.includes(tag.name));@@ -100,175 +97,137 @@ async function fetchAndFilterSpec() {// Remove CookieAuth from security schemesif (spec.components?.securitySchemes?.CookieAuth) {delete spec.components.securitySchemes.CookieAuth;- console.log('Removed CookieAuth from securitySchemes');}// Remove CookieAuth from all endpoint security arrays- let cookieAuthRemovedCount = 0;for (const methods of Object.values(spec.paths)) {for (const operation of Object.values(methods)) {if (operation.security) {- const originalLength = operation.security.length;operation.security = operation.security.filter(sec => !('CookieAuth' in sec));- if (operation.security.length < originalLength) {- cookieAuthRemovedCount++;- }- // Remove empty security arrayif (operation.security.length === 0) {delete operation.security;}}}}- console.log(`Removed CookieAuth from ${cookieAuthRemovedCount} endpoint security definitions`);- console.log(`Removed ${removedCount} endpoints/operations`);- console.log(`Final spec has ${Object.keys(filteredPaths).length} paths`);-- // Normalize overly complex anyOf/oneOf schemas (e.g., connection_data with 68 object variants)- // Merges similar object schemas into a single object with all properties- let unionNormalizedCount = 0;-- // Helper to merge two property schemas, combining enums if present+ // Normalize overly complex anyOf/oneOf schemasconst mergePropertySchemas = (existing, incoming) => {if (!existing) return JSON.parse(JSON.stringify(incoming));-const merged = JSON.parse(JSON.stringify(existing));-- // Merge enum values if both have enumsif (existing.enum && incoming.enum) {- const enumSet = new Set([...existing.enum, ...incoming.enum]);- merged.enum = [...enumSet];+ merged.enum = [...new Set([...existing.enum, ...incoming.enum])];}-- // Recursively merge nested properties for objectsif (existing.properties && incoming.properties) {merged.properties = { ...existing.properties };for (const [key, val] of Object.entries(incoming.properties)) {merged.properties[key] = mergePropertySchemas(merged.properties[key], val);}}-return merged;};const normalizeUnionSchemas = (obj) => {if (!obj || typeof obj !== 'object') return;-- // Check for anyOf or oneOf with many similar object schemasfor (const unionKey of ['anyOf', 'oneOf']) {if (obj[unionKey] && Array.isArray(obj[unionKey]) && obj[unionKey].length > 5) {- const objectSchemas = obj[unionKey].filter(- (schema) => schema.type === 'object' && schema.properties- );-- // If most variants are objects, merge them+ const objectSchemas = obj[unionKey].filter(s => s.type === 'object' && s.properties);if (objectSchemas.length > 5 && objectSchemas.length >= obj[unionKey].length * 0.8) {const mergedProperties = {};const allRequired = new Set();-- // Collect all properties from all variants, merging enumsfor (const schema of objectSchemas) {for (const [propName, propSchema] of Object.entries(schema.properties || {})) {mergedProperties[propName] = mergePropertySchemas(mergedProperties[propName], propSchema);}- // Track required fields (only if required in ALL variants)if (schema.required) {- for (const req of schema.required) {- allRequired.add(req);- }+ for (const req of schema.required) allRequired.add(req);}}-- // Check which fields are required in ALL object schemas- const universallyRequired = [];- for (const req of allRequired) {- const requiredInAll = objectSchemas.every(- (schema) => schema.required && schema.required.includes(req)- );- if (requiredInAll) {- universallyRequired.push(req);- }- }-- // Replace union with merged object schema+ const universallyRequired = [...allRequired].filter(req =>+ objectSchemas.every(s => s.required && s.required.includes(req))+ );delete obj[unionKey];obj.type = 'object';obj.properties = mergedProperties;- if (universallyRequired.length > 0) {- obj.required = universallyRequired;- }+ if (universallyRequired.length > 0) obj.required = universallyRequired;obj.additionalProperties = true;-- unionNormalizedCount++;- console.log(- ` Merged ${unionKey} with ${objectSchemas.length} object variants into single object with ${Object.keys(mergedProperties).length} properties`- );}}}-- // Recurse into all propertiesfor (const val of Object.values(obj)) {- if (Array.isArray(val)) {- val.forEach((item) => normalizeUnionSchemas(item));- } else {- normalizeUnionSchemas(val);- }+ if (Array.isArray(val)) val.forEach(item => normalizeUnionSchemas(item));+ else normalizeUnionSchemas(val);}};normalizeUnionSchemas(spec);- if (unionNormalizedCount > 0) {- console.log(`Normalized ${unionNormalizedCount} complex union schemas`);- }- // Fix invalid OpenAPI 3.0: "nullable: true" without "type" is invalid- // See: https://swagger.io/docs/specification/data-models/data-types/#null- let nullableFixCount = 0;+ // Fix invalid OpenAPI 3.0: "nullable: true" without "type"const fixNullableWithoutType = (obj, parentKey = '') => {if (!obj || typeof obj !== 'object') return;-- // Check if this schema has nullable but no type definitionif (obj.nullable === true && !obj.type && !obj.$ref && !obj.oneOf && !obj.anyOf && !obj.allOf) {- // For additionalProperties, just remove nullable (allows any type)if (parentKey === 'additionalProperties') {delete obj.nullable;- }- // For schemas with an object example, infer type: object- else if (obj.example && typeof obj.example === 'object' && !Array.isArray(obj.example)) {+ } else if (obj.example && typeof obj.example === 'object' && !Array.isArray(obj.example)) {obj.type = 'object';- }- // For schemas with an array example, infer type: array- else if (obj.example && Array.isArray(obj.example)) {+ } else if (obj.example && Array.isArray(obj.example)) {obj.type = 'array';- }- // Default: add type: object (most common case for flexible schemas)- else {+ } else {obj.type = 'object';}- nullableFixCount++;}-- // Recurse into all propertiesfor (const [key, val] of Object.entries(obj)) {- if (Array.isArray(val)) {- val.forEach((item) => fixNullableWithoutType(item, key));- } else {- fixNullableWithoutType(val, key);- }+ if (Array.isArray(val)) val.forEach(item => fixNullableWithoutType(item, key));+ else fixNullableWithoutType(val, key);}};fixNullableWithoutType(spec);- if (nullableFixCount > 0) {- console.log(`Fixed ${nullableFixCount} schemas with nullable but no type`);+}++async function fetchAndFilterSpec() {+ // Fetch both specs in parallel+ const [v3Raw, v31Raw] = await Promise.all([+ fetchSpec(OPENAPI_V3_URL),+ fetchSpec(OPENAPI_V31_URL),+ ]);++ // --- v3.1 spec (latest, default) ---+ const v31Spec = JSON.parse(JSON.stringify(v31Raw));+ const v31Filtered = filterPaths(v31Spec.paths);+ v31Spec.paths = v31Filtered.filteredPaths;+ // Clean operationIds: getV3_1Tools → getTools (so URLs are clean)+ cleanOperationIds(v31Spec.paths);+ // Annotate all operations with version+ for (const methods of Object.values(v31Spec.paths)) {+ for (const op of Object.values(methods)) {+ op['x-api-version'] = '3.1';+ }}+ postProcessSpec(v31Spec);+ console.log(`v3.1: ${Object.keys(v31Spec.paths).length} paths`);++ // --- v3.0 spec ---+ const v3Spec = JSON.parse(JSON.stringify(v3Raw));+ const v3Filtered = filterPaths(v3Spec.paths);+ v3Spec.paths = v3Filtered.filteredPaths;+ cleanOperationIds(v3Spec.paths);+ for (const methods of Object.values(v3Spec.paths)) {+ for (const op of Object.values(methods)) {+ op['x-api-version'] = '3.0';+ }+ }+ postProcessSpec(v3Spec);+ console.log(`v3.0: ${Object.keys(v3Spec.paths).length} paths`);- // Write to public directory for fumadocs to fetch+ // Write both spec filesconst __dirname = dirname(fileURLToPath(import.meta.url));- const outputPath = join(__dirname, '../public/openapi.json');- writeFileSync(outputPath, JSON.stringify(spec, null, 2));- console.log(`Written to ${outputPath}`);+ const v31Path = join(__dirname, '../public/openapi.json');+ writeFileSync(v31Path, JSON.stringify(v31Spec, null, 2));+ console.log(`Written v3.1 spec to ${v31Path}`);++ const v3Path = join(__dirname, '../public/openapi-v3.json');+ writeFileSync(v3Path, JSON.stringify(v3Spec, null, 2));+ console.log(`Written v3.0 spec to ${v3Path}`);}fetchAndFilterSpec().catch(console.error);diff --git a/docs/scripts/generate-api-index.ts b/docs/scripts/generate-api-index.tsindex a58ed2ab9..d87a52b6f 100644--- a/docs/scripts/generate-api-index.ts+++ b/docs/scripts/generate-api-index.ts@@ -1,18 +1,32 @@/**- * Generates simple markdown index pages for each OpenAPI tag.- * These pages provide:- * - Tag description from OpenAPI spec- * - Links to all endpoints in that tag+ * Generates markdown index pages for each OpenAPI tag.+ * Reads both v3.1 and v3.0 specs and generates a table that+ * uses the ApiEndpointsTable component to switch versions dynamically.** Run: bun scripts/generate-api-index.ts*/-import { readFileSync, writeFileSync, mkdirSync } from 'fs';+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';import { join } from 'path';+interface OpenAPIOperation {+ summary?: string;+ tags?: string[];+ description?: string;+ operationId?: string;+ 'x-api-version'?: string;+}+interface OpenAPISpec {tags: Array<{ name: string; description?: string }>;- paths: Record<string, Record<string, { summary?: string; tags?: string[]; description?: string; operationId?: string }>>;+ paths: Record<string, Record<string, OpenAPIOperation>>;+}++interface OperationEntry {+ summary: string;+ method: string;+ path: string;+ operationId: string;}function slugify(text: string): string {@@ -22,83 +36,113 @@ function slugify(text: string): string {.replace(/^-|-$/g, '');}-function generateIndexPages() {- // Read OpenAPI spec- const specPath = join(process.cwd(), 'public/openapi.json');- const spec: OpenAPISpec = JSON.parse(readFileSync(specPath, 'utf-8'));-- // Build tag -> operations map- const tagOperations: Record<string, Array<{ summary: string; description?: string; method: string; path: string; operationId: string }>> = {};- const tagDescriptions: Record<string, string> = {};+function getOperationsByTag(spec: OpenAPISpec): Record<string, OperationEntry[]> {+ const tagOps: Record<string, OperationEntry[]> = {};- // Get tag descriptionsfor (const tag of spec.tags) {- tagDescriptions[tag.name] = tag.description || '';- tagOperations[tag.name] = [];- }-- // For endpoints that exist under multiple API versions (e.g. /api/v3/ and /api/v3.1/),- // only show the latest version. Extract version from path like /api/v3.1/tools/... → "3.1"- const supersededPaths: Set<string> = new Set();- const versionedPaths = new Map<string, { version: string; fullPath: string }[]>();-- for (const path of Object.keys(spec.paths)) {- const match = path.match(/^\/api\/v([\d.]+)\/(.+)$/);- if (!match) continue;- const [, version, rest] = match;- if (!versionedPaths.has(rest)) versionedPaths.set(rest, []);- versionedPaths.get(rest)!.push({ version, fullPath: path });+ tagOps[tag.name] = [];}- for (const entries of versionedPaths.values()) {- if (entries.length <= 1) continue;- // Sort by version descending; keep only the latest- entries.sort((a, b) => parseFloat(b.version) - parseFloat(a.version));- for (const entry of entries.slice(1)) {- supersededPaths.add(entry.fullPath);- }- }-- // Group operations by tagfor (const [path, methods] of Object.entries(spec.paths)) {- // Skip endpoints superseded by a newer API version- if (supersededPaths.has(path)) continue;for (const [method, operation] of Object.entries(methods)) {if (operation.tags) {for (const tag of operation.tags) {- if (!tagOperations[tag]) {- tagOperations[tag] = [];- }- const summaryFallback = operation.summary || `${method.toUpperCase()} ${path}`;- tagOperations[tag].push({- summary: summaryFallback,- description: operation.description,+ if (!tagOps[tag]) tagOps[tag] = [];+ tagOps[tag].push({+ summary: operation.summary || `${method.toUpperCase()} ${path}`,method: method.toUpperCase(),path,- operationId: operation.operationId || slugify(summaryFallback),+ operationId: operation.operationId || slugify(operation.summary || path),});}}}}- // Generate MDX files for each tag as index.mdx inside folders+ return tagOps;+}++function generateIndexPages() {+ const specV31Path = join(process.cwd(), 'public/openapi.json');+ const specV3Path = join(process.cwd(), 'public/openapi-v3.json');++ const specV31: OpenAPISpec = JSON.parse(readFileSync(specV31Path, 'utf-8'));+ const v31Ops = getOperationsByTag(specV31);++ let v3Ops: Record<string, OperationEntry[]> = {};+ if (existsSync(specV3Path)) {+ const specV3: OpenAPISpec = JSON.parse(readFileSync(specV3Path, 'utf-8'));+ v3Ops = getOperationsByTag(specV3);+ }++ // Collect tag descriptions from v3.1 spec+ const tagDescriptions: Record<string, string> = {};+ for (const tag of specV31.tags) {+ tagDescriptions[tag.name] = tag.description || '';+ }+const outputDir = join(process.cwd(), 'content/reference/api-reference');- for (const [tagName, operations] of Object.entries(tagOperations)) {- if (operations.length === 0) continue;+ // Get all unique tag names+ const allTags = new Set([...Object.keys(v31Ops), ...Object.keys(v3Ops)]);++ for (const tagName of allTags) {+ const ops31 = v31Ops[tagName] || [];+ const ops3 = v3Ops[tagName] || [];+ if (ops31.length === 0 && ops3.length === 0) continue;const tagSlug = slugify(tagName);const tagDescription = tagDescriptions[tagName] || `${tagName} API endpoints`;- // Generate endpoint table- const tableRows = operations.map(op => {- const url = `/reference/api-reference/${tagSlug}/${op.operationId}`;+ // Only generate v3.1 index page if the tag has v3.1 operations+ if (ops31.length > 0) {+ const v3ByOpId: Record<string, OperationEntry> = {};+ for (const op of ops3) {+ v3ByOpId[op.operationId] = op;+ }++ const endpoints = ops31.map(op => {+ const v3Op = v3ByOpId[op.operationId];+ return {+ method: op.method,+ pathV31: op.path,+ pathV3: v3Op ? v3Op.path : op.path.replace('/v3.1/', '/v3/'),+ summary: op.summary,+ href: `/reference/api-reference/${tagSlug}/${op.operationId}`,+ };+ });++ const content = `---+title: ${tagName}+description: "${tagDescription}"+---++{/* Auto-generated from OpenAPI spec. Do not edit directly. */}++${tagDescription}++## Endpoints- return `| \`${op.method} ${op.path}\` | [${op.summary}](${url}) |`;- }).join('\n');+<ApiEndpointsTable endpoints={${JSON.stringify(endpoints)}} />+`;- const content = `---+ const folderPath = join(outputDir, tagSlug);+ mkdirSync(folderPath, { recursive: true });+ writeFileSync(join(folderPath, 'index.mdx'), content);+ console.log(`Generated: ${tagSlug}/index.mdx`);+ }++ // Also generate v3 index page with v3-specific hrefs+ if (ops3.length > 0) {+ const v3Endpoints = ops3.map(op => ({+ method: op.method,+ pathV31: op.path.replace('/v3/', '/v3.1/'),+ pathV3: op.path,+ summary: op.summary,+ href: `/reference/v3/api-reference/${tagSlug}/${op.operationId}`,+ }));++ const v3Content = `---title: ${tagName}description: "${tagDescription}"---@@ -109,17 +153,14 @@ ${tagDescription}## Endpoints-| Endpoint | Quick Link |-|----------|------------|-${tableRows}+<ApiEndpointsTable endpoints={${JSON.stringify(v3Endpoints)}} />`;- // Create folder and write index.mdx inside- const folderPath = join(outputDir, tagSlug);- mkdirSync(folderPath, { recursive: true });- const filePath = join(folderPath, 'index.mdx');- writeFileSync(filePath, content);- console.log(`Generated: ${tagSlug}/index.mdx`);+ const v3FolderPath = join(process.cwd(), 'content/reference/v3/api-reference', tagSlug);+ mkdirSync(v3FolderPath, { recursive: true });+ writeFileSync(join(v3FolderPath, 'index.mdx'), v3Content);+ console.log(`Generated: v3/api-reference/${tagSlug}/index.mdx`);+ }}console.log('Done generating API index pages');