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
- Add authentication page explaining API key usage - Add errors page with HTTP status codes and error types - Add rate limits page with plan-based limits and headers - Improve overview page with REST API table and SDK cards - Set API Reference and SDK Reference folders to expand by default - Remove navigation footer from OpenAPI reference pages Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Jan 30, 2026 at 15:36 UTC
d0f87dff6f40e6f41835753450ffe3b989f478aa
10 files changed
+240
-25
docs/app/(home)/reference/[[...slug]]/page.tsx
+1
-1
@@ -33,7 +33,7 @@ export default async function Page({
33
if ('getAPIPageProps' in page.data) {
34
const pageData = page.data as OpenAPIPageData;
35
return (
36
- <DocsPage full tableOfContentPopover={{ enabled: false }}>
36
+ <DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
37
<h1 className="text-2xl font-semibold mb-4">{pageData.title}</h1>
38
<PageActions path={page.url} />
39
<DocsBody>
docs/components/breadcrumb-schema.tsx
new
+70
@@ -0,0 +1,70 @@
1
+const BASE_URL = 'https://docs.composio.dev';
2
+
3
+interface BreadcrumbItem {
4
+ name: string;
5
+ url: string;
6
+}
7
+
8
+interface BreadcrumbSchemaProps {
9
+ items: BreadcrumbItem[];
10
+}
11
+
12
+/**
13
+ * Generates JSON-LD BreadcrumbList schema for SEO.
14
+ * Helps Google display breadcrumb trails in search results.
15
+ *
16
+ * @see https://developers.google.com/search/docs/appearance/structured-data/breadcrumb
17
+ */
18
+export function BreadcrumbSchema({ items }: BreadcrumbSchemaProps) {
19
+ if (items.length === 0) return null;
20
+
21
+ const schema = {
22
+ '@context': 'https://schema.org',
23
+ '@type': 'BreadcrumbList',
24
+ itemListElement: items.map((item, index) => ({
25
+ '@type': 'ListItem',
26
+ position: index + 1,
27
+ name: item.name,
28
+ item: `${BASE_URL}${item.url}`,
29
+ })),
30
+ };
31
+
32
+ return (
33
+ <script
34
+ type="application/ld+json"
35
+ dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
36
+ />
37
+ );
38
+}
39
+
40
+/**
41
+ * Builds breadcrumb items from a URL path and page title.
42
+ *
43
+ * Example: buildBreadcrumbs('/docs/auth/oauth', 'OAuth Guide')
44
+ * Returns: [
45
+ * { name: 'Docs', url: '/docs' },
46
+ * { name: 'Auth', url: '/docs/auth' },
47
+ * { name: 'OAuth Guide', url: '/docs/auth/oauth' }
48
+ * ]
49
+ */
50
+export function buildBreadcrumbs(url: string, pageTitle: string): BreadcrumbItem[] {
51
+ const segments = url.split('/').filter(Boolean);
52
+ const items: BreadcrumbItem[] = [];
53
+
54
+ // Build intermediate breadcrumbs from URL segments
55
+ let currentPath = '';
56
+ for (let i = 0; i < segments.length - 1; i++) {
57
+ currentPath += `/${segments[i]}`;
58
+ // Capitalize and format segment name (e.g., 'auth-configuration' -> 'Auth Configuration')
59
+ const name = segments[i]
60
+ .split('-')
61
+ .map(word => word.charAt(0).toUpperCase() + word.slice(1))
62
+ .join(' ');
63
+ items.push({ name, url: currentPath });
64
+ }
65
+
66
+ // Add final page with actual title
67
+ items.push({ name: pageTitle, url });
68
+
69
+ return items;
70
+}
docs/content/reference/api-reference/meta.json
+1
@@ -1,4 +1,5 @@
1
{
2
"title": "API Reference",
3
+ "defaultOpen": true,
4
"pages": ["..."]
5
}
docs/content/reference/authentication.mdx
new
+56
@@ -0,0 +1,56 @@
1
+---
2
+title: Authentication
3
+description: How to authenticate with Composio APIs using project and organization API keys
4
+keywords: [API authentication, API key, x-api-key, x-org-api-key, Composio authentication, authorization]
5
+---
6
+
7
+All Composio API endpoints require authentication via API key.
8
+
9
+## API Key Authentication
10
+
11
+Include your API key in the `x-api-key` header.
12
+
13
+### Getting Your API Key
14
+
15
+1. Sign in to [composio.dev](https://composio.dev)
16
+2. Navigate to **Settings**
17
+3. In **Project Settings**, copy the key from the **API Keys** section
18
+
19
+<Video src="/videos/fetch-project-key.mp4" autoPlay />
20
+
21
+## Organization API Key
22
+
23
+For organization-level access across multiple projects, use the `x-org-api-key` header instead.
24
+
25
+### Getting Your Organization API Key
26
+
27
+1. Sign in to [composio.dev](https://composio.dev)
28
+2. Navigate to **Organization Settings** → **General Settings**
29
+3. Copy the token under **Organization Access Tokens**
30
+
31
+<Video src="/videos/fetch-org-key.mp4" autoPlay />
32
+
33
+## Using the API Key
34
+
35
+Include your API key in the request header:
36
+
37
+```bash
38
+curl https://backend.composio.dev/api/v3/tools \
39
+ -H "x-api-key: $COMPOSIO_API_KEY"
40
+```
41
+
42
+For organization-level endpoints:
43
+
44
+```bash
45
+curl https://backend.composio.dev/api/v3/org/projects \
46
+ -H "x-org-api-key: $COMPOSIO_ORG_API_KEY"
47
+```
48
+
49
+<Cards>
50
+ <Card title="Errors" href="/reference/errors">
51
+ Understanding API error responses
52
+ </Card>
53
+ <Card title="Rate Limits" href="/reference/rate-limits">
54
+ API rate limits by plan
55
+ </Card>
56
+</Cards>
docs/content/reference/errors.mdx
+3
-3
@@ -1,7 +1,7 @@
1
---
2
title: Errors
3
-description: Understanding and handling Composio API errors
4
-keywords: [errors, error handling, HTTP status codes, troubleshooting, API errors]
3
+description: Composio API error codes, HTTP status codes, and troubleshooting guide
4
+keywords: [API errors, error codes, HTTP status codes, error handling, troubleshooting, "400 bad request", "401 unauthorized", "429 rate limit"]
5
---
6
7
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.
100
101
## Rate limiting
102
103
-When you hit rate limits, you'll receive a `429` status code. Back off exponentially and retry.
103
+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.
104
105
## Getting help
106
docs/content/reference/index.mdx
+26
-21
@@ -1,32 +1,37 @@
1
---
2
title: Overview
3
-description: Authentication and getting started with Composio APIs
3
+description: Composio REST API and SDK reference for AI agent tool execution, authentication, and integrations
4
+keywords: [Composio API, REST API, SDK reference, AI agent tools, tool execution, API documentation]
5
---
6
6
-## Authentication
7
+Composio powers tool discovery, execution, authentication, and context management for your AI agents with 800+ toolkits. This reference covers our REST APIs and SDKs.
8
8
-All Composio API endpoints require authentication via API key.
9
+## Quick Reference
10
10
-### API Key Authentication
11
+- **Base URL**: `https://backend.composio.dev/api/v3`
12
+- **[Authentication](/reference/authentication)**: `x-api-key` (project) or `x-org-api-key` (organization) header
13
+- **[Rate Limits](/reference/rate-limits)**: 20K-100K requests per 10 minutes (plan-dependent)
14
12
-Include your API key in the `x-api-key` header.
15
+## REST API
16
14
-#### Getting Your API Key
17
+Browse endpoints in the sidebar. Key APIs include:
18
16
-1. Sign in to [composio.dev](https://composio.dev)
17
-2. Navigate to **Settings**
18
-3. In **Project Settings**, copy the key from the **API Keys** section
19
+| API | Description |
20
+|-----|-------------|
21
+| Tool Router | Session-based API for AI agents to discover and execute tools |
22
+| Tools | List, search, and execute individual actions |
23
+| Connected Accounts | Manage user OAuth connections to apps |
24
+| Auth Configs | Configure how users authenticate to toolkits |
25
+| Triggers | Subscribe to webhooks from connected apps |
26
+| Toolkits | Browse available apps and their tools |
27
20
-<Video src="/videos/fetch-project-key.mp4" autoPlay />
28
+## SDK Reference
29
22
-### Organization API Key
23
-
24
-For organization-level access, use the `x-org-api-key` header.
25
-
26
-#### Getting Your Organization API Key
27
-
28
-1. Sign in to [composio.dev](https://composio.dev)
29
-2. Navigate to **Organization Settings** → **General Settings**
30
-3. Copy the token under **Organization Access Tokens**
31
-
32
-<Video src="/videos/fetch-org-key.mp4" autoPlay />
30
+<Cards>
31
+ <Card icon={<img src="/images/providers/typescript-logo.svg" alt="TypeScript" width={20} height={20} />} title="TypeScript SDK" href="/reference/sdk-reference/typescript">
32
+ TypeScript SDK reference
33
+ </Card>
34
+ <Card icon={<img src="/images/providers/python-logo.svg" alt="Python" width={20} height={20} />} title="Python SDK" href="/reference/sdk-reference/python">
35
+ Python SDK reference
36
+ </Card>
37
+</Cards>
docs/content/reference/meta.json
+2
@@ -2,6 +2,8 @@
2
"title": "Reference",
3
"pages": [
4
"index",
5
+ "authentication",
6
+ "rate-limits",
7
"errors",
8
"api-reference",
9
"sdk-reference"
docs/content/reference/rate-limits.mdx
new
+62
@@ -0,0 +1,62 @@
1
+---
2
+title: Rate Limits
3
+description: Composio API rate limits by plan, rate limit headers, and best practices
4
+keywords: [API rate limits, rate limiting, throttling, 429 too many requests, API quotas, request limits]
5
+---
6
+
7
+Rate limits are enforced **per organization** and reset on a rolling 10-minute window.
8
+
9
+## Rate limits by plan
10
+
11
+| Plan | Rate Limit | Window |
12
+|------|------------|--------|
13
+| Starter | 20,000 requests | 10 minutes |
14
+| Hobby | 20,000 requests | 10 minutes |
15
+| Growth | 100,000 requests | 10 minutes |
16
+| Enterprise | Unlimited | - |
17
+
18
+<Callout>
19
+All authenticated API endpoints share your organization's rate limit. This includes tool execution, connected accounts, triggers, and all other API operations.
20
+</Callout>
21
+
22
+## Rate limit headers
23
+
24
+API responses include headers to help you track your usage:
25
+
26
+| Header | Description |
27
+|--------|-------------|
28
+| `X-RateLimit` | Total requests allowed in the current window |
29
+| `X-RateLimit-Remaining` | Requests remaining in the current window |
30
+| `X-RateLimit-Window-Size` | Window size (e.g., `600s` for 600 seconds) |
31
+| `Retry-After` | Seconds until the window resets (only on 429 responses) |
32
+
33
+## Rate limit response
34
+
35
+When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:
36
+
37
+```json
38
+{
39
+ "message": "Rate limit exceeded. Limit: 100000 requests per 10 minutes"
40
+}
41
+```
42
+
43
+## Best practices
44
+
45
+1. **Monitor your usage** - Check the `X-RateLimit-Remaining` header to track how close you are to the limit.
46
+
47
+2. **Implement backoff** - When you receive a `429`, wait for the duration specified in `Retry-After` before retrying.
48
+
49
+3. **Cache responses** - Cache tool definitions and other static data to reduce unnecessary API calls.
50
+
51
+## Need higher limits?
52
+
53
+If you're hitting rate limits regularly, consider upgrading your plan or [contact us](mailto:tech@composio.dev) to discuss custom limits for your use case.
54
+
55
+<Cards>
56
+ <Card title="Errors" href="/reference/errors">
57
+ Understanding API error responses
58
+ </Card>
59
+ <Card title="Pricing" href="https://composio.dev/pricing">
60
+ Compare plans and limits
61
+ </Card>
62
+</Cards>
docs/content/reference/sdk-reference/meta.json
+1
@@ -1,4 +1,5 @@
1
{
2
"title": "SDK Reference",
3
+ "defaultOpen": true,
4
"pages": ["typescript", "python"]
5
}
docs/lib/source.ts
+18
@@ -4,6 +4,20 @@ import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
4
import { openapi } from './openapi';
5
import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';
6
7
+/**
8
+ * Transformer to set defaultOpen: true for specific folders in the reference sidebar.
9
+ * This is needed because openapiSource doesn't support meta.json files.
10
+ */
11
+const defaultOpenTransformer = {
12
+ folder(node: { name: string; defaultOpen?: boolean }, folderPath: string) {
13
+ // Set defaultOpen for API Reference and SDK Reference folders
14
+ if (folderPath === 'api-reference' || folderPath === 'sdk-reference') {
15
+ return { ...node, defaultOpen: true };
16
+ }
17
+ return node;
18
+ },
19
+};
20
+
21
// See https://fumadocs.dev/docs/headless/source-api for more info
22
export const source = loader({
23
baseUrl: '/docs',
@@ -38,6 +52,10 @@ export async function getReferenceSource() {
52
openapi: openapiPages,
53
}),
54
plugins: [lucideIconsPlugin(), openapiPlugin()],
55
+ pageTree: {
56
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
57
+ transformers: [defaultOpenTransformer as any],
58
+ },
59
});
60
}
61
return _referenceSource;