Python, TypeScript and API examples, with checks behind them

Finding the right documentation is frustrating when the example is in another language, or when it fails in the project the tutorial told you to create. You end up debugging documentation before you can build your application.

We've overhauled Composio's documentation examples to make that experience less likely. Our docs now feature maintained, operation examples in Python, TypeScript and API options (direct REST in curl). We also added validation and fixed rendering paths that could lose examples before a reader or coding agent ever saw them.

The work shipped in PR #5100. In the course of writing equivalent examples, we exposed incorrect assumptions about SDK responses, project setup and what our documentation pipeline actually preserved.

Choose your language without changing the task

Across our guides, examples, API overviews, toolkit FAQs and knowledge-base articles, language groups follow the same order: Python, TypeScript, API. They use the same labels, and shared language tabs remember your selection.

For example, creating a session now includes these options:

Python

session = composio.sessions.create(user_id="user_123")

TypeScript

import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.create("user_123");

API

curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_123"}'

The API examples also spell out work the SDK normally handles. Where a helper polls for authentication, transforms inputs or sends multiple requests, its curl counterpart needs to show those steps.

The CSV report and email-triggered agent tutorials also gained TypeScript implementations. Generated API reference requests gained Python and TypeScript options too. Those reference samples use raw HTTP clients, not necessarily Composio SDK methods.

There are genuine exceptions. CrewAI integration code is Python-specific. The saved session configs guide explains unavailable Python operations and links to REST alternatives. Local agent orchestration is not always one remote operation. We record scoped exceptions rather than inventing counterparts. But we'd rather this be known exceptions rather than just choosing only one SDK or option for a given example.

Equivalent examples exposed real bugs

A response object was not a dictionary

Our manual-authentication guide indexed a Python proxy response with response["status"] and response["data"]. That response is an SDK model. The corrected example uses response.status and response.data. Dictionary indexing could raise TypeError at runtime.

The Python checker now attributes model-indexing diagnostics to the SDK, and a real-helper regression fixture checks that case.

Session proxy execution has a different return type: a discriminated dictionary. We fixed that example to check result_type before reading status and data, because a hook can block the request.

Valid TypeScript still needed a runnable project

The new TypeScript tutorials use top-level await. During review, their documented setup needed an explicit ES-module setting: npm pkg set type=module. Without it, npx tsx rejected the scripts in the npm-created project.

Our snippet checker compiles in an ES-module context; it does not execute the installation instructions or validate a reader's package.json. The PR records a separate setup smoke check. Compiler validation alone would not establish that the tutorial runs as documented.

What we check locally and in CI

Contributors can run the following checks from docs/, alongside the production build.

Structure and coverage. bun run inventory:code-examples records examples and their validation categories, including generated, historical and component-backed sources. bun run check:code-examples parses Markdown and MDX to check language-group order, missing or duplicate tabs, empty content, wrong-language fences and exception placement. It checks structure, not whether two implementations mean the same thing.

Python syntax and SDK usage. bun run check:python-snippets compiles maintained Python fences without executing them, then uses mypy to identify SDK-related errors against local Python SDK and provider source. It catches supported classes of wrong calls, attributes, imports, TypedDict access and response-model misuse. Conventional fragment bindings supply some missing context. The helper keeps unrelated Python and third-party diagnostics separate from the errors that fail the gate, so a passing fragment may still need work to run as a complete application.

The Python environment uses Python 3.12 and a frozen docs-snippets dependency group. Type ignores must name error codes, include an explanation and still suppress an actual error. The dedicated Python CI workflow runs the helper regressions and snippet gate, including when Python SDK source changes.

TypeScript coverage beyond the build. Twoslash already checked build-covered TypeScript. We kept it and added bun run check:typescript-snippets for maintained API overviews, authored reference pages and Markdown FAQ/KB inputs outside that coverage. The standalone gate rejects blanket diagnostic-suppression directives. TypeScript CI runs it, focused regressions and the production build. Unlike Python's local-source check, these checks resolve SDK packages installed in the docs project.

Direct API requests. bun run check:api-snippets parses supported curl syntax and checks the base URL, version policy, HTTP method and route, authentication headers, and JSON request bodies against committed OpenAPI specifications. Exceptions identify a rule and operation, optionally a field. An exception fails when it no longer matches a diagnostic, so schema fixes do not leave silent waivers behind.

The static test suite, run in docs CI, also checks maintained structure and API examples. The validation guide documents the commands and boundaries. None of these static checks proves that credentials work, an upstream service accepts the request, or an entire agent workflow succeeds. The curl checker also does not validate query parameters.

Keeping examples in agent-readable Markdown

We now convert Cards and tab boundaries using the parsed MDX tree. A regression test verifies that later examples retain all three labels and code fences.

When a coding agent reads the Markdown version of a page, it needs the examples and their language labels, including any notes about unavailable SDK operations. Otherwise it can miss an existing implementation or generate code for an operation the SDK does not support.

Better maintenance, with visible limits

The inventory shows contributors which examples the gates check and which they skip. When an SDK or guide changes, run the checks that apply to it.

Try the examples in your stack. If one is incorrect, confusing or missing a useful counterpart, open an issue with the page, language and SDK version. We'll use that information to fix the example and add a regression check where the failure can be detected automatically.