Skip to content

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

docs: 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.tsx
index 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.tsx
new file mode 100644
index 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.json
index 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.mdx
new file mode 100644
index 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.mdx
index 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 help
diff --git a/docs/content/reference/index.mdx b/docs/content/reference/index.mdx
index 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.json
index 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.mdx
new file mode 100644
index 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.json
index 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.ts
index 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 info
export 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;