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: Improve API reference section with authentication, errors, and rate limits pages
Sushmithamalleshd0f87dff6f40
diff --git a/docs/app/(home)/reference/[[...slug]]/page.tsx b/docs/app/(home)/reference/[[...slug]]/page.tsxindex 30c506afc..e34fc9d0c 100644--- a/docs/app/(home)/reference/[[...slug]]/page.tsx+++ b/docs/app/(home)/reference/[[...slug]]/page.tsx@@ -33,7 +33,7 @@ export default async function Page({if ('getAPIPageProps' in page.data) {const pageData = page.data as OpenAPIPageData;return (- <DocsPage full tableOfContentPopover={{ enabled: false }}>+ <DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}><h1 className="text-2xl font-semibold mb-4">{pageData.title}</h1><PageActions path={page.url} /><DocsBody>diff --git a/docs/components/breadcrumb-schema.tsx b/docs/components/breadcrumb-schema.tsxnew file mode 100644index 000000000..92156d221--- /dev/null+++ b/docs/components/breadcrumb-schema.tsx@@ -0,0 +1,70 @@+const BASE_URL = 'https://docs.composio.dev';++interface BreadcrumbItem {+ name: string;+ url: string;+}++interface BreadcrumbSchemaProps {+ items: BreadcrumbItem[];+}++/**+ * Generates JSON-LD BreadcrumbList schema for SEO.+ * Helps Google display breadcrumb trails in search results.+ *+ * @see https://developers.google.com/search/docs/appearance/structured-data/breadcrumb+ */+export function BreadcrumbSchema({ items }: BreadcrumbSchemaProps) {+ if (items.length === 0) return null;++ const schema = {+ '@context': 'https://schema.org',+ '@type': 'BreadcrumbList',+ itemListElement: items.map((item, index) => ({+ '@type': 'ListItem',+ position: index + 1,+ name: item.name,+ item: `${BASE_URL}${item.url}`,+ })),+ };++ return (+ <script+ type="application/ld+json"+ dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}+ />+ );+}++/**+ * Builds breadcrumb items from a URL path and page title.+ *+ * Example: buildBreadcrumbs('/docs/auth/oauth', 'OAuth Guide')+ * Returns: [+ * { name: 'Docs', url: '/docs' },+ * { name: 'Auth', url: '/docs/auth' },+ * { name: 'OAuth Guide', url: '/docs/auth/oauth' }+ * ]+ */+export function buildBreadcrumbs(url: string, pageTitle: string): BreadcrumbItem[] {+ const segments = url.split('/').filter(Boolean);+ const items: BreadcrumbItem[] = [];++ // Build intermediate breadcrumbs from URL segments+ let currentPath = '';+ for (let i = 0; i < segments.length - 1; i++) {+ currentPath += `/${segments[i]}`;+ // Capitalize and format segment name (e.g., 'auth-configuration' -> 'Auth Configuration')+ const name = segments[i]+ .split('-')+ .map(word => word.charAt(0).toUpperCase() + word.slice(1))+ .join(' ');+ items.push({ name, url: currentPath });+ }++ // Add final page with actual title+ items.push({ name: pageTitle, url });++ return items;+}diff --git a/docs/content/reference/api-reference/meta.json b/docs/content/reference/api-reference/meta.jsonindex 51c85eb9d..51b32ff19 100644--- a/docs/content/reference/api-reference/meta.json+++ b/docs/content/reference/api-reference/meta.json@@ -1,4 +1,5 @@{"title": "API Reference",+ "defaultOpen": true,"pages": ["..."]}diff --git a/docs/content/reference/authentication.mdx b/docs/content/reference/authentication.mdxnew file mode 100644index 000000000..2869fa00d--- /dev/null+++ b/docs/content/reference/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/errors">+ Understanding API error responses+ </Card>+ <Card title="Rate Limits" href="/reference/rate-limits">+ API rate limits by plan+ </Card>+</Cards>diff --git a/docs/content/reference/errors.mdx b/docs/content/reference/errors.mdxindex 153f851af..62e2747bd 100644--- a/docs/content/reference/errors.mdx+++ b/docs/content/reference/errors.mdx@@ -1,7 +1,7 @@---title: Errors-description: Understanding and handling Composio API errors-keywords: [errors, error handling, HTTP status codes, troubleshooting, API 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.@@ -100,7 +100,7 @@ See [Triggers Troubleshooting](/docs/troubleshooting/triggers) for more help.## Rate limiting-When you hit rate limits, you'll receive a `429` status code. Back off exponentially and retry.+When you hit rate limits, you'll receive a `429` status code. See [Rate Limits](/reference/rate-limits) for details on limits by plan and best practices for handling rate limit errors.## Getting helpdiff --git a/docs/content/reference/index.mdx b/docs/content/reference/index.mdxindex aaa8195a6..d9cfd218f 100644--- a/docs/content/reference/index.mdx+++ b/docs/content/reference/index.mdx@@ -1,32 +1,37 @@---title: Overview-description: Authentication and getting started with Composio APIs+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]----## Authentication+Composio powers tool discovery, execution, authentication, and context management for your AI agents with 800+ toolkits. This reference covers our REST APIs and SDKs.-All Composio API endpoints require authentication via API key.+## Quick Reference-### API Key Authentication+- **Base URL**: `https://backend.composio.dev/api/v3`+- **[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)-Include your API key in the `x-api-key` header.+## REST API-#### Getting Your API Key+Browse endpoints in the sidebar. Key APIs include:-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+| API | Description |+|-----|-------------|+| Tool Router | Session-based API for AI agents to discover and execute tools |+| Tools | List, search, and execute individual actions |+| Connected Accounts | Manage user OAuth connections to apps |+| Auth Configs | Configure how users authenticate to toolkits |+| Triggers | Subscribe to webhooks from connected apps |+| Toolkits | Browse available apps and their tools |-<Video src="/videos/fetch-project-key.mp4" autoPlay />+## SDK Reference-### Organization API Key--For organization-level access, use the `x-org-api-key` header.--#### 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 />+<Cards>+ <Card icon={<img src="/images/providers/typescript-logo.svg" alt="TypeScript" width={20} height={20} />} title="TypeScript SDK" href="/reference/sdk-reference/typescript">+ TypeScript SDK reference+ </Card>+ <Card icon={<img src="/images/providers/python-logo.svg" alt="Python" width={20} height={20} />} title="Python SDK" href="/reference/sdk-reference/python">+ Python SDK reference+ </Card>+</Cards>diff --git a/docs/content/reference/meta.json b/docs/content/reference/meta.jsonindex 44198ba25..7faf27f68 100644--- a/docs/content/reference/meta.json+++ b/docs/content/reference/meta.json@@ -2,6 +2,8 @@"title": "Reference","pages": ["index",+ "authentication",+ "rate-limits","errors","api-reference","sdk-reference"diff --git a/docs/content/reference/rate-limits.mdx b/docs/content/reference/rate-limits.mdxnew file mode 100644index 000000000..393604330--- /dev/null+++ b/docs/content/reference/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 [contact us](mailto:[email protected]) to discuss custom limits for your use case.++<Cards>+ <Card title="Errors" href="/reference/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/reference/sdk-reference/meta.json b/docs/content/reference/sdk-reference/meta.jsonindex a5e11ead3..7b9527d86 100644--- a/docs/content/reference/sdk-reference/meta.json+++ b/docs/content/reference/sdk-reference/meta.json@@ -1,4 +1,5 @@{"title": "SDK Reference",+ "defaultOpen": true,"pages": ["typescript", "python"]}diff --git a/docs/lib/source.ts b/docs/lib/source.tsindex 58769d998..a1df9871f 100644--- a/docs/lib/source.ts+++ b/docs/lib/source.ts@@ -4,6 +4,20 @@ import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';import { openapi } from './openapi';import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';+/**+ * 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') {+ return { ...node, defaultOpen: true };+ }+ return node;+ },+};+// See https://fumadocs.dev/docs/headless/source-api for more infoexport const source = loader({baseUrl: '/docs',@@ -38,6 +52,10 @@ export async function getReferenceSource() {openapi: openapiPages,}),plugins: [lucideIconsPlugin(), openapiPlugin()],+ pageTree: {+ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ transformers: [defaultOpenTransformer as any],+ },});}return _referenceSource;