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

next
md 125 lines 9.71 KB
Rendered Raw
1 # Code examples: Python, TypeScript, and API
2
3 Maintained operation examples offer Python, TypeScript, and API options. A valid marker records an exception; it does not establish that the exception is justified or the examples are equivalent.
4
5 ## Canonical language group
6
7 ````mdx
8 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
9 <Tab value="Python">
10 ```python
11 # Python SDK operation
12 ```
13 </Tab>
14 <Tab value="TypeScript">
15 ```typescript
16 // Equivalent TypeScript SDK operation
17 ```
18 </Tab>
19 <Tab value="API">
20 ```bash
21 curl https://backend.composio.dev/api/v3.1/tools \
22 -H "x-api-key: $COMPOSIO_API_KEY"
23 ```
24 </Tab>
25 </Tabs>
26 ````
27
28 - Keep the order Python, TypeScript, API. Use `python`, `typescript`, and `bash` fences.
29 - Preserve the operation, inputs, user identity, account pinning, filters, pagination, permissions, version selection, and output in all options. Expand SDK defaults, transformations, polling, and create-or-update behavior in curl.
30 - A tab may contain installation instructions, output fences, a table, or an SDK-gap Callout. Empty code fences and another language's code are not substitutes.
31 - Versioned migration labels may share a suffix such as `(previous)` or `(current)`. A suffix never implicitly waives the API option. Current operations need an API tab; obsolete names may use a precise `no-api` marker pointing to the current replacement.
32 - A polling helper still has an HTTP equivalent. Show the initial request and the polling/terminal states, not only the first request.
33
34 ### Plain Markdown
35
36 FAQ and KB Markdown uses consecutive headings at the same depth:
37
38 ````md
39 ### Python
40
41 ```python
42 # Python operation
43 ```
44
45 ### TypeScript
46
47 ```typescript
48 // Equivalent operation
49 ```
50
51 ### API
52
53 ```bash
54 curl ...
55 ```
56 ````
57
58 The FAQ and KB renderers turn these headings into persistent language tabs. Agent Markdown keeps the labels and all variants. For an unavailable SDK endpoint, a `> [!NOTE]` block under that language heading becomes an SDK-gap Callout.
59
60 The last option runs until the next heading at the same or a higher level. When prose after the group applies to every language, close the group with `<!-- end-languages -->` on its own line before that prose. Without the marker, the renderers hide the shared prose inside the last tab.
61
62 ## Exceptions and SDK gaps
63
64 Use MDX comments in `.mdx` files and HTML comments in `.md`. A marker must be an actual comment node, not text inside code, an attribute, a string, or inline code. Local markers attach only across whitespace.
65
66 | Kind | Placement | Allowed reason |
67 |---|---|---|
68 | `single-language` | Immediately before a standalone SDK/API fence or a framework-selector Tabs group | The named runtime, provider, or package genuinely exists in only one language |
69 | `single-language-page` | After frontmatter | The entire page is about a language-specific runtime; do not use it for a project that can be implemented in both SDKs |
70 | `no-api` | Immediately before a language group, including a Markdown heading group | The operation is local orchestration or transformation, not a remote operation hidden behind an SDK helper |
71 | `unchecked-api` | Immediately before the affected curl fence | One identified rule/operation/field cannot be checked against the committed schema |
72
73 Every marker needs a specific `reason="..."`. Project size or translation effort is not a reason. Use local markers instead of page-wide exemptions when other examples have counterparts. Install commands do not require an API option.
74
75 If an SDK lacks the operation, keep its language option and explain the gap in a nonempty Callout. Link to the working API equivalent. Verify the SDK implementation, generated client, and committed OpenAPI schema before claiming a gap. Prefer a real raw-client call when the public raw client supports the operation.
76
77 ### Narrow API exceptions
78
79 An API exception identifies the exact rule and operation, and the affected field when applicable:
80
81 ```mdx
82 {/* code-example: unchecked-api reason="The committed session schema omits this supported callback field" rule="api-body-schema" operation="PATCH /api/v3.1/tool_router/session/{session_id}" field="manage_connections.callback_url" */}
83 ```
84
85 Allowed exception rules are defined by `EXEMPTIBLE_RULES` in `lib/api-snippets.ts`. Add separate markers for separate operations. A field exception does not waive route, method, authentication, version, or other body validation. Unused exceptions fail, so remove them when the schema catches up. Unsupported shell/curl syntax and opaque request bodies must not silently bypass validation.
86
87 ## Inventory and validation scope
88
89 Run `bun run inventory:code-examples` for JSON records with source path, line, kind, language/options, validation category, and exception reason. The inventory includes:
90
91 - Authored guides, examples, reference overviews, toolkit FAQs, KB source and curated KB articles.
92 - Generated API/KB presentation copies and every OpenAPI path/webhook operation.
93 - Generated language-specific SDK symbol references, including signatures and partial usage fragments.
94 - Historical changelog fences.
95 - `PackageInstall`, `FileBuildup`, and `RepoBrowser` invocations and their committed source files/stages. Shared source-runtime reasons live in `lib/example-sources.ts`; new sources require an explicit classification.
96 - Agent-only Markdown examples injected from `lib/llm-guardrails`. The checks use `#rendered.md` projections with source-line padding, not the TypeScript template-literal syntax.
97
98 The maintained-file checks read `content/docs`, `content/examples`, authored `content/reference`, `content/toolkits`, `api-overviews`, `kb/source`, `kb/articles`, and the injected guardrail projections. Generated API overview and KB copies are checked through their maintained inputs, not treated as independent editable examples.
99
100 Generated SDK symbol references remain language-specific: signatures and partial fragments are inventoried, not translated or certified by the maintained-example gates. Historical release examples are also inventoried rather than rewritten against today's API. These are explicit validation limits, not proof that every rendered fence offers three runnable equivalents. Edit reference generators/SDK docstrings or historical source deliberately; do not hand-edit generated pages to satisfy a gate.
101
102 Component-backed complete applications use runtime-specific source classifications, not invisible parser exclusions. A Pi, Vercel AI SDK, local-workbench, or eve/macOS application does not acquire a second runtime merely because its source browser is indexed. Shared SDK operations elsewhere on those pages still need counterparts.
103
104 ## Checks
105
106 Run from `docs/`:
107
108 | Command | What it establishes |
109 |---|---|
110 | `bun run inventory:code-examples` | Full recorded surface and explicit validation/exemption categories |
111 | `bun run check:code-examples` | Markdown/MDX AST boundaries, tab order/content/languages, local marker placement, known file-backed sources |
112 | `bun run check:api-snippets` | Supported curl syntax, operation selection, auth alternatives, API versions, and JSON Schema constraints against committed v3.1/v3 specs |
113 | `bun run check:python-snippets` | Syntax for maintained Python fences, SDK-attributed mypy diagnostics against the local Python SDK/providers, and `# type: ignore` policy |
114 | `bun run test:python-snippets` | Real Python helper regressions, including aliases, local classes, argument/TypedDict errors, SDK-model indexing, misspelled SDK bindings, suppressions, and fragment scope |
115 | `bun run check:typescript-snippets` | Actual TypeScript diagnostics for API overviews, authored reference, and Markdown FAQ/KB inputs outside build-time Twoslash |
116 | `bun run test` | Python-free static checker and rendering regressions |
117 | `GITHUB_ACTIONS=true bun run build` | Production rendering and build-covered Twoslash examples, using the CI worker limit |
118
119 The Python helper uses `uv run --frozen` with the locked `docs-snippets` dependency group and Python 3.12. Its conventional-fragment prelude supplies missing module-level SDK names without replacing imported aliases, local classes, or nested bindings. It retains unrelated Python/third-party diagnostics separately; the gate fails syntax and SDK-attributed errors, not every possible Python error. SDK-attributed errors include wrong calls, attributes, and imports; missing keys on SDK TypedDicts; indexing an SDK model such as `response["status"]` (use `response.status`); assigning an SDK result to an incompatible annotation; and an undefined name that mypy identifies as a misspelling of an SDK-valued binding. Undefined fragment context and unknown third-party or hypothetical packages stay separate. `(previous)` examples are syntax-only. This is a local-source compatibility check, not a check against a separately installed published Python release.
120
121 A `# type: ignore` must name its mypy error codes, such as `# type: ignore[arg-type]`, and be explained by a comment on the same line, inside the enclosing statement, or directly above it. The explanation must describe a verified SDK typing gap. Ignores that no longer suppress an error fail as unused.
122
123 TypeScript uses the SDK/provider versions installed from `docs/package.json` and `docs/bun.lock`, not the local TypeScript workspace source. See `twoslash.md` for build coverage and precise annotations. Python and TypeScript therefore have different version boundaries; review install instructions and release compatibility explicitly.
124
125 All static checks are offline with respect to Composio: no credentials, accounts, tool execution, or authenticated API requests are needed. They do not prove response schemas beyond the committed contract, jq correctness, live endpoint behavior, cross-language semantic equivalence, or justified exemption reasons. Review those against SDK implementation and schema evidence, and inspect the rendered options and agent Markdown.