mirror of
https://github.com/ComposioHQ/composio.git
synced 2026-09-22 11:46:35 +08:00
Rahul Tarak
d17a268d3f
Integration branch for the next docs release: a **sessions-first
documentation rewrite** — new and rewritten guides, example pages,
interactive components, and docs tooling — plus the supporting SDK
changes that the new docs describe.
The bulk of this PR is docs (~24k lines across ~150 commits); the SDK
changes (~5k lines) back the new guides.
## Documentation (the bulk)
- **Sessions-first restructure** — reorganized navigation and section
structure (incl. the "Sandbox (prev workbench)" section), with
v3-reorganization redirects so old URLs keep resolving.
- **Rewritten core guides** — quickstart, configuring sessions, triggers
(creating + subscribing to events), proxy-execute, toolkits
enable/disable, and common FAQ, rewritten in the house voice.
- **New example pages** — local-sandbox PR reviewer, daily standup bot,
and slack bot, with runnable build-ups.
- **New interactive components & diagrams** — triggers flow animation,
manage-connections visual, connection-refresh visual, and the
terminal-kit components.
- **Docs tooling** — a docs-graph link-graph connectivity checker,
search reprioritization (deprioritize legacy pages), and SDK-reference
regeneration.
## Supporting SDK changes
**`@composio/core` → 0.13.0 (minor)**
- `composio.sessions.create()` as the first-class sessions API
(`composio.create()` kept as an alias).
- **MCP is opt-in:** default `create()` / `use()` return native-tool
sessions (`SessionWithoutMcp`); pass `{ mcp: true }` to surface
`session.mcp`. _Migration: read `session.mcp` only after creating with
`{ mcp: true }`._
- `session.sandbox` is the canonical resolved config;
`session.workbench` kept as a deprecated alias. `sandbox` is the
preferred session-config key (`workbench` still accepted).
- `connectedAccounts.updateAcl()` graduated from experimental (alias
kept).
- `triggers.parse()` (parse + optionally verify an incoming webhook) and
`triggers.setWebhookSubscription()`.
**`@composio/experimental` → minor** — local-workbench helpers moved
onto the `@composio/experimental/workbench` subpath (out of
`@composio/core/experimental`), keeping the ~14 KB embedded Python
helper out of core. Plus the experimental Pi provider.
**`@composio/slim` → minor.**
**Python → 0.17.0** — mirrors the TS surface: `composio.sessions` mount
(`tool_router` deprecated), `triggers.parse()` /
`set_webhook_subscription()`, the `sandbox` config key, and
`connected_accounts.update_acl()`.
## Review response (#3664)
Addressed the `@composio/core` review:
- **Security:** `triggers.parse()` no longer fails open — a
present-but-empty `verifySecret` (e.g. unset `COMPOSIO_WEBHOOK_SECRET`)
now throws instead of silently skipping verification; omitting it stays
an explicit opt-out (both SDKs).
- Removed snake_case leakage from `transformWebhookSubscription` (+ the
index signature that allowed it).
- **Removed** the TS-only `connectedAccounts.link()` toolkit
auto-resolve (shipped with cancellability / orphaned-auth-config bugs
and was effectively undocumented; to be reintroduced properly later).
- Unified Python error types on `ValidationError`; added `mcp=True`
Python tests; fixed runtime-portability + error-type test assertions.
- Polished deprecation messages; fixed the backwards `/experimental`
`@deprecated` note and the `SessionWithMcp` JSDoc.
## Testing
- **TS:** `@composio/core` + `@composio/experimental` typecheck pass;
vitest green for the touched suites.
- **Python:** `test_tool_router.py` + `test_triggers.py` pass (161
tests).
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Kshitij Jhunjhunwala <kj@composio.dev>
Co-authored-by: Malay Vasa <malayvasa@gmail.com>
Co-authored-by: Sarah Simionescu <sarah@composio.dev>
Co-authored-by: Kshitij Jhunjhunwala <113939507+KJ-11@users.noreply.github.com>
32 lines
3.1 KiB
Plaintext
32 lines
3.1 KiB
Plaintext
---
|
|
title: Triggers
|
|
description: "Trigger management and execution"
|
|
---
|
|
|
|
{/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/triggers.mdx, not this file. */}
|
|
|
|
Triggers let you subscribe to events from a user's connected app, such as a new Gmail message, a GitHub commit, or a Slack message, and receive the event data as a structured payload at your webhook endpoint.
|
|
|
|
There are two layers to understand:
|
|
|
|
- A **trigger type** is a template that defines what event to listen for and what configuration it needs. For example, `GITHUB_COMMIT_EVENT` requires an `owner` and a `repo`. Each toolkit exposes its own trigger types.
|
|
- A **trigger instance** is a trigger type scoped to a specific user and connected account. Creating one produces an instance with its own `ti_*` ID that you can enable, disable, or delete independently.
|
|
|
|
Reach for these endpoints when you want to:
|
|
|
|
- Discover the trigger types a toolkit offers, or fetch one type by `slug` to inspect its config and payload schema.
|
|
- Create or update a trigger instance for a connected account with the upsert endpoint.
|
|
- List active trigger instances, or enable, disable, and delete an instance by `triggerId`.
|
|
|
|
These endpoints authenticate with your project API key in the `x-api-key` header.
|
|
|
|
<Callout type="info">
|
|
Creating a trigger instance only registers it. To actually receive events, set a webhook URL for your project once, then route incoming events on `metadata.trigger_slug`. See [Subscribing to events](/docs/setting-up-triggers/subscribing-to-events).
|
|
</Callout>
|
|
|
|
For the full concept overview, see [Triggers](/docs/triggers).
|
|
|
|
## Endpoints
|
|
|
|
<ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/trigger_instances/{slug}/upsert","pathV3":"/api/v3/trigger_instances/{slug}/upsert","summary":"Create or update a trigger","href":"/reference/api-reference/triggers/postTriggerInstancesBySlugUpsert"},{"method":"GET","pathV31":"/api/v3.1/trigger_instances/active","pathV3":"/api/v3/trigger_instances/active","summary":"List active triggers","href":"/reference/api-reference/triggers/getTriggerInstancesActive"},{"method":"DELETE","pathV31":"/api/v3.1/trigger_instances/manage/{triggerId}","pathV3":"/api/v3/trigger_instances/manage/{triggerId}","summary":"Delete a trigger","href":"/reference/api-reference/triggers/deleteTriggerInstancesManageByTriggerId"},{"method":"PATCH","pathV31":"/api/v3.1/trigger_instances/manage/{triggerId}","pathV3":"/api/v3/trigger_instances/manage/{triggerId}","summary":"Enable or disable a trigger","href":"/reference/api-reference/triggers/patchTriggerInstancesManageByTriggerId"},{"method":"GET","pathV31":"/api/v3.1/triggers_types/list/enum","pathV3":"/api/v3/triggers_types/list/enum","summary":"List trigger type enums","href":"/reference/api-reference/triggers/getTriggersTypesListEnum"},{"method":"GET","pathV31":"/api/v3.1/triggers_types/{slug}","pathV3":"/api/v3/triggers_types/{slug}","summary":"Get trigger type by slug","href":"/reference/api-reference/triggers/getTriggersTypesBySlug"},{"method":"GET","pathV31":"/api/v3.1/triggers_types","pathV3":"/api/v3/triggers_types","summary":"List trigger types","href":"/reference/api-reference/triggers/getTriggersTypes"}]} />
|