@devries-cameron20 / composio Mirror · read-only / commits / d0f87dff6
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 12:00 UTC

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;