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, 00:45 UTC
docs: add v3.1 tool endpoints to API reference
- Re-fetch OpenAPI spec which now includes v3.1 tool endpoints (hermes#8990) - Update fetch-openapi.mjs to remove older API versions when a newer one exists for the same endpoint path (e.g. v3 hidden when v3.1 available) - Update generate-api-index.ts with the same version deduplication logic - Regenerate API reference index pages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sushmithamallesh committed
Apr 1, 2026 at 15:03 UTC
b8adad5c56e05e9facd6f15796b100259195e7ea
4 files changed
+3955
-3736
docs/content/reference/api-reference/tools/index.mdx
+4
-3
@@ -13,7 +13,8 @@ Tool execution endpoints
13
|----------|------------|
14
| `GET /api/v3/tools` | [List available tools](/reference/api-reference/tools/getTools) |
15
| `GET /api/v3/tools/enum` | [Get tool enum list](/reference/api-reference/tools/getToolsEnum) |
16
-| `GET /api/v3/tools/{tool_slug}` | [Get tool by slug](/reference/api-reference/tools/getToolsByToolSlug) |
17
-| `POST /api/v3/tools/execute/{tool_slug}` | [Execute tool](/reference/api-reference/tools/postToolsExecuteByToolSlug) |
18
-| `POST /api/v3/tools/execute/{tool_slug}/input` | [Generate tool inputs from natural language](/reference/api-reference/tools/postToolsExecuteByToolSlugInput) |
16
| `POST /api/v3/tools/execute/proxy` | [Execute proxy request](/reference/api-reference/tools/postToolsExecuteProxy) |
17
+| `GET /api/v3.1/tools/{tool_slug}` | [Get tool by slug](/reference/api-reference/tools/getV3_1ToolsByToolSlug) |
18
+| `POST /api/v3.1/tools/execute/{tool_slug}` | [Execute tool](/reference/api-reference/tools/postV3_1ToolsExecuteByToolSlug) |
19
+| `POST /api/v3.1/tools/execute/{tool_slug}/input` | [Generate tool inputs from natural language](/reference/api-reference/tools/postV3_1ToolsExecuteByToolSlugInput) |
20
+| `POST /api/v3.1/tools/scopes/required` | [Get required scopes for tools](/reference/api-reference/tools/postV3_1ToolsScopesRequired) |
docs/public/openapi.json
+3903
-3733
@@ -7937,133 +7937,6 @@
7937
}
7938
}
7939
},
7940
- "/api/v3/tools/{tool_slug}": {
7941
- "get": {
7942
- "summary": "Get tool by slug",
7943
- "description": "Retrieve detailed information about a specific tool using its slug identifier. This endpoint returns full metadata about a tool including input/output parameters, versions, and toolkit information.",
7944
- "tags": [
7945
- "Tools"
7946
- ],
7947
- "operationId": "getToolsByToolSlug",
7948
- "security": [
7949
- {
7950
- "ApiKeyAuth": []
7951
- },
7952
- {
7953
- "UserApiKeyAuth": []
7954
- }
7955
- ],
7956
- "parameters": [
7957
- {
7958
- "schema": {
7959
- "type": "string"
7960
- },
7961
- "required": true,
7962
- "description": "The unique slug identifier of the tool",
7963
- "name": "tool_slug",
7964
- "in": "path"
7965
- },
7966
- {
7967
- "schema": {
7968
- "type": "string"
7969
- },
7970
- "required": false,
7971
- "description": "Optional version of the tool to retrieve",
7972
- "name": "version",
7973
- "in": "query"
7974
- },
7975
- {
7976
- "schema": {
7977
- "oneOf": [
7978
- {
7979
- "type": "null"
7980
- },
7981
- {
7982
- "type": "string"
7983
- },
7984
- {
7985
- "type": "object",
7986
- "additionalProperties": {
7987
- "type": "string"
7988
- },
7989
- "description": "Object representation of parsed bracket notation"
7990
- }
7991
- ]
7992
- },
7993
- "required": false,
7994
- "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",
7995
- "in": "query",
7996
- "name": "toolkit_versions",
7997
- "examples": {
7998
- "latest_version": {
7999
- "summary": "Latest version for all toolkits",
8000
- "value": "latest"
8001
- },
8002
- "bracket_notation": {
8003
- "summary": "Specific versions using bracket notation",
8004
- "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"
8005
- },
8006
- "null_value": {
8007
- "summary": "No version specified (uses 00000000_00)",
8008
- "value": null
8009
- }
8010
- }
8011
- }
8012
- ],
8013
- "responses": {
8014
- "200": {
8015
- "description": "Successfully retrieved tool details",
8016
- "content": {
8017
- "application/json": {
8018
- "schema": {
8019
- "$ref": "#/components/schemas/Tool"
8020
- }
8021
- }
8022
- }
8023
- },
8024
- "400": {
8025
- "description": "Bad request - Invalid tool slug format",
8026
- "content": {
8027
- "application/json": {
8028
- "schema": {
8029
- "$ref": "#/components/schemas/Error"
8030
- }
8031
- }
8032
- }
8033
- },
8034
- "401": {
8035
- "description": "Unauthorized - Authentication credentials are missing or invalid",
8036
- "content": {
8037
- "application/json": {
8038
- "schema": {
8039
- "$ref": "#/components/schemas/Error"
8040
- }
8041
- }
8042
- }
8043
- },
8044
- "404": {
8045
- "description": "Not found - Tool with the specified slug does not exist",
8046
- "content": {
8047
- "application/json": {
8048
- "schema": {
8049
- "$ref": "#/components/schemas/Error"
8050
- }
8051
- }
8052
- }
8053
- },
8054
- "500": {
8055
- "description": "Internal server error - Something went wrong on the server",
8056
- "content": {
8057
- "application/json": {
8058
- "schema": {
8059
- "$ref": "#/components/schemas/Error"
8060
- }
8061
- }
8062
- }
8063
- }
8064
- }
8065
- }
8066
- },
7940
"/api/v3/toolkits/multi": {
7941
"post": {
7942
"summary": "Fetch multiple toolkits",
@@ -8365,14 +8238,14 @@
8238
}
8239
}
8240
},
8368
- "/api/v3/tools/execute/{tool_slug}": {
8241
+ "/api/v3/tools/execute/proxy": {
8242
"post": {
8370
- "summary": "Execute tool",
8371
- "description": "Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.",
8243
+ "summary": "Execute proxy request",
8244
+ "description": "Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.",
8245
"tags": [
8246
"Tools"
8247
],
8375
- "operationId": "postToolsExecuteByToolSlug",
8248
+ "operationId": "postToolsExecuteProxy",
8249
"security": [
8250
{
8251
"ApiKeyAuth": []
@@ -8381,27 +8254,6 @@
8254
"UserApiKeyAuth": []
8255
}
8256
],
8384
- "parameters": [
8385
- {
8386
- "schema": {
8387
- "type": "string"
8388
- },
8389
- "required": true,
8390
- "description": "The tool slug to execute",
8391
- "name": "tool_slug",
8392
- "in": "path"
8393
- },
8394
- {
8395
- "schema": {
8396
- "type": "string",
8397
- "description": "JSON object containing custom headers to pass to LLM providers (OpenAI, Bedrock, etc.)",
8398
- "example": "{\"x-custom-header\": \"value\", \"authorization\": \"Bearer token\"}"
8399
- },
8400
- "required": false,
8401
- "name": "x-llm-gateway-headers",
8402
- "in": "header"
8403
- }
8404
- ],
8257
"requestBody": {
8258
"content": {
8259
"application/json": {
@@ -8410,95 +8262,123 @@
8262
"properties": {
8263
"connected_account_id": {
8264
"type": "string",
8413
- "description": "Unique identifier for the connected account to use for authentication",
8265
+ "format": "connectedAccountId",
8266
+ "description": "The ID of the connected account to use for authentication (if not provided, will use the default account for the project)",
8267
"example": "ca_1a2b3c4d5e6f"
8268
},
8416
- "entity_id": {
8269
+ "endpoint": {
8270
"type": "string",
8418
- "description": "Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations)",
8419
- "example": "repo-123",
8420
- "deprecated": true
8271
+ "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",
8272
+ "example": "/api/v1/resources"
8273
},
8422
- "user_id": {
8274
+ "method": {
8275
"type": "string",
8424
- "description": "User id for multi-user connected accounts (e.g. multiple users, organizations)",
8425
- "example": "user-123"
8276
+ "enum": [
8277
+ "GET",
8278
+ "POST",
8279
+ "PUT",
8280
+ "DELETE",
8281
+ "PATCH",
8282
+ "HEAD"
8283
+ ],
8284
+ "description": "The HTTP method to use for the request",
8285
+ "example": "GET"
8286
},
8427
- "version": {
8428
- "type": "string",
8429
- "description": "Tool version to execute (defaults to \"00000000_00\" if not specified)",
8430
- "example": "latest"
8287
+ "body": {
8288
+ "nullable": true,
8289
+ "description": "The request body (for POST, PUT, and PATCH requests)",
8290
+ "example": {
8291
+ "name": "New Resource",
8292
+ "description": "This is a new resource"
8293
+ },
8294
+ "type": "object"
8295
},
8432
- "custom_auth_params": {
8433
- "type": "object",
8434
- "properties": {
8435
- "base_url": {
8436
- "type": "string",
8437
- "description": "The base URL (root address) what you should use while making http requests to the connected account. For example, for gmail, it would be 'https://gmail.googleapis.com'"
8438
- },
8439
- "parameters": {
8440
- "type": "array",
8441
- "items": {
8442
- "type": "object",
8443
- "properties": {
8444
- "name": {
8445
- "type": "string",
8446
- "description": "The name of the parameter. For example, 'x-api-key', 'Content-Type', etc."
8447
- },
8448
- "in": {
8449
- "type": "string",
8450
- "enum": [
8451
- "query",
8452
- "header"
8453
- ],
8454
- "description": "The location of the parameter. Can be 'query' or 'header'."
8455
- },
8456
- "value": {
8457
- "anyOf": [
8458
- {
8459
- "type": "string"
8460
- },
8461
- {
8462
- "type": "number"
8463
- }
8464
- ],
8465
- "description": "The value of the parameter. For example, '1234567890', 'application/json', etc."
8466
- }
8296
+ "binary_body": {
8297
+ "anyOf": [
8298
+ {
8299
+ "type": "object",
8300
+ "properties": {
8301
+ "url": {
8302
+ "type": "string",
8303
+ "format": "uri",
8304
+ "description": "URL to fetch binary content from"
8305
},
8468
- "required": [
8469
- "name",
8470
- "in",
8471
- "value"
8472
- ]
8473
- }
8306
+ "content_type": {
8307
+ "type": "string",
8308
+ "description": "Content-Type header to use for the request"
8309
+ }
8310
+ },
8311
+ "required": [
8312
+ "url"
8313
+ ]
8314
},
8475
- "body": {
8315
+ {
8316
"type": "object",
8477
- "additionalProperties": {},
8478
- "description": "The body to be sent to the endpoint for authentication. This is a JSON object. Note: This is very rarely needed and is only required by very few apps."
8479
- }
8480
- },
8481
- "description": "Custom authentication parameters for tools that support parameterized authentication",
8482
- "example": {
8483
- "base_url": "https://api.example.com",
8484
- "parameters": [
8485
- {
8486
- "name": "x-api-key",
8487
- "value": "secret-key",
8488
- "in": "header"
8317
+ "properties": {
8318
+ "base64": {
8319
+ "type": "string",
8320
+ "minLength": 1,
8321
+ "description": "Base64-encoded binary data"
8322
+ },
8323
+ "content_type": {
8324
+ "type": "string",
8325
+ "description": "Content-Type header to use for the request"
8326
+ }
8327
+ },
8328
+ "required": [
8329
+ "base64"
8330
+ ]
8331
+ }
8332
+ ],
8333
+ "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."
8334
+ },
8335
+ "parameters": {
8336
+ "type": "array",
8337
+ "items": {
8338
+ "type": "object",
8339
+ "properties": {
8340
+ "name": {
8341
+ "type": "string",
8342
+ "description": "Parameter name",
8343
+ "example": "x-api-key"
8344
+ },
8345
+ "value": {
8346
+ "type": "string",
8347
+ "description": "Parameter value",
8348
+ "example": "abc123def456"
8349
+ },
8350
+ "type": {
8351
+ "type": "string",
8352
+ "enum": [
8353
+ "header",
8354
+ "query"
8355
+ ],
8356
+ "description": "Parameter type (header or query)",
8357
+ "example": "header"
8358
}
8359
+ },
8360
+ "required": [
8361
+ "name",
8362
+ "value",
8363
+ "type"
8364
]
8491
- }
8365
+ },
8366
+ "description": "Additional HTTP headers or query parameters to include in the request",
8367
+ "example": [
8368
+ {
8369
+ "name": "x-api-key",
8370
+ "value": "abc123def456",
8371
+ "type": "header"
8372
+ },
8373
+ {
8374
+ "name": "filter",
8375
+ "value": "active",
8376
+ "type": "query"
8377
+ }
8378
+ ]
8379
},
8380
"custom_connection_data": {
8494
- "description": "Custom connection data for tools that support custom connection data",
8495
- "example": {
8496
- "authScheme": "OAUTH2",
8497
- "toolkitSlug": "github",
8498
- "val": {
8499
- "access_token": "secret-token"
8500
- }
8501
- },
8381
+ "deprecated": true,
8382
"type": "object",
8383
"properties": {
8384
"authScheme": {
@@ -8738,92 +8618,88 @@
8618
"val"
8619
],
8620
"additionalProperties": true
8741
- },
8742
- "arguments": {
8743
- "type": "object",
8744
- "additionalProperties": {},
8745
- "description": "Key-value pairs of arguments required by the tool (mutually exclusive with text)",
8746
- "example": {
8747
- "repository": "octocat/Hello-World",
8748
- "workflow_id": "main.yml",
8749
- "ref": "main",
8750
- "inputs": {
8751
- "environment": "production"
8752
- }
8753
- }
8754
- },
8755
- "text": {
8756
- "type": "string",
8757
- "description": "Natural language description of the task to perform (mutually exclusive with arguments)",
8758
- "example": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment"
8759
- },
8760
- "allow_tracing": {
8761
- "type": "boolean",
8762
- "nullable": true,
8763
- "description": "Deprecated. Enable debug tracing for tool execution (useful for debugging)",
8764
- "deprecated": true,
8765
- "example": false
8621
}
8767
- }
8622
+ },
8623
+ "required": [
8624
+ "endpoint",
8625
+ "method"
8626
+ ]
8627
}
8628
}
8629
}
8630
},
8631
"responses": {
8632
"200": {
8774
- "description": "Successfully executed action and received response",
8633
+ "description": "Successfully executed proxy request and received response",
8634
"content": {
8635
"application/json": {
8636
"schema": {
8637
"type": "object",
8638
"properties": {
8639
"data": {
8781
- "type": "object",
8782
- "additionalProperties": {},
8783
- "description": "Tool execution output data that varies based on the specific tool",
8784
- "example": {
8785
- "run_id": 12345678,
8786
- "status": "queued",
8787
- "created_at": "2023-01-01T12:00:00Z",
8788
- "html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"
8789
- }
8790
- },
8791
- "error": {
8792
- "type": "string",
8793
- "nullable": true,
8794
- "description": "Error message if the tool execution was not successful (null if successful)"
8795
- },
8796
- "successful": {
8797
- "type": "boolean",
8798
- "description": "Indicates if the tool execution was successful",
8799
- "example": true
8800
- },
8801
- "session_info": {
8640
"nullable": true,
8803
- "description": "Optional session information for tools that return session context",
8641
+ "description": "The response data returned from the proxied API",
8642
"example": {
8805
- "session_id": "session-12345",
8806
- "expires_at": "2023-01-01T13:00:00Z"
8643
+ "id": "123",
8644
+ "name": "Resource Name",
8645
+ "created_at": "2023-01-01T00:00:00Z"
8646
},
8647
"type": "object"
8648
},
8810
- "log_id": {
8811
- "type": "string",
8812
- "description": "Unique identifier for the execution log (useful for debugging and support)",
8813
- "example": "log_abc123def456"
8649
+ "binary_data": {
8650
+ "type": "object",
8651
+ "properties": {
8652
+ "url": {
8653
+ "type": "string",
8654
+ "description": "URL to download binary content"
8655
+ },
8656
+ "content_type": {
8657
+ "type": "string",
8658
+ "description": "Content-Type of the binary data"
8659
+ },
8660
+ "size": {
8661
+ "type": "number",
8662
+ "description": "File size in bytes"
8663
+ },
8664
+ "expires_at": {
8665
+ "type": "string",
8666
+ "description": "ISO 8601 timestamp when the URL expires"
8667
+ }
8668
+ },
8669
+ "required": [
8670
+ "url",
8671
+ "content_type",
8672
+ "size"
8673
+ ],
8674
+ "description": "Binary body response data. Present when the response is a binary file."
8675
+ },
8676
+ "status": {
8677
+ "type": "number",
8678
+ "description": "The HTTP status code returned from the proxied API",
8679
+ "example": 200
8680
+ },
8681
+ "headers": {
8682
+ "type": "object",
8683
+ "additionalProperties": {
8684
+ "type": "string"
8685
+ },
8686
+ "description": "The HTTP headers returned from the proxied API",
8687
+ "example": {
8688
+ "content-type": "application/json",
8689
+ "cache-control": "no-cache",
8690
+ "host": "api.example.com"
8691
+ }
8692
}
8693
},
8694
"required": [
8817
- "data",
8818
- "error",
8819
- "successful"
8695
+ "status"
8696
]
8697
}
8698
}
8699
}
8700
},
8701
"400": {
8826
- "description": "Bad request - Invalid request parameters, missing required arguments, or conflicting parameters",
8702
+ "description": "Bad request - Invalid request parameters or body format",
8703
"content": {
8704
"application/json": {
8705
"schema": {
@@ -8843,7 +8719,7 @@
8719
}
8720
},
8721
"403": {
8846
- "description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource",
8722
+ "description": "Forbidden - Connected account does not have permission to access the requested resource",
8723
"content": {
8724
"application/json": {
8725
"schema": {
@@ -8853,37 +8729,7 @@
8729
}
8730
},
8731
"404": {
8856
- "description": "Not found - Tool or connected account not found",
8857
- "content": {
8858
- "application/json": {
8859
- "schema": {
8860
- "$ref": "#/components/schemas/Error"
8861
- }
8862
- }
8863
- }
8864
- },
8865
- "408": {
8866
- "description": "Request timeout - Tool execution exceeded the maximum allowed time",
8867
- "content": {
8868
- "application/json": {
8869
- "schema": {
8870
- "$ref": "#/components/schemas/Error"
8871
- }
8872
- }
8873
- }
8874
- },
8875
- "410": {
8876
- "description": "Gone - Tool has been deprecated and is no longer available",
8877
- "content": {
8878
- "application/json": {
8879
- "schema": {
8880
- "$ref": "#/components/schemas/Error"
8881
- }
8882
- }
8883
- }
8884
- },
8885
- "413": {
8886
- "description": "Payload too large - Request or response payload exceeds size limits",
8732
+ "description": "Not found - Resource not found or connected account not found",
8733
"content": {
8734
"application/json": {
8735
"schema": {
@@ -8903,7 +8749,7 @@
8749
}
8750
},
8751
"429": {
8906
- "description": "Rate limit exceeded - Too many requests to the tool or underlying API",
8752
+ "description": "Too many requests - Rate limit exceeded on the connected account or proxy service",
8753
"content": {
8754
"application/json": {
8755
"schema": {
@@ -8923,7 +8769,7 @@
8769
}
8770
},
8771
"501": {
8926
- "description": "Not implemented",
8772
+ "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",
8773
"content": {
8774
"application/json": {
8775
"schema": {
@@ -8933,7 +8779,7 @@
8779
}
8780
},
8781
"502": {
8936
- "description": "Bad gateway - Error communicating with the tool provider API",
8782
+ "description": "Bad gateway - Error communicating with the upstream API",
8783
"content": {
8784
"application/json": {
8785
"schema": {
@@ -8942,8 +8788,8 @@
8788
}
8789
}
8790
},
8945
- "503": {
8946
- "description": "Upstream service unavailable - Tool provider API is currently down or unavailable",
8791
+ "504": {
8792
+ "description": "Gateway timeout - Upstream API timed out",
8793
"content": {
8794
"application/json": {
8795
"schema": {
@@ -8955,14 +8801,14 @@
8801
}
8802
}
8803
},
8958
- "/api/v3/tools/execute/{tool_slug}/input": {
8804
+ "/api/v3/trigger_instances/{slug}/upsert": {
8805
"post": {
8960
- "summary": "Generate tool inputs from natural language",
8961
- "description": "Uses AI to translate a natural language description into structured arguments for a specific tool. This endpoint is useful when you want to let users describe what they want to do in plain language instead of providing structured parameters.",
8806
+ "summary": "Create or update a trigger",
8807
+ "description": "Creates a new trigger instance or updates an existing one with the same configuration. Triggers listen for events from external services (webhooks or polling) and can invoke your workflows. If a matching trigger already exists and is disabled, it will be re-enabled. Requires a connected account ID to associate the trigger with a specific user connection.",
8808
"tags": [
8963
- "Tools"
8809
+ "Triggers"
8810
],
8965
- "operationId": "postToolsExecuteByToolSlugInput",
8811
+ "operationId": "postTriggerInstancesBySlugUpsert",
8812
"security": [
8813
{
8814
"ApiKeyAuth": []
@@ -8974,11 +8820,12 @@
8820
"parameters": [
8821
{
8822
"schema": {
8977
- "type": "string"
8823
+ "type": "string",
8824
+ "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase)."
8825
},
8826
"required": true,
8980
- "description": "The tool slug to generate inputs for",
8981
- "name": "tool_slug",
8827
+ "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).",
8828
+ "name": "slug",
8829
"in": "path"
8830
}
8831
],
@@ -8988,67 +8835,136 @@
8835
"schema": {
8836
"type": "object",
8837
"properties": {
8991
- "text": {
8838
+ "connectedAuthId": {
8839
"type": "string",
8993
- "description": "Natural language description of what you want to accomplish with this tool",
8994
- "example": "I need to trigger the main workflow in the octocat/Hello-World repository to deploy to production"
8840
+ "format": "connectedAccountId",
8841
+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.",
8842
+ "deprecated": true
8843
},
8996
- "custom_description": {
8997
- "type": "string",
8998
- "description": "Custom description of the tool to help guide the LLM in generating more accurate inputs",
8999
- "example": "This tool triggers GitHub Actions workflows in a repository. It requires the repository name, workflow ID, and optional input parameters."
8844
+ "triggerConfig": {
8845
+ "type": "object",
8846
+ "additionalProperties": {},
8847
+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.",
8848
+ "deprecated": true
8849
},
9001
- "system_prompt": {
8850
+ "connected_account_id": {
8851
"type": "string",
9003
- "description": "System prompt to control and guide the behavior of the LLM when generating inputs",
9004
- "example": "You are an expert assistant that generates precise GitHub Actions workflow parameters. Extract exact repository names, workflow IDs, and input values from user descriptions."
8852
+ "format": "connectedAccountId",
8853
+ "description": "Connected account nanoid"
8854
+ },
8855
+ "trigger_config": {
8856
+ "type": "object",
8857
+ "additionalProperties": {},
8858
+ "description": "Trigger configuration"
8859
},
8860
"version": {
8861
"type": "string",
9008
- "description": "Tool version to use when generating inputs (defaults to \"latest\" if not specified)",
8862
+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.",
8863
+ "deprecated": true,
8864
+ "example": "latest"
8865
+ },
8866
+ "toolkit_versions": {
8867
+ "anyOf": [
8868
+ {
8869
+ "type": "string"
8870
+ },
8871
+ {
8872
+ "type": "object",
8873
+ "additionalProperties": {
8874
+ "type": "string"
8875
+ }
8876
+ },
8877
+ {
8878
+ "nullable": true,
8879
+ "type": "object"
8880
+ }
8881
+ ],
8882
+ "description": "Toolkit version specification. Supports \"latest\" string or a record mapping toolkit slugs to specific versions.",
8883
"example": "latest"
8884
}
9011
- },
9012
- "required": [
9013
- "text"
9014
- ]
8885
+ }
8886
}
8887
}
8888
}
8889
},
8890
"responses": {
8891
"200": {
9021
- "description": "Successfully generated structured inputs for the action based on natural language description",
8892
+ "description": "Successfully upserted trigger instance",
8893
"content": {
8894
"application/json": {
8895
"schema": {
8896
"type": "object",
8897
"properties": {
9027
- "arguments": {
8898
+ "trigger_id": {
8899
+ "type": "string",
8900
+ "description": "ID of the updated trigger"
8901
+ },
8902
+ "deprecated": {
8903
"type": "object",
9029
- "additionalProperties": {},
9030
- "description": "Key-value pairs of arguments required by the tool to accomplish the described task",
9031
- "example": {
9032
- "repository": "octocat/Hello-World",
9033
- "workflow_id": "main.yml",
9034
- "ref": "main",
9035
- "inputs": {
9036
- "environment": "production"
8904
+ "properties": {
8905
+ "uuid": {
8906
+ "type": "string",
8907
+ "description": "ID of the updated trigger"
8908
}
9038
- }
9039
- },
9040
- "error": {
8909
+ },
8910
+ "required": [
8911
+ "uuid"
8912
+ ]
8913
+ }
8914
+ },
8915
+ "required": [
8916
+ "trigger_id",
8917
+ "deprecated"
8918
+ ]
8919
+ }
8920
+ }
8921
+ }
8922
+ },
8923
+ "201": {
8924
+ "description": "Successfully created trigger instance",
8925
+ "content": {
8926
+ "application/json": {
8927
+ "schema": {
8928
+ "type": "object",
8929
+ "properties": {
8930
+ "trigger_id": {
8931
"type": "string",
9042
- "description": "Error message if the arguments could not be generated (null if successful)",
9043
- "example": "Unable to determine the repository name from the provided description"
8932
+ "description": "ID of the updated trigger"
8933
+ },
8934
+ "deprecated": {
8935
+ "type": "object",
8936
+ "properties": {
8937
+ "uuid": {
8938
+ "type": "string",
8939
+ "description": "ID of the updated trigger"
8940
+ }
8941
+ },
8942
+ "required": [
8943
+ "uuid"
8944
+ ]
8945
}
9045
- }
8946
+ },
8947
+ "required": [
8948
+ "trigger_id",
8949
+ "deprecated"
8950
+ ]
8951
+ }
8952
+ }
8953
+ }
8954
+ },
8955
+ "204": {
8956
+ "description": "No content",
8957
+ "content": {
8958
+ "application/json": {
8959
+ "schema": {
8960
+ "type": "object",
8961
+ "properties": {}
8962
}
8963
}
8964
}
8965
},
8966
"400": {
9051
- "description": "Bad request - Invalid input parameters or insufficient description to generate tool arguments",
8967
+ "description": "Bad request",
8968
"content": {
8969
"application/json": {
8970
"schema": {
@@ -9058,7 +8974,7 @@
8974
}
8975
},
8976
"401": {
9061
- "description": "Unauthorized - Authentication credentials are missing or invalid",
8977
+ "description": "Unauthorized",
8978
"content": {
8979
"application/json": {
8980
"schema": {
@@ -9068,7 +8984,7 @@
8984
}
8985
},
8986
"404": {
9071
- "description": "Not found - The specified tool does not exist",
8987
+ "description": "Trigger instance not found",
8988
"content": {
8989
"application/json": {
8990
"schema": {
@@ -9077,8 +8993,8 @@
8993
}
8994
}
8995
},
9080
- "422": {
9081
- "description": "Unprocessable entity - Invalid state of the connected account",
8996
+ "408": {
8997
+ "description": "Request timeout",
8998
"content": {
8999
"application/json": {
9000
"schema": {
@@ -9087,8 +9003,18 @@
9003
}
9004
}
9005
},
9090
- "429": {
9091
- "description": "Too many requests - Rate limit exceeded for natural language processing",
9006
+ "410": {
9007
+ "description": "Gone",
9008
+ "content": {
9009
+ "application/json": {
9010
+ "schema": {
9011
+ "$ref": "#/components/schemas/Error"
9012
+ }
9013
+ }
9014
+ }
9015
+ },
9016
+ "422": {
9017
+ "description": "Unprocessable entity",
9018
"content": {
9019
"application/json": {
9020
"schema": {
@@ -9098,7 +9024,17 @@
9024
}
9025
},
9026
"500": {
9101
- "description": "Internal server error - AI processing failed or other server error occurred",
9027
+ "description": "Internal server error",
9028
+ "content": {
9029
+ "application/json": {
9030
+ "schema": {
9031
+ "$ref": "#/components/schemas/Error"
9032
+ }
9033
+ }
9034
+ }
9035
+ },
9036
+ "501": {
9037
+ "description": "Not implemented",
9038
"content": {
9039
"application/json": {
9040
"schema": {
@@ -9110,822 +9046,14 @@
9046
}
9047
}
9048
},
9113
- "/api/v3/tools/execute/proxy": {
9114
- "post": {
9115
- "summary": "Execute proxy request",
9116
- "description": "Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.",
9049
+ "/api/v3/trigger_instances/active": {
9050
+ "get": {
9051
+ "summary": "List active triggers",
9052
+ "description": "Retrieves all active trigger instances for your project. Triggers listen for events from connected accounts (e.g., new emails, Slack messages, GitHub commits) and can invoke webhooks or workflows. Use filters to find triggers for specific users, connected accounts, or trigger types.",
9053
"tags": [
9118
- "Tools"
9054
+ "Triggers"
9055
],
9120
- "operationId": "postToolsExecuteProxy",
9121
- "security": [
9122
- {
9123
- "ApiKeyAuth": []
9124
- },
9125
- {
9126
- "UserApiKeyAuth": []
9127
- }
9128
- ],
9129
- "requestBody": {
9130
- "content": {
9131
- "application/json": {
9132
- "schema": {
9133
- "type": "object",
9134
- "properties": {
9135
- "connected_account_id": {
9136
- "type": "string",
9137
- "format": "connectedAccountId",
9138
- "description": "The ID of the connected account to use for authentication (if not provided, will use the default account for the project)",
9139
- "example": "ca_1a2b3c4d5e6f"
9140
- },
9141
- "endpoint": {
9142
- "type": "string",
9143
- "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",
9144
- "example": "/api/v1/resources"
9145
- },
9146
- "method": {
9147
- "type": "string",
9148
- "enum": [
9149
- "GET",
9150
- "POST",
9151
- "PUT",
9152
- "DELETE",
9153
- "PATCH",
9154
- "HEAD"
9155
- ],
9156
- "description": "The HTTP method to use for the request",
9157
- "example": "GET"
9158
- },
9159
- "body": {
9160
- "nullable": true,
9161
- "description": "The request body (for POST, PUT, and PATCH requests)",
9162
- "example": {
9163
- "name": "New Resource",
9164
- "description": "This is a new resource"
9165
- },
9166
- "type": "object"
9167
- },
9168
- "binary_body": {
9169
- "anyOf": [
9170
- {
9171
- "type": "object",
9172
- "properties": {
9173
- "url": {
9174
- "type": "string",
9175
- "format": "uri",
9176
- "description": "URL to fetch binary content from"
9177
- },
9178
- "content_type": {
9179
- "type": "string",
9180
- "description": "Content-Type header to use for the request"
9181
- }
9182
- },
9183
- "required": [
9184
- "url"
9185
- ]
9186
- },
9187
- {
9188
- "type": "object",
9189
- "properties": {
9190
- "base64": {
9191
- "type": "string",
9192
- "minLength": 1,
9193
- "description": "Base64-encoded binary data"
9194
- },
9195
- "content_type": {
9196
- "type": "string",
9197
- "description": "Content-Type header to use for the request"
9198
- }
9199
- },
9200
- "required": [
9201
- "base64"
9202
- ]
9203
- }
9204
- ],
9205
- "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."
9206
- },
9207
- "parameters": {
9208
- "type": "array",
9209
- "items": {
9210
- "type": "object",
9211
- "properties": {
9212
- "name": {
9213
- "type": "string",
9214
- "description": "Parameter name",
9215
- "example": "x-api-key"
9216
- },
9217
- "value": {
9218
- "type": "string",
9219
- "description": "Parameter value",
9220
- "example": "abc123def456"
9221
- },
9222
- "type": {
9223
- "type": "string",
9224
- "enum": [
9225
- "header",
9226
- "query"
9227
- ],
9228
- "description": "Parameter type (header or query)",
9229
- "example": "header"
9230
- }
9231
- },
9232
- "required": [
9233
- "name",
9234
- "value",
9235
- "type"
9236
- ]
9237
- },
9238
- "description": "Additional HTTP headers or query parameters to include in the request",
9239
- "example": [
9240
- {
9241
- "name": "x-api-key",
9242
- "value": "abc123def456",
9243
- "type": "header"
9244
- },
9245
- {
9246
- "name": "filter",
9247
- "value": "active",
9248
- "type": "query"
9249
- }
9250
- ]
9251
- },
9252
- "custom_connection_data": {
9253
- "deprecated": true,
9254
- "type": "object",
9255
- "properties": {
9256
- "authScheme": {
9257
- "type": "string",
9258
- "enum": [
9259
- "OAUTH2",
9260
- "DCR_OAUTH",
9261
- "API_KEY",
9262
- "BASIC_WITH_JWT",
9263
- "BASIC",
9264
- "BEARER_TOKEN",
9265
- "OAUTH1",
9266
- "NO_AUTH",
9267
- "SERVICE_ACCOUNT",
9268
- "GOOGLE_SERVICE_ACCOUNT",
9269
- "S2S_OAUTH2"
9270
- ]
9271
- },
9272
- "toolkitSlug": {
9273
- "type": "string"
9274
- },
9275
- "val": {
9276
- "type": "object",
9277
- "properties": {
9278
- "subdomain": {
9279
- "type": "string"
9280
- },
9281
- "your-domain": {
9282
- "type": "string"
9283
- },
9284
- "region": {
9285
- "type": "string"
9286
- },
9287
- "shop": {
9288
- "type": "string"
9289
- },
9290
- "account_url": {
9291
- "type": "string"
9292
- },
9293
- "COMPANYDOMAIN": {
9294
- "type": "string"
9295
- },
9296
- "extension": {
9297
- "type": "string"
9298
- },
9299
- "form_api_base_url": {
9300
- "type": "string"
9301
- },
9302
- "instanceEndpoint": {
9303
- "type": "string"
9304
- },
9305
- "api_url": {
9306
- "type": "string"
9307
- },
9308
- "borneo_dashboard_url": {
9309
- "type": "string"
9310
- },
9311
- "proxy_username": {
9312
- "type": "string"
9313
- },
9314
- "proxy_password": {
9315
- "type": "string"
9316
- },
9317
- "domain": {
9318
- "type": "string"
9319
- },
9320
- "version": {
9321
- "type": "string"
9322
- },
9323
- "dc": {
9324
- "type": "string"
9325
- },
9326
- "site_name": {
9327
- "type": "string"
9328
- },
9329
- "instanceName": {
9330
- "type": "string"
9331
- },
9332
- "account_id": {
9333
- "type": "string"
9334
- },
9335
- "your_server": {
9336
- "type": "string"
9337
- },
9338
- "server_location": {
9339
- "type": "string"
9340
- },
9341
- "base_url": {
9342
- "type": "string"
9343
- },
9344
- "state_prefix": {
9345
- "type": "string",
9346
- "maxLength": 40,
9347
- "description": "The oauth2 state prefix for the connection"
9348
- },
9349
- "long_redirect_url": {
9350
- "type": "boolean",
9351
- "description": "Whether to return the redirect url without shortening"
9352
- },
9353
- "access_token": {
9354
- "type": "string"
9355
- },
9356
- "id_token": {
9357
- "type": "string"
9358
- },
9359
- "token_type": {
9360
- "type": "string"
9361
- },
9362
- "refresh_token": {
9363
- "type": "string",
9364
- "nullable": true
9365
- },
9366
- "expires_in": {
9367
- "anyOf": [
9368
- {
9369
- "type": "number"
9370
- },
9371
- {
9372
- "type": "string"
9373
- },
9374
- {
9375
- "nullable": true,
9376
- "type": "object"
9377
- }
9378
- ]
9379
- },
9380
- "scope": {
9381
- "anyOf": [
9382
- {
9383
- "type": "string"
9384
- },
9385
- {
9386
- "type": "array",
9387
- "items": {
9388
- "type": "string"
9389
- }
9390
- },
9391
- {
9392
- "nullable": true,
9393
- "type": "object"
9394
- }
9395
- ]
9396
- },
9397
- "webhook_signature": {
9398
- "type": "string"
9399
- },
9400
- "authed_user": {
9401
- "type": "object",
9402
- "properties": {
9403
- "access_token": {
9404
- "type": "string"
9405
- },
9406
- "scope": {
9407
- "type": "string"
9408
- }
9409
- },
9410
- "description": "for slack user scopes"
9411
- },
9412
- "client_id": {
9413
- "type": "string",
9414
- "description": "Dynamically registered client ID"
9415
- },
9416
- "client_secret": {
9417
- "type": "string",
9418
- "description": "Dynamically registered client secret"
9419
- },
9420
- "client_id_issued_at": {
9421
- "type": "number"
9422
- },
9423
- "client_secret_expires_at": {
9424
- "type": "number"
9425
- },
9426
- "generic_api_key": {
9427
- "type": "string"
9428
- },
9429
- "api_key": {
9430
- "type": "string"
9431
- },
9432
- "bearer_token": {
9433
- "type": "string"
9434
- },
9435
- "basic_encoded": {
9436
- "type": "string"
9437
- },
9438
- "username": {
9439
- "type": "string"
9440
- },
9441
- "password": {
9442
- "type": "string"
9443
- },
9444
- "token": {
9445
- "type": "string"
9446
- },
9447
- "oauth_token": {
9448
- "type": "string"
9449
- },
9450
- "oauth_token_secret": {
9451
- "type": "string"
9452
- },
9453
- "oauth_verifier": {
9454
- "type": "string"
9455
- },
9456
- "consumer_key": {
9457
- "type": "string"
9458
- },
9459
- "redirectUrl": {
9460
- "type": "string"
9461
- },
9462
- "callback_url": {
9463
- "type": "string"
9464
- },
9465
- "application_id": {
9466
- "type": "string"
9467
- },
9468
- "installation_id": {
9469
- "type": "string"
9470
- },
9471
- "private_key": {
9472
- "type": "string"
9473
- },
9474
- "credentials_json": {
9475
- "type": "string"
9476
- },
9477
- "expires_at": {
9478
- "type": "string"
9479
- }
9480
- },
9481
- "required": [
9482
- "access_token"
9483
- ],
9484
- "additionalProperties": {}
9485
- }
9486
- },
9487
- "required": [
9488
- "authScheme",
9489
- "toolkitSlug",
9490
- "val"
9491
- ],
9492
- "additionalProperties": true
9493
- }
9494
- },
9495
- "required": [
9496
- "endpoint",
9497
- "method"
9498
- ]
9499
- }
9500
- }
9501
- }
9502
- },
9503
- "responses": {
9504
- "200": {
9505
- "description": "Successfully executed proxy request and received response",
9506
- "content": {
9507
- "application/json": {
9508
- "schema": {
9509
- "type": "object",
9510
- "properties": {
9511
- "data": {
9512
- "nullable": true,
9513
- "description": "The response data returned from the proxied API",
9514
- "example": {
9515
- "id": "123",
9516
- "name": "Resource Name",
9517
- "created_at": "2023-01-01T00:00:00Z"
9518
- },
9519
- "type": "object"
9520
- },
9521
- "binary_data": {
9522
- "type": "object",
9523
- "properties": {
9524
- "url": {
9525
- "type": "string",
9526
- "description": "URL to download binary content"
9527
- },
9528
- "content_type": {
9529
- "type": "string",
9530
- "description": "Content-Type of the binary data"
9531
- },
9532
- "size": {
9533
- "type": "number",
9534
- "description": "File size in bytes"
9535
- },
9536
- "expires_at": {
9537
- "type": "string",
9538
- "description": "ISO 8601 timestamp when the URL expires"
9539
- }
9540
- },
9541
- "required": [
9542
- "url",
9543
- "content_type",
9544
- "size"
9545
- ],
9546
- "description": "Binary body response data. Present when the response is a binary file."
9547
- },
9548
- "status": {
9549
- "type": "number",
9550
- "description": "The HTTP status code returned from the proxied API",
9551
- "example": 200
9552
- },
9553
- "headers": {
9554
- "type": "object",
9555
- "additionalProperties": {
9556
- "type": "string"
9557
- },
9558
- "description": "The HTTP headers returned from the proxied API",
9559
- "example": {
9560
- "content-type": "application/json",
9561
- "cache-control": "no-cache",
9562
- "host": "api.example.com"
9563
- }
9564
- }
9565
- },
9566
- "required": [
9567
- "status"
9568
- ]
9569
- }
9570
- }
9571
- }
9572
- },
9573
- "400": {
9574
- "description": "Bad request - Invalid request parameters or body format",
9575
- "content": {
9576
- "application/json": {
9577
- "schema": {
9578
- "$ref": "#/components/schemas/Error"
9579
- }
9580
- }
9581
- }
9582
- },
9583
- "401": {
9584
- "description": "Unauthorized - Authentication credentials are missing or invalid",
9585
- "content": {
9586
- "application/json": {
9587
- "schema": {
9588
- "$ref": "#/components/schemas/Error"
9589
- }
9590
- }
9591
- }
9592
- },
9593
- "403": {
9594
- "description": "Forbidden - Connected account does not have permission to access the requested resource",
9595
- "content": {
9596
- "application/json": {
9597
- "schema": {
9598
- "$ref": "#/components/schemas/Error"
9599
- }
9600
- }
9601
- }
9602
- },
9603
- "404": {
9604
- "description": "Not found - Resource not found or connected account not found",
9605
- "content": {
9606
- "application/json": {
9607
- "schema": {
9608
- "$ref": "#/components/schemas/Error"
9609
- }
9610
- }
9611
- }
9612
- },
9613
- "422": {
9614
- "description": "Unprocessable entity - Invalid state of the connected account",
9615
- "content": {
9616
- "application/json": {
9617
- "schema": {
9618
- "$ref": "#/components/schemas/Error"
9619
- }
9620
- }
9621
- }
9622
- },
9623
- "429": {
9624
- "description": "Too many requests - Rate limit exceeded on the connected account or proxy service",
9625
- "content": {
9626
- "application/json": {
9627
- "schema": {
9628
- "$ref": "#/components/schemas/Error"
9629
- }
9630
- }
9631
- }
9632
- },
9633
- "500": {
9634
- "description": "Internal server error - Something went wrong on the server",
9635
- "content": {
9636
- "application/json": {
9637
- "schema": {
9638
- "$ref": "#/components/schemas/Error"
9639
- }
9640
- }
9641
- }
9642
- },
9643
- "501": {
9644
- "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",
9645
- "content": {
9646
- "application/json": {
9647
- "schema": {
9648
- "$ref": "#/components/schemas/Error"
9649
- }
9650
- }
9651
- }
9652
- },
9653
- "502": {
9654
- "description": "Bad gateway - Error communicating with the upstream API",
9655
- "content": {
9656
- "application/json": {
9657
- "schema": {
9658
- "$ref": "#/components/schemas/Error"
9659
- }
9660
- }
9661
- }
9662
- },
9663
- "504": {
9664
- "description": "Gateway timeout - Upstream API timed out",
9665
- "content": {
9666
- "application/json": {
9667
- "schema": {
9668
- "$ref": "#/components/schemas/Error"
9669
- }
9670
- }
9671
- }
9672
- }
9673
- }
9674
- }
9675
- },
9676
- "/api/v3/trigger_instances/{slug}/upsert": {
9677
- "post": {
9678
- "summary": "Create or update a trigger",
9679
- "description": "Creates a new trigger instance or updates an existing one with the same configuration. Triggers listen for events from external services (webhooks or polling) and can invoke your workflows. If a matching trigger already exists and is disabled, it will be re-enabled. Requires a connected account ID to associate the trigger with a specific user connection.",
9680
- "tags": [
9681
- "Triggers"
9682
- ],
9683
- "operationId": "postTriggerInstancesBySlugUpsert",
9684
- "security": [
9685
- {
9686
- "ApiKeyAuth": []
9687
- },
9688
- {
9689
- "UserApiKeyAuth": []
9690
- }
9691
- ],
9692
- "parameters": [
9693
- {
9694
- "schema": {
9695
- "type": "string",
9696
- "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase)."
9697
- },
9698
- "required": true,
9699
- "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).",
9700
- "name": "slug",
9701
- "in": "path"
9702
- }
9703
- ],
9704
- "requestBody": {
9705
- "content": {
9706
- "application/json": {
9707
- "schema": {
9708
- "type": "object",
9709
- "properties": {
9710
- "connectedAuthId": {
9711
- "type": "string",
9712
- "format": "connectedAccountId",
9713
- "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.",
9714
- "deprecated": true
9715
- },
9716
- "triggerConfig": {
9717
- "type": "object",
9718
- "additionalProperties": {},
9719
- "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.",
9720
- "deprecated": true
9721
- },
9722
- "connected_account_id": {
9723
- "type": "string",
9724
- "format": "connectedAccountId",
9725
- "description": "Connected account nanoid"
9726
- },
9727
- "trigger_config": {
9728
- "type": "object",
9729
- "additionalProperties": {},
9730
- "description": "Trigger configuration"
9731
- },
9732
- "version": {
9733
- "type": "string",
9734
- "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.",
9735
- "deprecated": true,
9736
- "example": "latest"
9737
- },
9738
- "toolkit_versions": {
9739
- "anyOf": [
9740
- {
9741
- "type": "string"
9742
- },
9743
- {
9744
- "type": "object",
9745
- "additionalProperties": {
9746
- "type": "string"
9747
- }
9748
- },
9749
- {
9750
- "nullable": true,
9751
- "type": "object"
9752
- }
9753
- ],
9754
- "description": "Toolkit version specification. Supports \"latest\" string or a record mapping toolkit slugs to specific versions.",
9755
- "example": "latest"
9756
- }
9757
- }
9758
- }
9759
- }
9760
- }
9761
- },
9762
- "responses": {
9763
- "200": {
9764
- "description": "Successfully upserted trigger instance",
9765
- "content": {
9766
- "application/json": {
9767
- "schema": {
9768
- "type": "object",
9769
- "properties": {
9770
- "trigger_id": {
9771
- "type": "string",
9772
- "description": "ID of the updated trigger"
9773
- },
9774
- "deprecated": {
9775
- "type": "object",
9776
- "properties": {
9777
- "uuid": {
9778
- "type": "string",
9779
- "description": "ID of the updated trigger"
9780
- }
9781
- },
9782
- "required": [
9783
- "uuid"
9784
- ]
9785
- }
9786
- },
9787
- "required": [
9788
- "trigger_id",
9789
- "deprecated"
9790
- ]
9791
- }
9792
- }
9793
- }
9794
- },
9795
- "201": {
9796
- "description": "Successfully created trigger instance",
9797
- "content": {
9798
- "application/json": {
9799
- "schema": {
9800
- "type": "object",
9801
- "properties": {
9802
- "trigger_id": {
9803
- "type": "string",
9804
- "description": "ID of the updated trigger"
9805
- },
9806
- "deprecated": {
9807
- "type": "object",
9808
- "properties": {
9809
- "uuid": {
9810
- "type": "string",
9811
- "description": "ID of the updated trigger"
9812
- }
9813
- },
9814
- "required": [
9815
- "uuid"
9816
- ]
9817
- }
9818
- },
9819
- "required": [
9820
- "trigger_id",
9821
- "deprecated"
9822
- ]
9823
- }
9824
- }
9825
- }
9826
- },
9827
- "204": {
9828
- "description": "No content",
9829
- "content": {
9830
- "application/json": {
9831
- "schema": {
9832
- "type": "object",
9833
- "properties": {}
9834
- }
9835
- }
9836
- }
9837
- },
9838
- "400": {
9839
- "description": "Bad request",
9840
- "content": {
9841
- "application/json": {
9842
- "schema": {
9843
- "$ref": "#/components/schemas/Error"
9844
- }
9845
- }
9846
- }
9847
- },
9848
- "401": {
9849
- "description": "Unauthorized",
9850
- "content": {
9851
- "application/json": {
9852
- "schema": {
9853
- "$ref": "#/components/schemas/Error"
9854
- }
9855
- }
9856
- }
9857
- },
9858
- "404": {
9859
- "description": "Trigger instance not found",
9860
- "content": {
9861
- "application/json": {
9862
- "schema": {
9863
- "$ref": "#/components/schemas/Error"
9864
- }
9865
- }
9866
- }
9867
- },
9868
- "408": {
9869
- "description": "Request timeout",
9870
- "content": {
9871
- "application/json": {
9872
- "schema": {
9873
- "$ref": "#/components/schemas/Error"
9874
- }
9875
- }
9876
- }
9877
- },
9878
- "410": {
9879
- "description": "Gone",
9880
- "content": {
9881
- "application/json": {
9882
- "schema": {
9883
- "$ref": "#/components/schemas/Error"
9884
- }
9885
- }
9886
- }
9887
- },
9888
- "422": {
9889
- "description": "Unprocessable entity",
9890
- "content": {
9891
- "application/json": {
9892
- "schema": {
9893
- "$ref": "#/components/schemas/Error"
9894
- }
9895
- }
9896
- }
9897
- },
9898
- "500": {
9899
- "description": "Internal server error",
9900
- "content": {
9901
- "application/json": {
9902
- "schema": {
9903
- "$ref": "#/components/schemas/Error"
9904
- }
9905
- }
9906
- }
9907
- },
9908
- "501": {
9909
- "description": "Not implemented",
9910
- "content": {
9911
- "application/json": {
9912
- "schema": {
9913
- "$ref": "#/components/schemas/Error"
9914
- }
9915
- }
9916
- }
9917
- }
9918
- }
9919
- }
9920
- },
9921
- "/api/v3/trigger_instances/active": {
9922
- "get": {
9923
- "summary": "List active triggers",
9924
- "description": "Retrieves all active trigger instances for your project. Triggers listen for events from connected accounts (e.g., new emails, Slack messages, GitHub commits) and can invoke webhooks or workflows. Use filters to find triggers for specific users, connected accounts, or trigger types.",
9925
- "tags": [
9926
- "Triggers"
9927
- ],
9928
- "operationId": "getTriggerInstancesActive",
9056
+ "operationId": "getTriggerInstancesActive",
9057
"security": [
9058
{
9059
"ApiKeyAuth": []
@@ -14376,227 +13504,664 @@
13504
"description": "The identifier of the user who is initiating the session, ideally a unique identifier from your database like a user ID or email address",
13505
"example": "user_123456789"
13506
},
14379
- "toolkits": {
13507
+ "toolkits": {
13508
+ "anyOf": [
13509
+ {
13510
+ "type": "object",
13511
+ "properties": {
13512
+ "enable": {
13513
+ "type": "array",
13514
+ "items": {
13515
+ "type": "string"
13516
+ },
13517
+ "description": "Only these specific toolkits will be enabled",
13518
+ "example": [
13519
+ "gmail",
13520
+ "slack",
13521
+ "github"
13522
+ ]
13523
+ }
13524
+ },
13525
+ "required": [
13526
+ "enable"
13527
+ ],
13528
+ "additionalProperties": false,
13529
+ "description": "Enable only specific toolkits (allowlist)"
13530
+ },
13531
+ {
13532
+ "type": "object",
13533
+ "properties": {
13534
+ "disable": {
13535
+ "type": "array",
13536
+ "items": {
13537
+ "type": "string"
13538
+ },
13539
+ "description": "These specific toolkits will be disabled",
13540
+ "example": [
13541
+ "gmail",
13542
+ "slack"
13543
+ ]
13544
+ }
13545
+ },
13546
+ "required": [
13547
+ "disable"
13548
+ ],
13549
+ "additionalProperties": false,
13550
+ "description": "Disable specific toolkits (denylist)"
13551
+ }
13552
+ ],
13553
+ "description": "Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive."
13554
+ },
13555
+ "auth_configs": {
13556
+ "type": "object",
13557
+ "additionalProperties": {
13558
+ "type": "string",
13559
+ "format": "authConfigId"
13560
+ },
13561
+ "description": "The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed",
13562
+ "example": {
13563
+ "gmail": "ac_1223434343",
13564
+ "slack": "ac_23343434343434"
13565
+ }
13566
+ },
13567
+ "connected_accounts": {
13568
+ "type": "object",
13569
+ "additionalProperties": {
13570
+ "type": "string",
13571
+ "format": "connectedAccountId"
13572
+ },
13573
+ "description": "The connected accounts to use for the session. This will override the default behaviour and use the given connected account when specific toolkits are being executed",
13574
+ "example": {
13575
+ "github": "ca_34454545454545"
13576
+ }
13577
+ },
13578
+ "manage_connections": {
13579
+ "type": "object",
13580
+ "properties": {
13581
+ "enable": {
13582
+ "type": "boolean",
13583
+ "nullable": true,
13584
+ "default": true,
13585
+ "description": "Whether to enable the connection manager for automatic connection handling. If true, we will provide a tool your agent can use to initiate connections to toolkits if it doesnt exist. If set to false, then you have to manage connections manually.",
13586
+ "example": true
13587
+ },
13588
+ "callback_url": {
13589
+ "type": "string",
13590
+ "format": "uri",
13591
+ "description": "The URL to redirect to after a user completes authentication for a connected account. This allows you to handle the auth callback in your own application.",
13592
+ "example": "https://your-app.com/auth/callback"
13593
+ },
13594
+ "enable_wait_for_connections": {
13595
+ "type": "boolean",
13596
+ "nullable": true,
13597
+ "default": false,
13598
+ "description": "When true, the COMPOSIO_WAIT_FOR_CONNECTIONS tool is available for agents to poll connection status after sharing auth URLs. Default is false (disabled). May not work reliably with GPT models.",
13599
+ "example": false
13600
+ },
13601
+ "enable_connection_removal": {
13602
+ "type": "boolean",
13603
+ "nullable": true,
13604
+ "default": true,
13605
+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected accounts. Default true."
13606
+ }
13607
+ },
13608
+ "default": {
13609
+ "enable": true,
13610
+ "enable_wait_for_connections": false,
13611
+ "enable_connection_removal": true
13612
+ },
13613
+ "additionalProperties": false,
13614
+ "description": "Configuration for connection management settings"
13615
+ },
13616
+ "tools": {
13617
+ "type": "object",
13618
+ "additionalProperties": {
13619
+ "anyOf": [
13620
+ {
13621
+ "type": "object",
13622
+ "properties": {
13623
+ "enable": {
13624
+ "type": "array",
13625
+ "items": {
13626
+ "type": "string"
13627
+ },
13628
+ "description": "Only these specific tools will be available for this toolkit",
13629
+ "example": [
13630
+ "GMAIL_SEND_EMAIL",
13631
+ "GMAIL_FETCH_EMAILS"
13632
+ ]
13633
+ }
13634
+ },
13635
+ "required": [
13636
+ "enable"
13637
+ ],
13638
+ "additionalProperties": false
13639
+ },
13640
+ {
13641
+ "type": "object",
13642
+ "properties": {
13643
+ "disable": {
13644
+ "type": "array",
13645
+ "items": {
13646
+ "type": "string"
13647
+ },
13648
+ "description": "These specific tools will be disabled for this toolkit",
13649
+ "example": [
13650
+ "SLACK_ADD_EMOJI"
13651
+ ]
13652
+ }
13653
+ },
13654
+ "required": [
13655
+ "disable"
13656
+ ],
13657
+ "additionalProperties": false
13658
+ },
13659
+ {
13660
+ "type": "object",
13661
+ "properties": {
13662
+ "tags": {
13663
+ "anyOf": [
13664
+ {
13665
+ "type": "array",
13666
+ "items": {
13667
+ "type": "string",
13668
+ "enum": [
13669
+ "readOnlyHint",
13670
+ "destructiveHint",
13671
+ "idempotentHint",
13672
+ "openWorldHint"
13673
+ ]
13674
+ }
13675
+ },
13676
+ {
13677
+ "type": "object",
13678
+ "properties": {
13679
+ "enable": {
13680
+ "type": "array",
13681
+ "items": {
13682
+ "type": "string",
13683
+ "enum": [
13684
+ "readOnlyHint",
13685
+ "destructiveHint",
13686
+ "idempotentHint",
13687
+ "openWorldHint"
13688
+ ]
13689
+ },
13690
+ "description": "Tags that the tool must have at least one of"
13691
+ },
13692
+ "disable": {
13693
+ "type": "array",
13694
+ "items": {
13695
+ "type": "string",
13696
+ "enum": [
13697
+ "readOnlyHint",
13698
+ "destructiveHint",
13699
+ "idempotentHint",
13700
+ "openWorldHint"
13701
+ ]
13702
+ },
13703
+ "description": "Tags that the tool must NOT have any of"
13704
+ }
13705
+ }
13706
+ }
13707
+ ],
13708
+ "description": "MCP tags to filter tools. Array format is treated as enabled list. Object format supports both enabled and disabled lists.",
13709
+ "example": {
13710
+ "enable": [
13711
+ "openWorldHint"
13712
+ ],
13713
+ "disable": [
13714
+ "destructiveHint"
13715
+ ]
13716
+ }
13717
+ }
13718
+ },
13719
+ "required": [
13720
+ "tags"
13721
+ ],
13722
+ "additionalProperties": false
13723
+ }
13724
+ ]
13725
+ },
13726
+ "description": "Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit",
13727
+ "example": {
13728
+ "gmail": {
13729
+ "enable": [
13730
+ "GMAIL_SEND_EMAIL",
13731
+ "GMAIL_FETCH_EMAILS"
13732
+ ]
13733
+ },
13734
+ "slack": {
13735
+ "disable": [
13736
+ "SLACK_ADD_EMOJI"
13737
+ ]
13738
+ },
13739
+ "slack_bot": {
13740
+ "tags": {
13741
+ "enable": [
13742
+ "destructiveHint"
13743
+ ],
13744
+ "disable": [
13745
+ "openWorldHint"
13746
+ ]
13747
+ }
13748
+ }
13749
+ }
13750
+ },
13751
+ "tags": {
13752
"anyOf": [
13753
+ {
13754
+ "type": "array",
13755
+ "items": {
13756
+ "type": "string",
13757
+ "enum": [
13758
+ "readOnlyHint",
13759
+ "destructiveHint",
13760
+ "idempotentHint",
13761
+ "openWorldHint"
13762
+ ]
13763
+ }
13764
+ },
13765
{
13766
"type": "object",
13767
"properties": {
13768
"enable": {
13769
"type": "array",
13770
"items": {
14387
- "type": "string"
13771
+ "type": "string",
13772
+ "enum": [
13773
+ "readOnlyHint",
13774
+ "destructiveHint",
13775
+ "idempotentHint",
13776
+ "openWorldHint"
13777
+ ]
13778
+ },
13779
+ "description": "Tags that the tool must have at least one of"
13780
+ },
13781
+ "disable": {
13782
+ "type": "array",
13783
+ "items": {
13784
+ "type": "string",
13785
+ "enum": [
13786
+ "readOnlyHint",
13787
+ "destructiveHint",
13788
+ "idempotentHint",
13789
+ "openWorldHint"
13790
+ ]
13791
+ },
13792
+ "description": "Tags that the tool must NOT have any of"
13793
+ }
13794
+ }
13795
+ }
13796
+ ],
13797
+ "description": "Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.",
13798
+ "example": {
13799
+ "enable": [
13800
+ "openWorldHint"
13801
+ ],
13802
+ "disable": [
13803
+ "destructiveHint"
13804
+ ]
13805
+ }
13806
+ },
13807
+ "workbench": {
13808
+ "type": "object",
13809
+ "properties": {
13810
+ "enable": {
13811
+ "type": "boolean",
13812
+ "default": true,
13813
+ "description": "Set to false to disable the workbench entirely. When disabled, no code execution tools are available in the session.",
13814
+ "example": true
13815
+ },
13816
+ "enable_proxy_execution": {
13817
+ "type": "boolean",
13818
+ "default": true,
13819
+ "description": "Whether proxy execution is enabled. When enabled, workbench can call URLs and APIs directly.",
13820
+ "example": true
13821
+ },
13822
+ "auto_offload_threshold": {
13823
+ "type": "number",
13824
+ "minimum": 0,
13825
+ "exclusiveMinimum": true,
13826
+ "description": "Character threshold for automatic offloading. When workbench response exceeds this threshold, it will be automatically offloaded. Default is picked automatically based on the response size.",
13827
+ "example": 20000
13828
+ }
13829
+ },
13830
+ "default": {
13831
+ "enable": true,
13832
+ "enable_proxy_execution": true
13833
+ },
13834
+ "additionalProperties": false,
13835
+ "description": "Configuration for workbench behavior"
13836
+ },
13837
+ "experimental": {
13838
+ "type": "object",
13839
+ "properties": {
13840
+ "assistive_prompt_config": {
13841
+ "type": "object",
13842
+ "properties": {
13843
+ "user_timezone": {
13844
+ "type": "string",
13845
+ "description": "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to customize the system prompt with timezone-aware instructions.",
13846
+ "example": "America/New_York"
13847
+ }
13848
+ },
13849
+ "additionalProperties": false,
13850
+ "description": "Customize assistive prompt generation (e.g., timezone)."
13851
+ },
13852
+ "custom_toolkits": {
13853
+ "type": "array",
13854
+ "items": {
13855
+ "type": "object",
13856
+ "properties": {
13857
+ "slug": {
13858
+ "type": "string",
13859
+ "minLength": 1,
13860
+ "pattern": "^[a-zA-Z0-9_-]+$",
13861
+ "description": "Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.",
13862
+ "example": "ecommerce"
13863
+ },
13864
+ "name": {
13865
+ "type": "string",
13866
+ "minLength": 1,
13867
+ "maxLength": 128,
13868
+ "description": "Display name shown to the LLM and in search results.",
13869
+ "example": "E-Commerce API"
13870
+ },
13871
+ "description": {
13872
+ "type": "string",
13873
+ "minLength": 1,
13874
+ "maxLength": 2048,
13875
+ "description": "Used for BM25 search matching and shown in toolkit connection statuses.",
13876
+ "example": "Internal e-commerce API for order management and fulfillment"
13877
+ },
13878
+ "tools": {
13879
+ "type": "array",
13880
+ "items": {
13881
+ "type": "object",
13882
+ "properties": {
13883
+ "slug": {
13884
+ "type": "string",
13885
+ "minLength": 1,
13886
+ "pattern": "^[a-zA-Z0-9_-]+$",
13887
+ "description": "Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).",
13888
+ "example": "GET_CUSTOMER_ORDERS"
13889
+ },
13890
+ "name": {
13891
+ "type": "string",
13892
+ "minLength": 1,
13893
+ "maxLength": 128,
13894
+ "description": "Human-readable display name",
13895
+ "example": "Get Customer Orders"
13896
+ },
13897
+ "description": {
13898
+ "type": "string",
13899
+ "minLength": 1,
13900
+ "maxLength": 5120,
13901
+ "description": "Used for BM25 search matching and shown to the LLM.",
13902
+ "example": "Fetch recent orders for a customer by their email address"
13903
+ },
13904
+ "input_schema": {
13905
+ "type": "object",
13906
+ "additionalProperties": {},
13907
+ "description": "Must have type: \"object\" and a properties field.",
13908
+ "example": {
13909
+ "type": "object",
13910
+ "properties": {
13911
+ "email": {
13912
+ "type": "string",
13913
+ "description": "Customer email"
13914
+ }
13915
+ },
13916
+ "required": [
13917
+ "email"
13918
+ ]
13919
+ }
13920
+ },
13921
+ "output_schema": {
13922
+ "type": "object",
13923
+ "additionalProperties": {},
13924
+ "description": "Optional output schema for the tool response."
13925
+ }
13926
+ },
13927
+ "required": [
13928
+ "slug",
13929
+ "name",
13930
+ "description",
13931
+ "input_schema"
13932
+ ]
13933
+ },
13934
+ "minItems": 1,
13935
+ "maxItems": 100,
13936
+ "description": "Tools in this custom toolkit"
13937
+ }
13938
+ },
13939
+ "required": [
13940
+ "slug",
13941
+ "name",
13942
+ "description",
13943
+ "tools"
13944
+ ]
13945
+ },
13946
+ "description": "Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth."
13947
+ },
13948
+ "custom_tools": {
13949
+ "type": "array",
13950
+ "items": {
13951
+ "type": "object",
13952
+ "properties": {
13953
+ "slug": {
13954
+ "type": "string",
13955
+ "minLength": 1,
13956
+ "pattern": "^[a-zA-Z0-9_-]+$",
13957
+ "description": "Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.",
13958
+ "example": "GET_IMPORTANT_EMAILS"
13959
+ },
13960
+ "name": {
13961
+ "type": "string",
13962
+ "minLength": 1,
13963
+ "maxLength": 128,
13964
+ "description": "Human-readable display name",
13965
+ "example": "Get Important Emails"
13966
+ },
13967
+ "description": {
13968
+ "type": "string",
13969
+ "minLength": 1,
13970
+ "maxLength": 5120,
13971
+ "description": "Used for BM25 search matching and shown to the LLM.",
13972
+ "example": "Fetch emails marked as important from the last 24 hours"
13973
},
14389
- "description": "Only these specific toolkits will be enabled",
14390
- "example": [
14391
- "gmail",
14392
- "slack",
14393
- "github"
14394
- ]
14395
- }
14396
- },
14397
- "required": [
14398
- "enable"
14399
- ],
14400
- "additionalProperties": false,
14401
- "description": "Enable only specific toolkits (allowlist)"
14402
- },
14403
- {
14404
- "type": "object",
14405
- "properties": {
14406
- "disable": {
14407
- "type": "array",
14408
- "items": {
14409
- "type": "string"
13974
+ "input_schema": {
13975
+ "type": "object",
13976
+ "additionalProperties": {},
13977
+ "description": "Must have type: \"object\" and a properties field.",
13978
+ "example": {
13979
+ "type": "object",
13980
+ "properties": {
13981
+ "limit": {
13982
+ "type": "number",
13983
+ "description": "Max results to return"
13984
+ }
13985
+ }
13986
+ }
13987
},
14411
- "description": "These specific toolkits will be disabled",
14412
- "example": [
14413
- "gmail",
14414
- "slack"
14415
- ]
14416
- }
13988
+ "output_schema": {
13989
+ "type": "object",
13990
+ "additionalProperties": {},
13991
+ "description": "JSON Schema describing tool output (optional)"
13992
+ },
13993
+ "extends_toolkit": {
13994
+ "type": "string",
13995
+ "minLength": 1,
13996
+ "description": "If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's auth/connection status. If omitted, the tool is standalone (no-auth).",
13997
+ "example": "gmail"
13998
+ }
13999
+ },
14000
+ "required": [
14001
+ "slug",
14002
+ "name",
14003
+ "description",
14004
+ "input_schema"
14005
+ ]
14006
},
14418
- "required": [
14419
- "disable"
14420
- ],
14421
- "additionalProperties": false,
14422
- "description": "Disable specific toolkits (denylist)"
14007
+ "description": "Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection."
14008
}
14424
- ],
14425
- "description": "Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive."
14426
- },
14427
- "auth_configs": {
14428
- "type": "object",
14429
- "additionalProperties": {
14430
- "type": "string",
14431
- "format": "authConfigId"
14009
},
14433
- "description": "The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed",
14434
- "example": {
14010
+ "additionalProperties": false,
14011
+ "description": "Experimental features - not stable, may be modified or removed in future versions.",
14012
+ "x-experimental": true
14013
+ }
14014
+ },
14015
+ "required": [
14016
+ "user_id"
14017
+ ]
14018
+ },
14019
+ "examples": {
14020
+ "Session with all toolkits": {
14021
+ "value": {
14022
+ "user_id": "user_123456789"
14023
+ }
14024
+ },
14025
+ "Session with only specific toolkits": {
14026
+ "value": {
14027
+ "user_id": "user_123456789",
14028
+ "toolkits": {
14029
+ "enable": [
14030
+ "gmail",
14031
+ "slack"
14032
+ ]
14033
+ }
14034
+ }
14035
+ },
14036
+ "Session with only specific toolkits disabled": {
14037
+ "value": {
14038
+ "user_id": "user_123456789",
14039
+ "toolkits": {
14040
+ "disable": [
14041
+ "gmail",
14042
+ "slack"
14043
+ ]
14044
+ }
14045
+ }
14046
+ },
14047
+ "Session with connection manager enabled": {
14048
+ "value": {
14049
+ "user_id": "user_123456789",
14050
+ "manage_connections": {
14051
+ "enable": true
14052
+ }
14053
+ }
14054
+ },
14055
+ "Session with connection manager and specific toolkits": {
14056
+ "value": {
14057
+ "user_id": "user_123456789",
14058
+ "toolkits": {
14059
+ "enable": [
14060
+ "gmail",
14061
+ "slack"
14062
+ ]
14063
+ },
14064
+ "manage_connections": {
14065
+ "enable": true
14066
+ }
14067
+ }
14068
+ },
14069
+ "Session with custom callback URL": {
14070
+ "value": {
14071
+ "user_id": "user_123456789",
14072
+ "toolkits": {
14073
+ "enable": [
14074
+ "github",
14075
+ "slack"
14076
+ ]
14077
+ },
14078
+ "manage_connections": {
14079
+ "enable": true,
14080
+ "callback_url": "https://your-app.com/auth/callback"
14081
+ }
14082
+ }
14083
+ },
14084
+ "Session with workbench configuration": {
14085
+ "value": {
14086
+ "user_id": "user_123456789",
14087
+ "toolkits": {
14088
+ "enable": [
14089
+ "gmail"
14090
+ ]
14091
+ },
14092
+ "workbench": {
14093
+ "enable_proxy_execution": true,
14094
+ "auto_offload_threshold": 10000
14095
+ }
14096
+ }
14097
+ },
14098
+ "Session with global tags filter": {
14099
+ "value": {
14100
+ "user_id": "user_123456789",
14101
+ "toolkits": {
14102
+ "enable": [
14103
+ "gmail",
14104
+ "slack"
14105
+ ]
14106
+ },
14107
+ "tags": [
14108
+ "readOnlyHint",
14109
+ "idempotentHint"
14110
+ ]
14111
+ }
14112
+ },
14113
+ "Session with auth config overrides": {
14114
+ "value": {
14115
+ "user_id": "user_123456789",
14116
+ "toolkits": {
14117
+ "enable": [
14118
+ "gmail",
14119
+ "slack"
14120
+ ]
14121
+ },
14122
+ "auth_configs": {
14123
"gmail": "ac_1223434343",
14124
"slack": "ac_23343434343434"
14125
}
14438
- },
14439
- "connected_accounts": {
14440
- "type": "object",
14441
- "additionalProperties": {
14442
- "type": "string",
14443
- "format": "connectedAccountId"
14126
+ }
14127
+ },
14128
+ "Session with connected account overrides": {
14129
+ "value": {
14130
+ "user_id": "user_123456789",
14131
+ "toolkits": {
14132
+ "enable": [
14133
+ "gmail",
14134
+ "slack"
14135
+ ]
14136
},
14445
- "description": "The connected accounts to use for the session. This will override the default behaviour and use the given connected account when specific toolkits are being executed",
14446
- "example": {
14447
- "github": "ca_34454545454545"
14137
+ "connected_accounts": {
14138
+ "gmail": "ca_1223434343",
14139
+ "slack": "ca_23344434343434"
14140
}
14449
- },
14450
- "manage_connections": {
14451
- "type": "object",
14452
- "properties": {
14453
- "enable": {
14454
- "type": "boolean",
14455
- "nullable": true,
14456
- "default": true,
14457
- "description": "Whether to enable the connection manager for automatic connection handling. If true, we will provide a tool your agent can use to initiate connections to toolkits if it doesnt exist. If set to false, then you have to manage connections manually.",
14458
- "example": true
14459
- },
14460
- "callback_url": {
14461
- "type": "string",
14462
- "format": "uri",
14463
- "description": "The URL to redirect to after a user completes authentication for a connected account. This allows you to handle the auth callback in your own application.",
14464
- "example": "https://your-app.com/auth/callback"
14465
- },
14466
- "enable_wait_for_connections": {
14467
- "type": "boolean",
14468
- "nullable": true,
14469
- "default": false,
14470
- "description": "When true, the COMPOSIO_WAIT_FOR_CONNECTIONS tool is available for agents to poll connection status after sharing auth URLs. Default is false (disabled). May not work reliably with GPT models.",
14471
- "example": false
14472
- },
14473
- "enable_connection_removal": {
14474
- "type": "boolean",
14475
- "nullable": true,
14476
- "default": true,
14477
- "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected accounts. Default true."
14478
- }
14141
+ }
14142
+ },
14143
+ "Session with comprehensive configuration": {
14144
+ "value": {
14145
+ "user_id": "user_123456789",
14146
+ "toolkits": {
14147
+ "enable": [
14148
+ "gmail",
14149
+ "slack",
14150
+ "github"
14151
+ ]
14152
+ },
14153
+ "auth_configs": {
14154
+ "gmail": "ac_1223434343",
14155
+ "slack": "ac_23343434343434"
14156
},
14480
- "default": {
14481
- "enable": true,
14482
- "enable_wait_for_connections": false,
14483
- "enable_connection_removal": true
14157
+ "connected_accounts": {
14158
+ "github": "ca_34454545454545"
14159
},
14485
- "additionalProperties": false,
14486
- "description": "Configuration for connection management settings"
14487
- },
14488
- "tools": {
14489
- "type": "object",
14490
- "additionalProperties": {
14491
- "anyOf": [
14492
- {
14493
- "type": "object",
14494
- "properties": {
14495
- "enable": {
14496
- "type": "array",
14497
- "items": {
14498
- "type": "string"
14499
- },
14500
- "description": "Only these specific tools will be available for this toolkit",
14501
- "example": [
14502
- "GMAIL_SEND_EMAIL",
14503
- "GMAIL_FETCH_EMAILS"
14504
- ]
14505
- }
14506
- },
14507
- "required": [
14508
- "enable"
14509
- ],
14510
- "additionalProperties": false
14511
- },
14512
- {
14513
- "type": "object",
14514
- "properties": {
14515
- "disable": {
14516
- "type": "array",
14517
- "items": {
14518
- "type": "string"
14519
- },
14520
- "description": "These specific tools will be disabled for this toolkit",
14521
- "example": [
14522
- "SLACK_ADD_EMOJI"
14523
- ]
14524
- }
14525
- },
14526
- "required": [
14527
- "disable"
14528
- ],
14529
- "additionalProperties": false
14530
- },
14531
- {
14532
- "type": "object",
14533
- "properties": {
14534
- "tags": {
14535
- "anyOf": [
14536
- {
14537
- "type": "array",
14538
- "items": {
14539
- "type": "string",
14540
- "enum": [
14541
- "readOnlyHint",
14542
- "destructiveHint",
14543
- "idempotentHint",
14544
- "openWorldHint"
14545
- ]
14546
- }
14547
- },
14548
- {
14549
- "type": "object",
14550
- "properties": {
14551
- "enable": {
14552
- "type": "array",
14553
- "items": {
14554
- "type": "string",
14555
- "enum": [
14556
- "readOnlyHint",
14557
- "destructiveHint",
14558
- "idempotentHint",
14559
- "openWorldHint"
14560
- ]
14561
- },
14562
- "description": "Tags that the tool must have at least one of"
14563
- },
14564
- "disable": {
14565
- "type": "array",
14566
- "items": {
14567
- "type": "string",
14568
- "enum": [
14569
- "readOnlyHint",
14570
- "destructiveHint",
14571
- "idempotentHint",
14572
- "openWorldHint"
14573
- ]
14574
- },
14575
- "description": "Tags that the tool must NOT have any of"
14576
- }
14577
- }
14578
- }
14579
- ],
14580
- "description": "MCP tags to filter tools. Array format is treated as enabled list. Object format supports both enabled and disabled lists.",
14581
- "example": {
14582
- "enable": [
14583
- "openWorldHint"
14584
- ],
14585
- "disable": [
14586
- "destructiveHint"
14587
- ]
14588
- }
14589
- }
14590
- },
14591
- "required": [
14592
- "tags"
14593
- ],
14594
- "additionalProperties": false
14595
- }
14596
- ]
14160
+ "manage_connections": {
14161
+ "enable": true,
14162
+ "callback_url": "https://your-app.com/auth/callback"
14163
},
14598
- "description": "Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit",
14599
- "example": {
14164
+ "tools": {
14165
"gmail": {
14166
"enable": [
14167
"GMAIL_SEND_EMAIL",
@@ -14609,478 +14174,864 @@
14174
]
14175
},
14176
"slack_bot": {
14612
- "tags": {
14613
- "enable": [
14614
- "destructiveHint"
14615
- ],
14616
- "disable": [
14617
- "openWorldHint"
14618
- ]
14619
- }
14620
- }
14621
- }
14622
- },
14623
- "tags": {
14624
- "anyOf": [
14625
- {
14626
- "type": "array",
14627
- "items": {
14628
- "type": "string",
14629
- "enum": [
14630
- "readOnlyHint",
14631
- "destructiveHint",
14632
- "idempotentHint",
14633
- "openWorldHint"
14634
- ]
14635
- }
14636
- },
14637
- {
14638
- "type": "object",
14639
- "properties": {
14640
- "enable": {
14641
- "type": "array",
14642
- "items": {
14643
- "type": "string",
14644
- "enum": [
14645
- "readOnlyHint",
14646
- "destructiveHint",
14647
- "idempotentHint",
14648
- "openWorldHint"
14649
- ]
14650
- },
14651
- "description": "Tags that the tool must have at least one of"
14652
- },
14653
- "disable": {
14654
- "type": "array",
14655
- "items": {
14656
- "type": "string",
14657
- "enum": [
14658
- "readOnlyHint",
14659
- "destructiveHint",
14660
- "idempotentHint",
14661
- "openWorldHint"
14662
- ]
14663
- },
14664
- "description": "Tags that the tool must NOT have any of"
14665
- }
14666
- }
14177
+ "tags": [
14178
+ "destructiveHint"
14179
+ ]
14180
}
14181
+ },
14182
+ "tags": [
14183
+ "destructiveHint",
14184
+ "idempotentHint"
14185
],
14669
- "description": "Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.",
14670
- "example": {
14671
- "enable": [
14672
- "openWorldHint"
14673
- ],
14186
+ "workbench": {
14187
+ "enable_proxy_execution": true,
14188
+ "auto_offload_threshold": 10000
14189
+ }
14190
+ }
14191
+ },
14192
+ "Session with disabled toolkits and global tags": {
14193
+ "value": {
14194
+ "user_id": "user_123456789",
14195
+ "toolkits": {
14196
"disable": [
14675
- "destructiveHint"
14197
+ "gmail"
14198
]
14677
- }
14678
- },
14679
- "workbench": {
14680
- "type": "object",
14681
- "properties": {
14682
- "enable": {
14683
- "type": "boolean",
14684
- "default": true,
14685
- "description": "Set to false to disable the workbench entirely. When disabled, no code execution tools are available in the session.",
14686
- "example": true
14687
- },
14688
- "enable_proxy_execution": {
14689
- "type": "boolean",
14690
- "default": true,
14691
- "description": "Whether proxy execution is enabled. When enabled, workbench can call URLs and APIs directly.",
14692
- "example": true
14199
+ },
14200
+ "tags": [
14201
+ "readOnlyHint"
14202
+ ]
14203
+ }
14204
+ }
14205
+ }
14206
+ }
14207
+ }
14208
+ },
14209
+ "responses": {
14210
+ "201": {
14211
+ "description": "Session successfully created. Returns the session ID and MCP server URL for the created session.",
14212
+ "content": {
14213
+ "application/json": {
14214
+ "schema": {
14215
+ "type": "object",
14216
+ "properties": {
14217
+ "session_id": {
14218
+ "type": "string",
14219
+ "format": "toolRouterSessionId",
14220
+ "description": "The identifier of the session",
14221
+ "example": "trs_123456789"
14222
+ },
14223
+ "mcp": {
14224
+ "type": "object",
14225
+ "properties": {
14226
+ "type": {
14227
+ "type": "string",
14228
+ "enum": [
14229
+ "http"
14230
+ ],
14231
+ "description": "The type of the MCP server. Can be http"
14232
+ },
14233
+ "url": {
14234
+ "type": "string",
14235
+ "format": "uri",
14236
+ "description": "The URL of the MCP server",
14237
+ "example": "https://app.composio.dev/tool_router/v3/trs_123456789/mcp"
14238
+ }
14239
},
14694
- "auto_offload_threshold": {
14695
- "type": "number",
14696
- "minimum": 0,
14697
- "exclusiveMinimum": true,
14698
- "description": "Character threshold for automatic offloading. When workbench response exceeds this threshold, it will be automatically offloaded. Default is picked automatically based on the response size.",
14699
- "example": 20000
14700
- }
14240
+ "required": [
14241
+ "type",
14242
+ "url"
14243
+ ]
14244
},
14702
- "default": {
14703
- "enable": true,
14704
- "enable_proxy_execution": true
14245
+ "tool_router_tools": {
14246
+ "type": "array",
14247
+ "items": {
14248
+ "type": "string"
14249
+ },
14250
+ "description": "List of available tools in this session"
14251
},
14706
- "additionalProperties": false,
14707
- "description": "Configuration for workbench behavior"
14708
- },
14709
- "experimental": {
14710
- "type": "object",
14711
- "properties": {
14712
- "assistive_prompt_config": {
14713
- "type": "object",
14714
- "properties": {
14715
- "user_timezone": {
14252
+ "config": {
14253
+ "type": "object",
14254
+ "properties": {
14255
+ "user_id": {
14256
+ "type": "string",
14257
+ "description": "User identifier for this session"
14258
+ },
14259
+ "toolkits": {
14260
+ "anyOf": [
14261
+ {
14262
+ "type": "object",
14263
+ "properties": {
14264
+ "enabled": {
14265
+ "type": "array",
14266
+ "items": {
14267
+ "type": "string"
14268
+ }
14269
+ }
14270
+ },
14271
+ "required": [
14272
+ "enabled"
14273
+ ],
14274
+ "additionalProperties": false
14275
+ },
14276
+ {
14277
+ "type": "object",
14278
+ "properties": {
14279
+ "disabled": {
14280
+ "type": "array",
14281
+ "items": {
14282
+ "type": "string"
14283
+ }
14284
+ }
14285
+ },
14286
+ "required": [
14287
+ "disabled"
14288
+ ],
14289
+ "additionalProperties": false
14290
+ }
14291
+ ],
14292
+ "description": "Toolkit configuration - either enabled list or disabled list"
14293
+ },
14294
+ "auth_configs": {
14295
+ "type": "object",
14296
+ "additionalProperties": {
14297
"type": "string",
14717
- "description": "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to customize the system prompt with timezone-aware instructions.",
14718
- "example": "America/New_York"
14719
- }
14298
+ "format": "authConfigId"
14299
+ },
14300
+ "description": "Auth config overrides per toolkit"
14301
},
14721
- "additionalProperties": false,
14722
- "description": "Customize assistive prompt generation (e.g., timezone)."
14723
- },
14724
- "custom_toolkits": {
14725
- "type": "array",
14726
- "items": {
14302
+ "connected_accounts": {
14303
+ "type": "object",
14304
+ "additionalProperties": {
14305
+ "type": "string",
14306
+ "format": "connectedAccountId"
14307
+ },
14308
+ "description": "Connected account overrides per toolkit"
14309
+ },
14310
+ "manage_connections": {
14311
"type": "object",
14312
"properties": {
14729
- "slug": {
14730
- "type": "string",
14731
- "minLength": 1,
14732
- "pattern": "^[a-zA-Z0-9_-]+$",
14733
- "description": "Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.",
14734
- "example": "ecommerce"
14313
+ "enabled": {
14314
+ "type": "boolean",
14315
+ "default": true,
14316
+ "description": "Whether to enable the connection manager for automatic connection handling"
14317
},
14736
- "name": {
14318
+ "callback_url": {
14319
"type": "string",
14738
- "minLength": 1,
14739
- "maxLength": 128,
14740
- "description": "Display name shown to the LLM and in search results.",
14741
- "example": "E-Commerce API"
14320
+ "format": "uri",
14321
+ "description": "Custom callback URL for connected account auth flows"
14322
},
14743
- "description": {
14744
- "type": "string",
14745
- "minLength": 1,
14746
- "maxLength": 2048,
14747
- "description": "Used for BM25 search matching and shown in toolkit connection statuses.",
14748
- "example": "Internal e-commerce API for order management and fulfillment"
14323
+ "enable_wait_for_connections": {
14324
+ "type": "boolean",
14325
+ "default": false,
14326
+ "description": "Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models."
14327
},
14750
- "tools": {
14751
- "type": "array",
14752
- "items": {
14328
+ "enable_connection_removal": {
14329
+ "type": "boolean",
14330
+ "default": true,
14331
+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS. Default true."
14332
+ }
14333
+ },
14334
+ "description": "Manage connections configuration"
14335
+ },
14336
+ "tools": {
14337
+ "type": "object",
14338
+ "additionalProperties": {
14339
+ "anyOf": [
14340
+ {
14341
"type": "object",
14342
"properties": {
14755
- "slug": {
14756
- "type": "string",
14757
- "minLength": 1,
14758
- "pattern": "^[a-zA-Z0-9_-]+$",
14759
- "description": "Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).",
14760
- "example": "GET_CUSTOMER_ORDERS"
14761
- },
14762
- "name": {
14763
- "type": "string",
14764
- "minLength": 1,
14765
- "maxLength": 128,
14766
- "description": "Human-readable display name",
14767
- "example": "Get Customer Orders"
14768
- },
14769
- "description": {
14770
- "type": "string",
14771
- "minLength": 1,
14772
- "maxLength": 5120,
14773
- "description": "Used for BM25 search matching and shown to the LLM.",
14774
- "example": "Fetch recent orders for a customer by their email address"
14775
- },
14776
- "input_schema": {
14343
+ "enabled": {
14344
+ "type": "array",
14345
+ "items": {
14346
+ "type": "string"
14347
+ }
14348
+ }
14349
+ },
14350
+ "required": [
14351
+ "enabled"
14352
+ ],
14353
+ "additionalProperties": false
14354
+ },
14355
+ {
14356
+ "type": "object",
14357
+ "properties": {
14358
+ "disabled": {
14359
+ "type": "array",
14360
+ "items": {
14361
+ "type": "string"
14362
+ }
14363
+ }
14364
+ },
14365
+ "required": [
14366
+ "disabled"
14367
+ ],
14368
+ "additionalProperties": false
14369
+ },
14370
+ {
14371
+ "type": "object",
14372
+ "properties": {
14373
+ "tags": {
14374
"type": "object",
14778
- "additionalProperties": {},
14779
- "description": "Must have type: \"object\" and a properties field.",
14780
- "example": {
14781
- "type": "object",
14782
- "properties": {
14783
- "email": {
14375
+ "properties": {
14376
+ "enabled": {
14377
+ "type": "array",
14378
+ "items": {
14379
"type": "string",
14785
- "description": "Customer email"
14786
- }
14380
+ "enum": [
14381
+ "readOnlyHint",
14382
+ "destructiveHint",
14383
+ "idempotentHint",
14384
+ "openWorldHint"
14385
+ ]
14386
+ },
14387
+ "description": "Tags that the tool must have at least one of"
14388
},
14788
- "required": [
14789
- "email"
14790
- ]
14389
+ "disabled": {
14390
+ "type": "array",
14391
+ "items": {
14392
+ "type": "string",
14393
+ "enum": [
14394
+ "readOnlyHint",
14395
+ "destructiveHint",
14396
+ "idempotentHint",
14397
+ "openWorldHint"
14398
+ ]
14399
+ },
14400
+ "description": "Tags that the tool must NOT have any of"
14401
+ }
14402
}
14792
- },
14793
- "output_schema": {
14794
- "type": "object",
14795
- "additionalProperties": {},
14796
- "description": "Optional output schema for the tool response."
14403
}
14404
},
14405
"required": [
14800
- "slug",
14801
- "name",
14802
- "description",
14803
- "input_schema"
14406
+ "tags"
14407
+ ],
14408
+ "additionalProperties": false
14409
+ }
14410
+ ]
14411
+ },
14412
+ "description": "Tool-level configuration per toolkit"
14413
+ },
14414
+ "tags": {
14415
+ "type": "object",
14416
+ "properties": {
14417
+ "enabled": {
14418
+ "type": "array",
14419
+ "items": {
14420
+ "type": "string",
14421
+ "enum": [
14422
+ "readOnlyHint",
14423
+ "destructiveHint",
14424
+ "idempotentHint",
14425
+ "openWorldHint"
14426
]
14427
},
14806
- "minItems": 1,
14807
- "maxItems": 100,
14808
- "description": "Tools in this custom toolkit"
14428
+ "description": "Tags that the tool must have at least one of"
14429
+ },
14430
+ "disabled": {
14431
+ "type": "array",
14432
+ "items": {
14433
+ "type": "string",
14434
+ "enum": [
14435
+ "readOnlyHint",
14436
+ "destructiveHint",
14437
+ "idempotentHint",
14438
+ "openWorldHint"
14439
+ ]
14440
+ },
14441
+ "description": "Tags that the tool must NOT have any of"
14442
}
14443
},
14811
- "required": [
14812
- "slug",
14813
- "name",
14814
- "description",
14815
- "tools"
14816
- ]
14444
+ "description": "MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied."
14445
},
14818
- "description": "Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth."
14819
- },
14820
- "custom_tools": {
14821
- "type": "array",
14822
- "items": {
14446
+ "workbench": {
14447
"type": "object",
14448
"properties": {
14825
- "slug": {
14826
- "type": "string",
14827
- "minLength": 1,
14828
- "pattern": "^[a-zA-Z0-9_-]+$",
14829
- "description": "Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.",
14830
- "example": "GET_IMPORTANT_EMAILS"
14831
- },
14832
- "name": {
14833
- "type": "string",
14834
- "minLength": 1,
14835
- "maxLength": 128,
14836
- "description": "Human-readable display name",
14837
- "example": "Get Important Emails"
14838
- },
14839
- "description": {
14840
- "type": "string",
14841
- "minLength": 1,
14842
- "maxLength": 5120,
14843
- "description": "Used for BM25 search matching and shown to the LLM.",
14844
- "example": "Fetch emails marked as important from the last 24 hours"
14845
- },
14846
- "input_schema": {
14847
- "type": "object",
14848
- "additionalProperties": {},
14849
- "description": "Must have type: \"object\" and a properties field.",
14850
- "example": {
14851
- "type": "object",
14852
- "properties": {
14853
- "limit": {
14854
- "type": "number",
14855
- "description": "Max results to return"
14856
- }
14857
- }
14858
- }
14859
- },
14860
- "output_schema": {
14861
- "type": "object",
14862
- "additionalProperties": {},
14863
- "description": "JSON Schema describing tool output (optional)"
14449
+ "enable": {
14450
+ "type": "boolean",
14451
+ "description": "Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed."
14452
},
14865
- "extends_toolkit": {
14866
- "type": "string",
14867
- "minLength": 1,
14868
- "description": "If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's auth/connection status. If omitted, the tool is standalone (no-auth).",
14869
- "example": "gmail"
14870
- }
14871
- },
14872
- "required": [
14873
- "slug",
14874
- "name",
14875
- "description",
14876
- "input_schema"
14877
- ]
14878
- },
14879
- "description": "Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection."
14880
- }
14881
- },
14882
- "additionalProperties": false,
14883
- "description": "Experimental features - not stable, may be modified or removed in future versions.",
14884
- "x-experimental": true
14885
- }
14886
- },
14887
- "required": [
14888
- "user_id"
14889
- ]
14890
- },
14891
- "examples": {
14892
- "Session with all toolkits": {
14893
- "value": {
14894
- "user_id": "user_123456789"
14895
- }
14896
- },
14897
- "Session with only specific toolkits": {
14898
- "value": {
14899
- "user_id": "user_123456789",
14900
- "toolkits": {
14901
- "enable": [
14902
- "gmail",
14903
- "slack"
14904
- ]
14905
- }
14906
- }
14907
- },
14908
- "Session with only specific toolkits disabled": {
14909
- "value": {
14910
- "user_id": "user_123456789",
14911
- "toolkits": {
14912
- "disable": [
14913
- "gmail",
14914
- "slack"
14915
- ]
14916
- }
14917
- }
14918
- },
14919
- "Session with connection manager enabled": {
14920
- "value": {
14921
- "user_id": "user_123456789",
14922
- "manage_connections": {
14923
- "enable": true
14924
- }
14925
- }
14926
- },
14927
- "Session with connection manager and specific toolkits": {
14928
- "value": {
14929
- "user_id": "user_123456789",
14930
- "toolkits": {
14931
- "enable": [
14932
- "gmail",
14933
- "slack"
14934
- ]
14935
- },
14936
- "manage_connections": {
14937
- "enable": true
14938
- }
14939
- }
14940
- },
14941
- "Session with custom callback URL": {
14942
- "value": {
14943
- "user_id": "user_123456789",
14944
- "toolkits": {
14945
- "enable": [
14946
- "github",
14947
- "slack"
14948
- ]
14949
- },
14950
- "manage_connections": {
14951
- "enable": true,
14952
- "callback_url": "https://your-app.com/auth/callback"
14953
- }
14954
- }
14955
- },
14956
- "Session with workbench configuration": {
14957
- "value": {
14958
- "user_id": "user_123456789",
14959
- "toolkits": {
14960
- "enable": [
14961
- "gmail"
14962
- ]
14963
- },
14964
- "workbench": {
14965
- "enable_proxy_execution": true,
14966
- "auto_offload_threshold": 10000
14967
- }
14968
- }
14969
- },
14970
- "Session with global tags filter": {
14971
- "value": {
14972
- "user_id": "user_123456789",
14973
- "toolkits": {
14974
- "enable": [
14975
- "gmail",
14976
- "slack"
14977
- ]
14978
- },
14979
- "tags": [
14980
- "readOnlyHint",
14981
- "idempotentHint"
14982
- ]
14983
- }
14984
- },
14985
- "Session with auth config overrides": {
14986
- "value": {
14987
- "user_id": "user_123456789",
14988
- "toolkits": {
14989
- "enable": [
14990
- "gmail",
14991
- "slack"
14992
- ]
14993
- },
14994
- "auth_configs": {
14995
- "gmail": "ac_1223434343",
14996
- "slack": "ac_23343434343434"
14997
- }
14998
- }
14999
- },
15000
- "Session with connected account overrides": {
15001
- "value": {
15002
- "user_id": "user_123456789",
15003
- "toolkits": {
15004
- "enable": [
15005
- "gmail",
15006
- "slack"
15007
- ]
15008
- },
15009
- "connected_accounts": {
15010
- "gmail": "ca_1223434343",
15011
- "slack": "ca_23344434343434"
15012
- }
15013
- }
15014
- },
15015
- "Session with comprehensive configuration": {
15016
- "value": {
15017
- "user_id": "user_123456789",
15018
- "toolkits": {
15019
- "enable": [
15020
- "gmail",
15021
- "slack",
15022
- "github"
15023
- ]
15024
- },
15025
- "auth_configs": {
15026
- "gmail": "ac_1223434343",
15027
- "slack": "ac_23343434343434"
15028
- },
15029
- "connected_accounts": {
15030
- "github": "ca_34454545454545"
15031
- },
15032
- "manage_connections": {
15033
- "enable": true,
15034
- "callback_url": "https://your-app.com/auth/callback"
15035
- },
15036
- "tools": {
15037
- "gmail": {
15038
- "enable": [
15039
- "GMAIL_SEND_EMAIL",
15040
- "GMAIL_FETCH_EMAILS"
15041
- ]
14453
+ "proxy_execution_enabled": {
14454
+ "type": "boolean",
14455
+ "description": "Whether proxy execution is enabled in the workbench"
14456
+ },
14457
+ "auto_offload_threshold": {
14458
+ "type": "number",
14459
+ "minimum": 0,
14460
+ "exclusiveMinimum": true,
14461
+ "description": "Character threshold after which tool execution response are saved to a file in workbench. Default is 20k."
14462
+ }
14463
+ },
14464
+ "default": {
14465
+ "enable": true,
14466
+ "proxy_execution_enabled": true
14467
+ },
14468
+ "description": "Workbench configuration"
14469
+ }
14470
},
15043
- "slack": {
15044
- "disable": [
15045
- "SLACK_ADD_EMOJI"
15046
- ]
14471
+ "required": [
14472
+ "user_id"
14473
+ ],
14474
+ "description": "The session configuration including user, toolkits, and overrides"
14475
+ },
14476
+ "experimental": {
14477
+ "type": "object",
14478
+ "properties": {
14479
+ "assistive_prompt": {
14480
+ "type": "string",
14481
+ "description": "The assistive system prompt for the tool router session"
14482
+ },
14483
+ "custom_toolkits": {
14484
+ "type": "array",
14485
+ "items": {
14486
+ "type": "object",
14487
+ "properties": {
14488
+ "slug": {
14489
+ "type": "string",
14490
+ "minLength": 1,
14491
+ "pattern": "^[a-zA-Z0-9_-]+$"
14492
+ },
14493
+ "name": {
14494
+ "type": "string",
14495
+ "minLength": 1,
14496
+ "maxLength": 128
14497
+ },
14498
+ "description": {
14499
+ "type": "string",
14500
+ "minLength": 1,
14501
+ "maxLength": 2048
14502
+ },
14503
+ "tools": {
14504
+ "type": "array",
14505
+ "items": {
14506
+ "type": "object",
14507
+ "properties": {
14508
+ "slug": {
14509
+ "type": "string",
14510
+ "description": "Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)"
14511
+ },
14512
+ "name": {
14513
+ "type": "string",
14514
+ "minLength": 1,
14515
+ "maxLength": 128
14516
+ },
14517
+ "description": {
14518
+ "type": "string",
14519
+ "minLength": 1,
14520
+ "maxLength": 5120
14521
+ },
14522
+ "input_schema": {
14523
+ "type": "object",
14524
+ "additionalProperties": {}
14525
+ },
14526
+ "output_schema": {
14527
+ "type": "object",
14528
+ "additionalProperties": {}
14529
+ },
14530
+ "original_slug": {
14531
+ "type": "string",
14532
+ "description": "Original tool slug as provided by the user"
14533
+ }
14534
+ },
14535
+ "required": [
14536
+ "slug",
14537
+ "name",
14538
+ "description",
14539
+ "input_schema",
14540
+ "original_slug"
14541
+ ]
14542
+ }
14543
+ }
14544
+ },
14545
+ "required": [
14546
+ "slug",
14547
+ "name",
14548
+ "description",
14549
+ "tools"
14550
+ ]
14551
+ },
14552
+ "description": "User-defined custom toolkits with grouped tools (no-auth)"
14553
+ },
14554
+ "custom_tools": {
14555
+ "type": "array",
14556
+ "items": {
14557
+ "type": "object",
14558
+ "properties": {
14559
+ "slug": {
14560
+ "type": "string",
14561
+ "description": "Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)"
14562
+ },
14563
+ "name": {
14564
+ "type": "string",
14565
+ "minLength": 1,
14566
+ "maxLength": 128
14567
+ },
14568
+ "description": {
14569
+ "type": "string",
14570
+ "minLength": 1,
14571
+ "maxLength": 5120
14572
+ },
14573
+ "input_schema": {
14574
+ "type": "object",
14575
+ "additionalProperties": {}
14576
+ },
14577
+ "output_schema": {
14578
+ "type": "object",
14579
+ "additionalProperties": {}
14580
+ },
14581
+ "extends_toolkit": {
14582
+ "type": "string",
14583
+ "minLength": 1
14584
+ },
14585
+ "original_slug": {
14586
+ "type": "string",
14587
+ "description": "Original tool slug as provided by the user"
14588
+ }
14589
+ },
14590
+ "required": [
14591
+ "slug",
14592
+ "name",
14593
+ "description",
14594
+ "input_schema",
14595
+ "original_slug"
14596
+ ]
14597
+ },
14598
+ "description": "Custom tools — standalone or extending Composio toolkits"
14599
+ }
14600
},
15048
- "slack_bot": {
15049
- "tags": [
15050
- "destructiveHint"
15051
- ]
14601
+ "description": "Experimental features including the generated system prompt. Only returned on session creation, not on GET.",
14602
+ "x-experimental": true
14603
+ }
14604
+ },
14605
+ "required": [
14606
+ "session_id",
14607
+ "mcp",
14608
+ "tool_router_tools",
14609
+ "config"
14610
+ ]
14611
+ }
14612
+ }
14613
+ }
14614
+ },
14615
+ "400": {
14616
+ "description": "Bad request. This may occur if the user_id format is invalid, toolkit names are invalid, or auth_config_id IDs are malformed.",
14617
+ "content": {
14618
+ "application/json": {
14619
+ "schema": {
14620
+ "$ref": "#/components/schemas/Error"
14621
+ }
14622
+ }
14623
+ }
14624
+ },
14625
+ "401": {
14626
+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",
14627
+ "content": {
14628
+ "application/json": {
14629
+ "schema": {
14630
+ "$ref": "#/components/schemas/Error"
14631
+ }
14632
+ }
14633
+ }
14634
+ },
14635
+ "403": {
14636
+ "description": "Forbidden. The user is not authorized to create a tool router session.",
14637
+ "content": {
14638
+ "application/json": {
14639
+ "schema": {
14640
+ "$ref": "#/components/schemas/Error"
14641
+ }
14642
+ }
14643
+ }
14644
+ },
14645
+ "500": {
14646
+ "description": "Internal server error. An unexpected error occurred while processing the request.",
14647
+ "content": {
14648
+ "application/json": {
14649
+ "schema": {
14650
+ "$ref": "#/components/schemas/Error"
14651
+ }
14652
+ }
14653
+ }
14654
+ }
14655
+ }
14656
+ }
14657
+ },
14658
+ "/api/v3/tool_router/session/{session_id}/execute": {
14659
+ "post": {
14660
+ "summary": "Execute a tool within a tool router session",
14661
+ "description": "Executes a specific tool within a tool router session. The toolkit is automatically inferred from the tool slug. The tool must belong to an allowed toolkit and must not be disabled in the session configuration. This endpoint validates permissions, resolves connected accounts, and executes the tool with the session context.",
14662
+ "tags": [
14663
+ "Tool Router"
14664
+ ],
14665
+ "operationId": "postToolRouterSessionBySessionIdExecute",
14666
+ "security": [
14667
+ {
14668
+ "ApiKeyAuth": []
14669
+ },
14670
+ {
14671
+ "UserApiKeyAuth": []
14672
+ },
14673
+ {
14674
+ "workbench_access_key": []
14675
+ }
14676
+ ],
14677
+ "parameters": [
14678
+ {
14679
+ "schema": {
14680
+ "type": "string",
14681
+ "format": "toolRouterSessionId",
14682
+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",
14683
+ "example": "trs_LX9uJKBinWWr"
14684
+ },
14685
+ "required": false,
14686
+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",
14687
+ "name": "session_id",
14688
+ "in": "path"
14689
+ }
14690
+ ],
14691
+ "requestBody": {
14692
+ "content": {
14693
+ "application/json": {
14694
+ "schema": {
14695
+ "type": "object",
14696
+ "properties": {
14697
+ "tool_slug": {
14698
+ "type": "string",
14699
+ "minLength": 1,
14700
+ "description": "The unique slug identifier of the tool to execute",
14701
+ "example": "GITHUB_CREATE_ISSUE"
14702
+ },
14703
+ "arguments": {
14704
+ "type": "object",
14705
+ "additionalProperties": {},
14706
+ "default": {},
14707
+ "description": "The arguments required by the tool",
14708
+ "example": {
14709
+ "repository": "octocat/Hello-World",
14710
+ "workflow_id": "main.yml",
14711
+ "ref": "main",
14712
+ "inputs": {
14713
+ "environment": "production"
14714
+ }
14715
+ }
14716
+ },
14717
+ "account": {
14718
+ "type": "string",
14719
+ "description": "Account identifier to specify which connected account to use. Use the account ID (e.g. \"coup_hurricane_dal_analytical\") or an alias. When omitted with a single account, the default is used. When omitted with multiple accounts, an error lists available accounts.",
14720
+ "example": "coup_hurricane_dal_analytical"
14721
+ }
14722
+ },
14723
+ "required": [
14724
+ "tool_slug"
14725
+ ]
14726
+ }
14727
+ }
14728
+ }
14729
+ },
14730
+ "responses": {
14731
+ "200": {
14732
+ "description": "Successfully executed the tool. Returns execution result, logs, and status.",
14733
+ "content": {
14734
+ "application/json": {
14735
+ "schema": {
14736
+ "type": "object",
14737
+ "properties": {
14738
+ "data": {
14739
+ "type": "object",
14740
+ "additionalProperties": {},
14741
+ "description": "The data returned by the tool execution",
14742
+ "example": {
14743
+ "message": "Hello, World!",
14744
+ "status": "success"
14745
}
14746
},
15054
- "tags": [
15055
- "destructiveHint",
15056
- "idempotentHint"
14747
+ "error": {
14748
+ "type": "string",
14749
+ "nullable": true,
14750
+ "description": "Error message if the execution failed, null otherwise"
14751
+ },
14752
+ "log_id": {
14753
+ "type": "string",
14754
+ "description": "Unique identifier for the execution log",
14755
+ "example": "log_abc123xyz"
14756
+ }
14757
+ },
14758
+ "required": [
14759
+ "data",
14760
+ "error",
14761
+ "log_id"
14762
+ ]
14763
+ }
14764
+ }
14765
+ }
14766
+ },
14767
+ "400": {
14768
+ "description": "Bad request",
14769
+ "content": {
14770
+ "application/json": {
14771
+ "schema": {
14772
+ "$ref": "#/components/schemas/Error"
14773
+ }
14774
+ }
14775
+ }
14776
+ },
14777
+ "401": {
14778
+ "description": "Unauthorized",
14779
+ "content": {
14780
+ "application/json": {
14781
+ "schema": {
14782
+ "$ref": "#/components/schemas/Error"
14783
+ }
14784
+ }
14785
+ }
14786
+ },
14787
+ "403": {
14788
+ "description": "Forbidden",
14789
+ "content": {
14790
+ "application/json": {
14791
+ "schema": {
14792
+ "$ref": "#/components/schemas/Error"
14793
+ }
14794
+ }
14795
+ }
14796
+ },
14797
+ "404": {
14798
+ "description": "Not found",
14799
+ "content": {
14800
+ "application/json": {
14801
+ "schema": {
14802
+ "$ref": "#/components/schemas/Error"
14803
+ }
14804
+ }
14805
+ }
14806
+ },
14807
+ "413": {
14808
+ "description": "Payload too large",
14809
+ "content": {
14810
+ "application/json": {
14811
+ "schema": {
14812
+ "$ref": "#/components/schemas/Error"
14813
+ }
14814
+ }
14815
+ }
14816
+ },
14817
+ "500": {
14818
+ "description": "Internal server error",
14819
+ "content": {
14820
+ "application/json": {
14821
+ "schema": {
14822
+ "$ref": "#/components/schemas/Error"
14823
+ }
14824
+ }
14825
+ }
14826
+ }
14827
+ }
14828
+ }
14829
+ },
14830
+ "/api/v3/tool_router/session/{session_id}/execute_meta": {
14831
+ "post": {
14832
+ "summary": "Execute a meta tool within a tool router session",
14833
+ "description": "Executes a Composio meta tool (COMPOSIO_*) within a tool router session.",
14834
+ "tags": [
14835
+ "Tool Router"
14836
+ ],
14837
+ "operationId": "postToolRouterSessionBySessionIdExecuteMeta",
14838
+ "security": [
14839
+ {
14840
+ "ApiKeyAuth": []
14841
+ },
14842
+ {
14843
+ "UserApiKeyAuth": []
14844
+ }
14845
+ ],
14846
+ "parameters": [
14847
+ {
14848
+ "schema": {
14849
+ "type": "string",
14850
+ "format": "toolRouterSessionId",
14851
+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",
14852
+ "example": "trs_LX9uJKBinWWr"
14853
+ },
14854
+ "required": false,
14855
+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",
14856
+ "name": "session_id",
14857
+ "in": "path"
14858
+ }
14859
+ ],
14860
+ "requestBody": {
14861
+ "content": {
14862
+ "application/json": {
14863
+ "schema": {
14864
+ "type": "object",
14865
+ "properties": {
14866
+ "slug": {
14867
+ "type": "string",
14868
+ "enum": [
14869
+ "COMPOSIO_SEARCH_TOOLS",
14870
+ "COMPOSIO_MULTI_EXECUTE_TOOL",
14871
+ "COMPOSIO_MANAGE_CONNECTIONS",
14872
+ "COMPOSIO_WAIT_FOR_CONNECTIONS",
14873
+ "COMPOSIO_REMOTE_WORKBENCH",
14874
+ "COMPOSIO_REMOTE_BASH_TOOL",
14875
+ "COMPOSIO_GET_TOOL_SCHEMAS",
14876
+ "COMPOSIO_UPSERT_RECIPE",
14877
+ "COMPOSIO_GET_RECIPE"
14878
],
15058
- "workbench": {
15059
- "enable_proxy_execution": true,
15060
- "auto_offload_threshold": 10000
14879
+ "description": "The unique slug identifier of the meta tool to execute",
14880
+ "example": "COMPOSIO_MANAGE_CONNECTIONS"
14881
+ },
14882
+ "arguments": {
14883
+ "type": "object",
14884
+ "additionalProperties": {},
14885
+ "default": {},
14886
+ "description": "The arguments required by the meta tool",
14887
+ "example": {
14888
+ "toolkits": [
14889
+ "github"
14890
+ ],
14891
+ "reinitiate_all": false
14892
}
14893
}
14894
},
15064
- "Session with disabled toolkits and global tags": {
15065
- "value": {
15066
- "user_id": "user_123456789",
15067
- "toolkits": {
15068
- "disable": [
15069
- "gmail"
15070
- ]
14895
+ "required": [
14896
+ "slug"
14897
+ ]
14898
+ }
14899
+ }
14900
+ }
14901
+ },
14902
+ "responses": {
14903
+ "200": {
14904
+ "description": "Successfully executed the meta tool. Returns execution result, logs, and status.",
14905
+ "content": {
14906
+ "application/json": {
14907
+ "schema": {
14908
+ "type": "object",
14909
+ "properties": {
14910
+ "data": {
14911
+ "type": "object",
14912
+ "additionalProperties": {},
14913
+ "description": "The data returned by the tool execution",
14914
+ "example": {
14915
+ "message": "Hello, World!",
14916
+ "status": "success"
14917
+ }
14918
},
15072
- "tags": [
15073
- "readOnlyHint"
15074
- ]
15075
- }
14919
+ "error": {
14920
+ "type": "string",
14921
+ "nullable": true,
14922
+ "description": "Error message if the execution failed, null otherwise"
14923
+ },
14924
+ "log_id": {
14925
+ "type": "string",
14926
+ "description": "Unique identifier for the execution log",
14927
+ "example": "log_abc123xyz"
14928
+ }
14929
+ },
14930
+ "required": [
14931
+ "data",
14932
+ "error",
14933
+ "log_id"
14934
+ ]
14935
+ }
14936
+ }
14937
+ }
14938
+ },
14939
+ "400": {
14940
+ "description": "Bad request",
14941
+ "content": {
14942
+ "application/json": {
14943
+ "schema": {
14944
+ "$ref": "#/components/schemas/Error"
14945
+ }
14946
+ }
14947
+ }
14948
+ },
14949
+ "401": {
14950
+ "description": "Unauthorized",
14951
+ "content": {
14952
+ "application/json": {
14953
+ "schema": {
14954
+ "$ref": "#/components/schemas/Error"
14955
+ }
14956
+ }
14957
+ }
14958
+ },
14959
+ "403": {
14960
+ "description": "Forbidden",
14961
+ "content": {
14962
+ "application/json": {
14963
+ "schema": {
14964
+ "$ref": "#/components/schemas/Error"
14965
+ }
14966
+ }
14967
+ }
14968
+ },
14969
+ "404": {
14970
+ "description": "Not found",
14971
+ "content": {
14972
+ "application/json": {
14973
+ "schema": {
14974
+ "$ref": "#/components/schemas/Error"
14975
+ }
14976
+ }
14977
+ }
14978
+ },
14979
+ "413": {
14980
+ "description": "Payload too large",
14981
+ "content": {
14982
+ "application/json": {
14983
+ "schema": {
14984
+ "$ref": "#/components/schemas/Error"
14985
+ }
14986
+ }
14987
+ }
14988
+ },
14989
+ "500": {
14990
+ "description": "Internal server error",
14991
+ "content": {
14992
+ "application/json": {
14993
+ "schema": {
14994
+ "$ref": "#/components/schemas/Error"
14995
}
14996
}
14997
}
14998
}
15080
- },
14999
+ }
15000
+ }
15001
+ },
15002
+ "/api/v3/tool_router/session/{session_id}": {
15003
+ "get": {
15004
+ "summary": "Get a tool router session by ID",
15005
+ "description": "Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.",
15006
+ "tags": [
15007
+ "Tool Router"
15008
+ ],
15009
+ "operationId": "getToolRouterSessionBySessionId",
15010
+ "security": [
15011
+ {
15012
+ "ApiKeyAuth": []
15013
+ },
15014
+ {
15015
+ "UserApiKeyAuth": []
15016
+ }
15017
+ ],
15018
+ "parameters": [
15019
+ {
15020
+ "schema": {
15021
+ "type": "string",
15022
+ "format": "toolRouterSessionId",
15023
+ "description": "The session ID returned when creating the session",
15024
+ "example": "trs_123456789"
15025
+ },
15026
+ "required": true,
15027
+ "description": "The unique identifier of the tool router session",
15028
+ "name": "session_id",
15029
+ "in": "path"
15030
+ }
15031
+ ],
15032
"responses": {
15082
- "201": {
15083
- "description": "Session successfully created. Returns the session ID and MCP server URL for the created session.",
15033
+ "200": {
15034
+ "description": "Session successfully retrieved. Returns the session details including configuration.",
15035
"content": {
15036
"application/json": {
15037
"schema": {
@@ -15452,192 +15403,40 @@
15403
},
15404
"extends_toolkit": {
15405
"type": "string",
15455
- "minLength": 1
15456
- },
15457
- "original_slug": {
15458
- "type": "string",
15459
- "description": "Original tool slug as provided by the user"
15460
- }
15461
- },
15462
- "required": [
15463
- "slug",
15464
- "name",
15465
- "description",
15466
- "input_schema",
15467
- "original_slug"
15468
- ]
15469
- },
15470
- "description": "Custom tools — standalone or extending Composio toolkits"
15471
- }
15472
- },
15473
- "description": "Experimental features including the generated system prompt. Only returned on session creation, not on GET.",
15474
- "x-experimental": true
15475
- }
15476
- },
15477
- "required": [
15478
- "session_id",
15479
- "mcp",
15480
- "tool_router_tools",
15481
- "config"
15482
- ]
15483
- }
15484
- }
15485
- }
15486
- },
15487
- "400": {
15488
- "description": "Bad request. This may occur if the user_id format is invalid, toolkit names are invalid, or auth_config_id IDs are malformed.",
15489
- "content": {
15490
- "application/json": {
15491
- "schema": {
15492
- "$ref": "#/components/schemas/Error"
15493
- }
15494
- }
15495
- }
15496
- },
15497
- "401": {
15498
- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",
15499
- "content": {
15500
- "application/json": {
15501
- "schema": {
15502
- "$ref": "#/components/schemas/Error"
15503
- }
15504
- }
15505
- }
15506
- },
15507
- "403": {
15508
- "description": "Forbidden. The user is not authorized to create a tool router session.",
15509
- "content": {
15510
- "application/json": {
15511
- "schema": {
15512
- "$ref": "#/components/schemas/Error"
15513
- }
15514
- }
15515
- }
15516
- },
15517
- "500": {
15518
- "description": "Internal server error. An unexpected error occurred while processing the request.",
15519
- "content": {
15520
- "application/json": {
15521
- "schema": {
15522
- "$ref": "#/components/schemas/Error"
15523
- }
15524
- }
15525
- }
15526
- }
15527
- }
15528
- }
15529
- },
15530
- "/api/v3/tool_router/session/{session_id}/execute": {
15531
- "post": {
15532
- "summary": "Execute a tool within a tool router session",
15533
- "description": "Executes a specific tool within a tool router session. The toolkit is automatically inferred from the tool slug. The tool must belong to an allowed toolkit and must not be disabled in the session configuration. This endpoint validates permissions, resolves connected accounts, and executes the tool with the session context.",
15534
- "tags": [
15535
- "Tool Router"
15536
- ],
15537
- "operationId": "postToolRouterSessionBySessionIdExecute",
15538
- "security": [
15539
- {
15540
- "ApiKeyAuth": []
15541
- },
15542
- {
15543
- "UserApiKeyAuth": []
15544
- },
15545
- {
15546
- "workbench_access_key": []
15547
- }
15548
- ],
15549
- "parameters": [
15550
- {
15551
- "schema": {
15552
- "type": "string",
15553
- "format": "toolRouterSessionId",
15554
- "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",
15555
- "example": "trs_LX9uJKBinWWr"
15556
- },
15557
- "required": false,
15558
- "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",
15559
- "name": "session_id",
15560
- "in": "path"
15561
- }
15562
- ],
15563
- "requestBody": {
15564
- "content": {
15565
- "application/json": {
15566
- "schema": {
15567
- "type": "object",
15568
- "properties": {
15569
- "tool_slug": {
15570
- "type": "string",
15571
- "minLength": 1,
15572
- "description": "The unique slug identifier of the tool to execute",
15573
- "example": "GITHUB_CREATE_ISSUE"
15574
- },
15575
- "arguments": {
15576
- "type": "object",
15577
- "additionalProperties": {},
15578
- "default": {},
15579
- "description": "The arguments required by the tool",
15580
- "example": {
15581
- "repository": "octocat/Hello-World",
15582
- "workflow_id": "main.yml",
15583
- "ref": "main",
15584
- "inputs": {
15585
- "environment": "production"
15586
- }
15587
- }
15588
- },
15589
- "account": {
15590
- "type": "string",
15591
- "description": "Account identifier to specify which connected account to use. Use the account ID (e.g. \"coup_hurricane_dal_analytical\") or an alias. When omitted with a single account, the default is used. When omitted with multiple accounts, an error lists available accounts.",
15592
- "example": "coup_hurricane_dal_analytical"
15593
- }
15594
- },
15595
- "required": [
15596
- "tool_slug"
15597
- ]
15598
- }
15599
- }
15600
- }
15601
- },
15602
- "responses": {
15603
- "200": {
15604
- "description": "Successfully executed the tool. Returns execution result, logs, and status.",
15605
- "content": {
15606
- "application/json": {
15607
- "schema": {
15608
- "type": "object",
15609
- "properties": {
15610
- "data": {
15611
- "type": "object",
15612
- "additionalProperties": {},
15613
- "description": "The data returned by the tool execution",
15614
- "example": {
15615
- "message": "Hello, World!",
15616
- "status": "success"
15617
- }
15618
- },
15619
- "error": {
15620
- "type": "string",
15621
- "nullable": true,
15622
- "description": "Error message if the execution failed, null otherwise"
15623
- },
15624
- "log_id": {
15625
- "type": "string",
15626
- "description": "Unique identifier for the execution log",
15627
- "example": "log_abc123xyz"
15406
+ "minLength": 1
15407
+ },
15408
+ "original_slug": {
15409
+ "type": "string",
15410
+ "description": "Original tool slug as provided by the user"
15411
+ }
15412
+ },
15413
+ "required": [
15414
+ "slug",
15415
+ "name",
15416
+ "description",
15417
+ "input_schema",
15418
+ "original_slug"
15419
+ ]
15420
+ },
15421
+ "description": "Custom tools — standalone or extending Composio toolkits"
15422
+ }
15423
+ },
15424
+ "description": "Experimental features",
15425
+ "x-experimental": true
15426
}
15427
},
15428
"required": [
15631
- "data",
15632
- "error",
15633
- "log_id"
15429
+ "session_id",
15430
+ "mcp",
15431
+ "tool_router_tools",
15432
+ "config"
15433
]
15434
}
15435
}
15436
}
15437
},
15438
"400": {
15640
- "description": "Bad request",
15439
+ "description": "Bad request. This may occur if the session_id format is invalid, please pass this in trs_ prefix format",
15440
"content": {
15441
"application/json": {
15442
"schema": {
@@ -15647,17 +15446,7 @@
15446
}
15447
},
15448
"401": {
15650
- "description": "Unauthorized",
15651
- "content": {
15652
- "application/json": {
15653
- "schema": {
15654
- "$ref": "#/components/schemas/Error"
15655
- }
15656
- }
15657
- }
15658
- },
15659
- "403": {
15660
- "description": "Forbidden",
15449
+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",
15450
"content": {
15451
"application/json": {
15452
"schema": {
@@ -15667,17 +15456,7 @@
15456
}
15457
},
15458
"404": {
15670
- "description": "Not found",
15671
- "content": {
15672
- "application/json": {
15673
- "schema": {
15674
- "$ref": "#/components/schemas/Error"
15675
- }
15676
- }
15677
- }
15678
- },
15679
- "413": {
15680
- "description": "Payload too large",
15459
+ "description": "Not found. The session with the provided ID does not exist or has been deleted.",
15460
"content": {
15461
"application/json": {
15462
"schema": {
@@ -15687,7 +15466,7 @@
15466
}
15467
},
15468
"500": {
15690
- "description": "Internal server error",
15469
+ "description": "Internal server error. An unexpected error occurred while processing the request.",
15470
"content": {
15471
"application/json": {
15472
"schema": {
@@ -15699,14 +15478,14 @@
15478
}
15479
}
15480
},
15702
- "/api/v3/tool_router/session/{session_id}/execute_meta": {
15481
+ "/api/v3/tool_router/session/{session_id}/link": {
15482
"post": {
15704
- "summary": "Execute a meta tool within a tool router session",
15705
- "description": "Executes a Composio meta tool (COMPOSIO_*) within a tool router session.",
15483
+ "summary": "Create a link session for a toolkit in a tool router session",
15484
+ "description": "Initiates an authentication link session for a specific toolkit within a tool router session. Returns a link token and redirect URL that users can use to complete the OAuth flow.",
15485
"tags": [
15486
"Tool Router"
15487
],
15709
- "operationId": "postToolRouterSessionBySessionIdExecuteMeta",
15488
+ "operationId": "postToolRouterSessionBySessionIdLink",
15489
"security": [
15490
{
15491
"ApiKeyAuth": []
@@ -15720,11 +15499,11 @@
15499
"schema": {
15500
"type": "string",
15501
"format": "toolRouterSessionId",
15723
- "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",
15502
+ "description": "The session ID returned when creating the session",
15503
"example": "trs_LX9uJKBinWWr"
15504
},
15726
- "required": false,
15727
- "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",
15505
+ "required": true,
15506
+ "description": "The unique identifier of the tool router session",
15507
"name": "session_id",
15508
"in": "path"
15509
}
@@ -15735,81 +15514,63 @@
15514
"schema": {
15515
"type": "object",
15516
"properties": {
15738
- "slug": {
15517
+ "toolkit": {
15518
"type": "string",
15740
- "enum": [
15741
- "COMPOSIO_SEARCH_TOOLS",
15742
- "COMPOSIO_MULTI_EXECUTE_TOOL",
15743
- "COMPOSIO_MANAGE_CONNECTIONS",
15744
- "COMPOSIO_WAIT_FOR_CONNECTIONS",
15745
- "COMPOSIO_REMOTE_WORKBENCH",
15746
- "COMPOSIO_REMOTE_BASH_TOOL",
15747
- "COMPOSIO_GET_TOOL_SCHEMAS",
15748
- "COMPOSIO_UPSERT_RECIPE",
15749
- "COMPOSIO_GET_RECIPE"
15750
- ],
15751
- "description": "The unique slug identifier of the meta tool to execute",
15752
- "example": "COMPOSIO_MANAGE_CONNECTIONS"
15519
+ "minLength": 1,
15520
+ "description": "The unique slug identifier of the toolkit to connect",
15521
+ "example": "github"
15522
},
15754
- "arguments": {
15755
- "type": "object",
15756
- "additionalProperties": {},
15757
- "default": {},
15758
- "description": "The arguments required by the meta tool",
15759
- "example": {
15760
- "toolkits": [
15761
- "github"
15762
- ],
15763
- "reinitiate_all": false
15764
- }
15523
+ "callback_url": {
15524
+ "type": "string",
15525
+ "format": "uri",
15526
+ "description": "URL where users will be redirected after completing auth",
15527
+ "example": "https://myapp.com/callback"
15528
}
15529
},
15530
"required": [
15768
- "slug"
15531
+ "toolkit"
15532
]
15533
}
15534
}
15535
}
15536
},
15537
"responses": {
15775
- "200": {
15776
- "description": "Successfully executed the meta tool. Returns execution result, logs, and status.",
15538
+ "201": {
15539
+ "description": "Successfully created link session. Returns link token, redirect URL, and connected account ID.",
15540
"content": {
15541
"application/json": {
15542
"schema": {
15543
"type": "object",
15544
"properties": {
15782
- "data": {
15783
- "type": "object",
15784
- "additionalProperties": {},
15785
- "description": "The data returned by the tool execution",
15786
- "example": {
15787
- "message": "Hello, World!",
15788
- "status": "success"
15789
- }
15545
+ "link_token": {
15546
+ "type": "string",
15547
+ "description": "Token used to complete the authentication flow",
15548
+ "example": "lt_abc123xyz"
15549
},
15791
- "error": {
15550
+ "redirect_url": {
15551
"type": "string",
15793
- "nullable": true,
15794
- "description": "Error message if the execution failed, null otherwise"
15552
+ "format": "uri",
15553
+ "description": "The URL where users should be redirected to complete OAuth",
15554
+ "example": "https://app.composio.dev/link/lt_abc123xyz"
15555
},
15796
- "log_id": {
15556
+ "connected_account_id": {
15557
"type": "string",
15798
- "description": "Unique identifier for the execution log",
15799
- "example": "log_abc123xyz"
15558
+ "format": "connectedAccountId",
15559
+ "description": "The unique identifier for the connected account",
15560
+ "example": "ca_abc123xyz"
15561
}
15562
},
15563
"required": [
15803
- "data",
15804
- "error",
15805
- "log_id"
15564
+ "link_token",
15565
+ "redirect_url",
15566
+ "connected_account_id"
15567
]
15568
}
15569
}
15570
}
15571
},
15572
"400": {
15812
- "description": "Bad request",
15573
+ "description": "Bad request. This may occur if the toolkit slug is invalid, request parameters are malformed, or a connected account is already defined for this toolkit in the session configuration.",
15574
"content": {
15575
"application/json": {
15576
"schema": {
@@ -15819,7 +15580,7 @@
15580
}
15581
},
15582
"401": {
15822
- "description": "Unauthorized",
15583
+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",
15584
"content": {
15585
"application/json": {
15586
"schema": {
@@ -15829,7 +15590,7 @@
15590
}
15591
},
15592
"403": {
15832
- "description": "Forbidden",
15593
+ "description": "Forbidden. The session does not belong to the authenticated user.",
15594
"content": {
15595
"application/json": {
15596
"schema": {
@@ -15839,17 +15600,7 @@
15600
}
15601
},
15602
"404": {
15842
- "description": "Not found",
15843
- "content": {
15844
- "application/json": {
15845
- "schema": {
15846
- "$ref": "#/components/schemas/Error"
15847
- }
15848
- }
15849
- }
15850
- },
15851
- "413": {
15852
- "description": "Payload too large",
15603
+ "description": "Not found. The session does not exist, toolkit not found, or no auth config exists for the toolkit.",
15604
"content": {
15605
"application/json": {
15606
"schema": {
@@ -15859,7 +15610,7 @@
15610
}
15611
},
15612
"500": {
15862
- "description": "Internal server error",
15613
+ "description": "Internal server error. An unexpected error occurred while creating the link session.",
15614
"content": {
15615
"application/json": {
15616
"schema": {
@@ -15871,20 +15622,23 @@
15622
}
15623
}
15624
},
15874
- "/api/v3/tool_router/session/{session_id}": {
15875
- "get": {
15876
- "summary": "Get a tool router session by ID",
15877
- "description": "Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.",
15625
+ "/api/v3/tool_router/session/{session_id}/proxy_execute": {
15626
+ "post": {
15627
+ "summary": "Execute proxy request within a tool router session",
15628
+ "description": "Execute any native API call on a toolkit with authentication automatically injected from Composio. This endpoint proxies HTTP requests to third-party APIs using connected account credentials resolved from the session context. Provide the toolkit slug, API endpoint, and HTTP method — Composio handles authentication injection, abstracting away credential management. Supports all HTTP methods, custom headers/query parameters, and binary request/response bodies.",
15629
"tags": [
15630
"Tool Router"
15631
],
15881
- "operationId": "getToolRouterSessionBySessionId",
15632
+ "operationId": "postToolRouterSessionBySessionIdProxyExecute",
15633
"security": [
15634
{
15635
"ApiKeyAuth": []
15636
},
15637
{
15638
"UserApiKeyAuth": []
15639
+ },
15640
+ {
15641
+ "workbench_access_key": []
15642
}
15643
],
15644
"parameters": [
@@ -15892,423 +15646,621 @@
15646
"schema": {
15647
"type": "string",
15648
"format": "toolRouterSessionId",
15895
- "description": "The session ID returned when creating the session",
15896
- "example": "trs_123456789"
15649
+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",
15650
+ "example": "trs_LX9uJKBinWWr"
15651
},
15898
- "required": true,
15899
- "description": "The unique identifier of the tool router session",
15652
+ "required": false,
15653
+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",
15654
"name": "session_id",
15655
"in": "path"
15656
}
15657
],
15904
- "responses": {
15905
- "200": {
15906
- "description": "Session successfully retrieved. Returns the session details including configuration.",
15907
- "content": {
15908
- "application/json": {
15909
- "schema": {
15910
- "type": "object",
15911
- "properties": {
15912
- "session_id": {
15913
- "type": "string",
15914
- "format": "toolRouterSessionId",
15915
- "description": "The identifier of the session",
15916
- "example": "trs_123456789"
15658
+ "requestBody": {
15659
+ "content": {
15660
+ "application/json": {
15661
+ "schema": {
15662
+ "type": "object",
15663
+ "properties": {
15664
+ "toolkit_slug": {
15665
+ "type": "string",
15666
+ "description": "The slug of the toolkit to use for the request",
15667
+ "example": "gmail"
15668
+ },
15669
+ "endpoint": {
15670
+ "type": "string",
15671
+ "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",
15672
+ "example": "/api/v1/resources"
15673
+ },
15674
+ "method": {
15675
+ "type": "string",
15676
+ "enum": [
15677
+ "GET",
15678
+ "POST",
15679
+ "PUT",
15680
+ "DELETE",
15681
+ "PATCH",
15682
+ "HEAD"
15683
+ ],
15684
+ "description": "The HTTP method to use for the request",
15685
+ "example": "GET"
15686
+ },
15687
+ "body": {
15688
+ "nullable": true,
15689
+ "description": "The request body (for POST, PUT, and PATCH requests)",
15690
+ "example": {
15691
+ "name": "New Resource",
15692
+ "description": "This is a new resource"
15693
},
15918
- "mcp": {
15694
+ "type": "object"
15695
+ },
15696
+ "binary_body": {
15697
+ "anyOf": [
15698
+ {
15699
+ "type": "object",
15700
+ "properties": {
15701
+ "url": {
15702
+ "type": "string",
15703
+ "format": "uri",
15704
+ "description": "URL to fetch binary content from"
15705
+ },
15706
+ "content_type": {
15707
+ "type": "string",
15708
+ "description": "Content-Type header to use for the request"
15709
+ }
15710
+ },
15711
+ "required": [
15712
+ "url"
15713
+ ]
15714
+ },
15715
+ {
15716
+ "type": "object",
15717
+ "properties": {
15718
+ "base64": {
15719
+ "type": "string",
15720
+ "minLength": 1,
15721
+ "description": "Base64-encoded binary data"
15722
+ },
15723
+ "content_type": {
15724
+ "type": "string",
15725
+ "description": "Content-Type header to use for the request"
15726
+ }
15727
+ },
15728
+ "required": [
15729
+ "base64"
15730
+ ]
15731
+ }
15732
+ ],
15733
+ "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."
15734
+ },
15735
+ "parameters": {
15736
+ "type": "array",
15737
+ "items": {
15738
"type": "object",
15739
"properties": {
15740
+ "name": {
15741
+ "type": "string",
15742
+ "description": "Parameter name",
15743
+ "example": "x-api-key"
15744
+ },
15745
+ "value": {
15746
+ "type": "string",
15747
+ "description": "Parameter value",
15748
+ "example": "abc123def456"
15749
+ },
15750
"type": {
15751
"type": "string",
15752
"enum": [
15924
- "http"
15753
+ "header",
15754
+ "query"
15755
],
15926
- "description": "The type of the MCP server. Can be http"
15927
- },
15928
- "url": {
15929
- "type": "string",
15930
- "format": "uri",
15931
- "description": "The URL of the MCP server",
15932
- "example": "https://app.composio.dev/tool_router/v3/trs_123456789/mcp"
15756
+ "description": "Parameter type (header or query)",
15757
+ "example": "header"
15758
}
15759
},
15760
"required": [
15936
- "type",
15937
- "url"
15761
+ "name",
15762
+ "value",
15763
+ "type"
15764
]
15765
},
15940
- "tool_router_tools": {
15941
- "type": "array",
15942
- "items": {
15766
+ "description": "Additional HTTP headers or query parameters to include in the request",
15767
+ "example": [
15768
+ {
15769
+ "name": "x-api-key",
15770
+ "value": "abc123def456",
15771
+ "type": "header"
15772
+ },
15773
+ {
15774
+ "name": "filter",
15775
+ "value": "active",
15776
+ "type": "query"
15777
+ }
15778
+ ]
15779
+ },
15780
+ "custom_connection_data": {
15781
+ "type": "object",
15782
+ "properties": {
15783
+ "authScheme": {
15784
+ "type": "string",
15785
+ "enum": [
15786
+ "OAUTH2",
15787
+ "DCR_OAUTH",
15788
+ "API_KEY",
15789
+ "BASIC_WITH_JWT",
15790
+ "BASIC",
15791
+ "BEARER_TOKEN",
15792
+ "OAUTH1",
15793
+ "NO_AUTH",
15794
+ "SERVICE_ACCOUNT",
15795
+ "GOOGLE_SERVICE_ACCOUNT",
15796
+ "S2S_OAUTH2"
15797
+ ]
15798
+ },
15799
+ "toolkitSlug": {
15800
"type": "string"
15801
},
15945
- "description": "List of available tools in this session"
15946
- },
15947
- "config": {
15948
- "type": "object",
15949
- "properties": {
15950
- "user_id": {
15951
- "type": "string",
15952
- "description": "User identifier for this session"
15953
- },
15954
- "toolkits": {
15955
- "anyOf": [
15956
- {
15957
- "type": "object",
15958
- "properties": {
15959
- "enabled": {
15960
- "type": "array",
15961
- "items": {
15962
- "type": "string"
15963
- }
15964
- }
15965
- },
15966
- "required": [
15967
- "enabled"
15968
- ],
15969
- "additionalProperties": false
15970
- },
15971
- {
15972
- "type": "object",
15973
- "properties": {
15974
- "disabled": {
15975
- "type": "array",
15976
- "items": {
15977
- "type": "string"
15978
- }
15979
- }
15980
- },
15981
- "required": [
15982
- "disabled"
15983
- ],
15984
- "additionalProperties": false
15985
- }
15986
- ],
15987
- "description": "Toolkit configuration - either enabled list or disabled list"
15988
- },
15989
- "auth_configs": {
15990
- "type": "object",
15991
- "additionalProperties": {
15992
- "type": "string",
15993
- "format": "authConfigId"
15802
+ "val": {
15803
+ "type": "object",
15804
+ "properties": {
15805
+ "subdomain": {
15806
+ "type": "string"
15807
},
15995
- "description": "Auth config overrides per toolkit"
15996
- },
15997
- "connected_accounts": {
15998
- "type": "object",
15999
- "additionalProperties": {
15808
+ "your-domain": {
15809
+ "type": "string"
15810
+ },
15811
+ "region": {
15812
+ "type": "string"
15813
+ },
15814
+ "shop": {
15815
+ "type": "string"
15816
+ },
15817
+ "account_url": {
15818
+ "type": "string"
15819
+ },
15820
+ "COMPANYDOMAIN": {
15821
+ "type": "string"
15822
+ },
15823
+ "extension": {
15824
+ "type": "string"
15825
+ },
15826
+ "form_api_base_url": {
15827
+ "type": "string"
15828
+ },
15829
+ "instanceEndpoint": {
15830
+ "type": "string"
15831
+ },
15832
+ "api_url": {
15833
+ "type": "string"
15834
+ },
15835
+ "borneo_dashboard_url": {
15836
+ "type": "string"
15837
+ },
15838
+ "proxy_username": {
15839
+ "type": "string"
15840
+ },
15841
+ "proxy_password": {
15842
+ "type": "string"
15843
+ },
15844
+ "domain": {
15845
+ "type": "string"
15846
+ },
15847
+ "version": {
15848
+ "type": "string"
15849
+ },
15850
+ "dc": {
15851
+ "type": "string"
15852
+ },
15853
+ "site_name": {
15854
+ "type": "string"
15855
+ },
15856
+ "instanceName": {
15857
+ "type": "string"
15858
+ },
15859
+ "account_id": {
15860
+ "type": "string"
15861
+ },
15862
+ "your_server": {
15863
+ "type": "string"
15864
+ },
15865
+ "server_location": {
15866
+ "type": "string"
15867
+ },
15868
+ "base_url": {
15869
+ "type": "string"
15870
+ },
15871
+ "state_prefix": {
15872
"type": "string",
16001
- "format": "connectedAccountId"
15873
+ "maxLength": 40,
15874
+ "description": "The oauth2 state prefix for the connection"
15875
},
16003
- "description": "Connected account overrides per toolkit"
16004
- },
16005
- "manage_connections": {
16006
- "type": "object",
16007
- "properties": {
16008
- "enabled": {
16009
- "type": "boolean",
16010
- "default": true,
16011
- "description": "Whether to enable the connection manager for automatic connection handling"
16012
- },
16013
- "callback_url": {
16014
- "type": "string",
16015
- "format": "uri",
16016
- "description": "Custom callback URL for connected account auth flows"
16017
- },
16018
- "enable_wait_for_connections": {
16019
- "type": "boolean",
16020
- "default": false,
16021
- "description": "Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models."
16022
- },
16023
- "enable_connection_removal": {
16024
- "type": "boolean",
16025
- "default": true,
16026
- "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS. Default true."
16027
- }
15876
+ "long_redirect_url": {
15877
+ "type": "boolean",
15878
+ "description": "Whether to return the redirect url without shortening"
15879
},
16029
- "description": "Manage connections configuration"
16030
- },
16031
- "tools": {
16032
- "type": "object",
16033
- "additionalProperties": {
15880
+ "access_token": {
15881
+ "type": "string"
15882
+ },
15883
+ "id_token": {
15884
+ "type": "string"
15885
+ },
15886
+ "token_type": {
15887
+ "type": "string"
15888
+ },
15889
+ "refresh_token": {
15890
+ "type": "string",
15891
+ "nullable": true
15892
+ },
15893
+ "expires_in": {
15894
"anyOf": [
15895
{
16036
- "type": "object",
16037
- "properties": {
16038
- "enabled": {
16039
- "type": "array",
16040
- "items": {
16041
- "type": "string"
16042
- }
16043
- }
16044
- },
16045
- "required": [
16046
- "enabled"
16047
- ],
16048
- "additionalProperties": false
15896
+ "type": "number"
15897
},
15898
{
16051
- "type": "object",
16052
- "properties": {
16053
- "disabled": {
16054
- "type": "array",
16055
- "items": {
16056
- "type": "string"
16057
- }
16058
- }
16059
- },
16060
- "required": [
16061
- "disabled"
16062
- ],
16063
- "additionalProperties": false
15899
+ "type": "string"
15900
},
15901
{
16066
- "type": "object",
16067
- "properties": {
16068
- "tags": {
16069
- "type": "object",
16070
- "properties": {
16071
- "enabled": {
16072
- "type": "array",
16073
- "items": {
16074
- "type": "string",
16075
- "enum": [
16076
- "readOnlyHint",
16077
- "destructiveHint",
16078
- "idempotentHint",
16079
- "openWorldHint"
16080
- ]
16081
- },
16082
- "description": "Tags that the tool must have at least one of"
16083
- },
16084
- "disabled": {
16085
- "type": "array",
16086
- "items": {
16087
- "type": "string",
16088
- "enum": [
16089
- "readOnlyHint",
16090
- "destructiveHint",
16091
- "idempotentHint",
16092
- "openWorldHint"
16093
- ]
16094
- },
16095
- "description": "Tags that the tool must NOT have any of"
16096
- }
16097
- }
16098
- }
16099
- },
16100
- "required": [
16101
- "tags"
16102
- ],
16103
- "additionalProperties": false
15902
+ "nullable": true,
15903
+ "type": "object"
15904
}
15905
]
15906
},
16107
- "description": "Tool-level configuration per toolkit"
16108
- },
16109
- "tags": {
16110
- "type": "object",
16111
- "properties": {
16112
- "enabled": {
16113
- "type": "array",
16114
- "items": {
16115
- "type": "string",
16116
- "enum": [
16117
- "readOnlyHint",
16118
- "destructiveHint",
16119
- "idempotentHint",
16120
- "openWorldHint"
16121
- ]
15907
+ "scope": {
15908
+ "anyOf": [
15909
+ {
15910
+ "type": "string"
15911
},
16123
- "description": "Tags that the tool must have at least one of"
16124
- },
16125
- "disabled": {
16126
- "type": "array",
16127
- "items": {
16128
- "type": "string",
16129
- "enum": [
16130
- "readOnlyHint",
16131
- "destructiveHint",
16132
- "idempotentHint",
16133
- "openWorldHint"
16134
- ]
15912
+ {
15913
+ "type": "array",
15914
+ "items": {
15915
+ "type": "string"
15916
+ }
15917
},
16136
- "description": "Tags that the tool must NOT have any of"
16137
- }
15918
+ {
15919
+ "nullable": true,
15920
+ "type": "object"
15921
+ }
15922
+ ]
15923
},
16139
- "description": "MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied."
16140
- },
16141
- "workbench": {
16142
- "type": "object",
16143
- "properties": {
16144
- "enable": {
16145
- "type": "boolean",
16146
- "description": "Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed."
16147
- },
16148
- "proxy_execution_enabled": {
16149
- "type": "boolean",
16150
- "description": "Whether proxy execution is enabled in the workbench"
15924
+ "webhook_signature": {
15925
+ "type": "string"
15926
+ },
15927
+ "authed_user": {
15928
+ "type": "object",
15929
+ "properties": {
15930
+ "access_token": {
15931
+ "type": "string"
15932
+ },
15933
+ "scope": {
15934
+ "type": "string"
15935
+ }
15936
},
16152
- "auto_offload_threshold": {
16153
- "type": "number",
16154
- "minimum": 0,
16155
- "exclusiveMinimum": true,
16156
- "description": "Character threshold after which tool execution response are saved to a file in workbench. Default is 20k."
16157
- }
15937
+ "description": "for slack user scopes"
15938
},
16159
- "default": {
16160
- "enable": true,
16161
- "proxy_execution_enabled": true
15939
+ "client_id": {
15940
+ "type": "string",
15941
+ "description": "Dynamically registered client ID"
15942
},
16163
- "description": "Workbench configuration"
16164
- }
16165
- },
16166
- "required": [
16167
- "user_id"
16168
- ],
16169
- "description": "The session configuration including user, toolkits, and overrides"
15943
+ "client_secret": {
15944
+ "type": "string",
15945
+ "description": "Dynamically registered client secret"
15946
+ },
15947
+ "client_id_issued_at": {
15948
+ "type": "number"
15949
+ },
15950
+ "client_secret_expires_at": {
15951
+ "type": "number"
15952
+ },
15953
+ "generic_api_key": {
15954
+ "type": "string"
15955
+ },
15956
+ "api_key": {
15957
+ "type": "string"
15958
+ },
15959
+ "bearer_token": {
15960
+ "type": "string"
15961
+ },
15962
+ "basic_encoded": {
15963
+ "type": "string"
15964
+ },
15965
+ "username": {
15966
+ "type": "string"
15967
+ },
15968
+ "password": {
15969
+ "type": "string"
15970
+ },
15971
+ "token": {
15972
+ "type": "string"
15973
+ },
15974
+ "oauth_token": {
15975
+ "type": "string"
15976
+ },
15977
+ "oauth_token_secret": {
15978
+ "type": "string"
15979
+ },
15980
+ "oauth_verifier": {
15981
+ "type": "string"
15982
+ },
15983
+ "consumer_key": {
15984
+ "type": "string"
15985
+ },
15986
+ "redirectUrl": {
15987
+ "type": "string"
15988
+ },
15989
+ "callback_url": {
15990
+ "type": "string"
15991
+ },
15992
+ "application_id": {
15993
+ "type": "string"
15994
+ },
15995
+ "installation_id": {
15996
+ "type": "string"
15997
+ },
15998
+ "private_key": {
15999
+ "type": "string"
16000
+ },
16001
+ "credentials_json": {
16002
+ "type": "string"
16003
+ },
16004
+ "expires_at": {
16005
+ "type": "string"
16006
+ }
16007
+ },
16008
+ "required": [
16009
+ "access_token"
16010
+ ],
16011
+ "additionalProperties": {}
16012
+ }
16013
+ },
16014
+ "required": [
16015
+ "authScheme",
16016
+ "toolkitSlug",
16017
+ "val"
16018
+ ],
16019
+ "additionalProperties": true
16020
+ }
16021
+ },
16022
+ "required": [
16023
+ "toolkit_slug",
16024
+ "endpoint",
16025
+ "method"
16026
+ ]
16027
+ }
16028
+ }
16029
+ }
16030
+ },
16031
+ "responses": {
16032
+ "200": {
16033
+ "description": "Successfully executed proxy request and received response",
16034
+ "content": {
16035
+ "application/json": {
16036
+ "schema": {
16037
+ "type": "object",
16038
+ "properties": {
16039
+ "data": {
16040
+ "nullable": true,
16041
+ "description": "The response data returned from the proxied API",
16042
+ "example": {
16043
+ "id": "123",
16044
+ "name": "Resource Name",
16045
+ "created_at": "2023-01-01T00:00:00Z"
16046
+ },
16047
+ "type": "object"
16048
},
16171
- "experimental": {
This file is too large to show in full.
docs/scripts/fetch-openapi.mjs
+24
@@ -66,6 +66,30 @@ async function fetchAndFilterSpec() {
66
}
67
}
68
69
+ // For endpoints that exist under multiple API versions (e.g. /api/v3/ and /api/v3.1/),
70
+ // only keep the latest version to avoid duplicate sidebar entries.
71
+ const versionedPaths = new Map();
72
+ for (const path of Object.keys(filteredPaths)) {
73
+ const match = path.match(/^\/api\/v([\d.]+)\/(.+)$/);
74
+ if (!match) continue;
75
+ const [, version, rest] = match;
76
+ if (!versionedPaths.has(rest)) versionedPaths.set(rest, []);
77
+ versionedPaths.get(rest).push({ version, fullPath: path });
78
+ }
79
+
80
+ let versionDedupCount = 0;
81
+ for (const entries of versionedPaths.values()) {
82
+ if (entries.length <= 1) continue;
83
+ entries.sort((a, b) => parseFloat(b.version) - parseFloat(a.version));
84
+ for (const entry of entries.slice(1)) {
85
+ delete filteredPaths[entry.fullPath];
86
+ versionDedupCount++;
87
+ }
88
+ }
89
+ if (versionDedupCount > 0) {
90
+ console.log(`Removed ${versionDedupCount} endpoints superseded by newer API versions`);
91
+ }
92
+
93
spec.paths = filteredPaths;
94
95
// Filter tags list
docs/scripts/generate-api-index.ts
+24
@@ -37,8 +37,32 @@ function generateIndexPages() {
37
tagOperations[tag.name] = [];
38
}
39
40
+ // For endpoints that exist under multiple API versions (e.g. /api/v3/ and /api/v3.1/),
41
+ // only show the latest version. Extract version from path like /api/v3.1/tools/... → "3.1"
42
+ const supersededPaths: Set<string> = new Set();
43
+ const versionedPaths = new Map<string, { version: string; fullPath: string }[]>();
44
+
45
+ for (const path of Object.keys(spec.paths)) {
46
+ const match = path.match(/^\/api\/v([\d.]+)\/(.+)$/);
47
+ if (!match) continue;
48
+ const [, version, rest] = match;
49
+ if (!versionedPaths.has(rest)) versionedPaths.set(rest, []);
50
+ versionedPaths.get(rest)!.push({ version, fullPath: path });
51
+ }
52
+
53
+ for (const entries of versionedPaths.values()) {
54
+ if (entries.length <= 1) continue;
55
+ // Sort by version descending; keep only the latest
56
+ entries.sort((a, b) => parseFloat(b.version) - parseFloat(a.version));
57
+ for (const entry of entries.slice(1)) {
58
+ supersededPaths.add(entry.fullPath);
59
+ }
60
+ }
61
+
62
// Group operations by tag
63
for (const [path, methods] of Object.entries(spec.paths)) {
64
+ // Skip endpoints superseded by a newer API version
65
+ if (supersededPaths.has(path)) continue;
66
for (const [method, operation] of Object.entries(methods)) {
67
if (operation.tags) {
68
for (const tag of operation.tags) {