Composio Integrations
GET /api/integrations/composio/callback
Section titled “GET /api/integrations/composio/callback”Composio Callback
Provider OAuth redirect target: verify, flip ACTIVE, bounce to the app.
Trusts only the signed state (binds connection_id ↔ org_id). The
connection id itself is read from the (org-scoped) row, never the query, so a
forged callback cannot activate another org’s connection. Always redirects to
the app — the authenticated status poll remains the source of truth.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| state | query | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | object |
| 422 | Validation Error | HTTPValidationError |
POST /api/orgs/{org_id}/integrations/composio/connect
Section titled “POST /api/orgs/{org_id}/integrations/composio/connect”Connect Toolkit
Initiate a Composio connection for a toolkit (any member — see #260).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| org_id | path | string (uuid) | yes |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
| credentials | object | no | |
| scope | string | no | |
| toolkit_slug | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | ConnectResponse |
| 422 | Validation Error | HTTPValidationError |
GET /api/orgs/{org_id}/integrations/composio/connect-fields
Section titled “GET /api/orgs/{org_id}/integrations/composio/connect-fields”Get Connect Fields
Return the credential fields required to connect a toolkit (any member — see #260).
For API-key / basic / bearer toolkits (requires_credentials=True) this
returns the list of fields the user must supply before calling /connect.
OAuth toolkits return an empty fields list with
requires_credentials=False — no form is needed, the redirect handles it.
Returns 404 when Composio has no enabled auth config for the toolkit, 502 for unexpected upstream failures.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| org_id | path | string (uuid) | yes | |
| toolkit_slug | query | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | ConnectSchemaResponse |
| 422 | Validation Error | HTTPValidationError |
GET /api/orgs/{org_id}/integrations/composio/connections
Section titled “GET /api/orgs/{org_id}/integrations/composio/connections”List Connections
List the org’s Composio connections and their lifecycle status.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| org_id | path | string (uuid) | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | agentdepot_api__routers__integrations_composio__ConnectionListResponse |
| 422 | Validation Error | HTTPValidationError |
DELETE /api/orgs/{org_id}/integrations/composio/connections/{integration_id}
Section titled “DELETE /api/orgs/{org_id}/integrations/composio/connections/{integration_id}”Disconnect Toolkit
Disconnect a toolkit: delete the Composio account and the row (any member — see #260).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| integration_id | path | string (uuid) | yes | |
| org_id | path | string (uuid) | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | |
| 422 | Validation Error | HTTPValidationError |
POST /api/orgs/{org_id}/integrations/composio/connections/{integration_id}/reinitiate
Section titled “POST /api/orgs/{org_id}/integrations/composio/connections/{integration_id}/reinitiate”Reinitiate Connection
Restart OAuth for a stuck PENDING/ERROR connection (any member — see #260).
The signed callback state expires after _STATE_MAX_AGE_SECONDS (30
minutes) and the original redirect_url isn’t persisted, so a user who
abandons the OAuth flow (or hits a connect error) has no way to resume —
this mints a fresh signed state and re-initiates the same toolkit/auth
config under the row’s original identity. 409 if the row isn’t PENDING or
ERROR (e.g. already ACTIVE).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| integration_id | path | string (uuid) | yes | |
| org_id | path | string (uuid) | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | ConnectResponse |
| 422 | Validation Error | HTTPValidationError |
GET /api/orgs/{org_id}/integrations/composio/connections/{integration_id}/status
Section titled “GET /api/orgs/{org_id}/integrations/composio/connections/{integration_id}/status”Get Connection Status
Poll Composio for a connection’s status and reconcile the row.
The authenticated source of truth the frontend polls after redirecting the user to OAuth — independent of whether the public callback fired.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| integration_id | path | string (uuid) | yes | |
| org_id | path | string (uuid) | yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | ConnectionStatusResponse |
| 422 | Validation Error | HTTPValidationError |
GET /api/orgs/{org_id}/integrations/composio/toolkits
Section titled “GET /api/orgs/{org_id}/integrations/composio/toolkits”List Toolkits
List only the toolkits the org’s Composio account has an auth config for.
Instead of returning the entire Composio catalog, this fetches the set of
auth configs the account has registered (e.g. outlook,
microsoft_teams), restricts the catalog to those slugs, and annotates
each with the org’s connection state. Any configured toolkit not found in
the catalog page is included as a minimal entry so nothing is silently
dropped.
The Composio catalog (list_auth_configs + list_toolkits) is cached
in-process (see services/composio_catalog.py) because it is
account-global and changes rarely. The search filter is applied in
Python against the cached unfiltered data so caching does not break
search. Per-org connection state is always fetched live from the DB.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| org_id | path | string (uuid) | yes | |
| search | query | string | no |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | ToolkitListResponse |
| 422 | Validation Error | HTTPValidationError |