124
}
125
},
126
"schemas": {
127
+ "Error": {
128
+ "type": "object",
129
+ "properties": {
130
+ "error": {
131
+ "type": "object",
132
+ "properties": {
133
+ "message": {
134
+ "type": "string"
135
+ },
136
+ "code": {
137
+ "type": "number"
138
+ },
139
+ "slug": {
140
+ "type": "string"
141
+ },
142
+ "status": {
143
+ "type": "number"
144
+ },
145
+ "request_id": {
146
+ "type": "string"
147
+ },
148
+ "suggested_fix": {
149
+ "type": "string"
150
+ },
151
+ "errors": {
152
+ "type": "array",
153
+ "items": {
154
+ "type": "string"
155
+ }
156
+ }
157
+ },
158
+ "required": [
159
+ "message",
160
+ "code",
161
+ "slug",
162
+ "status"
163
+ ]
164
+ }
165
+ },
166
+ "required": [
167
+ "error"
168
+ ]
169
+ },
170
"Tool": {
171
"type": "object",
172
"properties": {
451
"total_items"
452
]
453
},
411
- "Error": {
412
- "type": "object",
413
- "properties": {
414
- "error": {
415
- "type": "object",
416
- "properties": {
417
- "message": {
418
- "type": "string"
419
- },
420
- "code": {
421
- "type": "number"
422
- },
423
- "slug": {
424
- "type": "string"
425
- },
426
- "status": {
427
- "type": "number"
428
- },
429
- "request_id": {
430
- "type": "string"
431
- },
432
- "suggested_fix": {
433
- "type": "string"
434
- },
435
- "errors": {
436
- "type": "array",
437
- "items": {
438
- "type": "string"
439
- }
440
- }
441
- },
442
- "required": [
443
- "message",
444
- "code",
445
- "slug",
446
- "status"
447
- ]
448
- }
449
- },
450
- "required": [
451
- "error"
452
- ]
453
- },
454
"PatchConnectedAccountBody": {
455
"type": "object",
456
"properties": {
786
"parameters": {}
787
},
788
"paths": {
789
- "/api/v3.1/tools": {
789
+ "/api/v3.1/logs/tool_execution": {
790
+ "post": {
791
+ "summary": "Search and retrieve tool execution logs",
792
+ "description": "Search and retrieve tool execution logs with filtering, pagination, and time range support.",
793
+ "tags": [
794
+ "Logs"
795
+ ],
796
+ "operationId": "postLogsToolExecution",
797
+ "security": [
798
+ {
799
+ "ApiKeyAuth": []
800
+ },
801
+ {
802
+ "UserApiKeyAuth": []
803
+ }
804
+ ],
805
+ "requestBody": {
806
+ "content": {
807
+ "application/json": {
808
+ "schema": {
809
+ "type": "object",
810
+ "properties": {
811
+ "limit": {
812
+ "type": "number",
813
+ "minimum": 1,
814
+ "maximum": 100,
815
+ "default": 20
816
+ },
817
+ "cursor": {
818
+ "type": "string",
819
+ "nullable": true
820
+ },
821
+ "filters": {
822
+ "type": "array",
823
+ "items": {
824
+ "type": "object",
825
+ "properties": {
826
+ "field": {
827
+ "type": "string",
828
+ "enum": [
829
+ "tool_slug",
830
+ "toolkit_slug",
831
+ "connected_account_id",
832
+ "auth_config_id",
833
+ "status",
834
+ "user_id",
835
+ "session_id",
836
+ "sandbox_id",
837
+ "request_id",
838
+ "log_id"
839
+ ]
840
+ },
841
+ "operator": {
842
+ "type": "string",
843
+ "enum": [
844
+ "==",
845
+ "!=",
846
+ "contains",
847
+ "not_contains"
848
+ ]
849
+ },
850
+ "value": {
851
+ "type": "string"
852
+ }
853
+ },
854
+ "required": [
855
+ "field",
856
+ "operator",
857
+ "value"
858
+ ]
859
+ },
860
+ "default": []
861
+ },
862
+ "time_range": {
863
+ "type": "object",
864
+ "properties": {
865
+ "from": {
866
+ "type": "number",
867
+ "description": "Start time in epoch milliseconds"
868
+ },
869
+ "to": {
870
+ "type": "number",
871
+ "description": "End time in epoch milliseconds"
872
+ }
873
+ },
874
+ "required": [
875
+ "from",
876
+ "to"
877
+ ]
878
+ }
879
+ }
880
+ }
881
+ }
882
+ }
883
+ },
884
+ "responses": {
885
+ "200": {
886
+ "description": "Successfully retrieved tool logs",
887
+ "content": {
888
+ "application/json": {
889
+ "schema": {
890
+ "type": "object",
891
+ "properties": {
892
+ "logs": {
893
+ "type": "array",
894
+ "items": {
895
+ "type": "object",
896
+ "properties": {
897
+ "id": {
898
+ "type": "string"
899
+ },
900
+ "timestamp": {
901
+ "type": "string",
902
+ "format": "date-time",
903
+ "description": "ISO 8601 timestamp"
904
+ },
905
+ "type": {
906
+ "type": "string",
907
+ "description": "Log event type, e.g. tool.execution, trigger.message, connected_account.created"
908
+ },
909
+ "status": {
910
+ "type": "string",
911
+ "enum": [
912
+ "success",
913
+ "failed"
914
+ ]
915
+ },
916
+ "level": {
917
+ "type": "string",
918
+ "enum": [
919
+ "info",
920
+ "error",
921
+ "warn"
922
+ ]
923
+ },
924
+ "message": {
925
+ "type": "string"
926
+ },
927
+ "metadata": {
928
+ "type": "object",
929
+ "additionalProperties": {}
930
+ },
931
+ "metrics": {
932
+ "type": "object",
933
+ "additionalProperties": {}
934
+ },
935
+ "parent": {
936
+ "type": "object",
937
+ "nullable": true,
938
+ "properties": {
939
+ "log_id": {
940
+ "type": "string"
941
+ },
942
+ "tool_slug": {
943
+ "type": "string"
944
+ }
945
+ },
946
+ "required": [
947
+ "log_id",
948
+ "tool_slug"
949
+ ]
950
+ }
951
+ },
952
+ "required": [
953
+ "id",
954
+ "timestamp",
955
+ "type",
956
+ "status",
957
+ "level",
958
+ "metadata",
959
+ "metrics",
960
+ "parent"
961
+ ]
962
+ }
963
+ },
964
+ "next_cursor": {
965
+ "type": "string",
966
+ "nullable": true
967
+ }
968
+ },
969
+ "required": [
970
+ "logs",
971
+ "next_cursor"
972
+ ]
973
+ }
974
+ }
975
+ }
976
+ },
977
+ "400": {
978
+ "description": "Bad request",
979
+ "content": {
980
+ "application/json": {
981
+ "schema": {
982
+ "$ref": "#/components/schemas/Error"
983
+ }
984
+ }
985
+ }
986
+ },
987
+ "401": {
988
+ "description": "Unauthorized",
989
+ "content": {
990
+ "application/json": {
991
+ "schema": {
992
+ "$ref": "#/components/schemas/Error"
993
+ }
994
+ }
995
+ }
996
+ },
997
+ "500": {
998
+ "description": "Internal server error",
999
+ "content": {
1000
+ "application/json": {
1001
+ "schema": {
1002
+ "$ref": "#/components/schemas/Error"
1003
+ }
1004
+ }
1005
+ }
1006
+ }
1007
+ },
1008
+ "x-api-version": "3.1"
1009
+ }
1010
+ },
1011
+ "/api/v3.1/logs/tool_execution/{id}": {
1012
"get": {
791
- "summary": "List available tools",
792
- "description": "Retrieve a paginated list of available tools with comprehensive filtering, sorting and search capabilities. Use query parameters to narrow down results by toolkit, tags, or search terms.",
1013
+ "summary": "Get log details by ID",
1014
+ "description": "Retrieve detailed log information by log ID.",
1015
"tags": [
794
- "Tools"
1016
+ "Logs"
1017
],
796
- "operationId": "getTools",
1018
+ "operationId": "getLogsToolExecutionById",
1019
"security": [
1020
{
1021
"ApiKeyAuth": []
1027
"parameters": [
1028
{
1029
"schema": {
808
- "type": "string"
1030
+ "type": "string",
1031
+ "description": "The log ID"
1032
},
810
- "required": false,
1033
+ "required": true,
1034
+ "description": "The log ID",
1035
+ "name": "id",
1036
+ "in": "path"
1037
+ }
1038
+ ],
1039
+ "responses": {
1040
+ "200": {
1041
+ "description": "Successfully retrieved log details",
1042
+ "content": {
1043
+ "application/json": {
1044
+ "schema": {
1045
+ "type": "object",
1046
+ "properties": {
1047
+ "id": {
1048
+ "type": "string"
1049
+ },
1050
+ "timestamp": {
1051
+ "type": "string",
1052
+ "format": "date-time",
1053
+ "description": "ISO 8601 timestamp"
1054
+ },
1055
+ "type": {
1056
+ "type": "string",
1057
+ "description": "Log event type, e.g. tool.execution, trigger.message, connected_account.created"
1058
+ },
1059
+ "status": {
1060
+ "type": "string",
1061
+ "enum": [
1062
+ "success",
1063
+ "failed"
1064
+ ]
1065
+ },
1066
+ "level": {
1067
+ "type": "string",
1068
+ "enum": [
1069
+ "info",
1070
+ "error",
1071
+ "warn"
1072
+ ]
1073
+ },
1074
+ "message": {
1075
+ "type": "string"
1076
+ },
1077
+ "metadata": {
1078
+ "type": "object",
1079
+ "additionalProperties": {}
1080
+ },
1081
+ "metrics": {
1082
+ "type": "object",
1083
+ "additionalProperties": {}
1084
+ },
1085
+ "parent": {
1086
+ "type": "object",
1087
+ "nullable": true,
1088
+ "properties": {
1089
+ "log_id": {
1090
+ "type": "string"
1091
+ },
1092
+ "tool_slug": {
1093
+ "type": "string"
1094
+ }
1095
+ },
1096
+ "required": [
1097
+ "log_id",
1098
+ "tool_slug"
1099
+ ]
1100
+ },
1101
+ "timings": {
1102
+ "type": "object",
1103
+ "properties": {
1104
+ "start_time": {
1105
+ "type": "number",
1106
+ "description": "Epoch milliseconds"
1107
+ },
1108
+ "end_time": {
1109
+ "type": "number",
1110
+ "description": "Epoch milliseconds"
1111
+ }
1112
+ },
1113
+ "required": [
1114
+ "start_time",
1115
+ "end_time"
1116
+ ]
1117
+ },
1118
+ "context": {
1119
+ "type": "object",
1120
+ "properties": {
1121
+ "session_id": {
1122
+ "type": "string"
1123
+ },
1124
+ "trace_id": {
1125
+ "type": "string"
1126
+ },
1127
+ "request_id": {
1128
+ "type": "string"
1129
+ }
1130
+ }
1131
+ },
1132
+ "source": {
1133
+ "type": "object",
1134
+ "properties": {
1135
+ "host": {
1136
+ "type": "string"
1137
+ },
1138
+ "framework": {
1139
+ "type": "string"
1140
+ },
1141
+ "language": {
1142
+ "type": "string"
1143
+ }
1144
+ }
1145
+ },
1146
+ "data": {
1147
+ "type": "object",
1148
+ "additionalProperties": {}
1149
+ }
1150
+ },
1151
+ "required": [
1152
+ "id",
1153
+ "timestamp",
1154
+ "type",
1155
+ "status",
1156
+ "level",
1157
+ "metadata",
1158
+ "metrics",
1159
+ "parent",
1160
+ "context",
1161
+ "source",
1162
+ "data"
1163
+ ]
1164
+ }
1165
+ }
1166
+ }
1167
+ },
1168
+ "400": {
1169
+ "description": "Bad request",
1170
+ "content": {
1171
+ "application/json": {
1172
+ "schema": {
1173
+ "$ref": "#/components/schemas/Error"
1174
+ }
1175
+ }
1176
+ }
1177
+ },
1178
+ "401": {
1179
+ "description": "Unauthorized",
1180
+ "content": {
1181
+ "application/json": {
1182
+ "schema": {
1183
+ "$ref": "#/components/schemas/Error"
1184
+ }
1185
+ }
1186
+ }
1187
+ },
1188
+ "404": {
1189
+ "description": "Log not found",
1190
+ "content": {
1191
+ "application/json": {
1192
+ "schema": {
1193
+ "$ref": "#/components/schemas/Error"
1194
+ }
1195
+ }
1196
+ }
1197
+ },
1198
+ "500": {
1199
+ "description": "Internal server error",
1200
+ "content": {
1201
+ "application/json": {
1202
+ "schema": {
1203
+ "$ref": "#/components/schemas/Error"
1204
+ }
1205
+ }
1206
+ }
1207
+ }
1208
+ },
1209
+ "x-api-version": "3.1"
1210
+ }
1211
+ },
1212
+ "/api/v3.1/tools": {
1213
+ "get": {
1214
+ "summary": "List available tools",
1215
+ "description": "Retrieve a paginated list of available tools with comprehensive filtering, sorting and search capabilities. Use query parameters to narrow down results by toolkit, tags, or search terms.",
1216
+ "tags": [
1217
+ "Tools"
1218
+ ],
1219
+ "operationId": "getTools",
1220
+ "security": [
1221
+ {
1222
+ "ApiKeyAuth": []
1223
+ },
1224
+ {
1225
+ "UserApiKeyAuth": []
1226
+ }
1227
+ ],
1228
+ "parameters": [
1229
+ {
1230
+ "schema": {
1231
+ "type": "string"
1232
+ },
1233
+ "required": false,
1234
"description": "The slug of the toolkit to filter by",
1235
"in": "query",
1236
"name": "toolkit_slug"
3159
"x-api-version": "3.1"
3160
}
3161
},
2739
- "/api/v3.1/auth/session/info": {
2740
- "get": {
2741
- "summary": "Get current user session information",
2742
- "description": "Retrieves detailed information about the current authenticated user session, including project details, organization membership, and API key information if applicable. This endpoint is useful for verifying authentication status and retrieving contextual information about the authenticated user and their access privileges.",
3162
+ "/api/v3.1/tool_router/session": {
3163
+ "post": {
3164
+ "summary": "Create a new tool router session",
3165
+ "description": "Creates a new session for the tool router feature. This endpoint initializes a new session with specified toolkits and their authentication configurations. The session provides an isolated environment for testing and managing tool routing logic with scoped MCP server access.",
3166
"tags": [
2744
- "Authentication"
3167
+ "Tool Router"
3168
],
2746
- "operationId": "getAuthSessionInfo",
3169
+ "operationId": "postToolRouterSession",
3170
"security": [
3171
{
3172
"ApiKeyAuth": []
3175
"UserApiKeyAuth": []
3176
}
3177
],
2755
- "responses": {
2756
- "200": {
2757
- "description": "Session is valid and active. Returns detailed information about the authenticated user, their project, and organization.",
2758
- "content": {
2759
- "application/json": {
2760
- "schema": {
2761
- "type": "object",
2762
- "properties": {
2763
- "project": {
2764
- "type": "object",
2765
- "nullable": true,
2766
- "properties": {
2767
- "auto_id": {
2768
- "type": "number",
2769
- "description": "Internal auto-incrementing ID for the project",
2770
- "example": 12345
2771
- },
2772
- "id": {
2773
- "type": "string",
2774
- "description": "UUID identifier for the project",
2775
- "example": "550e8400-e29b-41d4-a716-446655440000"
2776
- },
2777
- "org_id": {
2778
- "type": "string",
2779
- "description": "Organization UUID that this project belongs to",
2780
- "example": "550e8400-e29b-41d4-a716-446655440001"
2781
- },
2782
- "name": {
2783
- "type": "string",
2784
- "description": "User-defined name for the project",
2785
- "example": "Production API"
3178
+ "requestBody": {
3179
+ "content": {
3180
+ "application/json": {
3181
+ "schema": {
3182
+ "type": "object",
3183
+ "properties": {
3184
+ "user_id": {
3185
+ "type": "string",
3186
+ "minLength": 1,
3187
+ "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",
3188
+ "example": "user_123456789"
3189
+ },
3190
+ "toolkits": {
3191
+ "anyOf": [
3192
+ {
3193
+ "type": "object",
3194
+ "properties": {
3195
+ "enable": {
3196
+ "type": "array",
3197
+ "items": {
3198
+ "type": "string"
3199
+ },
3200
+ "description": "Only these specific toolkits will be enabled",
3201
+ "example": [
3202
+ "gmail",
3203
+ "slack",
3204
+ "github"
3205
+ ]
3206
+ }
3207
},
2787
- "email": {
2788
- "type": "string",
2789
- "description": "Email address used for project notifications",
2790
- "example": "project-123@composio.dev"
3208
+ "required": [
3209
+ "enable"
3210
+ ],
3211
+ "additionalProperties": false,
3212
+ "description": "Enable only specific toolkits (allowlist)"
3213
+ },
3214
+ {
3215
+ "type": "object",
3216
+ "properties": {
3217
+ "disable": {
3218
+ "type": "array",
3219
+ "items": {
3220
+ "type": "string"
3221
+ },
3222
+ "description": "These specific toolkits will be disabled",
3223
+ "example": [
3224
+ "gmail",
3225
+ "slack"
3226
+ ]
3227
+ }
3228
},
2792
- "nano_id": {
2793
- "type": "string",
2794
- "format": "projectId",
2795
- "description": "Short, URL-friendly unique identifier for the project",
2796
- "example": "pr_1a2b3c4d5e6f"
2797
- },
2798
- "created_at": {
2799
- "type": "string",
2800
- "description": "Date and time when the project was created",
2801
- "example": "2023-05-16T14:30:00.000Z"
2802
- },
2803
- "updated_at": {
2804
- "type": "string",
2805
- "description": "Date and time when the project was last modified",
2806
- "example": "2023-05-18T09:15:30.000Z"
2807
- },
2808
- "webhook_url": {
2809
- "type": "string",
2810
- "nullable": true,
2811
- "description": "Endpoint URL for trigger webhook notifications",
2812
- "example": "https://example.com/webhook"
2813
- },
2814
- "event_webhook_url": {
2815
- "type": "string",
2816
- "nullable": true,
2817
- "description": "Endpoint URL for event webhook notifications",
2818
- "example": "https://example.com/events"
2819
- },
2820
- "webhook_secret": {
2821
- "type": "string",
2822
- "nullable": true,
2823
- "description": "Secret used to verify webhook signatures",
2824
- "example": "whsec_a1b2c3d4e5f6g7h8i9j0"
2825
- },
2826
- "triggers_enabled": {
2827
- "type": "boolean",
2828
- "description": "Flag indicating if triggers are enabled for this project",
2829
- "example": true
2830
- },
2831
- "last_subscribed_at": {
2832
- "type": "string",
2833
- "nullable": true,
2834
- "description": "Date and time when the project last subscribed to updates",
2835
- "example": "2023-05-17T10:00:00.000Z"
2836
- },
2837
- "deleted": {
2838
- "type": "boolean",
2839
- "description": "Flag indicating if the project has been deleted",
2840
- "example": false
2841
- },
2842
- "is_new_webhook": {
2843
- "type": "boolean",
2844
- "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",
2845
- "example": true,
2846
- "deprecated": true
3229
+ "required": [
3230
+ "disable"
3231
+ ],
3232
+ "additionalProperties": false,
3233
+ "description": "Disable specific toolkits (denylist)"
3234
+ }
3235
+ ],
3236
+ "description": "Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive."
3237
+ },
3238
+ "auth_configs": {
3239
+ "type": "object",
3240
+ "additionalProperties": {
3241
+ "type": "string",
3242
+ "format": "authConfigId"
3243
+ },
3244
+ "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",
3245
+ "example": {
3246
+ "gmail": "ac_1a2b3c4d5e6f",
3247
+ "slack": "ac_7g8h9i0j1k2l"
3248
+ }
3249
+ },
3250
+ "connected_accounts": {
3251
+ "type": "object",
3252
+ "additionalProperties": {
3253
+ "type": "string",
3254
+ "format": "connectedAccountId"
3255
+ },
3256
+ "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",
3257
+ "example": {
3258
+ "github": "ca_3m4n5o6p7q8r"
3259
+ }
3260
+ },
3261
+ "manage_connections": {
3262
+ "type": "object",
3263
+ "properties": {
3264
+ "enable": {
3265
+ "type": "boolean",
3266
+ "nullable": true,
3267
+ "default": true,
3268
+ "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.",
3269
+ "example": true
3270
+ },
3271
+ "callback_url": {
3272
+ "type": "string",
3273
+ "format": "uri",
3274
+ "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.",
3275
+ "example": "https://your-app.com/auth/callback"
3276
+ },
3277
+ "enable_wait_for_connections": {
3278
+ "type": "boolean",
3279
+ "nullable": true,
3280
+ "default": false,
3281
+ "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.",
3282
+ "example": false
3283
+ },
3284
+ "enable_connection_removal": {
3285
+ "type": "boolean",
3286
+ "nullable": true,
3287
+ "default": true,
3288
+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected accounts. Default true."
3289
+ }
3290
+ },
3291
+ "default": {
3292
+ "enable": true,
3293
+ "enable_wait_for_connections": false,
3294
+ "enable_connection_removal": true
3295
+ },
3296
+ "additionalProperties": false,
3297
+ "description": "Configuration for connection management settings"
3298
+ },
3299
+ "tools": {
3300
+ "type": "object",
3301
+ "additionalProperties": {
3302
+ "anyOf": [
3303
+ {
3304
+ "type": "object",
3305
+ "properties": {
3306
+ "enable": {
3307
+ "type": "array",
3308
+ "items": {
3309
+ "type": "string"
3310
+ },
3311
+ "description": "Only these specific tools will be available for this toolkit",
3312
+ "example": [
3313
+ "GMAIL_SEND_EMAIL",
3314
+ "GMAIL_FETCH_EMAILS"
3315
+ ]
3316
+ }
3317
+ },
3318
+ "required": [
3319
+ "enable"
3320
+ ],
3321
+ "additionalProperties": false
3322
},
2848
- "webhook_version": {
2849
- "type": "string",
2850
- "enum": [
2851
- "V1",
2852
- "V2",
2853
- "V3"
3323
+ {
3324
+ "type": "object",
3325
+ "properties": {
3326
+ "disable": {
3327
+ "type": "array",
3328
+ "items": {
3329
+ "type": "string"
3330
+ },
3331
+ "description": "These specific tools will be disabled for this toolkit",
3332
+ "example": [
3333
+ "SLACK_ADD_EMOJI"
3334
+ ]
3335
+ }
3336
+ },
3337
+ "required": [
3338
+ "disable"
3339
],
2855
- "description": "Version of the webhook configuration",
2856
- "example": "V2"
3340
+ "additionalProperties": false
3341
},
2858
- "org": {
3342
+ {
3343
"type": "object",
3344
"properties": {
2861
- "id": {
2862
- "type": "string",
2863
- "format": "orgId",
2864
- "description": "Short, URL-friendly unique identifier for the organization",
2865
- "example": "ok_1a2b3c4d5e6f"
2866
- },
2867
- "name": {
2868
- "type": "string",
2869
- "description": "User-defined name for the organization",
2870
- "example": "Acme Corp"
2871
- },
2872
- "plan": {
2873
- "type": "string",
2874
- "description": "Current subscription plan level",
2875
- "example": "BUSINESS"
3345
+ "tags": {
3346
+ "anyOf": [
3347
+ {
3348
+ "type": "array",
3349
+ "items": {
3350
+ "type": "string",
3351
+ "enum": [
3352
+ "readOnlyHint",
3353
+ "destructiveHint",
3354
+ "idempotentHint",
3355
+ "openWorldHint"
3356
+ ]
3357
+ }
3358
+ },
3359
+ {
3360
+ "type": "object",
3361
+ "properties": {
3362
+ "enable": {
3363
+ "type": "array",
3364
+ "items": {
3365
+ "type": "string",
3366
+ "enum": [
3367
+ "readOnlyHint",
3368
+ "destructiveHint",
3369
+ "idempotentHint",
3370
+ "openWorldHint"
3371
+ ]
3372
+ },
3373
+ "description": "Tags that the tool must have at least one of"
3374
+ },
3375
+ "disable": {
3376
+ "type": "array",
3377
+ "items": {
3378
+ "type": "string",
3379
+ "enum": [
3380
+ "readOnlyHint",
3381
+ "destructiveHint",
3382
+ "idempotentHint",
3383
+ "openWorldHint"
3384
+ ]
3385
+ },
3386
+ "description": "Tags that the tool must NOT have any of"
3387
+ }
3388
+ }
3389
+ }
3390
+ ],
3391
+ "description": "MCP tags to filter tools. Array format is treated as enabled list. Object format supports both enabled and disabled lists.",
3392
+ "example": {
3393
+ "enable": [
3394
+ "openWorldHint"
3395
+ ],
3396
+ "disable": [
3397
+ "destructiveHint"
3398
+ ]
3399
+ }
3400
}
3401
},
3402
"required": [
2879
- "id",
2880
- "name",
2881
- "plan"
3403
+ "tags"
3404
],
2883
- "description": "Organization details"
3405
+ "additionalProperties": false
3406
}
2885
- },
2886
- "required": [
2887
- "auto_id",
2888
- "id",
2889
- "org_id",
2890
- "name",
2891
- "email",
2892
- "nano_id",
2893
- "created_at",
2894
- "updated_at",
2895
- "webhook_url",
2896
- "event_webhook_url",
2897
- "webhook_secret",
2898
- "triggers_enabled",
2899
- "last_subscribed_at",
2900
- "deleted",
2901
- "is_new_webhook",
2902
- "webhook_version",
2903
- "org"
2904
- ],
2905
- "description": "Details of the current active project (null if accessing with org-level credentials)"
3407
+ ]
3408
},
2907
- "api_key": {
2908
- "type": "object",
2909
- "nullable": true,
2910
- "properties": {
2911
- "auto_id": {
2912
- "type": "number",
2913
- "description": "Internal auto-incrementing ID for the API key",
2914
- "example": 7890
2915
- },
2916
- "id": {
2917
- "type": "string",
2918
- "description": "UUID identifier for the API key",
2919
- "example": "550e8400-e29b-41d4-a716-446655440003"
2920
- },
2921
- "name": {
2922
- "type": "string",
2923
- "description": "User-defined name for the API key",
2924
- "example": "Development Key"
2925
- },
2926
- "project_id": {
2927
- "type": "string",
2928
- "format": "projectId",
2929
- "description": "Short, URL-friendly unique identifier for the associated project",
2930
- "example": "pr_1a2b3c4d5e6f"
2931
- },
2932
- "org_member_id": {
2933
- "type": "string",
2934
- "description": "UUID identifier for the organization member who owns this API key",
2935
- "example": "550e8400-e29b-41d4-a716-446655440002"
2936
- },
2937
- "created_at": {
2938
- "type": "string",
2939
- "description": "Date and time when the API key was created",
2940
- "example": "2023-05-01T10:00:00.000Z"
2941
- },
2942
- "updated_at": {
2943
- "type": "string",
2944
- "description": "Date and time when the API key was last modified",
2945
- "example": "2023-05-01T10:00:00.000Z"
2946
- },
2947
- "deleted_at": {
2948
- "type": "string",
2949
- "nullable": true,
2950
- "description": "Date and time when the API key was deleted (if applicable)"
2951
- },
2952
- "key": {
2953
- "type": "string",
2954
- "description": "The actual API key value (usually only shown once during creation)",
2955
- "example": "sk_live_abc123xyz456"
2956
- },
2957
- "deleted": {
2958
- "type": "boolean",
2959
- "description": "Flag indicating if the API key has been deleted",
2960
- "example": false
2961
- }
3409
+ "description": "Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit",
3410
+ "example": {
3411
+ "gmail": {
3412
+ "enable": [
3413
+ "GMAIL_SEND_EMAIL",
3414
+ "GMAIL_FETCH_EMAILS"
3415
+ ]
3416
},
2963
- "required": [
2964
- "auto_id",
2965
- "id",
2966
- "name",
2967
- "project_id",
2968
- "org_member_id",
2969
- "created_at",
2970
- "updated_at",
2971
- "deleted_at",
2972
- "key",
2973
- "deleted"
2974
- ],
2975
- "description": "Details of the API key used for authentication (null if using session auth)"
2976
- },
2977
- "org_member": {
2978
- "type": "object",
2979
- "properties": {
2980
- "id": {
2981
- "type": "string",
2982
- "description": "UUID identifier for the organization member",
2983
- "example": "550e8400-e29b-41d4-a716-446655440002"
2984
- },
2985
- "email": {
2986
- "type": "string",
2987
- "description": "Email address of the authenticated user",
2988
- "example": "user@example.com"
2989
- },
2990
- "name": {
2991
- "type": "string",
2992
- "description": "Display name of the authenticated user",
2993
- "example": "John Doe"
2994
- },
2995
- "role": {
2996
- "type": "string",
2997
- "description": "Access role of the authenticated user within the organization",
2998
- "example": "admin"
2999
- }
3417
+ "slack": {
3418
+ "disable": [
3419
+ "SLACK_ADD_EMOJI"
3420
+ ]
3421
},
3001
- "required": [
3002
- "id",
3003
- "email",
3004
- "name",
3005
- "role"
3006
- ],
3007
- "description": "Information about the authenticated user",
3008
- "example": {
3009
- "id": "550e8400-e29b-41d4-a716-446655440002",
3010
- "email": "user@example.com",
3011
- "name": "John Doe",
3012
- "role": "admin"
3422
+ "slack_bot": {
3423
+ "tags": {
3424
+ "enable": [
3425
+ "destructiveHint"
3426
+ ],
3427
+ "disable": [
3428
+ "openWorldHint"
3429
+ ]
3430
+ }
3431
}
3432
}
3433
},
3016
- "required": [
3017
- "project",
3018
- "api_key",
3019
- "org_member"
3020
- ],
3021
- "description": "Response containing user session information"
3022
- }
3023
- }
3024
- }
3025
- },
3026
- "400": {
3027
- "description": "Bad request. The request format may be invalid or missing required parameters.",
3028
- "content": {
3029
- "application/json": {
3030
- "schema": {
3031
- "$ref": "#/components/schemas/Error"
3032
- }
3033
- }
3034
- }
3035
- },
3036
- "401": {
3037
- "description": "Unauthorized. Authentication is required or the provided credentials are invalid or expired.",
3038
- "content": {
3039
- "application/json": {
3040
- "schema": {
3041
- "$ref": "#/components/schemas/Error"
3042
- }
3043
- }
3044
- }
3045
- },
3046
- "403": {
3047
- "description": "Forbidden. The authenticated user does not have permission to access this resource.",
3048
- "content": {
3049
- "application/json": {
3050
- "schema": {
3051
- "$ref": "#/components/schemas/Error"
3052
- }
3053
- }
3054
- }
3055
- },
3056
- "404": {
3057
- "description": "Not found. The requested project, organization, or member resource could not be found.",
3058
- "content": {
3059
- "application/json": {
3060
- "schema": {
3061
- "$ref": "#/components/schemas/Error"
3062
- }
3063
- }
3064
- }
3065
- },
3066
- "500": {
3067
- "description": "Internal server error. An unexpected error occurred while processing the request.",
3068
- "content": {
3069
- "application/json": {
3070
- "schema": {
3071
- "$ref": "#/components/schemas/Error"
3072
- }
3073
- }
3074
- }
3075
- }
3076
- },
3077
- "x-api-version": "3.1"
3078
- }
3079
- },
3080
- "/api/v3.1/auth_configs": {
3081
- "post": {
3082
- "summary": "Create new authentication configuration",
3083
- "description": "Creates a new auth config for a toolkit, allowing you to use your own OAuth credentials or API keys instead of Composio-managed authentication. This is required when you want to use custom OAuth apps (bring your own client ID/secret) or configure specific authentication parameters for a toolkit.",
3084
- "tags": [
3085
- "Auth Configs"
3086
- ],
3087
- "operationId": "postAuthConfigs",
3088
- "security": [
3089
- {
3090
- "ApiKeyAuth": []
3091
- },
3092
- {
3093
- "UserApiKeyAuth": []
3094
- }
3095
- ],
3096
- "requestBody": {
3097
- "content": {
3098
- "application/json": {
3099
- "schema": {
3100
- "type": "object",
3101
- "properties": {
3102
- "toolkit": {
3103
- "type": "object",
3104
- "properties": {
3105
- "slug": {
3106
- "type": "string",
3107
- "description": "Toolkit slug to create auth config for"
3108
- }
3109
- },
3110
- "required": [
3111
- "slug"
3112
- ]
3113
- },
3114
- "auth_config": {
3115
- "oneOf": [
3434
+ "tags": {
3435
+ "anyOf": [
3436
+ {
3437
+ "type": "array",
3438
+ "items": {
3439
+ "type": "string",
3440
+ "enum": [
3441
+ "readOnlyHint",
3442
+ "destructiveHint",
3443
+ "idempotentHint",
3444
+ "openWorldHint"
3445
+ ]
3446
+ }
3447
+ },
3448
{
3449
"type": "object",
3450
"properties": {
3119
- "type": {
3120
- "type": "string",
3121
- "enum": [
3122
- "use_composio_managed_auth"
3123
- ]
3124
- },
3125
- "name": {
3126
- "type": "string",
3127
- "description": "The name of the integration"
3128
- },
3129
- "credentials": {
3130
- "type": "object",
3131
- "properties": {
3132
- "scopes": {
3133
- "anyOf": [
3134
- {
3135
- "type": "string"
3136
- },
3137
- {
3138
- "type": "array",
3139
- "items": {
3140
- "type": "string"
3141
- }
3142
- }
3143
- ]
3144
- },
3145
- "user_scopes": {
3146
- "anyOf": [
3147
- {
3148
- "type": "string"
3149
- },
3150
- {
3151
- "type": "array",
3152
- "items": {
3153
- "type": "string"
3154
- }
3155
- }
3156
- ]
3157
- }
3158
- },
3159
- "default": {}
3160
- },
3161
- "tool_access_config": {
3162
- "type": "object",
3163
- "properties": {
3164
- "tools_for_connected_account_creation": {
3165
- "type": "array",
3166
- "items": {
3167
- "type": "string"
3168
- },
3169
- "default": [],
3170
- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."
3171
- }
3172
- }
3173
- },
3174
- "restrict_to_following_tools": {
3451
+ "enable": {
3452
"type": "array",
3453
"items": {
3177
- "type": "string"
3178
- },
3179
- "default": [],
3180
- "description": "Use tool_access_config instead. This field will be deprecated in the future.",
3181
- "deprecated": true
3182
- },
3183
- "shared_credentials": {
3184
- "type": "object",
3185
- "additionalProperties": {},
3186
- "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",
3187
- "x-experimental": true
3188
- },
3189
- "is_enabled_for_tool_router": {
3190
- "type": "boolean",
3191
- "description": "Whether this auth config is enabled for tool router"
3192
- }
3193
- },
3194
- "required": [
3195
- "type"
3196
- ]
3197
- },
3198
- {
3199
- "type": "object",
3200
- "properties": {
3201
- "type": {
3202
- "type": "string",
3203
- "enum": [
3204
- "use_custom_auth"
3205
- ]
3206
- },
3207
- "name": {
3208
- "type": "string",
3209
- "description": "The name of the integration"
3210
- },
3211
- "authScheme": {
3212
- "type": "string",
3213
- "enum": [
3214
- "OAUTH2",
3215
- "OAUTH1",
3216
- "API_KEY",
3217
- "BASIC",
3218
- "BILLCOM_AUTH",
3219
- "BEARER_TOKEN",
3220
- "GOOGLE_SERVICE_ACCOUNT",
3221
- "NO_AUTH",
3222
- "BASIC_WITH_JWT",
3223
- "CALCOM_AUTH",
3224
- "SERVICE_ACCOUNT",
3225
- "SAML",
3226
- "DCR_OAUTH",
3227
- "S2S_OAUTH2"
3228
- ]
3229
- },
3230
- "credentials": {
3231
- "type": "object",
3232
- "properties": {
3233
- "scopes": {
3234
- "anyOf": [
3235
- {
3236
- "type": "string"
3237
- },
3238
- {
3239
- "type": "array",
3240
- "items": {
3241
- "type": "string"
3242
- }
3243
- }
3244
- ]
3245
- },
3246
- "user_scopes": {
3247
- "anyOf": [
3248
- {
3249
- "type": "string"
3250
- },
3251
- {
3252
- "type": "array",
3253
- "items": {
3254
- "type": "string"
3255
- }
3256
- }
3257
- ]
3258
- }
3259
- },
3260
- "default": {}
3261
- },
3262
- "proxy_config": {
3263
- "type": "object",
3264
- "nullable": true,
3265
- "properties": {
3266
- "proxy_url": {
3267
- "type": "string",
3268
- "format": "uri",
3269
- "description": "The url of the auth proxy"
3270
- },
3271
- "proxy_auth_key": {
3272
- "type": "string",
3273
- "description": "The auth key for the auth proxy"
3274
- }
3454
+ "type": "string",
3455
+ "enum": [
3456
+ "readOnlyHint",
3457
+ "destructiveHint",
3458
+ "idempotentHint",
3459
+ "openWorldHint"
3460
+ ]
3461
},
3276
- "required": [
3277
- "proxy_url"
3278
- ]
3462
+ "description": "Tags that the tool must have at least one of"
3463
},
3280
- "restrict_to_following_tools": {
3464
+ "disable": {
3465
"type": "array",
3466
"items": {
3283
- "type": "string"
3467
+ "type": "string",
3468
+ "enum": [
3469
+ "readOnlyHint",
3470
+ "destructiveHint",
3471
+ "idempotentHint",
3472
+ "openWorldHint"
3473
+ ]
3474
},
3285
- "default": [],
3286
- "description": "Use tool_access_config instead. This field will be deprecated in the future.",
3287
- "deprecated": true
3288
- },
3289
- "tool_access_config": {
3290
- "type": "object",
3291
- "properties": {
3292
- "tools_for_connected_account_creation": {
3293
- "type": "array",
3294
- "items": {
3295
- "type": "string"
3296
- },
3297
- "default": [],
3298
- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."
3299
- }
3300
- }
3301
- },
3302
- "shared_credentials": {
3303
- "type": "object",
3304
- "additionalProperties": {},
3305
- "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",
3306
- "x-experimental": true
3307
- },
3308
- "is_enabled_for_tool_router": {
3309
- "type": "boolean",
3310
- "description": "Whether this auth config is enabled for tool router"
3475
+ "description": "Tags that the tool must NOT have any of"
3476
}
3312
- },
3313
- "required": [
3314
- "type",
3315
- "authScheme"
3316
- ]
3477
+ }
3478
}
3479
],
3319
- "default": {
3320
- "type": "use_composio_managed_auth",
3321
- "credentials": {},
3322
- "restrict_to_following_tools": []
3480
+ "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.",
3481
+ "example": {
3482
+ "enable": [
3483
+ "openWorldHint"
3484
+ ],
3485
+ "disable": [
3486
+ "destructiveHint"
3487
+ ]
3488
}
3324
- }
3325
- },
3326
- "required": [
3327
- "toolkit"
3328
- ]
3329
- }
3330
- }
3331
- }
3332
- },
3333
- "responses": {
3334
- "201": {
3335
- "description": "Successfully created auth config",
3336
- "content": {
3337
- "application/json": {
3338
- "schema": {
3339
- "type": "object",
3340
- "properties": {
3341
- "toolkit": {
3342
- "type": "object",
3343
- "properties": {
3344
- "slug": {
3345
- "type": "string",
3346
- "description": "The unique key of the toolkit"
3347
- }
3489
+ },
3490
+ "workbench": {
3491
+ "type": "object",
3492
+ "properties": {
3493
+ "enable": {
3494
+ "type": "boolean",
3495
+ "default": true,
3496
+ "description": "Set to false to disable the workbench entirely. When disabled, no code execution tools are available in the session.",
3497
+ "example": true
3498
},
3349
- "required": [
3350
- "slug"
3351
- ]
3352
- },
3353
- "auth_config": {
3354
- "type": "object",
3355
- "properties": {
3356
- "id": {
3357
- "type": "string",
3358
- "format": "authConfigId",
3359
- "description": "The auth config id of the toolkit (must be a valid auth config id)"
3360
- },
3361
- "auth_scheme": {
3362
- "type": "string",
3363
- "description": "The authentication mode of the toolkit"
3364
- },
3365
- "is_composio_managed": {
3366
- "type": "boolean",
3367
- "description": "Whether the auth config is managed by Composio"
3368
- },
3369
- "restrict_to_following_tools": {
3370
- "type": "array",
3371
- "items": {
3372
- "type": "string"
3373
- },
3374
- "default": [],
3375
- "description": "The tools that the user can use with the auth config"
3376
- }
3499
+ "enable_proxy_execution": {
3500
+ "type": "boolean",
3501
+ "default": true,
3502
+ "description": "Whether proxy execution is enabled. When enabled, workbench can call URLs and APIs directly.",
3503
+ "example": true
3504
},
3378
- "required": [
3379
- "id",
3380
- "auth_scheme",
3381
- "is_composio_managed"
3382
- ]
3383
- }
3505
+ "auto_offload_threshold": {
3506
+ "type": "number",
3507
+ "minimum": 0,
3508
+ "exclusiveMinimum": true,
3509
+ "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.",
3510
+ "example": 20000
3511
+ }
3512
+ },
3513
+ "default": {
3514
+ "enable": true,
3515
+ "enable_proxy_execution": true
3516
+ },
3517
+ "additionalProperties": false,
3518
+ "description": "Configuration for workbench behavior"
3519
},
3385
- "required": [
3386
- "toolkit",
3387
- "auth_config"
3388
- ]
3389
- }
3390
- }
3391
- }
3392
- },
3393
- "400": {
3394
- "description": "Bad request",
3395
- "content": {
3396
- "application/json": {
3397
- "schema": {
3398
- "$ref": "#/components/schemas/Error"
3399
- }
3400
- }
3401
- }
3402
- },
3403
- "401": {
3404
- "description": "Unauthorized",
3405
- "content": {
3406
- "application/json": {
3407
- "schema": {
3408
- "$ref": "#/components/schemas/Error"
3409
- }
3410
- }
3411
- }
3412
- },
3413
- "404": {
3414
- "description": "Not found",
3415
- "content": {
3416
- "application/json": {
3417
- "schema": {
3418
- "$ref": "#/components/schemas/Error"
3419
- }
3420
- }
3421
- }
3422
- },
3423
- "500": {
3424
- "description": "Internal server error",
3425
- "content": {
3426
- "application/json": {
3427
- "schema": {
3428
- "$ref": "#/components/schemas/Error"
3429
- }
3430
- }
3431
- }
3432
- }
3433
- },
3434
- "x-api-version": "3.1"
3435
- },
3436
- "get": {
3437
- "summary": "List authentication configurations with optional filters",
3438
- "description": "Retrieves all auth configs for your project. Auth configs define how users authenticate with external services (OAuth, API keys, etc.). Use filters to find configs for specific toolkits or to distinguish between Composio-managed and custom configurations.",
3439
- "tags": [
3440
- "Auth Configs"
3441
- ],
3442
- "operationId": "getAuthConfigs",
3443
- "security": [
3444
- {
3445
- "ApiKeyAuth": []
3446
- },
3447
- {
3448
- "UserApiKeyAuth": []
3449
- }
3450
- ],
3451
- "parameters": [
3452
- {
3453
- "schema": {
3454
- "anyOf": [
3455
- {
3456
- "type": "string"
3457
- },
3458
- {
3459
- "type": "boolean"
3460
- }
3461
- ],
3462
- "description": "Whether to filter by composio managed auth configs"
3463
- },
3464
- "required": false,
3465
- "description": "Whether to filter by composio managed auth configs",
3466
- "name": "is_composio_managed",
3467
- "in": "query"
3468
- },
3469
- {
3470
- "schema": {
3471
- "type": "string"
3472
- },
3473
- "required": false,
3474
- "description": "Comma-separated list of toolkit slugs to filter auth configs by",
3475
- "in": "query",
3476
- "name": "toolkit_slug"
3477
- },
3478
- {
3479
- "schema": {
3480
- "type": "string",
3481
- "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_slug instead.",
3482
- "deprecated": true
3483
- },
3484
- "required": false,
3485
- "description": "The app id to filter by",
3486
- "name": "deprecated_app_id",
3487
- "in": "query"
3488
- },
3489
- {
3490
- "schema": {
3491
- "type": "string",
3492
- "description": "DEPRECATED: This parameter will be removed in a future version.",
3493
- "deprecated": true
3494
- },
3495
- "required": false,
3496
- "name": "deprecated_status",
3497
- "in": "query"
3498
- },
3499
- {
3500
- "schema": {
3501
- "type": "boolean",
3502
- "nullable": true,
3503
- "default": false,
3504
- "description": "Show disabled auth configs"
3505
- },
3506
- "required": false,
3507
- "description": "Show disabled auth configs",
3508
- "name": "show_disabled",
3509
- "in": "query"
3510
- },
3511
- {
3512
- "schema": {
3513
- "type": "string",
3514
- "description": "Search auth configs by name or id"
3515
- },
3516
- "required": false,
3517
- "description": "Search auth configs by name or id",
3518
- "name": "search",
3519
- "in": "query"
3520
- },
3521
- {
3522
- "schema": {
3523
- "type": "number",
3524
- "nullable": true
3525
- },
3526
- "required": false,
3527
- "description": "Number of items per page, max allowed is 1000",
3528
- "name": "limit",
3529
- "in": "query"
3530
- },
3531
- {
3532
- "schema": {
3533
- "type": "string"
3534
- },
3535
- "required": false,
3536
- "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",
3537
- "name": "cursor",
3538
- "in": "query"
3539
- }
3540
- ],
3541
- "responses": {
3542
- "200": {
3543
- "description": "Successfully fetched auth configs",
3544
- "content": {
3545
- "application/json": {
3546
- "schema": {
3547
- "type": "object",
3548
- "properties": {
3549
- "items": {
3550
- "type": "array",
3551
- "items": {
3520
+ "multi_account": {
3521
+ "type": "object",
3522
+ "properties": {
3523
+ "enable": {
3524
+ "type": "boolean",
3525
+ "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration.",
3526
+ "example": true
3527
+ },
3528
+ "max_accounts_per_toolkit": {
3529
+ "type": "integer",
3530
+ "minimum": 2,
3531
+ "maximum": 10,
3532
+ "description": "Maximum number of connected accounts allowed per toolkit. Must be between 2 and 10.",
3533
+ "example": 5
3534
+ },
3535
+ "require_explicit_selection": {
3536
+ "type": "boolean",
3537
+ "description": "When true, the agent must explicitly select which account to use. When false (default), the first/default account is used automatically.",
3538
+ "example": false
3539
+ }
3540
+ },
3541
+ "additionalProperties": false,
3542
+ "description": "Configure multi-account behavior. When enabled, users can connect multiple accounts per toolkit."
3543
+ },
3544
+ "experimental": {
3545
+ "type": "object",
3546
+ "properties": {
3547
+ "assistive_prompt_config": {
3548
"type": "object",
3549
"properties": {
3554
- "id": {
3555
- "type": "string",
3556
- "format": "authConfigId",
3557
- "description": "The unique ID of the authentication configuration"
3558
- },
3559
- "uuid": {
3560
- "type": "string",
3561
- "description": "The UUID of the authentication configuration (for backward compatibility)"
3562
- },
3563
- "type": {
3550
+ "user_timezone": {
3551
"type": "string",
3565
- "enum": [
3566
- "default",
3567
- "custom"
3568
- ],
3569
- "description": "The type of the authentication configuration (custom or default)"
3570
- },
3571
- "toolkit": {
3572
- "type": "object",
3573
- "properties": {
3574
- "slug": {
3575
- "type": "string",
3576
- "description": "The unique identifier of the integration app"
3577
- },
3578
- "logo": {
3579
- "type": "string",
3580
- "description": "The URL to the integration app's logo image"
3581
- },
3582
- "auth_guide_url": {
3583
- "type": "string",
3584
- "nullable": true,
3585
- "description": "URL to a guide page with authentication setup instructions"
3586
- },
3587
- "auth_hint_url": {
3588
- "type": "string",
3589
- "nullable": true,
3590
- "description": "URL to a page where users can obtain or configure credentials"
3591
- }
3592
- },
3593
- "required": [
3594
- "slug",
3595
- "logo"
3596
- ],
3597
- "description": "Information about the associated integration"
3598
- },
3599
- "name": {
3600
- "type": "string",
3601
- "description": "The display name of the authentication configuration"
3602
- },
3603
- "auth_scheme": {
3604
- "type": "string",
3605
- "enum": [
3606
- "OAUTH2",
3607
- "OAUTH1",
3608
- "API_KEY",
3609
- "BASIC",
3610
- "BILLCOM_AUTH",
3611
- "BEARER_TOKEN",
3612
- "GOOGLE_SERVICE_ACCOUNT",
3613
- "NO_AUTH",
3614
- "BASIC_WITH_JWT",
3615
- "CALCOM_AUTH",
3616
- "SERVICE_ACCOUNT",
3617
- "SAML",
3618
- "DCR_OAUTH",
3619
- "S2S_OAUTH2"
3620
- ],
3621
- "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"
3622
- },
3623
- "is_composio_managed": {
3624
- "type": "boolean",
3625
- "description": "Whether this authentication configuration is managed by Composio or the user"
3626
- },
3627
- "credentials": {
3628
- "type": "object",
3629
- "additionalProperties": {},
3630
- "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"
3631
- },
3632
- "proxy_config": {
3633
- "type": "object",
3634
- "nullable": true,
3635
- "properties": {
3636
- "proxy_url": {
3637
- "type": "string",
3638
- "format": "uri",
3639
- "description": "The url of the auth proxy"
3640
- },
3641
- "proxy_auth_key": {
3642
- "type": "string",
3643
- "description": "The auth key for the auth proxy"
3644
- }
3552
+ "description": "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to customize the system prompt with timezone-aware instructions.",
3553
+ "example": "America/New_York"
3554
+ }
3555
+ },
3556
+ "additionalProperties": false,
3557
+ "description": "Customize assistive prompt generation (e.g., timezone)."
3558
+ },
3559
+ "custom_toolkits": {
3560
+ "type": "array",
3561
+ "items": {
3562
+ "type": "object",
3563
+ "properties": {
3564
+ "slug": {
3565
+ "type": "string",
3566
+ "minLength": 1,
3567
+ "pattern": "^[a-zA-Z0-9_-]+$",
3568
+ "description": "Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.",
3569
+ "example": "ecommerce"
3570
},
3646
- "required": [
3647
- "proxy_url"
3648
- ]
3649
- },
3650
- "status": {
3651
- "type": "string",
3652
- "enum": [
3653
- "ENABLED",
3654
- "DISABLED"
3655
- ],
3656
- "description": "Current status of the authentication configuration"
3657
- },
3658
- "created_by": {
3659
- "type": "string",
3660
- "description": "The identifier of the user who created the auth config"
3661
- },
3662
- "created_at": {
3663
- "type": "string",
3664
- "description": "ISO 8601 date-time when the auth config was created"
3665
- },
3666
- "last_updated_at": {
3667
- "type": "string",
3668
- "description": "ISO 8601 date-time when the auth config was last updated"
3669
- },
3670
- "no_of_connections": {
3671
- "type": "number",
3672
- "description": "The number of active connections using this auth config"
3673
- },
3674
- "expected_input_fields": {
3675
- "type": "array",
3676
- "items": {
3677
- "nullable": true,
3678
- "type": "object"
3571
+ "name": {
3572
+ "type": "string",
3573
+ "minLength": 1,
3574
+ "maxLength": 128,
3575
+ "description": "Display name shown to the LLM and in search results.",
3576
+ "example": "E-Commerce API"
3577
},
3680
- "description": "Fields expected during connection initialization"
3681
- },
3682
- "restrict_to_following_tools": {
3683
- "type": "array",
3684
- "items": {
3685
- "type": "string"
3578
+ "description": {
3579
+ "type": "string",
3580
+ "minLength": 1,
3581
+ "maxLength": 2048,
3582
+ "description": "Used for BM25 search matching and shown in toolkit connection statuses.",
3583
+ "example": "Internal e-commerce API for order management and fulfillment"
3584
},
3687
- "description": "Use tool_access_config instead. This field will be deprecated in the future.",
3688
- "deprecated": true
3689
- },
3690
- "tool_access_config": {
3691
- "type": "object",
3692
- "properties": {
3693
- "tools_for_connected_account_creation": {
3694
- "type": "array",
3695
- "items": {
3696
- "type": "string"
3585
+ "tools": {
3586
+ "type": "array",
3587
+ "items": {
3588
+ "type": "object",
3589
+ "properties": {
3590
+ "slug": {
3591
+ "type": "string",
3592
+ "minLength": 1,
3593
+ "pattern": "^[a-zA-Z0-9_-]+$",
3594
+ "description": "Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).",
3595
+ "example": "GET_CUSTOMER_ORDERS"
3596
+ },
3597
+ "name": {
3598
+ "type": "string",
3599
+ "minLength": 1,
3600
+ "maxLength": 128,
3601
+ "description": "Human-readable display name",
3602
+ "example": "Get Customer Orders"
3603
+ },
3604
+ "description": {
3605
+ "type": "string",
3606
+ "minLength": 1,
3607
+ "maxLength": 5120,
3608
+ "description": "Used for BM25 search matching and shown to the LLM.",
3609
+ "example": "Fetch recent orders for a customer by their email address"
3610
+ },
3611
+ "input_schema": {
3612
+ "type": "object",
3613
+ "additionalProperties": {},
3614
+ "description": "Must have type: \"object\" and a properties field.",
3615
+ "example": {
3616
+ "type": "object",
3617
+ "properties": {
3618
+ "email": {
3619
+ "type": "string",
3620
+ "description": "Customer email"
3621
+ }
3622
+ },
3623
+ "required": [
3624
+ "email"
3625
+ ]
3626
+ }
3627
+ },
3628
+ "output_schema": {
3629
+ "type": "object",
3630
+ "additionalProperties": {},
3631
+ "description": "Optional output schema for the tool response."
3632
+ }
3633
},
3698
- "default": [],
3699
- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."
3634
+ "required": [
3635
+ "slug",
3636
+ "name",
3637
+ "description",
3638
+ "input_schema"
3639
+ ]
3640
},
3701
- "tools_available_for_execution": {
3702
- "type": "array",
3703
- "items": {
3704
- "type": "string"
3705
- },
3706
- "default": [],
3707
- "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."
3708
- }
3641
+ "minItems": 1,
3642
+ "maxItems": 100,
3643
+ "description": "Tools in this custom toolkit"
3644
}
3645
},
3711
- "shared_credentials": {
3712
- "type": "object",
3713
- "additionalProperties": {},
3714
- "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",
3715
- "x-experimental": true
3716
- },
3717
- "is_enabled_for_tool_router": {
3718
- "type": "boolean",
3719
- "description": "Whether this auth config is enabled for tool router"
3720
- },
3721
- "deprecated_params": {
3722
- "type": "object",
3723
- "properties": {
3724
- "default_connector_id": {
3725
- "type": "string",
3726
- "nullable": true,
3727
- "description": "Deprecated: Default connector ID"
3728
- },
3729
- "member_uuid": {
3730
- "type": "string",
3731
- "description": "Deprecated: Member UUID"
3732
- },
3733
- "toolkit_id": {
3734
- "type": "string",
3735
- "description": "Deprecated: Toolkit ID"
3736
- },
3737
- "expected_input_fields": {
3738
- "type": "array",
3739
- "items": {
3740
- "type": "object",
3741
- "additionalProperties": {}
3742
- },
3743
- "description": "Deprecated: Fields expected during connection initialization"
3646
+ "required": [
3647
+ "slug",
3648
+ "name",
3649
+ "description",
3650
+ "tools"
3651
+ ]
3652
+ },
3653
+ "description": "Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth."
3654
+ },
3655
+ "custom_tools": {
3656
+ "type": "array",
3657
+ "items": {
3658
+ "type": "object",
3659
+ "properties": {
3660
+ "slug": {
3661
+ "type": "string",
3662
+ "minLength": 1,
3663
+ "pattern": "^[a-zA-Z0-9_-]+$",
3664
+ "description": "Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.",
3665
+ "example": "GET_IMPORTANT_EMAILS"
3666
+ },
3667
+ "name": {
3668
+ "type": "string",
3669
+ "minLength": 1,
3670
+ "maxLength": 128,
3671
+ "description": "Human-readable display name",
3672
+ "example": "Get Important Emails"
3673
+ },
3674
+ "description": {
3675
+ "type": "string",
3676
+ "minLength": 1,
3677
+ "maxLength": 5120,
3678
+ "description": "Used for BM25 search matching and shown to the LLM.",
3679
+ "example": "Fetch emails marked as important from the last 24 hours"
3680
+ },
3681
+ "input_schema": {
3682
+ "type": "object",
3683
+ "additionalProperties": {},
3684
+ "description": "Must have type: \"object\" and a properties field.",
3685
+ "example": {
3686
+ "type": "object",
3687
+ "properties": {
3688
+ "limit": {
3689
+ "type": "number",
3690
+ "description": "Max results to return"
3691
+ }
3692
+ }
3693
}
3694
},
3746
- "required": [
3747
- "default_connector_id"
3748
- ],
3749
- "description": "DEPRECATED: This parameter will be removed in a future version.",
3750
- "deprecated": true
3751
- }
3695
+ "output_schema": {
3696
+ "type": "object",
3697
+ "additionalProperties": {},
3698
+ "description": "JSON Schema describing tool output (optional)"
3699
+ },
3700
+ "extends_toolkit": {
3701
+ "type": "string",
3702
+ "minLength": 1,
3703
+ "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).",
3704
+ "example": "gmail"
3705
+ }
3706
+ },
3707
+ "required": [
3708
+ "slug",
3709
+ "name",
3710
+ "description",
3711
+ "input_schema"
3712
+ ]
3713
},
3753
- "required": [
3754
- "id",
3755
- "uuid",
3756
- "type",
3757
- "toolkit",
3758
- "name",
3759
- "status",
3760
- "no_of_connections",
3761
- "tool_access_config"
3762
- ]
3714
+ "description": "Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection."
3715
}
3716
},
3765
- "next_cursor": {
3766
- "type": "string",
3767
- "nullable": true
3717
+ "additionalProperties": false,
3718
+ "description": "Experimental features - not stable, may be modified or removed in future versions.",
3719
+ "x-experimental": true
3720
+ }
3721
+ },
3722
+ "required": [
3723
+ "user_id"
3724
+ ]
3725
+ },
3726
+ "examples": {
3727
+ "Session with all toolkits": {
3728
+ "value": {
3729
+ "user_id": "user_123456789"
3730
+ }
3731
+ },
3732
+ "Session with only specific toolkits": {
3733
+ "value": {
3734
+ "user_id": "user_123456789",
3735
+ "toolkits": {
3736
+ "enable": [
3737
+ "gmail",
3738
+ "slack"
3739
+ ]
3740
+ }
3741
+ }
3742
+ },
3743
+ "Session with only specific toolkits disabled": {
3744
+ "value": {
3745
+ "user_id": "user_123456789",
3746
+ "toolkits": {
3747
+ "disable": [
3748
+ "gmail",
3749
+ "slack"
3750
+ ]
3751
+ }
3752
+ }
3753
+ },
3754
+ "Session with connection manager enabled": {
3755
+ "value": {
3756
+ "user_id": "user_123456789",
3757
+ "manage_connections": {
3758
+ "enable": true
3759
+ }
3760
+ }
3761
+ },
3762
+ "Session with connection manager and specific toolkits": {
3763
+ "value": {
3764
+ "user_id": "user_123456789",
3765
+ "toolkits": {
3766
+ "enable": [
3767
+ "gmail",
3768
+ "slack"
3769
+ ]
3770
},
3769
- "total_pages": {
3770
- "type": "number"
3771
+ "manage_connections": {
3772
+ "enable": true
3773
+ }
3774
+ }
3775
+ },
3776
+ "Session with custom callback URL": {
3777
+ "value": {
3778
+ "user_id": "user_123456789",
3779
+ "toolkits": {
3780
+ "enable": [
3781
+ "github",
3782
+ "slack"
3783
+ ]
3784
},
3772
- "current_page": {
3773
- "type": "number"
3785
+ "manage_connections": {
3786
+ "enable": true,
3787
+ "callback_url": "https://your-app.com/auth/callback"
3788
+ }
3789
+ }
3790
+ },
3791
+ "Session with workbench configuration": {
3792
+ "value": {
3793
+ "user_id": "user_123456789",
3794
+ "toolkits": {
3795
+ "enable": [
3796
+ "gmail"
3797
+ ]
3798
},
3775
- "total_items": {
3776
- "type": "number"
3799
+ "workbench": {
3800
+ "enable_proxy_execution": true,
3801
+ "auto_offload_threshold": 10000
3802
}
3778
- },
3779
- "required": [
3780
- "items",
3781
- "total_pages",
3782
- "current_page",
3783
- "total_items"
3784
- ]
3785
- }
3786
- }
3787
- }
3788
- },
3789
- "400": {
3790
- "description": "Bad request",
3791
- "content": {
3792
- "application/json": {
3793
- "schema": {
3794
- "$ref": "#/components/schemas/Error"
3795
- }
3796
- }
3797
- }
3798
- },
3799
- "401": {
3800
- "description": "Unauthorized",
3801
- "content": {
3802
- "application/json": {
3803
- "schema": {
3804
- "$ref": "#/components/schemas/Error"
3805
- }
3806
- }
3807
- }
3808
- },
3809
- "404": {
3810
- "description": "Not found",
3811
- "content": {
3812
- "application/json": {
3813
- "schema": {
3814
- "$ref": "#/components/schemas/Error"
3815
- }
3816
- }
3817
- }
3818
- },
3819
- "500": {
3820
- "description": "Internal server error",
3821
- "content": {
3822
- "application/json": {
3823
- "schema": {
3824
- "$ref": "#/components/schemas/Error"
3825
- }
3826
- }
3827
- }
3828
- }
3829
- },
3830
- "x-api-version": "3.1"
3831
- }
3832
- },
3833
- "/api/v3.1/auth_configs/{nanoid}": {
3834
- "get": {
3835
- "summary": "Get single authentication configuration by ID",
3836
- "description": "Retrieves detailed information about a specific authentication configuration using its unique identifier.",
3837
- "tags": [
3838
- "Auth Configs"
3839
- ],
3840
- "operationId": "getAuthConfigsByNanoid",
3841
- "security": [
3842
- {
3843
- "ApiKeyAuth": []
3844
- },
3845
- {
3846
- "UserApiKeyAuth": []
3847
- }
3848
- ],
3849
- "parameters": [
3850
- {
3851
- "schema": {
3852
- "type": "string",
3853
- "format": "authConfigId",
3854
- "description": "The unique identifier of the authentication configuration to retrieve"
3855
- },
3856
- "required": true,
3857
- "description": "The unique identifier of the authentication configuration to retrieve",
3858
- "name": "nanoid",
3859
- "in": "path"
3803
+ }
3804
+ },
3805
+ "Session with global tags filter": {
3806
+ "value": {
3807
+ "user_id": "user_123456789",
3808
+ "toolkits": {
3809
+ "enable": [
3810
+ "gmail",
3811
+ "slack"
3812
+ ]
3813
+ },
3814
+ "tags": [
3815
+ "readOnlyHint",
3816
+ "idempotentHint"
3817
+ ]
3818
+ }
3819
+ },
3820
+ "Session with auth config overrides": {
3821
+ "value": {
3822
+ "user_id": "user_123456789",
3823
+ "toolkits": {
3824
+ "enable": [
3825
+ "gmail",
3826
+ "slack"
3827
+ ]
3828
+ },
3829
+ "auth_configs": {
3830
+ "gmail": "ac_1a2b3c4d5e6f",
3831
+ "slack": "ac_7g8h9i0j1k2l"
3832
+ }
3833
+ }
3834
+ },
3835
+ "Session with connected account overrides": {
3836
+ "value": {
3837
+ "user_id": "user_123456789",
3838
+ "toolkits": {
3839
+ "enable": [
3840
+ "gmail",
3841
+ "slack"
3842
+ ]
3843
+ },
3844
+ "connected_accounts": {
3845
+ "gmail": "ca_1a2b3c4d5e6f",
3846
+ "slack": "ca_7g8h9i0j1k2l"
3847
+ }
3848
+ }
3849
+ },
3850
+ "Session with comprehensive configuration": {
3851
+ "value": {
3852
+ "user_id": "user_123456789",
3853
+ "toolkits": {
3854
+ "enable": [
3855
+ "gmail",
3856
+ "slack",
3857
+ "github"
3858
+ ]
3859
+ },
3860
+ "auth_configs": {
3861
+ "gmail": "ac_1a2b3c4d5e6f",
3862
+ "slack": "ac_7g8h9i0j1k2l"
3863
+ },
3864
+ "connected_accounts": {
3865
+ "github": "ca_3m4n5o6p7q8r"
3866
+ },
3867
+ "manage_connections": {
3868
+ "enable": true,
3869
+ "callback_url": "https://your-app.com/auth/callback"
3870
+ },
3871
+ "tools": {
3872
+ "gmail": {
3873
+ "enable": [
3874
+ "GMAIL_SEND_EMAIL",
3875
+ "GMAIL_FETCH_EMAILS"
3876
+ ]
3877
+ },
3878
+ "slack": {
3879
+ "disable": [
3880
+ "SLACK_ADD_EMOJI"
3881
+ ]
3882
+ },
3883
+ "slack_bot": {
3884
+ "tags": [
3885
+ "destructiveHint"
3886
+ ]
3887
+ }
3888
+ },
3889
+ "tags": [
3890
+ "destructiveHint",
3891
+ "idempotentHint"
3892
+ ],
3893
+ "workbench": {
3894
+ "enable_proxy_execution": true,
3895
+ "auto_offload_threshold": 10000
3896
+ }
3897
+ }
3898
+ },
3899
+ "Session with disabled toolkits and global tags": {
3900
+ "value": {
3901
+ "user_id": "user_123456789",
3902
+ "toolkits": {
3903
+ "disable": [
3904
+ "gmail"
3905
+ ]
3906
+ },
3907
+ "tags": [
3908
+ "readOnlyHint"
3909
+ ]
3910
+ }
3911
+ }
3912
+ }
3913
+ }
3914
}
3861
- ],
3915
+ },
3916
"responses": {
3863
- "200": {
3864
- "description": "Successfully fetched auth config",
3917
+ "201": {
3918
+ "description": "Session successfully created. Returns the session ID and MCP server URL for the created session.",
3919
"content": {
3920
"application/json": {
3921
"schema": {
3922
"type": "object",
3923
"properties": {
3870
- "id": {
3871
- "type": "string",
3872
- "format": "authConfigId",
3873
- "description": "The unique ID of the authentication configuration"
3874
- },
3875
- "uuid": {
3876
- "type": "string",
3877
- "description": "The UUID of the authentication configuration (for backward compatibility)"
3878
- },
3879
- "type": {
3924
+ "session_id": {
3925
"type": "string",
3881
- "enum": [
3882
- "default",
3883
- "custom"
3884
- ],
3885
- "description": "The type of the authentication configuration (custom or default)"
3926
+ "format": "toolRouterSessionId",
3927
+ "description": "The identifier of the session",
3928
+ "example": "trs_1a2b3c4d5e6f"
3929
},
3887
- "toolkit": {
3930
+ "mcp": {
3931
"type": "object",
3932
"properties": {
3890
- "slug": {
3891
- "type": "string",
3892
- "description": "The unique identifier of the integration app"
3893
- },
3894
- "logo": {
3895
- "type": "string",
3896
- "description": "The URL to the integration app's logo image"
3897
- },
3898
- "auth_guide_url": {
3933
+ "type": {
3934
"type": "string",
3900
- "nullable": true,
3901
- "description": "URL to a guide page with authentication setup instructions"
3935
+ "enum": [
3936
+ "http"
3937
+ ],
3938
+ "description": "The type of the MCP server. Can be http"
3939
},
3903
- "auth_hint_url": {
3904
- "type": "string",
3905
- "nullable": true,
3906
- "description": "URL to a page where users can obtain or configure credentials"
3907
- }
3908
- },
3909
- "required": [
3910
- "slug",
3911
- "logo"
3912
- ],
3913
- "description": "Information about the associated integration"
3914
- },
3915
- "name": {
3916
- "type": "string",
3917
- "description": "The display name of the authentication configuration"
3918
- },
3919
- "auth_scheme": {
3920
- "type": "string",
3921
- "enum": [
3922
- "OAUTH2",
3923
- "OAUTH1",
3924
- "API_KEY",
3925
- "BASIC",
3926
- "BILLCOM_AUTH",
3927
- "BEARER_TOKEN",
3928
- "GOOGLE_SERVICE_ACCOUNT",
3929
- "NO_AUTH",
3930
- "BASIC_WITH_JWT",
3931
- "CALCOM_AUTH",
3932
- "SERVICE_ACCOUNT",
3933
- "SAML",
3934
- "DCR_OAUTH",
3935
- "S2S_OAUTH2"
3936
- ],
3937
- "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"
3938
- },
3939
- "is_composio_managed": {
3940
- "type": "boolean",
3941
- "description": "Whether this authentication configuration is managed by Composio or the user"
3942
- },
3943
- "credentials": {
3944
- "type": "object",
3945
- "additionalProperties": {},
3946
- "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"
3947
- },
3948
- "proxy_config": {
3949
- "type": "object",
3950
- "nullable": true,
3951
- "properties": {
3952
- "proxy_url": {
3940
+ "url": {
3941
"type": "string",
3942
"format": "uri",
3955
- "description": "The url of the auth proxy"
3956
- },
3957
- "proxy_auth_key": {
3958
- "type": "string",
3959
- "description": "The auth key for the auth proxy"
3943
+ "description": "The URL of the MCP server",
3944
+ "example": "https://app.composio.dev/tool_router/v3/trs_1a2b3c4d5e6f/mcp"
3945
}
3946
},
3947
"required": [
3963
- "proxy_url"
3948
+ "type",
3949
+ "url"
3950
]
3951
},
3966
- "status": {
3967
- "type": "string",
3968
- "enum": [
3969
- "ENABLED",
3970
- "DISABLED"
3971
- ],
3972
- "description": "Current status of the authentication configuration"
3973
- },
3974
- "created_by": {
3975
- "type": "string",
3976
- "description": "The identifier of the user who created the auth config"
3977
- },
3978
- "created_at": {
3979
- "type": "string",
3980
- "description": "ISO 8601 date-time when the auth config was created"
3981
- },
3982
- "last_updated_at": {
3983
- "type": "string",
3984
- "description": "ISO 8601 date-time when the auth config was last updated"
3985
- },
3986
- "no_of_connections": {
3987
- "type": "number",
3988
- "description": "The number of active connections using this auth config"
3989
- },
3990
- "expected_input_fields": {
3991
- "type": "array",
3992
- "items": {
3993
- "nullable": true,
3994
- "type": "object"
3995
- },
3996
- "description": "Fields expected during connection initialization"
3997
- },
3998
- "restrict_to_following_tools": {
3952
+ "tool_router_tools": {
3953
"type": "array",
3954
"items": {
3955
"type": "string"
3956
},
4003
- "description": "Use tool_access_config instead. This field will be deprecated in the future.",
4004
- "deprecated": true
3957
+ "description": "List of available tools in this session"
3958
},
4006
- "tool_access_config": {
3959
+ "config": {
3960
"type": "object",
3961
"properties": {
4009
- "tools_for_connected_account_creation": {
4010
- "type": "array",
4011
- "items": {
4012
- "type": "string"
4013
- },
4014
- "default": [],
4015
- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."
4016
- },
4017
- "tools_available_for_execution": {
4018
- "type": "array",
4019
- "items": {
4020
- "type": "string"
4021
- },
4022
- "default": [],
4023
- "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."
4024
- }
4025
- }
4026
- },
4027
- "shared_credentials": {
4028
- "type": "object",
4029
- "additionalProperties": {},
4030
- "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config",
4031
- "x-experimental": true
4032
- },
4033
- "is_enabled_for_tool_router": {
4034
- "type": "boolean",
4035
- "description": "Whether this auth config is enabled for tool router"
4036
- },
4037
- "deprecated_params": {
4038
- "type": "object",
4039
- "properties": {
4040
- "default_connector_id": {
4041
- "type": "string",
4042
- "nullable": true,
4043
- "description": "Deprecated: Default connector ID"
4044
- },
4045
- "member_uuid": {
4046
- "type": "string",
4047
- "description": "Deprecated: Member UUID"
4048
- },
4049
- "toolkit_id": {
3962
+ "user_id": {
3963
"type": "string",
4051
- "description": "Deprecated: Toolkit ID"
3964
+ "description": "User identifier for this session"
3965
},
4053
- "expected_input_fields": {
4054
- "type": "array",
4055
- "items": {
4056
- "type": "object",
4057
- "additionalProperties": {}
4058
- },
4059
- "description": "Deprecated: Fields expected during connection initialization"
4060
- }
4061
- },
4062
- "required": [
4063
- "default_connector_id"
4064
- ],
4065
- "description": "DEPRECATED: This parameter will be removed in a future version.",
4066
- "deprecated": true
4067
- }
4068
- },
4069
- "required": [
4070
- "id",
4071
- "uuid",
4072
- "type",
4073
- "toolkit",
4074
- "name",
4075
- "status",
4076
- "no_of_connections",
4077
- "tool_access_config"
4078
- ]
4079
- }
4080
- }
4081
- }
4082
- },
4083
- "400": {
4084
- "description": "Bad request - Invalid auth config ID format",
4085
- "content": {
4086
- "application/json": {
4087
- "schema": {
4088
- "$ref": "#/components/schemas/Error"
4089
- }
4090
- }
4091
- }
4092
- },
4093
- "401": {
4094
- "description": "Unauthorized - Authentication required",
4095
- "content": {
4096
- "application/json": {
4097
- "schema": {
4098
- "$ref": "#/components/schemas/Error"
4099
- }
4100
- }
4101
- }
4102
- },
4103
- "404": {
4104
- "description": "Not found - Auth configuration does not exist",
4105
- "content": {
4106
- "application/json": {
4107
- "schema": {
4108
- "$ref": "#/components/schemas/Error"
4109
- }
4110
- }
4111
- }
4112
- },
4113
- "500": {
4114
- "description": "Internal server error - Something went wrong on the server",
4115
- "content": {
4116
- "application/json": {
4117
- "schema": {
4118
- "$ref": "#/components/schemas/Error"
4119
- }
4120
- }
4121
- }
4122
- }
4123
- },
4124
- "x-api-version": "3.1"
4125
- },
4126
- "patch": {
4127
- "summary": "Update an authentication configuration",
4128
- "description": "Modifies an existing authentication configuration with new credentials or other settings. Only specified fields will be updated.",
4129
- "tags": [
4130
- "Auth Configs"
4131
- ],
4132
- "operationId": "patchAuthConfigsByNanoid",
4133
- "security": [
4134
- {
4135
- "ApiKeyAuth": []
4136
- },
4137
- {
4138
- "UserApiKeyAuth": []
4139
- }
4140
- ],
4141
- "parameters": [
4142
- {
4143
- "schema": {
4144
- "type": "string",
4145
- "format": "authConfigId",
4146
- "description": "The unique identifier of the authentication configuration to update"
4147
- },
4148
- "required": true,
4149
- "description": "The unique identifier of the authentication configuration to update",
4150
- "name": "nanoid",
4151
- "in": "path"
4152
- }
4153
- ],
4154
- "requestBody": {
4155
- "content": {
4156
- "application/json": {
4157
- "schema": {
4158
- "oneOf": [
4159
- {
4160
- "type": "object",
4161
- "properties": {
4162
- "type": {
4163
- "type": "string",
4164
- "enum": [
4165
- "custom"
4166
- ]
4167
- },
4168
- "name": {
4169
- "type": "string",
4170
- "minLength": 1,
4171
- "description": "The display name of the authentication configuration"
4172
- },
4173
- "credentials": {
4174
- "type": "object",
4175
- "properties": {
4176
- "scopes": {
4177
- "anyOf": [
4178
- {
4179
- "type": "string"
4180
- },
4181
- {
4182
- "type": "array",
4183
- "items": {
4184
- "type": "string"
3966
+ "toolkits": {
3967
+ "anyOf": [
3968
+ {
3969
+ "type": "object",
3970
+ "properties": {
3971
+ "enabled": {
3972
+ "type": "array",
3973
+ "items": {
3974
+ "type": "string"
3975
+ }
3976
}
4186
- }
4187
- ]
4188
- },
4189
- "user_scopes": {
4190
- "anyOf": [
4191
- {
4192
- "type": "string"
3977
},
4194
- {
4195
- "type": "array",
4196
- "items": {
4197
- "type": "string"
3978
+ "required": [
3979
+ "enabled"
3980
+ ],
3981
+ "additionalProperties": false
3982
+ },
3983
+ {
3984
+ "type": "object",
3985
+ "properties": {
3986
+ "disabled": {
3987
+ "type": "array",
3988
+ "items": {
3989
+ "type": "string"
3990
+ }
3991
}
4199
- }
4200
- ]
4201
- }
4202
- }
4203
- },
4204
- "proxy_config": {
4205
- "type": "object",
4206
- "nullable": true,
4207
- "properties": {
4208
- "proxy_url": {
3992
+ },
3993
+ "required": [
3994
+ "disabled"
3995
+ ],
3996
+ "additionalProperties": false
3997
+ }
3998
+ ],
3999
+ "description": "Toolkit configuration - either enabled list or disabled list"
4000
+ },
4001
+ "auth_configs": {
4002
+ "type": "object",
4003
+ "additionalProperties": {
4004
"type": "string",
4210
- "format": "uri",
4211
- "description": "The url of the auth proxy"
4005
+ "format": "authConfigId"
4006
},
4213
- "proxy_auth_key": {
4214
- "type": "string",
4215
- "description": "The auth key for the auth proxy"
4216
- }
4007
+ "description": "Auth config overrides per toolkit"
4008
},
4218
- "required": [
4219
- "proxy_url"
4220
- ]
4221
- },
4222
- "restrict_to_following_tools": {
4223
- "type": "array",
4224
- "items": {
4225
- "type": "string"
4009
+ "connected_accounts": {
4010
+ "type": "object",
4011
+ "additionalProperties": {
4012
+ "type": "string",
4013
+ "format": "connectedAccountId"
4014
+ },
4015
+ "description": "Connected account overrides per toolkit"
4016
},
4227
- "description": "Use tool_access_config instead. This field will be deprecated in the future.",
4228
- "deprecated": true
4229
- },
4230
- "tool_access_config": {
4231
- "type": "object",
4232
- "properties": {
4233
- "tools_for_connected_account_creation": {
4234
- "type": "array",
4235
- "items": {
4236
- "type": "string"
4017
+ "manage_connections": {
4018
+ "type": "object",
4019
+ "properties": {
4020
+ "enabled": {
4021
+ "type": "boolean",
4022
+ "default": true,
4023
+ "description": "Whether to enable the connection manager for automatic connection handling"
4024
},
4238
- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."
4239
- },
4240
- "tools_available_for_execution": {
4241
- "type": "array",
4242
- "items": {
4243
- "type": "string"
4025
+ "callback_url": {
4026
+ "type": "string",
4027
+ "format": "uri",
4028
+ "description": "Custom callback URL for connected account auth flows"
4029
},
4245
- "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."
4246
- }
4247
- }
4248
- },
4249
- "shared_credentials": {
4250
- "type": "object",
4251
- "additionalProperties": {},
4252
- "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config."
4253
- },
4254
- "is_enabled_for_tool_router": {
4255
- "type": "boolean",
4256
- "description": "Whether this auth config is enabled for tool router"
4257
- }
4258
- },
4259
- "required": [
4260
- "type"
4261
- ]
4262
- },
4263
- {
4264
- "type": "object",
4265
- "properties": {
4266
- "type": {
4267
- "type": "string",
4268
- "enum": [
4269
- "default"
4270
- ]
4271
- },
4272
- "name": {
4273
- "type": "string",
4274
- "minLength": 1,
4275
- "description": "The display name of the authentication configuration"
4276
- },
4277
- "scopes": {
4278
- "anyOf": [
4279
- {
4280
- "type": "string"
4281
- },
4282
- {
4283
- "type": "array",
4284
- "items": {
4285
- "type": "string"
4030
+ "enable_wait_for_connections": {
4031
+ "type": "boolean",
4032
+ "default": false,
4033
+ "description": "Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models."
4034
+ },
4035
+ "enable_connection_removal": {
4036
+ "type": "boolean",
4037
+ "default": true,
4038
+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS. Default true."
4039
}
4287
- }
4288
- ]
4289
- },
4290
- "user_scopes": {
4291
- "anyOf": [
4292
- {
4293
- "type": "string"
4040
},
4295
- {
4296
- "type": "array",
4297
- "items": {
4298
- "type": "string"
4041
+ "description": "Manage connections configuration"
4042
+ },
4043
+ "tools": {
4044
+ "type": "object",
4045
+ "additionalProperties": {
4046
+ "anyOf": [
4047
+ {
4048
+ "type": "object",
4049
+ "properties": {
4050
+ "enabled": {
4051
+ "type": "array",
4052
+ "items": {
4053
+ "type": "string"
4054
+ }
4055
+ }
4056
+ },
4057
+ "required": [
4058
+ "enabled"
4059
+ ],
4060
+ "additionalProperties": false
4061
+ },
4062
+ {
4063
+ "type": "object",
4064
+ "properties": {
4065
+ "disabled": {
4066
+ "type": "array",
4067
+ "items": {
4068
+ "type": "string"
4069
+ }
4070
+ }
4071
+ },
4072
+ "required": [
4073
+ "disabled"
4074
+ ],
4075
+ "additionalProperties": false
4076
+ },
4077
+ {
4078
+ "type": "object",
4079
+ "properties": {
4080
+ "tags": {
4081
+ "type": "object",
4082
+ "properties": {
4083
+ "enabled": {
4084
+ "type": "array",
4085
+ "items": {
4086
+ "type": "string",
4087
+ "enum": [
4088
+ "readOnlyHint",
4089
+ "destructiveHint",
4090
+ "idempotentHint",
4091
+ "openWorldHint"
4092
+ ]
4093
+ },
4094
+ "description": "Tags that the tool must have at least one of"
4095
+ },
4096
+ "disabled": {
4097
+ "type": "array",
4098
+ "items": {
4099
+ "type": "string",
4100
+ "enum": [
4101
+ "readOnlyHint",
4102
+ "destructiveHint",
4103
+ "idempotentHint",
4104
+ "openWorldHint"
4105
+ ]
4106
+ },
4107
+ "description": "Tags that the tool must NOT have any of"
4108
+ }
4109
+ }
4110
+ }
4111
+ },
4112
+ "required": [
4113
+ "tags"
4114
+ ],
4115
+ "additionalProperties": false
4116
+ }
4117
+ ]
4118
+ },
4119
+ "description": "Tool-level configuration per toolkit"
4120
+ },
4121
+ "tags": {
4122
+ "type": "object",
4123
+ "properties": {
4124
+ "enabled": {
4125
+ "type": "array",
4126
+ "items": {
4127
+ "type": "string",
4128
+ "enum": [
4129
+ "readOnlyHint",
4130
+ "destructiveHint",
4131
+ "idempotentHint",
4132
+ "openWorldHint"
4133
+ ]
4134
+ },
4135
+ "description": "Tags that the tool must have at least one of"
4136
+ },
4137
+ "disabled": {
4138
+ "type": "array",
4139
+ "items": {
4140
+ "type": "string",
4141
+ "enum": [
4142
+ "readOnlyHint",
4143
+ "destructiveHint",
4144
+ "idempotentHint",
4145
+ "openWorldHint"
4146
+ ]
4147
+ },
4148
+ "description": "Tags that the tool must NOT have any of"
4149
}
4300
- }
4301
- ]
4302
- },
4303
- "restrict_to_following_tools": {
4304
- "type": "array",
4305
- "items": {
4306
- "type": "string"
4150
+ },
4151
+ "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."
4152
},
4308
- "description": "Use tool_access_config instead. This field will be deprecated in the future.",
4309
- "deprecated": true
4310
- },
4311
- "tool_access_config": {
4312
- "type": "object",
4313
- "properties": {
4314
- "tools_for_connected_account_creation": {
4315
- "type": "array",
4316
- "items": {
4317
- "type": "string"
4153
+ "workbench": {
4154
+ "type": "object",
4155
+ "properties": {
4156
+ "enable": {
4157
+ "type": "boolean",
4158
+ "description": "Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed."
4159
},
4319
- "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes."
4160
+ "proxy_execution_enabled": {
4161
+ "type": "boolean",
4162
+ "description": "Whether proxy execution is enabled in the workbench"
4163
+ },
4164
+ "auto_offload_threshold": {
4165
+ "type": "number",
4166
+ "minimum": 0,
4167
+ "exclusiveMinimum": true,
4168
+ "description": "Character threshold after which tool execution response are saved to a file in workbench. Default is 20k."
4169
+ }
4170
},
4321
- "tools_available_for_execution": {
4322
- "type": "array",
4323
- "items": {
4324
- "type": "string"
4171
+ "default": {
4172
+ "enable": true,
4173
+ "proxy_execution_enabled": true
4174
+ },
4175
+ "description": "Workbench configuration"
4176
+ },
4177
+ "multi_account": {
4178
+ "type": "object",
4179
+ "properties": {
4180
+ "enable": {
4181
+ "type": "boolean",
4182
+ "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration."
4183
},
4326
- "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config."
4327
- }
4328
- }
4329
- },
4330
- "shared_credentials": {
4331
- "type": "object",
4332
- "additionalProperties": {},
4333
- "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config."
4334
- },
4335
- "is_enabled_for_tool_router": {
4336
- "type": "boolean",
4337
- "description": "Whether this auth config is enabled for tool router"
4338
- }
4184
+ "max_accounts_per_toolkit": {
4185
+ "type": "integer",
4186
+ "description": "Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled."
4187
+ },
4188
+ "require_explicit_selection": {
4189
+ "type": "boolean",
4190
+ "description": "When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account."
4191
+ }
4192
+ },
4193
+ "description": "Multi-account configuration for this session."
4194
+ }
4195
+ },
4196
+ "required": [
4197
+ "user_id"
4198
+ ],
4199
+ "description": "The session configuration including user, toolkits, and overrides"
4200
},
4340
- "required": [
4341
- "type"
4342
- ]
4343
- }
4344
- ]
4345
- },
4346
- "examples": {
4347
- "standardUpdate": {
4348
- "summary": "Standard credential update",
4349
- "value": {
4350
- "auth_config": {
4351
- "credentials": {
4352
- "api_key": "YOUR_NEW_API_KEY",
4353
- "client_secret": "YOUR_NEW_CLIENT_SECRET"
4201
+ "experimental": {
4202
+ "type": "object",
4203
+ "properties": {
4204
+ "assistive_prompt": {
4205
+ "type": "string",
4206
+ "description": "The assistive system prompt for the tool router session"
4207
+ },
4208
+ "custom_toolkits": {
4209
+ "type": "array",
4210
+ "items": {
4211
+ "type": "object",
4212
+ "properties": {
4213
+ "slug": {
4214
+ "type": "string",
4215
+ "minLength": 1,
4216
+ "pattern": "^[a-zA-Z0-9_-]+$"
4217
+ },
4218
+ "name": {
4219
+ "type": "string",
4220
+ "minLength": 1,
4221
+ "maxLength": 128
4222
+ },
4223
+ "description": {
4224
+ "type": "string",
4225
+ "minLength": 1,
4226
+ "maxLength": 2048
4227
+ },
4228
+ "tools": {
4229
+ "type": "array",
4230
+ "items": {
4231
+ "type": "object",
4232
+ "properties": {
4233
+ "slug": {
4234
+ "type": "string",
4235
+ "description": "Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)"
4236
+ },
4237
+ "name": {
4238
+ "type": "string",
4239
+ "minLength": 1,
4240
+ "maxLength": 128
4241
+ },
4242
+ "description": {
4243
+ "type": "string",
4244
+ "minLength": 1,
4245
+ "maxLength": 5120
4246
+ },
4247
+ "input_schema": {
4248
+ "type": "object",
4249
+ "additionalProperties": {}
4250
+ },
4251
+ "output_schema": {
4252
+ "type": "object",
4253
+ "additionalProperties": {}
4254
+ },
4255
+ "original_slug": {
4256
+ "type": "string",
4257
+ "description": "Original tool slug as provided by the user"
4258
+ }
4259
+ },
4260
+ "required": [
4261
+ "slug",
4262
+ "name",
4263
+ "description",
4264
+ "input_schema",
4265
+ "original_slug"
4266
+ ]
4267
+ }
4268
+ }
4269
+ },
4270
+ "required": [
4271
+ "slug",
4272
+ "name",
4273
+ "description",
4274
+ "tools"
4275
+ ]
4276
+ },
4277
+ "description": "User-defined custom toolkits with grouped tools (no-auth)"
4278
+ },
4279
+ "custom_tools": {
4280
+ "type": "array",
4281
+ "items": {
4282
+ "type": "object",
4283
+ "properties": {
4284
+ "slug": {
4285
+ "type": "string",
4286
+ "description": "Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)"
4287
+ },
4288
+ "name": {
4289
+ "type": "string",
4290
+ "minLength": 1,
4291
+ "maxLength": 128
4292
+ },
4293
+ "description": {
4294
+ "type": "string",
4295
+ "minLength": 1,
4296
+ "maxLength": 5120
4297
+ },
4298
+ "input_schema": {
4299
+ "type": "object",
4300
+ "additionalProperties": {}
4301
+ },
4302
+ "output_schema": {
4303
+ "type": "object",
4304
+ "additionalProperties": {}
4305
+ },
4306
+ "extends_toolkit": {
4307
+ "type": "string",
4308
+ "minLength": 1
4309
+ },
4310
+ "original_slug": {
4311
+ "type": "string",
4312
+ "description": "Original tool slug as provided by the user"
4313
+ }
4314
+ },
4315
+ "required": [
4316
+ "slug",
4317
+ "name",
4318
+ "description",
4319
+ "input_schema",
4320
+ "original_slug"
4321
+ ]
4322
+ },
4323
+ "description": "Custom tools — standalone or extending Composio toolkits"
4324
+ }
4325
},
4355
- "restrict_to_following_tools": [
4356
- "GMAIL_SEND_EMAIL",
4357
- "GMAIL_FETCH_EMAILS"
4358
- ]
4326
+ "description": "Experimental features including the generated system prompt. Only returned on session creation, not on GET.",
4327
+ "x-experimental": true
4328
}
4360
- }
4329
+ },
4330
+ "required": [
4331
+ "session_id",
4332
+ "mcp",
4333
+ "tool_router_tools",
4334
+ "config"
4335
+ ]
4336
}
4337
}
4338
}
4364
- }
4365
- },
4366
- "responses": {
4367
- "200": {
4368
- "description": "Successfully updated auth config",
4339
+ },
4340
+ "400": {
4341
+ "description": "Bad request. This may occur if the user_id format is invalid, toolkit names are invalid, or auth_config_id IDs are malformed.",
4342
"content": {
4343
"application/json": {
4344
"schema": {
4372
- "type": "object",
4373
- "properties": {}
4345
+ "$ref": "#/components/schemas/Error"
4346
}
4347
}
4348
}
4349
},
4378
- "400": {
4379
- "description": "Bad request - Invalid input or credentials format",
4350
+ "401": {
4351
+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",
4352
"content": {
4353
"application/json": {
4354
"schema": {
4357
}
4358
}
4359
},
4388
- "401": {
4389
- "description": "Unauthorized - Authentication required",
4360
+ "403": {
4361
+ "description": "Forbidden. The user is not authorized to create a tool router session.",
4362
"content": {
4363
"application/json": {
4364
"schema": {
4367
}
4368
}
4369
},
4398
- "404": {
4399
- "description": "Not found - Auth configuration does not exist",
4370
+ "408": {
4371
+ "description": "Request timeout. The session creation took too long to complete.",
4372
"content": {
4373
"application/json": {
4374
"schema": {
4378
}
4379
},
4380
"500": {
4409
- "description": "Internal server error - Something went wrong on the server",
4381
+ "description": "Internal server error. An unexpected error occurred while processing the request.",
4382
"content": {
4383
"application/json": {
4384
"schema": {
4389
}
4390
},
4391
"x-api-version": "3.1"
4420
- },
4421
- "delete": {
4422
- "summary": "Delete an authentication configuration",
4423
- "description": "Soft-deletes an authentication configuration by marking it as deleted in the database. This operation cannot be undone.",
4392
+ }
4393
+ },
4394
+ "/api/v3.1/org/usage/summary": {
4395
+ "post": {
4396
+ "summary": "Org usage summary",
4397
+ "description": "Aggregated metering usage for the authenticated organization. By default includes all projects; use `filters.project_id` to restrict to one or more projects (must belong to the org). Values are summed from raw metering events grouped by `entity_type`.",
4398
"tags": [
4425
- "Auth Configs"
4399
+ "Organization"
4400
],
4427
- "operationId": "deleteAuthConfigsByNanoid",
4401
+ "operationId": "postOrgUsageSummary",
4402
"security": [
4403
{
4430
- "ApiKeyAuth": []
4431
- },
4432
- {
4433
- "UserApiKeyAuth": []
4434
- }
4435
- ],
4436
- "parameters": [
4437
- {
4438
- "schema": {
4439
- "type": "string",
4440
- "format": "authConfigId",
4441
- "description": "The unique identifier of the authentication configuration to delete"
4442
- },
4443
- "required": true,
4444
- "description": "The unique identifier of the authentication configuration to delete",
4445
- "name": "nanoid",
4446
- "in": "path"
4404
+ "OrgApiKeyAuth": []
4405
}
4406
],
4449
- "responses": {
4450
- "200": {
4451
- "description": "Successfully deleted auth config",
4452
- "content": {
4453
- "application/json": {
4454
- "schema": {
4455
- "type": "object",
4456
- "properties": {}
4457
- }
4458
- }
4459
- }
4460
- },
4461
- "400": {
4462
- "description": "Bad request - Invalid auth config ID format",
4463
- "content": {
4464
- "application/json": {
4465
- "schema": {
4466
- "$ref": "#/components/schemas/Error"
4467
- }
4468
- }
4469
- }
4470
- },
4471
- "401": {
4472
- "description": "Unauthorized - Authentication required",
4473
- "content": {
4474
- "application/json": {
4475
- "schema": {
4476
- "$ref": "#/components/schemas/Error"
4477
- }
4478
- }
4479
- }
4407
+ "requestBody": {
4408
+ "content": {
4409
+ "application/json": {
4410
+ "schema": {
4411
+ "type": "object",
4412
+ "properties": {
4413
+ "from": {
4414
+ "type": "number",
4415
+ "description": "Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`."
4416
+ },
4417
+ "to": {
4418
+ "type": "number",
4419
+ "description": "Exclusive range end (Unix epoch milliseconds). Defaults to now."
4420
+ },
4421
+ "entity_types": {
4422
+ "type": "array",
4423
+ "items": {
4424
+ "type": "string"
4425
+ },
4426
+ "description": "Filter to these metering entity types. Omit for all types."
4427
+ },
4428
+ "filters": {
4429
+ "type": "object",
4430
+ "properties": {
4431
+ "user_id": {
4432
+ "type": "array",
4433
+ "nullable": true,
4434
+ "items": {
4435
+ "type": "string",
4436
+ "minLength": 1
4437
+ },
4438
+ "description": "Filter to events matching these external end-user IDs. OR logic within the array."
4439
+ },
4440
+ "session_id": {
4441
+ "type": "array",
4442
+ "nullable": true,
4443
+ "items": {
4444
+ "type": "string",
4445
+ "minLength": 1
4446
+ },
4447
+ "description": "Filter to events matching these session IDs. OR logic within the array."
4448
+ },
4449
+ "project_id": {
4450
+ "type": "array",
4451
+ "nullable": true,
4452
+ "items": {
4453
+ "type": "string",
4454
+ "format": "projectId"
4455
+ },
4456
+ "description": "Restrict aggregates to one or more projects (must belong to the authenticated organization). OR logic within the array. Omit for org-wide totals."
4457
+ }
4458
+ }
4459
+ }
4460
+ }
4461
+ }
4462
+ }
4463
+ }
4464
+ },
4465
+ "responses": {
4466
+ "200": {
4467
+ "description": "Usage aggregates for the organization.",
4468
+ "content": {
4469
+ "application/json": {
4470
+ "schema": {
4471
+ "type": "object",
4472
+ "properties": {
4473
+ "entities": {
4474
+ "type": "object",
4475
+ "additionalProperties": {
4476
+ "type": "object",
4477
+ "properties": {
4478
+ "unit": {
4479
+ "type": "string"
4480
+ },
4481
+ "total_quantity": {
4482
+ "type": "string"
4483
+ },
4484
+ "event_count": {
4485
+ "type": "integer",
4486
+ "minimum": 0
4487
+ }
4488
+ },
4489
+ "required": [
4490
+ "unit",
4491
+ "total_quantity",
4492
+ "event_count"
4493
+ ]
4494
+ }
4495
+ }
4496
+ },
4497
+ "required": [
4498
+ "entities"
4499
+ ]
4500
+ }
4501
+ }
4502
+ }
4503
+ },
4504
+ "400": {
4505
+ "description": "Invalid time range, entity_types, or query parameters.",
4506
+ "content": {
4507
+ "application/json": {
4508
+ "schema": {
4509
+ "$ref": "#/components/schemas/Error"
4510
+ }
4511
+ }
4512
+ }
4513
+ },
4514
+ "401": {
4515
+ "description": "Authentication required.",
4516
+ "content": {
4517
+ "application/json": {
4518
+ "schema": {
4519
+ "$ref": "#/components/schemas/Error"
4520
+ }
4521
+ }
4522
+ }
4523
+ },
4524
+ "403": {
4525
+ "description": "Forbidden.",
4526
+ "content": {
4527
+ "application/json": {
4528
+ "schema": {
4529
+ "$ref": "#/components/schemas/Error"
4530
+ }
4531
+ }
4532
+ }
4533
},
4534
"404": {
4482
- "description": "Auth config not found - The specified configuration does not exist or was already deleted",
4535
+ "description": "Unknown project_id or project not in this organization.",
4536
"content": {
4537
"application/json": {
4538
"schema": {
4486
- "type": "object",
4487
- "properties": {}
4539
+ "$ref": "#/components/schemas/Error"
4540
}
4541
}
4542
}
4543
},
4544
"500": {
4493
- "description": "Internal server error - Something went wrong on the server",
4545
+ "description": "Failed to load usage from analytics store or feature configuration.",
4546
"content": {
4547
"application/json": {
4548
"schema": {
4555
"x-api-version": "3.1"
4556
}
4557
},
4506
- "/api/v3.1/auth_configs/{nanoid}/{status}": {
4507
- "patch": {
4508
- "summary": "Enable or disable an authentication configuration",
4509
- "description": "Updates the status of an authentication configuration to either enabled or disabled. Disabled configurations cannot be used for new connections.",
4558
+ "/api/v3.1/org/usage/{entity_type}": {
4559
+ "post": {
4560
+ "summary": "Org usage breakdown",
4561
+ "description": "Grouped metering usage breakdown for the authenticated organization. Groups results by a single dimension or column key. By default includes all projects; use `filters.project_id` to restrict.",
4562
"tags": [
4511
- "Auth Configs"
4563
+ "Organization"
4564
],
4513
- "operationId": "patchAuthConfigsByNanoidByStatus",
4565
+ "operationId": "postOrgUsageByEntityType",
4566
"security": [
4567
{
4516
- "ApiKeyAuth": []
4517
- },
4518
- {
4519
- "UserApiKeyAuth": []
4568
+ "OrgApiKeyAuth": []
4569
}
4570
],
4571
"parameters": [
4572
{
4573
"schema": {
4574
"type": "string",
4526
- "format": "authConfigId",
4527
- "description": "The unique identifier of the authentication configuration to update"
4528
- },
4529
- "required": true,
4530
- "description": "The unique identifier of the authentication configuration to update",
4531
- "name": "nanoid",
4532
- "in": "path"
4533
- },
4534
- {
4535
- "schema": {
4536
- "type": "string",
4537
- "enum": [
4538
- "ENABLED",
4539
- "DISABLED"
4540
- ],
4541
- "description": "The new status to set for the auth configuration"
4575
+ "description": "Metering entity type to break down (e.g. `tool_calls`, `sessions`)."
4576
},
4577
"required": true,
4544
- "description": "The new status to set for the auth configuration",
4545
- "name": "status",
4578
+ "description": "Metering entity type to break down (e.g. `tool_calls`, `sessions`).",
4579
+ "name": "entity_type",
4580
"in": "path"
4581
}
4582
],
4583
+ "requestBody": {
4584
+ "content": {
4585
+ "application/json": {
4586
+ "schema": {
4587
+ "type": "object",
4588
+ "properties": {
4589
+ "from": {
4590
+ "type": "number",
4591
+ "description": "Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`."
4592
+ },
4593
+ "to": {
4594
+ "type": "number",
4595
+ "description": "Exclusive range end (Unix epoch milliseconds). Defaults to now."
4596
+ },
4597
+ "group_by": {
4598
+ "type": "string",
4599
+ "description": "Dimension or column to group results by. Defaults to `tool_slug` for tool_calls and `user_id` for sessions."
4600
+ },
4601
+ "order_by": {
4602
+ "type": "string",
4603
+ "enum": [
4604
+ "key",
4605
+ "total_quantity",
4606
+ "event_count"
4607
+ ],
4608
+ "description": "Field to order groups by. Defaults to `total_quantity`."
4609
+ },
4610
+ "order_direction": {
4611
+ "type": "string",
4612
+ "enum": [
4613
+ "asc",
4614
+ "desc"
4615
+ ],
4616
+ "description": "Sort direction. Defaults to `desc`."
4617
+ },
4618
+ "limit": {
4619
+ "type": "integer",
4620
+ "minimum": 1,
4621
+ "maximum": 1000,
4622
+ "description": "Maximum number of groups to return. Defaults to 100, max 1000."
4623
+ },
4624
+ "filters": {
4625
+ "type": "object",
4626
+ "properties": {
4627
+ "user_id": {
4628
+ "type": "array",
4629
+ "nullable": true,
4630
+ "items": {
4631
+ "type": "string",
4632
+ "minLength": 1
4633
+ },
4634
+ "description": "Filter to events matching these external end-user IDs. OR logic within the array."
4635
+ },
4636
+ "session_id": {
4637
+ "type": "array",
4638
+ "nullable": true,
4639
+ "items": {
4640
+ "type": "string",
4641
+ "minLength": 1
4642
+ },
4643
+ "description": "Filter to events matching these session IDs. OR logic within the array."
4644
+ },
4645
+ "project_id": {
4646
+ "type": "array",
4647
+ "nullable": true,
4648
+ "items": {
4649
+ "type": "string",
4650
+ "format": "projectId"
4651
+ },
4652
+ "description": "Restrict aggregates to one or more projects (must belong to the authenticated organization). OR logic within the array. Omit for org-wide totals."
4653
+ }
4654
+ }
4655
+ }
4656
+ }
4657
+ }
4658
+ }
4659
+ }
4660
+ },
4661
"responses": {
4662
"200": {
4551
- "description": "Successfully updated auth config status",
4663
+ "description": "Usage breakdown for the organization.",
4664
"content": {
4665
"application/json": {
4666
"schema": {
4667
"type": "object",
4556
- "properties": {}
4668
+ "properties": {
4669
+ "entity_type": {
4670
+ "type": "string"
4671
+ },
4672
+ "unit": {
4673
+ "type": "string"
4674
+ },
4675
+ "total_quantity": {
4676
+ "type": "string"
4677
+ },
4678
+ "event_count": {
4679
+ "type": "integer",
4680
+ "minimum": 0
4681
+ },
4682
+ "groups": {
4683
+ "type": "array",
4684
+ "items": {
4685
+ "type": "object",
4686
+ "properties": {
4687
+ "key": {
4688
+ "type": "string"
4689
+ },
4690
+ "total_quantity": {
4691
+ "type": "string"
4692
+ },
4693
+ "event_count": {
4694
+ "type": "integer",
4695
+ "minimum": 0
4696
+ }
4697
+ },
4698
+ "required": [
4699
+ "key",
4700
+ "total_quantity",
4701
+ "event_count"
4702
+ ]
4703
+ }
4704
+ }
4705
+ },
4706
+ "required": [
4707
+ "entity_type",
4708
+ "unit",
4709
+ "total_quantity",
4710
+ "event_count",
4711
+ "groups"
4712
+ ]
4713
}
4714
}
4715
}
4716
},
4717
"400": {
4562
- "description": "Bad request - Invalid auth config ID or status value",
4718
+ "description": "Invalid entity_type, group_by, time range, or query parameters.",
4719
"content": {
4720
"application/json": {
4721
"schema": {
4725
}
4726
},
4727
"401": {
4572
- "description": "Unauthorized - Authentication required",
4728
+ "description": "Authentication required.",
4729
+ "content": {
4730
+ "application/json": {
4731
+ "schema": {
4732
+ "$ref": "#/components/schemas/Error"
4733
+ }
4734
+ }
4735
+ }
4736
+ },
4737
+ "403": {
4738
+ "description": "Forbidden.",
4739
"content": {
4740
"application/json": {
4741
"schema": {
4745
}
4746
},
4747
"404": {
4582
- "description": "Not found - Auth configuration does not exist",
4748
+ "description": "Unknown project_id or project not in this organization.",
4749
"content": {
4750
"application/json": {
4751
"schema": {
4755
}
4756
},
4757
"500": {
4592
- "description": "Internal server error - Something went wrong on the server",
4758
+ "description": "Failed to load usage from analytics store or feature configuration.",
4759
"content": {
4760
"application/json": {
4761
"schema": {
4768
"x-api-version": "3.1"
4769
}
4770
},
4605
- "/api/v3.1/connected_accounts": {
4606
- "get": {
4607
- "summary": "List connected accounts with optional filters",
4608
- "description": "Retrieves all connected accounts for your project. Connected accounts represent authenticated user connections to external services (e.g., a user's Gmail account, Slack workspace). Filter by toolkit, status, user ID, or auth config to find specific connections.",
4771
+ "/api/v3.1/project/usage/summary": {
4772
+ "post": {
4773
+ "summary": "Project usage summary",
4774
+ "description": "Aggregated metering usage for the authenticated project only. Values are summed from raw metering events grouped by `entity_type`.",
4775
"tags": [
4610
- "Connected Accounts"
4776
+ "Projects"
4777
],
4612
- "operationId": "getConnectedAccounts",
4778
+ "operationId": "postProjectUsageSummary",
4779
"security": [
4780
{
4781
"ApiKeyAuth": []
4784
"UserApiKeyAuth": []
4785
}
4786
],
4621
- "parameters": [
4622
- {
4623
- "schema": {
4624
- "type": "array",
4625
- "nullable": true,
4626
- "items": {
4627
- "type": "string"
4628
- },
4629
- "description": "The toolkit slugs of the connected accounts"
4630
- },
4631
- "required": false,
4632
- "description": "The toolkit slugs of the connected accounts",
4633
- "name": "toolkit_slugs",
4634
- "in": "query"
4635
- },
4636
- {
4637
- "schema": {
4638
- "type": "array",
4639
- "nullable": true,
4640
- "items": {
4641
- "type": "string",
4642
- "enum": [
4643
- "INITIALIZING",
4644
- "INITIATED",
4645
- "ACTIVE",
4646
- "FAILED",
4647
- "EXPIRED",
4648
- "INACTIVE"
4649
- ]
4650
- },
4651
- "description": "The status of the connected account"
4652
- },
4653
- "required": false,
4654
- "description": "The status of the connected account",
4655
- "name": "statuses",
4656
- "in": "query"
4787
+ "requestBody": {
4788
+ "content": {
4789
+ "application/json": {
4790
+ "schema": {
4791
+ "type": "object",
4792
+ "properties": {
4793
+ "from": {
4794
+ "type": "number",
4795
+ "description": "Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`."
4796
+ },
4797
+ "to": {
4798
+ "type": "number",
4799
+ "description": "Exclusive range end (Unix epoch milliseconds). Defaults to now."
4800
+ },
4801
+ "entity_types": {
4802
+ "type": "array",
4803
+ "items": {
4804
+ "type": "string"
4805
+ },
4806
+ "description": "Filter to these metering entity types. Omit for all types."
4807
+ },
4808
+ "filters": {
4809
+ "type": "object",
4810
+ "properties": {
4811
+ "user_id": {
4812
+ "type": "array",
4813
+ "nullable": true,
4814
+ "items": {
4815
+ "type": "string",
4816
+ "minLength": 1
4817
+ },
4818
+ "description": "Filter to events matching these external end-user IDs. OR logic within the array."
4819
+ },
4820
+ "session_id": {
4821
+ "type": "array",
4822
+ "nullable": true,
4823
+ "items": {
4824
+ "type": "string",
4825
+ "minLength": 1
4826
+ },
4827
+ "description": "Filter to events matching these session IDs. OR logic within the array."
4828
+ }
4829
+ }
4830
+ }
4831
+ }
4832
+ }
4833
+ }
4834
+ }
4835
+ },
4836
+ "responses": {
4837
+ "200": {
4838
+ "description": "Usage aggregates for the project.",
4839
+ "content": {
4840
+ "application/json": {
4841
+ "schema": {
4842
+ "type": "object",
4843
+ "properties": {
4844
+ "entities": {
4845
+ "type": "object",
4846
+ "additionalProperties": {
4847
+ "type": "object",
4848
+ "properties": {
4849
+ "unit": {
4850
+ "type": "string"
4851
+ },
4852
+ "total_quantity": {
4853
+ "type": "string"
4854
+ },
4855
+ "event_count": {
4856
+ "type": "integer",
4857
+ "minimum": 0
4858
+ }
4859
+ },
4860
+ "required": [
4861
+ "unit",
4862
+ "total_quantity",
4863
+ "event_count"
4864
+ ]
4865
+ }
4866
+ }
4867
+ },
4868
+ "required": [
4869
+ "entities"
4870
+ ]
4871
+ }
4872
+ }
4873
+ }
4874
},
4658
- {
4659
- "schema": {
4660
- "type": "string",
4661
- "nullable": true,
4662
- "description": "The cursor to paginate through the connected accounts"
4663
- },
4664
- "required": false,
4665
- "description": "The cursor to paginate through the connected accounts",
4666
- "name": "cursor",
4667
- "in": "query"
4875
+ "400": {
4876
+ "description": "Invalid time range, entity_types, or query parameters.",
4877
+ "content": {
4878
+ "application/json": {
4879
+ "schema": {
4880
+ "$ref": "#/components/schemas/Error"
4881
+ }
4882
+ }
4883
+ }
4884
},
4669
- {
4670
- "schema": {
4671
- "type": "number",
4672
- "nullable": true,
4673
- "description": "The limit of the connected accounts to return"
4674
- },
4675
- "required": false,
4676
- "description": "The limit of the connected accounts to return",
4677
- "name": "limit",
4678
- "in": "query"
4885
+ "401": {
4886
+ "description": "Authentication required.",
4887
+ "content": {
4888
+ "application/json": {
4889
+ "schema": {
4890
+ "$ref": "#/components/schemas/Error"
4891
+ }
4892
+ }
4893
+ }
4894
},
4680
- {
4681
- "schema": {
4682
- "type": "array",
4683
- "nullable": true,
4684
- "items": {
4685
- "type": "string"
4686
- },
4687
- "description": "The user ids of the connected accounts"
4688
- },
4689
- "required": false,
4690
- "description": "The user ids of the connected accounts",
4691
- "name": "user_ids",
4692
- "in": "query"
4895
+ "403": {
4896
+ "description": "Forbidden.",
4897
+ "content": {
4898
+ "application/json": {
4899
+ "schema": {
4900
+ "$ref": "#/components/schemas/Error"
4901
+ }
4902
+ }
4903
+ }
4904
},
4694
- {
4695
- "schema": {
4696
- "type": "array",
4697
- "nullable": true,
4698
- "items": {
4699
- "type": "string",
4700
- "format": "authConfigId"
4701
- },
4702
- "description": "The auth config ids of the connected accounts"
4703
- },
4704
- "required": false,
4705
- "description": "The auth config ids of the connected accounts",
4706
- "name": "auth_config_ids",
4707
- "in": "query"
4905
+ "404": {
4906
+ "description": "Project not found.",
4907
+ "content": {
4908
+ "application/json": {
4909
+ "schema": {
4910
+ "$ref": "#/components/schemas/Error"
4911
+ }
4912
+ }
4913
+ }
4914
},
4915
+ "500": {
4916
+ "description": "Failed to load usage from analytics store or feature configuration.",
4917
+ "content": {
4918
+ "application/json": {
4919
+ "schema": {
4920
+ "$ref": "#/components/schemas/Error"
4921
+ }
4922
+ }
4923
+ }
4924
+ }
4925
+ },
4926
+ "x-api-version": "3.1"
4927
+ }
4928
+ },
4929
+ "/api/v3.1/project/usage/{entity_type}": {
4930
+ "post": {
4931
+ "summary": "Project usage breakdown",
4932
+ "description": "Grouped metering usage breakdown for the authenticated project. Groups results by a single dimension or column key.",
4933
+ "tags": [
4934
+ "Projects"
4935
+ ],
4936
+ "operationId": "postProjectUsageByEntityType",
4937
+ "security": [
4938
{
4710
- "schema": {
4711
- "type": "array",
4712
- "nullable": true,
4713
- "items": {
4714
- "type": "string",
4715
- "format": "connectedAccountId"
4716
- },
4717
- "description": "The connected account ids to filter by"
4718
- },
4719
- "required": false,
4720
- "description": "The connected account ids to filter by",
4721
- "name": "connected_account_ids",
4722
- "in": "query"
4939
+ "ApiKeyAuth": []
4940
},
4941
{
4725
- "schema": {
4726
- "type": "string",
4727
- "enum": [
4728
- "created_at",
4729
- "updated_at"
4730
- ],
4731
- "default": "created_at",
4732
- "description": "The order by of the connected accounts"
4733
- },
4734
- "required": false,
4735
- "description": "The order by of the connected accounts",
4736
- "name": "order_by",
4737
- "in": "query"
4738
- },
4942
+ "UserApiKeyAuth": []
4943
+ }
4944
+ ],
4945
+ "parameters": [
4946
{
4947
"schema": {
4948
"type": "string",
4742
- "enum": [
4743
- "asc",
4744
- "desc"
4745
- ],
4746
- "default": "desc",
4747
- "description": "The order direction of the connected accounts"
4949
+ "description": "Metering entity type to break down (e.g. `tool_calls`, `sessions`)."
4950
},
4749
- "required": false,
4750
- "description": "The order direction of the connected accounts",
4751
- "name": "order_direction",
4752
- "in": "query"
4951
+ "required": true,
4952
+ "description": "Metering entity type to break down (e.g. `tool_calls`, `sessions`).",
4953
+ "name": "entity_type",
4954
+ "in": "path"
4955
}
4956
],
4755
- "responses": {
4957
+ "requestBody": {
4958
+ "content": {
4959
+ "application/json": {
4960
+ "schema": {
4961
+ "type": "object",
4962
+ "properties": {
4963
+ "from": {
4964
+ "type": "number",
4965
+ "description": "Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`."
4966
+ },
4967
+ "to": {
4968
+ "type": "number",
4969
+ "description": "Exclusive range end (Unix epoch milliseconds). Defaults to now."
4970
+ },
4971
+ "group_by": {
4972
+ "type": "string",
4973
+ "description": "Dimension or column to group results by. Defaults to `tool_slug` for tool_calls and `user_id` for sessions."
4974
+ },
4975
+ "order_by": {
4976
+ "type": "string",
4977
+ "enum": [
4978
+ "key",
4979
+ "total_quantity",
4980
+ "event_count"
4981
+ ],
4982
+ "description": "Field to order groups by. Defaults to `total_quantity`."
4983
+ },
4984
+ "order_direction": {
4985
+ "type": "string",
4986
+ "enum": [
4987
+ "asc",
4988
+ "desc"
4989
+ ],
4990
+ "description": "Sort direction. Defaults to `desc`."
4991
+ },
4992
+ "limit": {
4993
+ "type": "integer",
4994
+ "minimum": 1,
4995
+ "maximum": 1000,
4996
+ "description": "Maximum number of groups to return. Defaults to 100, max 1000."
4997
+ },
4998
+ "filters": {
4999
+ "type": "object",
5000
+ "properties": {
5001
+ "user_id": {
5002
+ "type": "array",
5003
+ "nullable": true,
5004
+ "items": {
5005
+ "type": "string",
5006
+ "minLength": 1
5007
+ },
5008
+ "description": "Filter to events matching these external end-user IDs. OR logic within the array."
5009
+ },
5010
+ "session_id": {
5011
+ "type": "array",
5012
+ "nullable": true,
5013
+ "items": {
5014
+ "type": "string",
5015
+ "minLength": 1
5016
+ },
5017
+ "description": "Filter to events matching these session IDs. OR logic within the array."
5018
+ }
5019
+ }
5020
+ }
5021
+ }
5022
+ }
5023
+ }
5024
+ }
5025
+ },
5026
+ "responses": {
5027
"200": {
4757
- "description": "Successfully retrieved connected accounts",
5028
+ "description": "Usage breakdown for the project.",
5029
"content": {
5030
"application/json": {
5031
"schema": {
5032
"type": "object",
5033
"properties": {
4763
- "items": {
5034
+ "entity_type": {
5035
+ "type": "string"
5036
+ },
5037
+ "unit": {
5038
+ "type": "string"
5039
+ },
5040
+ "total_quantity": {
5041
+ "type": "string"
5042
+ },
5043
+ "event_count": {
5044
+ "type": "integer",
5045
+ "minimum": 0
5046
+ },
5047
+ "groups": {
5048
"type": "array",
5049
"items": {
5050
"type": "object",
5051
"properties": {
4768
- "toolkit": {
4769
- "type": "object",
4770
- "properties": {
4771
- "slug": {
4772
- "type": "string",
4773
- "description": "The slug of the toolkit"
4774
- }
4775
- },
4776
- "required": [
4777
- "slug"
4778
- ]
4779
- },
4780
- "auth_config": {
4781
- "type": "object",
4782
- "properties": {
4783
- "id": {
4784
- "type": "string",
4785
- "format": "authConfigId",
4786
- "description": "The id of the auth config"
4787
- },
4788
- "auth_scheme": {
4789
- "type": "string",
4790
- "enum": [
4791
- "OAUTH2",
4792
- "OAUTH1",
4793
- "API_KEY",
4794
- "BASIC",
4795
- "BILLCOM_AUTH",
4796
- "BEARER_TOKEN",
4797
- "GOOGLE_SERVICE_ACCOUNT",
4798
- "NO_AUTH",
4799
- "BASIC_WITH_JWT",
4800
- "CALCOM_AUTH",
4801
- "SERVICE_ACCOUNT",
4802
- "SAML",
4803
- "DCR_OAUTH",
4804
- "S2S_OAUTH2"
4805
- ],
4806
- "description": "the authScheme is part of the connection state use it there",
4807
- "deprecated": true
4808
- },
4809
- "is_composio_managed": {
4810
- "type": "boolean",
4811
- "description": "Whether the auth config is managed by Composio"
4812
- },
4813
- "is_disabled": {
4814
- "type": "boolean",
4815
- "description": "Whether the auth config is disabled"
4816
- },
4817
- "deprecated": {
4818
- "type": "object",
4819
- "properties": {
4820
- "uuid": {
4821
- "type": "string",
4822
- "format": "uuid",
4823
- "description": "The uuid of the auth config"
4824
- }
4825
- },
4826
- "required": [
4827
- "uuid"
4828
- ],
4829
- "deprecated": true
4830
- }
4831
- },
4832
- "required": [
4833
- "id",
4834
- "auth_scheme",
4835
- "is_composio_managed",
4836
- "is_disabled"
4837
- ]
4838
- },
4839
- "id": {
4840
- "type": "string",
4841
- "format": "connectedAccountId",
4842
- "description": "The id of the connection"
4843
- },
4844
- "word_id": {
4845
- "type": "string",
4846
- "nullable": true,
4847
- "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")"
4848
- },
4849
- "alias": {
4850
- "type": "string",
4851
- "nullable": true,
4852
- "description": "A user-defined alias for the connected account"
4853
- },
4854
- "user_id": {
4855
- "type": "string",
4856
- "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back",
4857
- "deprecated": true
4858
- },
4859
- "status": {
4860
- "type": "string",
4861
- "enum": [
4862
- "INITIALIZING",
4863
- "INITIATED",
4864
- "ACTIVE",
4865
- "FAILED",
4866
- "EXPIRED",
4867
- "INACTIVE"
4868
- ],
4869
- "description": "The status of the connection"
4870
- },
4871
- "created_at": {
4872
- "type": "string",
4873
- "description": "The created at of the connection"
5052
+ "key": {
5053
+ "type": "string"
5054
},
4875
- "updated_at": {
4876
- "type": "string",
4877
- "description": "The updated at of the connection"
5055
+ "total_quantity": {
5056
+ "type": "string"
5057
},
4879
- "state": {
4880
- "description": "The state of the connection",
4881
- "type": "object",
4882
- "properties": {
4883
- "authScheme": {
4884
- "type": "string",
4885
- "enum": [
4886
- "OAUTH1",
4887
- "OAUTH2",
4888
- "API_KEY",
4889
- "BASIC",
4890
- "BEARER_TOKEN",
4891
- "GOOGLE_SERVICE_ACCOUNT",
4892
- "NO_AUTH",
4893
- "CALCOM_AUTH",
4894
- "BILLCOM_AUTH",
4895
- "BASIC_WITH_JWT",
4896
- "SERVICE_ACCOUNT",
4897
- "SAML",
4898
- "DCR_OAUTH",
4899
- "S2S_OAUTH2"
4900
- ]
4901
- },
4902
- "val": {
4903
- "type": "object",
4904
- "properties": {
4905
- "subdomain": {
4906
- "type": "string"
4907
- },
4908
- "your-domain": {
4909
- "type": "string"
4910
- },
4911
- "region": {
4912
- "type": "string"
4913
- },
4914
- "shop": {
4915
- "type": "string"
4916
- },
4917
- "account_url": {
4918
- "type": "string"
4919
- },
4920
- "COMPANYDOMAIN": {
4921
- "type": "string"
4922
- },
4923
- "extension": {
4924
- "type": "string"
4925
- },
4926
- "form_api_base_url": {
4927
- "type": "string"
4928
- },
4929
- "instanceEndpoint": {
4930
- "type": "string"
4931
- },
4932
- "api_url": {
4933
- "type": "string"
4934
- },
4935
- "borneo_dashboard_url": {
4936
- "type": "string"
4937
- },
4938
- "proxy_username": {
4939
- "type": "string"
4940
- },
4941
- "proxy_password": {
4942
- "type": "string"
4943
- },
4944
- "domain": {
4945
- "type": "string"
4946
- },
4947
- "version": {
4948
- "type": "string"
4949
- },
4950
- "dc": {
4951
- "type": "string"
4952
- },
4953
- "site_name": {
4954
- "type": "string"
4955
- },
4956
- "instanceName": {
4957
- "type": "string"
4958
- },
4959
- "account_id": {
4960
- "type": "string"
4961
- },
4962
- "your_server": {
4963
- "type": "string"
4964
- },
4965
- "server_location": {
4966
- "type": "string"
4967
- },
4968
- "base_url": {
4969
- "type": "string"
4970
- },
4971
- "status": {
4972
- "type": "string",
4973
- "enum": [
4974
- "INITIALIZING",
4975
- "INITIATED",
4976
- "ACTIVE",
4977
- "FAILED",
4978
- "EXPIRED",
4979
- "INACTIVE"
4980
- ]
4981
- },
4982
- "oauth_token": {
4983
- "type": "string"
4984
- },
4985
- "authUri": {
4986
- "type": "string"
4987
- },
4988
- "oauth_token_secret": {
4989
- "type": "string"
4990
- },
4991
- "redirectUrl": {
4992
- "type": "string"
4993
- },
4994
- "callbackUrl": {
4995
- "type": "string"
4996
- },
4997
- "oauth_verifier": {
4998
- "type": "string"
4999
- },
5000
- "consumer_key": {
5001
- "type": "string"
5002
- },
5003
- "callback_url": {
5004
- "type": "string"
5005
- },
5006
- "error": {
5007
- "type": "string"
5008
- },
5009
- "error_description": {
5010
- "type": "string"
5011
- },
5012
- "expired_at": {
5013
- "type": "string"
5014
- }
5015
- },
5016
- "required": [
5017
- "status"
5018
- ],
5019
- "additionalProperties": true
5020
- }
5021
- },
5022
- "required": [
5023
- "authScheme",
5024
- "val"
5025
- ],
5026
- "additionalProperties": true
5027
- },
5028
- "data": {
5029
- "type": "object",
5030
- "additionalProperties": {},
5031
- "description": "This is deprecated, use `state` instead",
5032
- "deprecated": true
5033
- },
5034
- "status_reason": {
5035
- "type": "string",
5036
- "nullable": true,
5037
- "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled"
5038
- },
5039
- "is_disabled": {
5040
- "type": "boolean",
5041
- "description": "Whether the connection is disabled"
5042
- },
5043
- "test_request_endpoint": {
5044
- "type": "string",
5045
- "description": "The endpoint to make test request for verification"
5046
- },
5047
- "deprecated": {
5048
- "type": "object",
5049
- "properties": {
5050
- "labels": {
5051
- "type": "array",
5052
- "items": {
5053
- "type": "string"
5054
- },
5055
- "description": "The labels of the connection"
5056
- },
5057
- "uuid": {
5058
- "type": "string",
5059
- "format": "uuid",
5060
- "description": "The uuid of the connection"
5061
- }
5062
- },
5063
- "required": [
5064
- "labels",
5065
- "uuid"
5066
- ],
5067
- "deprecated": true
5058
+ "event_count": {
5059
+ "type": "integer",
5060
+ "minimum": 0
5061
}
5062
},
5063
"required": [
5071
- "toolkit",
5072
- "auth_config",
5073
- "id",
5074
- "word_id",
5075
- "alias",
5076
- "user_id",
5077
- "status",
5078
- "created_at",
5079
- "updated_at",
5080
- "state",
5081
- "data",
5082
- "status_reason",
5083
- "is_disabled"
5064
+ "key",
5065
+ "total_quantity",
5066
+ "event_count"
5067
]
5068
}
5086
- },
5087
- "next_cursor": {
5088
- "type": "string",
5089
- "nullable": true
5090
- },
5091
- "total_pages": {
5092
- "type": "number"
5093
- },
5094
- "current_page": {
5095
- "type": "number"
5096
- },
5097
- "total_items": {
5098
- "type": "number"
5069
}
5070
},
5071
"required": [
5102
- "items",
5103
- "total_pages",
5104
- "current_page",
5105
- "total_items"
5072
+ "entity_type",
5073
+ "unit",
5074
+ "total_quantity",
5075
+ "event_count",
5076
+ "groups"
5077
]
5078
}
5079
}
5080
}
5081
},
5082
"400": {
5112
- "description": "Bad request",
5083
+ "description": "Invalid entity_type, group_by, time range, or query parameters.",
5084
"content": {
5085
"application/json": {
5086
"schema": {
5090
}
5091
},
5092
"401": {
5122
- "description": "Unauthorized",
5093
+ "description": "Authentication required.",
5094
"content": {
5095
"application/json": {
5096
"schema": {
5099
}
5100
}
5101
},
5131
- "404": {
5132
- "description": "Not found",
5102
+ "403": {
5103
+ "description": "Forbidden.",
5104
"content": {
5105
"application/json": {
5106
"schema": {
5109
}
5110
}
5111
},
5141
- "422": {
5142
- "description": "Unprocessable entity",
5112
+ "404": {
5113
+ "description": "Project not found.",
5114
"content": {
5115
"application/json": {
5116
"schema": {
5120
}
5121
},
5122
"500": {
5152
- "description": "Internal server error",
5123
+ "description": "Failed to load usage from analytics store or feature configuration.",
5124
"content": {
5125
"application/json": {
5126
"schema": {
5131
}
5132
},
5133
"x-api-version": "3.1"
5163
- },
5164
- "post": {
5165
- "summary": "Create a new connected account",
5166
- "description": "Initiates a new connection to an external service for a user. For OAuth-based toolkits, this returns a redirect URL to complete authentication. For API key-based toolkits, provide the credentials directly in the request body. Use the `user_id` field to associate the connection with a specific user in your system.",
5134
+ }
5135
+ },
5136
+ "/api/v3.1/auth/session/info": {
5137
+ "get": {
5138
+ "summary": "Get current user session information",
5139
+ "description": "Retrieves detailed information about the current authenticated user session, including project details, organization membership, and API key information if applicable. This endpoint is useful for verifying authentication status and retrieving contextual information about the authenticated user and their access privileges.",
5140
"tags": [
5168
- "Connected Accounts"
5141
+ "Authentication"
5142
],
5170
- "operationId": "postConnectedAccounts",
5143
+ "operationId": "getAuthSessionInfo",
5144
"security": [
5145
{
5146
"ApiKeyAuth": []
5149
"UserApiKeyAuth": []
5150
}
5151
],
5179
- "requestBody": {
5180
- "content": {
5181
- "application/json": {
5182
- "schema": {
5183
- "type": "object",
5184
- "properties": {
5185
- "auth_config": {
5186
- "type": "object",
5187
- "properties": {
5188
- "id": {
5189
- "type": "string",
5190
- "format": "authConfigId",
5191
- "description": "The auth config id of the app (must be a valid auth config id)"
5192
- }
5193
- },
5194
- "required": [
5195
- "id"
5196
- ]
5197
- },
5198
- "connection": {
5199
- "type": "object",
5200
- "properties": {
5201
- "state": {
5202
- "description": "The state of the connected account",
5203
- "type": "object",
5204
- "properties": {
5205
- "authScheme": {
5206
- "type": "string",
5207
- "enum": [
5208
- "OAUTH1",
5209
- "OAUTH2",
5210
- "API_KEY",
5211
- "BASIC",
5212
- "BEARER_TOKEN",
5213
- "GOOGLE_SERVICE_ACCOUNT",
5214
- "NO_AUTH",
5215
- "CALCOM_AUTH",
5216
- "BILLCOM_AUTH",
5217
- "BASIC_WITH_JWT",
5218
- "SERVICE_ACCOUNT",
5219
- "SAML",
5220
- "DCR_OAUTH",
5221
- "S2S_OAUTH2"
5222
- ]
5223
- },
5224
- "val": {
5225
- "type": "object",
5226
- "properties": {
5227
- "subdomain": {
5228
- "type": "string"
5229
- },
5230
- "your-domain": {
5231
- "type": "string"
5232
- },
5233
- "region": {
5234
- "type": "string"
5235
- },
5236
- "shop": {
5237
- "type": "string"
5238
- },
5239
- "account_url": {
5240
- "type": "string"
5241
- },
5242
- "COMPANYDOMAIN": {
5243
- "type": "string"
5244
- },
5245
- "extension": {
5246
- "type": "string"
5247
- },
5248
- "form_api_base_url": {
5249
- "type": "string"
5250
- },
5251
- "instanceEndpoint": {
5252
- "type": "string"
5253
- },
5254
- "api_url": {
5255
- "type": "string"
5256
- },
5257
- "borneo_dashboard_url": {
5258
- "type": "string"
5259
- },
5260
- "proxy_username": {
5261
- "type": "string"
5262
- },
5263
- "proxy_password": {
5264
- "type": "string"
5265
- },
5266
- "domain": {
5267
- "type": "string"
5268
- },
5269
- "version": {
5270
- "type": "string"
5271
- },
5272
- "dc": {
5273
- "type": "string"
5274
- },
5275
- "site_name": {
5276
- "type": "string"
5277
- },
5278
- "instanceName": {
5279
- "type": "string"
5280
- },
5281
- "account_id": {
5282
- "type": "string"
5283
- },
5284
- "your_server": {
5285
- "type": "string"
5286
- },
5287
- "server_location": {
5288
- "type": "string"
5289
- },
5290
- "base_url": {
5291
- "type": "string"
5292
- },
5293
- "status": {
5294
- "type": "string",
5295
- "enum": [
5296
- "INITIALIZING",
5297
- "INITIATED",
5298
- "ACTIVE",
5299
- "FAILED",
5300
- "EXPIRED",
5301
- "INACTIVE"
5302
- ]
5303
- },
5304
- "oauth_token": {
5305
- "type": "string"
5306
- },
5307
- "authUri": {
5308
- "type": "string"
5309
- },
5310
- "oauth_token_secret": {
5311
- "type": "string"
5312
- },
5313
- "redirectUrl": {
5314
- "type": "string"
5315
- },
5316
- "callbackUrl": {
5317
- "type": "string"
5318
- },
5319
- "oauth_verifier": {
5320
- "type": "string"
5321
- },
5322
- "consumer_key": {
5323
- "type": "string"
5324
- },
5325
- "callback_url": {
5326
- "type": "string"
5327
- },
5328
- "error": {
5329
- "type": "string"
5330
- },
5331
- "error_description": {
5332
- "type": "string"
5333
- },
5334
- "expired_at": {
5335
- "type": "string"
5336
- }
5337
- },
5338
- "required": [
5339
- "status"
5340
- ],
5341
- "additionalProperties": true
5342
- }
5343
- },
5344
- "required": [
5345
- "authScheme",
5346
- "val"
5347
- ],
5348
- "additionalProperties": true
5349
- },
5350
- "data": {
5351
- "type": "object",
5352
- "additionalProperties": {},
5353
- "description": "DEPRECATED: This parameter will be removed in a future version. Please use state instead.",
5354
- "deprecated": true
5355
- },
5356
- "user_id": {
5357
- "type": "string",
5358
- "default": "default",
5359
- "description": "The user id of the connected account"
5360
- },
5361
- "alias": {
5362
- "type": "string",
5363
- "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."
5364
- },
5365
- "callback_url": {
5366
- "type": "string",
5367
- "format": "uri",
5368
- "description": "The URL to redirect to after connection completion"
5369
- },
5370
- "redirect_uri": {
5371
- "type": "string",
5372
- "format": "uri",
5373
- "description": "DEPRECATED: This parameter will be removed in a future version. Please use callback_url instead.",
5374
- "deprecated": true
5375
- },
5376
- "deprecated_is_v1_rerouted": {
5377
- "type": "boolean",
5378
- "default": false,
5379
- "description": "DEPRECATED: This parameter will be removed in a future version.",
5380
- "deprecated": true
5381
- }
5382
- }
5383
- },
5384
- "validate_credentials": {
5385
- "type": "boolean",
5386
- "default": false,
5387
- "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme",
5388
- "x-experimental": true
5389
- }
5390
- },
5391
- "required": [
5392
- "auth_config",
5393
- "connection"
5394
- ]
5395
- }
5396
- }
5397
- }
5398
- },
5152
"responses": {
5400
- "201": {
5401
- "description": "Successfully created connected account",
5153
+ "200": {
5154
+ "description": "Session is valid and active. Returns detailed information about the authenticated user, their project, and organization.",
5155
"content": {
5156
"application/json": {
5157
"schema": {
5158
"type": "object",
5159
"properties": {
5407
- "id": {
5408
- "type": "string",
5409
- "format": "connectedAccountId",
5410
- "description": "The id of the connected account"
5411
- },
5412
- "connectionData": {
5413
- "description": "The connection data of the connected account",
5160
+ "project": {
5161
"type": "object",
5162
+ "nullable": true,
5163
"properties": {
5416
- "authScheme": {
5164
+ "auto_id": {
5165
+ "type": "number",
5166
+ "description": "Internal auto-incrementing ID for the project",
5167
+ "example": 12345
5168
+ },
5169
+ "id": {
5170
+ "type": "string",
5171
+ "description": "UUID identifier for the project",
5172
+ "example": "550e8400-e29b-41d4-a716-446655440000"
5173
+ },
5174
+ "org_id": {
5175
+ "type": "string",
5176
+ "description": "Organization UUID that this project belongs to",
5177
+ "example": "550e8400-e29b-41d4-a716-446655440001"
5178
+ },
5179
+ "name": {
5180
+ "type": "string",
5181
+ "description": "User-defined name for the project",
5182
+ "example": "Production API"
5183
+ },
5184
+ "email": {
5185
+ "type": "string",
5186
+ "description": "Email address used for project notifications",
5187
+ "example": "project-123@composio.dev"
5188
+ },
5189
+ "nano_id": {
5190
+ "type": "string",
5191
+ "format": "projectId",
5192
+ "description": "Short, URL-friendly unique identifier for the project",
5193
+ "example": "pr_1a2b3c4d5e6f"
5194
+ },
5195
+ "created_at": {
5196
+ "type": "string",
5197
+ "description": "Date and time when the project was created",
5198
+ "example": "2023-05-16T14:30:00.000Z"
5199
+ },
5200
+ "updated_at": {
5201
+ "type": "string",
5202
+ "description": "Date and time when the project was last modified",
5203
+ "example": "2023-05-18T09:15:30.000Z"
5204
+ },
5205
+ "webhook_url": {
5206
+ "type": "string",
5207
+ "nullable": true,
5208
+ "description": "Endpoint URL for trigger webhook notifications",
5209
+ "example": "https://example.com/webhook"
5210
+ },
5211
+ "event_webhook_url": {
5212
+ "type": "string",
5213
+ "nullable": true,
5214
+ "description": "Endpoint URL for event webhook notifications",
5215
+ "example": "https://example.com/events"
5216
+ },
5217
+ "webhook_secret": {
5218
+ "type": "string",
5219
+ "nullable": true,
5220
+ "description": "Secret used to verify webhook signatures",
5221
+ "example": "whsec_a1b2c3d4e5f6g7h8i9j0"
5222
+ },
5223
+ "triggers_enabled": {
5224
+ "type": "boolean",
5225
+ "description": "Flag indicating if triggers are enabled for this project",
5226
+ "example": true
5227
+ },
5228
+ "last_subscribed_at": {
5229
+ "type": "string",
5230
+ "nullable": true,
5231
+ "description": "Date and time when the project last subscribed to updates",
5232
+ "example": "2023-05-17T10:00:00.000Z"
5233
+ },
5234
+ "deleted": {
5235
+ "type": "boolean",
5236
+ "description": "Flag indicating if the project has been deleted",
5237
+ "example": false
5238
+ },
5239
+ "is_new_webhook": {
5240
+ "type": "boolean",
5241
+ "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)",
5242
+ "example": true,
5243
+ "deprecated": true
5244
+ },
5245
+ "webhook_version": {
5246
"type": "string",
5247
"enum": [
5419
- "OAUTH1",
5420
- "OAUTH2",
5421
- "API_KEY",
5422
- "BASIC",
5423
- "BEARER_TOKEN",
5424
- "GOOGLE_SERVICE_ACCOUNT",
5425
- "NO_AUTH",
5426
- "CALCOM_AUTH",
5427
- "BILLCOM_AUTH",
5428
- "BASIC_WITH_JWT",
5429
- "SERVICE_ACCOUNT",
5430
- "SAML",
5431
- "DCR_OAUTH",
5432
- "S2S_OAUTH2"
5433
- ]
5248
+ "V1",
5249
+ "V2",
5250
+ "V3"
5251
+ ],
5252
+ "description": "Version of the webhook configuration",
5253
+ "example": "V2"
5254
},
5435
- "val": {
5255
+ "org": {
5256
"type": "object",
5257
"properties": {
5438
- "subdomain": {
5439
- "type": "string"
5440
- },
5441
- "your-domain": {
5442
- "type": "string"
5258
+ "id": {
5259
+ "type": "string",
5260
+ "format": "orgId",
5261
+ "description": "Short, URL-friendly unique identifier for the organization",
5262
+ "example": "ok_1a2b3c4d5e6f"
5263
},
5444
- "region": {
5445
- "type": "string"
5446
- },
5447
- "shop": {
5448
- "type": "string"
5449
- },
5450
- "account_url": {
5451
- "type": "string"
5452
- },
5453
- "COMPANYDOMAIN": {
5454
- "type": "string"
5455
- },
5456
- "extension": {
5457
- "type": "string"
5458
- },
5459
- "form_api_base_url": {
5460
- "type": "string"
5461
- },
5462
- "instanceEndpoint": {
5463
- "type": "string"
5464
- },
5465
- "api_url": {
5466
- "type": "string"
5467
- },
5468
- "borneo_dashboard_url": {
5469
- "type": "string"
5470
- },
5471
- "proxy_username": {
5472
- "type": "string"
5473
- },
5474
- "proxy_password": {
5475
- "type": "string"
5476
- },
5477
- "domain": {
5478
- "type": "string"
5479
- },
5480
- "version": {
This file is too large to show in full.