@devries-cameron20 / composio Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 03:37 UTC

next
json 26,610 lines 1.05 MB
Raw
Large file — syntax highlighting disabled.
1 {
2 "openapi": "3.0.0",
3 "info": {
4 "version": "3.0.0",
5 "title": "Composio Platform API",
6 "description": "",
7 "contact": {
8 "name": "Composio Support",
9 "url": "https://composio.dev/support",
10 "email": "support@composio.dev"
11 },
12 "license": {
13 "name": "Proprietary",
14 "url": "https://composio.dev/terms"
15 }
16 },
17 "servers": [
18 {
19 "url": "https://backend.composio.dev",
20 "description": "PRODUCTION API"
21 }
22 ],
23 "tags": [
24 {
25 "name": "Authentication",
26 "description": "Authentication related endpoints"
27 },
28 {
29 "name": "Auth Configs",
30 "description": "Authentication configuration management"
31 },
32 {
33 "name": "Connected Accounts",
34 "description": "Connected account management"
35 },
36 {
37 "name": "Logs",
38 "description": "Logging and monitoring"
39 },
40 {
41 "name": "OpenAPI",
42 "description": "OpenAPI specification management"
43 },
44 {
45 "name": "Organization",
46 "description": "Organization management"
47 },
48 {
49 "name": "API Keys",
50 "description": "API key management"
51 },
52 {
53 "name": "Webhooks",
54 "description": "Webhook configuration"
55 },
56 {
57 "name": "Webhook Endpoints",
58 "description": "Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts to, plus signing secret storage and verification."
59 },
60 {
61 "name": "Webhook Subscriptions",
62 "description": "Webhook delivery subscriptions. Outbound URLs Composio posts trigger events to, plus signing secret rotation and event-type filters."
63 },
64 {
65 "name": "Team",
66 "description": "Team member management"
67 },
68 {
69 "name": "Consumer Skills",
70 "description": "Organization-authored Skill management"
71 },
72 {
73 "name": "Toolkits",
74 "description": "Toolkit and tool management"
75 },
76 {
77 "name": "Tools",
78 "description": "Tool execution endpoints"
79 },
80 {
81 "name": "Triggers",
82 "description": "Trigger management and execution"
83 },
84 {
85 "name": "Payments",
86 "description": "Payment and subscription management"
87 },
88 {
89 "name": "Billing",
90 "description": "Dashboard billing state — usage, subscription, contract (cookie-auth only)"
91 },
92 {
93 "name": "Compliance",
94 "description": "Organization compliance agreements and acceptance state"
95 },
96 {
97 "name": "Files",
98 "description": "File management"
99 },
100 {
101 "name": "MCP",
102 "description": "MCP server management"
103 },
104 {
105 "name": "MCP Partner",
106 "description": "MCP partner management"
107 },
108 {
109 "name": "Stripe Projects",
110 "description": "Stripe Projects provisioning"
111 },
112 {
113 "name": "Tool Router",
114 "description": "(Labs) Tool router endpoints"
115 },
116 {
117 "name": "Playground",
118 "description": "Dashboard playground chat"
119 },
120 {
121 "name": "Arena",
122 "description": "Arena conversations, messages and terms"
123 },
124 {
125 "name": "Organization Management"
126 },
127 {
128 "name": "Projects"
129 }
130 ],
131 "components": {
132 "securitySchemes": {
133 "ApiKeyAuth": {
134 "type": "apiKey",
135 "in": "header",
136 "name": "x-api-key",
137 "description": "Project API key authentication"
138 },
139 "UserApiKeyAuth": {
140 "type": "apiKey",
141 "in": "header",
142 "name": "x-user-api-key",
143 "description": "User API key authentication"
144 },
145 "OrgApiKeyAuth": {
146 "type": "apiKey",
147 "in": "header",
148 "name": "x-org-api-key",
149 "description": "Organization API key authentication"
150 }
151 },
152 "schemas": {
153 "Error": {
154 "type": "object",
155 "properties": {
156 "error": {
157 "type": "object",
158 "properties": {
159 "message": {
160 "type": "string"
161 },
162 "code": {
163 "type": "number"
164 },
165 "slug": {
166 "type": "string"
167 },
168 "status": {
169 "type": "number"
170 },
171 "request_id": {
172 "type": "string"
173 },
174 "suggested_fix": {
175 "type": "string"
176 },
177 "errors": {
178 "type": "array",
179 "items": {
180 "type": "string"
181 }
182 }
183 },
184 "required": [
185 "message",
186 "code",
187 "slug",
188 "status"
189 ]
190 }
191 },
192 "required": [
193 "error"
194 ]
195 },
196 "ComposioManagedAuthConfigCreate": {
197 "type": "object",
198 "properties": {
199 "type": {
200 "type": "string",
201 "enum": [
202 "use_composio_managed_auth"
203 ]
204 },
205 "name": {
206 "type": "string",
207 "maxLength": 255,
208 "description": "The name of the integration"
209 },
210 "managed_app_id": {
211 "type": "string",
212 "format": "managedAppId",
213 "description": "The Composio-managed app to use, as composio_managed_auth[].managed_app_id from GET /api/v3/toolkits/{toolkit_slug}. Omit to use the toolkit's default app."
214 },
215 "credentials": {
216 "type": "object",
217 "properties": {
218 "scopes": {
219 "anyOf": [
220 {
221 "type": "string"
222 },
223 {
224 "type": "array",
225 "items": {
226 "type": "string"
227 }
228 }
229 ],
230 "description": "OAuth scopes requested for the managed auth config."
231 },
232 "user_scopes": {
233 "anyOf": [
234 {
235 "type": "string"
236 },
237 {
238 "type": "array",
239 "items": {
240 "type": "string"
241 }
242 }
243 ],
244 "description": "OAuth user-token scopes requested for the managed auth config. This is primarily used by Slack OAuth v2."
245 }
246 },
247 "default": {}
248 },
249 "tool_access_config": {
250 "type": "object",
251 "properties": {
252 "tools_for_connected_account_creation": {
253 "type": "array",
254 "items": {
255 "type": "string"
256 },
257 "default": [],
258 "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
259 "deprecated": true
260 }
261 },
262 "description": "DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
263 "deprecated": true
264 },
265 "restrict_to_following_tools": {
266 "type": "array",
267 "items": {
268 "type": "string"
269 },
270 "default": [],
271 "description": "List of tool slugs this auth config is restricted to use with. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
272 "deprecated": true
273 },
274 "shared_credentials": {
275 "type": "object",
276 "additionalProperties": {},
277 "description": "Shared credentials that will be inherited by all connected accounts using this auth config. DEPRECATED: use `shared_connection_fields` instead. It takes the same value and behaves the same way.",
278 "deprecated": true
279 },
280 "shared_connection_fields": {
281 "type": "object",
282 "additionalProperties": {},
283 "description": "Connection field values inherited by every connected account created under this auth config (for example a region or subdomain). Non-secret values pre-fill the hosted Connect Link form; secret values are redacted in responses and never sent to the end user."
284 },
285 "is_enabled_for_tool_router": {
286 "type": "boolean",
287 "description": "Whether this auth config is enabled for tool router"
288 }
289 },
290 "required": [
291 "type"
292 ]
293 },
294 "CustomAuthConfigCreate": {
295 "type": "object",
296 "properties": {
297 "type": {
298 "type": "string",
299 "enum": [
300 "use_custom_auth"
301 ]
302 },
303 "name": {
304 "type": "string",
305 "maxLength": 255,
306 "description": "The name of the integration"
307 },
308 "authScheme": {
309 "type": "string",
310 "enum": [
311 "OAUTH2",
312 "OAUTH1",
313 "API_KEY",
314 "BASIC",
315 "BILLCOM_AUTH",
316 "BEARER_TOKEN",
317 "GOOGLE_SERVICE_ACCOUNT",
318 "NO_AUTH",
319 "BASIC_WITH_JWT",
320 "CALCOM_AUTH",
321 "SERVICE_ACCOUNT",
322 "SAML",
323 "DCR_OAUTH",
324 "CIMD_OAUTH",
325 "S2S_OAUTH2"
326 ]
327 },
328 "credentials": {
329 "type": "object",
330 "properties": {
331 "scopes": {
332 "anyOf": [
333 {
334 "type": "string"
335 },
336 {
337 "type": "array",
338 "items": {
339 "type": "string"
340 }
341 }
342 ],
343 "description": "OAuth scopes requested for the custom auth config."
344 },
345 "user_scopes": {
346 "anyOf": [
347 {
348 "type": "string"
349 },
350 {
351 "type": "array",
352 "items": {
353 "type": "string"
354 }
355 }
356 ],
357 "description": "OAuth user-token scopes requested for the custom auth config. This is primarily used by Slack OAuth v2."
358 }
359 },
360 "default": {}
361 },
362 "sealed_credentials": {
363 "type": "object",
364 "additionalProperties": {
365 "type": "string",
366 "minLength": 1,
367 "maxLength": 16384
368 },
369 "description": "[EXPERIMENTAL] Client-sealed secret fields to redeem through the organization keyring instance (GET /api/v3.1/keyring/transfer_keys). The plaintext must not also appear in credentials.",
370 "x-experimental": true
371 },
372 "proxy_config": {
373 "type": "object",
374 "nullable": true,
375 "properties": {
376 "proxy_url": {
377 "type": "string",
378 "format": "uri",
379 "description": "The url of the auth proxy"
380 },
381 "proxy_auth_key": {
382 "type": "string",
383 "description": "The auth key for the auth proxy"
384 }
385 },
386 "required": [
387 "proxy_url"
388 ]
389 },
390 "restrict_to_following_tools": {
391 "type": "array",
392 "items": {
393 "type": "string"
394 },
395 "default": [],
396 "description": "List of tool slugs this auth config is restricted to use with. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
397 "deprecated": true
398 },
399 "tool_access_config": {
400 "type": "object",
401 "properties": {
402 "tools_for_connected_account_creation": {
403 "type": "array",
404 "items": {
405 "type": "string"
406 },
407 "default": [],
408 "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
409 "deprecated": true
410 }
411 },
412 "description": "DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
413 "deprecated": true
414 },
415 "shared_credentials": {
416 "type": "object",
417 "additionalProperties": {},
418 "description": "Shared credentials that will be inherited by all connected accounts using this auth config. DEPRECATED: use `shared_connection_fields` instead. It takes the same value and behaves the same way.",
419 "deprecated": true
420 },
421 "shared_connection_fields": {
422 "type": "object",
423 "additionalProperties": {},
424 "description": "Connection field values inherited by every connected account created under this auth config (for example a region or subdomain). Non-secret values pre-fill the hosted Connect Link form; secret values are redacted in responses and never sent to the end user."
425 },
426 "is_enabled_for_tool_router": {
427 "type": "boolean",
428 "description": "Whether this auth config is enabled for tool router"
429 }
430 },
431 "required": [
432 "type",
433 "authScheme"
434 ]
435 },
436 "CustomAuthConfigUpdate": {
437 "type": "object",
438 "properties": {
439 "type": {
440 "type": "string",
441 "enum": [
442 "custom"
443 ]
444 },
445 "name": {
446 "type": "string",
447 "minLength": 1,
448 "maxLength": 255,
449 "description": "The display name of the authentication configuration"
450 },
451 "credentials": {
452 "type": "object",
453 "properties": {
454 "scopes": {
455 "anyOf": [
456 {
457 "type": "string"
458 },
459 {
460 "type": "array",
461 "items": {
462 "type": "string"
463 }
464 }
465 ],
466 "description": "OAuth scopes requested for the auth config."
467 },
468 "user_scopes": {
469 "anyOf": [
470 {
471 "type": "string"
472 },
473 {
474 "type": "array",
475 "items": {
476 "type": "string"
477 }
478 }
479 ],
480 "description": "OAuth user-token scopes requested for the auth config. This is primarily used by Slack OAuth v2."
481 }
482 }
483 },
484 "sealed_credentials": {
485 "type": "object",
486 "additionalProperties": {
487 "type": "string",
488 "minLength": 1,
489 "maxLength": 16384
490 },
491 "description": "[EXPERIMENTAL] Client-sealed secret fields to redeem through the organization keyring instance (GET /api/v3.1/keyring/transfer_keys). The plaintext must not also appear in credentials. Rotates the stored client_secret without Composio ever holding it.",
492 "x-experimental": true
493 },
494 "proxy_config": {
495 "type": "object",
496 "nullable": true,
497 "properties": {
498 "proxy_url": {
499 "type": "string",
500 "format": "uri",
501 "description": "The url of the auth proxy"
502 },
503 "proxy_auth_key": {
504 "type": "string",
505 "description": "The auth key for the auth proxy"
506 }
507 },
508 "required": [
509 "proxy_url"
510 ]
511 },
512 "restrict_to_following_tools": {
513 "type": "array",
514 "items": {
515 "type": "string"
516 },
517 "description": "List of tool slugs this auth config is restricted to use with. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
518 "deprecated": true
519 },
520 "tool_access_config": {
521 "type": "object",
522 "properties": {
523 "tools_for_connected_account_creation": {
524 "type": "array",
525 "items": {
526 "type": "string"
527 },
528 "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
529 "deprecated": true
530 },
531 "tools_available_for_execution": {
532 "type": "array",
533 "items": {
534 "type": "string"
535 },
536 "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. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
537 "deprecated": true
538 }
539 },
540 "description": "DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
541 "deprecated": true
542 },
543 "shared_credentials": {
544 "type": "object",
545 "additionalProperties": {},
546 "description": "Shared credentials inherited by all connected accounts using this auth config. Secret values are redacted in responses, so provide the real values when updating; omit this field to leave them unchanged. DEPRECATED: use `shared_connection_fields` instead. It takes the same value and behaves the same way.",
547 "deprecated": true
548 },
549 "shared_connection_fields": {
550 "type": "object",
551 "additionalProperties": {},
552 "description": "Connection field values inherited by every connected account created under this auth config. Secret values are redacted in responses, so provide the real values when updating; omit this field to leave them unchanged."
553 },
554 "is_enabled_for_tool_router": {
555 "type": "boolean",
556 "description": "Whether this auth config is enabled for tool router"
557 }
558 },
559 "required": [
560 "type"
561 ]
562 },
563 "DefaultAuthConfigUpdate": {
564 "type": "object",
565 "properties": {
566 "type": {
567 "type": "string",
568 "enum": [
569 "default"
570 ]
571 },
572 "name": {
573 "type": "string",
574 "minLength": 1,
575 "maxLength": 255,
576 "description": "The display name of the authentication configuration"
577 },
578 "scopes": {
579 "anyOf": [
580 {
581 "type": "string"
582 },
583 {
584 "type": "array",
585 "items": {
586 "type": "string"
587 }
588 }
589 ],
590 "description": "OAuth scopes requested for the auth config."
591 },
592 "user_scopes": {
593 "anyOf": [
594 {
595 "type": "string"
596 },
597 {
598 "type": "array",
599 "items": {
600 "type": "string"
601 }
602 }
603 ],
604 "description": "OAuth user-token scopes requested for the auth config. This is primarily used by Slack OAuth v2."
605 },
606 "restrict_to_following_tools": {
607 "type": "array",
608 "items": {
609 "type": "string"
610 },
611 "description": "List of tool slugs this auth config is restricted to use with. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
612 "deprecated": true
613 },
614 "tool_access_config": {
615 "type": "object",
616 "properties": {
617 "tools_for_connected_account_creation": {
618 "type": "array",
619 "items": {
620 "type": "string"
621 },
622 "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
623 "deprecated": true
624 },
625 "tools_available_for_execution": {
626 "type": "array",
627 "items": {
628 "type": "string"
629 },
630 "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. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
631 "deprecated": true
632 }
633 },
634 "description": "DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
635 "deprecated": true
636 },
637 "shared_credentials": {
638 "type": "object",
639 "additionalProperties": {},
640 "description": "Shared credentials inherited by all connected accounts using this auth config. Secret values are redacted in responses, so provide the real values when updating; omit this field to leave them unchanged. DEPRECATED: use `shared_connection_fields` instead. It takes the same value and behaves the same way.",
641 "deprecated": true
642 },
643 "shared_connection_fields": {
644 "type": "object",
645 "additionalProperties": {},
646 "description": "Connection field values inherited by every connected account created under this auth config. Secret values are redacted in responses, so provide the real values when updating; omit this field to leave them unchanged."
647 },
648 "is_enabled_for_tool_router": {
649 "type": "boolean",
650 "description": "Whether this auth config is enabled for tool router"
651 }
652 },
653 "required": [
654 "type"
655 ]
656 },
657 "PatchConnectedAccountBody": {
658 "type": "object",
659 "properties": {
660 "alias": {
661 "type": "string",
662 "maxLength": 255,
663 "description": "A human-readable alias for this connected account. Pass an empty string to clear the alias. Must be unique per entity and toolkit within the project."
664 },
665 "connection": {
666 "type": "object",
667 "properties": {
668 "state": {
669 "type": "object",
670 "properties": {
671 "authScheme": {
672 "type": "string",
673 "enum": [
674 "BEARER_TOKEN",
675 "API_KEY",
676 "BASIC",
677 "BASIC_WITH_JWT",
678 "GOOGLE_SERVICE_ACCOUNT",
679 "SERVICE_ACCOUNT"
680 ],
681 "description": "The auth scheme of the connected account. Must match the connection's actual auth scheme."
682 },
683 "val": {
684 "type": "object",
685 "properties": {
686 "token": {
687 "type": "string",
688 "nullable": true
689 },
690 "generic_api_key": {
691 "type": "string",
692 "nullable": true
693 },
694 "api_key": {
695 "type": "string",
696 "nullable": true
697 },
698 "bearer_token": {
699 "type": "string",
700 "nullable": true
701 },
702 "basic_encoded": {
703 "type": "string",
704 "nullable": true
705 },
706 "generic_token": {
707 "type": "string",
708 "nullable": true
709 },
710 "api_key_prefix": {
711 "type": "string",
712 "nullable": true
713 },
714 "generic_secret": {
715 "type": "string",
716 "nullable": true
717 },
718 "generic_id": {
719 "type": "string",
720 "nullable": true
721 },
722 "user_agent": {
723 "type": "string",
724 "nullable": true
725 },
726 "username": {
727 "type": "string",
728 "nullable": true
729 },
730 "password": {
731 "type": "string",
732 "nullable": true
733 },
734 "credentials_json": {
735 "type": "string",
736 "nullable": true
737 },
738 "application_id": {
739 "type": "string",
740 "nullable": true
741 },
742 "installation_id": {
743 "type": "string",
744 "nullable": true
745 },
746 "private_key": {
747 "type": "string",
748 "nullable": true
749 }
750 },
751 "additionalProperties": false,
752 "description": "Credential fields to update. Only provided fields are changed — omitted fields are preserved. Set a field to null to remove it."
753 }
754 },
755 "required": [
756 "authScheme",
757 "val"
758 ]
759 }
760 },
761 "required": [
762 "state"
763 ]
764 },
765 "experimental": {
766 "type": "object",
767 "properties": {
768 "acl_config_for_shared": {
769 "type": "object",
770 "properties": {
771 "allow_all_users": {
772 "type": "boolean",
773 "description": "Wildcard \"any user_id in the project\" allow toggle. Only valid on SHARED connections."
774 },
775 "allowed_user_ids": {
776 "type": "array",
777 "items": {
778 "type": "string",
779 "minLength": 1,
780 "maxLength": 256
781 },
782 "maxItems": 1000,
783 "description": "Explicit allow list of user_ids who can use this SHARED connection."
784 },
785 "not_allowed_user_ids": {
786 "type": "array",
787 "items": {
788 "type": "string",
789 "minLength": 1,
790 "maxLength": 256
791 },
792 "maxItems": 1000,
793 "description": "Explicit deny list. Wins on conflict with allow_all_users and allowed_user_ids."
794 }
795 },
796 "description": "Access control for SHARED connections. Resolution rule (only fires when caller != creator): user in not_allowed_user_ids → DENY; allow_all_users=true → ALLOW; user in allowed_user_ids → ALLOW; else DENY. Default state (omitted or {}) is deny-by-default — only the creator can use.",
797 "x-experimental": true
798 }
799 },
800 "description": "Experimental features - not stable, may be modified or removed in future versions.",
801 "x-experimental": true
802 }
803 }
804 },
805 "DeprecatedToolkitInfo": {
806 "type": "object",
807 "properties": {
808 "toolkitId": {
809 "type": "string"
810 }
811 },
812 "required": [
813 "toolkitId"
814 ],
815 "description": "Deprecated toolkit ID",
816 "deprecated": true,
817 "example": {
818 "toolkitId": "550e8400-e29b-41d4-a716-446655440000"
819 }
820 },
821 "ToolPricing": {
822 "type": "object",
823 "properties": {
824 "description": {
825 "type": "string",
826 "description": "Human-readable pricing description."
827 },
828 "discount": {
829 "type": "string",
830 "nullable": true,
831 "description": "Discount on top of provider charges."
832 }
833 },
834 "description": "Published pricing for the tool",
835 "additionalProperties": false
836 },
837 "InstantAccount": {
838 "type": "object",
839 "properties": {
840 "supported": {
841 "type": "boolean",
842 "enum": [
843 true
844 ]
845 },
846 "price": {
847 "$ref": "#/components/schemas/ToolPricing"
848 }
849 },
850 "required": [
851 "supported"
852 ],
853 "description": "Present only when the tool supports an Instant account and its selected toolkit version is the latest. Missing for older toolkit versions or ineligible tools."
854 },
855 "Tool": {
856 "type": "object",
857 "properties": {
858 "slug": {
859 "type": "string",
860 "description": "Unique identifier for the tool",
861 "example": "GITHUB_CREATE_A_WORKFLOW_DISPATCH_EVENT"
862 },
863 "name": {
864 "type": "string",
865 "description": "Human-readable display name of the tool",
866 "example": "GitHub Actions"
867 },
868 "description": {
869 "type": "string",
870 "description": "Detailed explanation of the tool's functionality and purpose",
871 "example": "Automate GitHub workflows including CI/CD, issue management, and release processes"
872 },
873 "toolkit": {
874 "type": "object",
875 "properties": {
876 "slug": {
877 "type": "string",
878 "description": "Unique identifier of the parent toolkit",
879 "example": "github"
880 },
881 "name": {
882 "type": "string",
883 "description": "Human-readable name of the parent toolkit",
884 "example": "GitHub"
885 },
886 "logo": {
887 "type": "string",
888 "description": "URL to the toolkit logo image",
889 "example": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
890 }
891 },
892 "required": [
893 "slug",
894 "name",
895 "logo"
896 ]
897 },
898 "input_parameters": {
899 "type": "object",
900 "additionalProperties": {},
901 "description": "Schema definition of required input parameters for the tool",
902 "example": {
903 "repo_name": {
904 "type": "string",
905 "description": "GitHub repository name in owner/repo format",
906 "required": true,
907 "example": "octocat/Hello-World"
908 },
909 "workflow_id": {
910 "type": "string",
911 "description": "ID or filename of the workflow to trigger",
912 "required": true,
913 "example": "main.yml"
914 }
915 }
916 },
917 "no_auth": {
918 "type": "boolean",
919 "description": "Indicates if the tool can be used without authentication",
920 "example": false
921 },
922 "available_versions": {
923 "type": "array",
924 "items": {
925 "type": "string"
926 },
927 "description": "List of all available versions for this tool",
928 "example": [
929 "20250905_00",
930 "20250906_00"
931 ]
932 },
933 "version": {
934 "type": "string",
935 "description": "Current version of the tool",
936 "example": "20250905_00"
937 },
938 "instant": {
939 "$ref": "#/components/schemas/InstantAccount"
940 },
941 "output_parameters": {
942 "type": "object",
943 "additionalProperties": {},
944 "description": "Schema definition of return values from the tool",
945 "example": {
946 "run_id": {
947 "type": "number",
948 "description": "ID of the workflow run that was triggered",
949 "example": 12345678
950 },
951 "status": {
952 "type": "string",
953 "description": "Status of the workflow run",
954 "example": "completed",
955 "enum": [
956 "queued",
957 "in_progress",
958 "completed",
959 "failed"
960 ]
961 }
962 }
963 },
964 "scopes": {
965 "type": "array",
966 "items": {
967 "type": "string"
968 },
969 "description": "List of scopes associated with the tool",
970 "example": [
971 "https://www.googleapis.com/auth/gmail.modify"
972 ]
973 },
974 "scope_requirements": {
975 "type": "object",
976 "nullable": true,
977 "properties": {
978 "all_of": {
979 "type": "array",
980 "items": {
981 "anyOf": [
982 {
983 "type": "string"
984 },
985 {
986 "type": "object",
987 "properties": {
988 "any_of": {
989 "type": "array",
990 "items": {
991 "anyOf": [
992 {
993 "type": "string"
994 },
995 {
996 "type": "object",
997 "properties": {
998 "all_of": {
999 "type": "array",
1000 "items": {
1001 "type": "string"
1002 },
1003 "minItems": 1
1004 },
1005 "source": {
1006 "type": "array",
1007 "items": {
1008 "type": "string",
1009 "minLength": 1
1010 },
1011 "minItems": 1
1012 }
1013 },
1014 "required": [
1015 "all_of"
1016 ]
1017 }
1018 ]
1019 },
1020 "minItems": 1
1021 },
1022 "when": {
1023 "type": "object",
1024 "additionalProperties": {
1025 "type": "array",
1026 "items": {
1027 "type": "string"
1028 },
1029 "minItems": 1
1030 }
1031 },
1032 "source": {
1033 "type": "array",
1034 "items": {
1035 "type": "string",
1036 "minLength": 1
1037 },
1038 "minItems": 1
1039 }
1040 },
1041 "required": [
1042 "any_of"
1043 ]
1044 }
1045 ]
1046 }
1047 },
1048 "source": {
1049 "type": "array",
1050 "items": {
1051 "type": "string",
1052 "minLength": 1
1053 },
1054 "minItems": 1
1055 }
1056 },
1057 "required": [
1058 "all_of"
1059 ],
1060 "description": "Structured scope requirements for the tool. Null means the tool is legacy and only exposes flat scopes.",
1061 "example": {
1062 "all_of": [
1063 "read:user",
1064 {
1065 "any_of": [
1066 "repo",
1067 "public_repo"
1068 ]
1069 }
1070 ]
1071 }
1072 },
1073 "tags": {
1074 "type": "array",
1075 "items": {
1076 "type": "string"
1077 },
1078 "description": "List of tags associated with the tool for categorization and filtering",
1079 "example": [
1080 "ci-cd",
1081 "github",
1082 "automation",
1083 "devops"
1084 ]
1085 },
1086 "human_description": {
1087 "type": "string",
1088 "description": "Human-friendly description of the tool, if available",
1089 "example": "Create a new issue in a GitHub repository"
1090 },
1091 "is_deprecated": {
1092 "type": "boolean",
1093 "description": "Indicates if this tool is deprecated and may be removed in the future",
1094 "example": false
1095 },
1096 "deprecated": {
1097 "type": "object",
1098 "properties": {
1099 "displayName": {
1100 "type": "string",
1101 "description": "The display name of the tool",
1102 "example": "GitHub Actions"
1103 },
1104 "version": {
1105 "type": "string",
1106 "description": "Current version identifier of the tool",
1107 "example": "20250905_00"
1108 },
1109 "available_versions": {
1110 "type": "array",
1111 "items": {
1112 "type": "string"
1113 },
1114 "description": "List of all available versions for this tool",
1115 "example": [
1116 "20250905_00",
1117 "20250906_00"
1118 ]
1119 },
1120 "is_deprecated": {
1121 "type": "boolean",
1122 "description": "Indicates if this tool is deprecated and may be removed in the future",
1123 "example": false
1124 },
1125 "toolkit": {
1126 "type": "object",
1127 "properties": {
1128 "logo": {
1129 "type": "string",
1130 "description": "URL to the toolkit logo image",
1131 "example": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
1132 }
1133 },
1134 "required": [
1135 "logo"
1136 ]
1137 }
1138 },
1139 "required": [
1140 "displayName",
1141 "version",
1142 "available_versions",
1143 "is_deprecated",
1144 "toolkit"
1145 ]
1146 }
1147 },
1148 "required": [
1149 "slug",
1150 "name",
1151 "description",
1152 "toolkit",
1153 "input_parameters",
1154 "no_auth",
1155 "available_versions",
1156 "version",
1157 "output_parameters",
1158 "scopes",
1159 "scope_requirements",
1160 "tags",
1161 "is_deprecated",
1162 "deprecated"
1163 ]
1164 },
1165 "ToolsPaginated": {
1166 "type": "object",
1167 "properties": {
1168 "items": {
1169 "type": "array",
1170 "items": {
1171 "$ref": "#/components/schemas/Tool"
1172 }
1173 },
1174 "next_cursor": {
1175 "type": "string",
1176 "nullable": true
1177 },
1178 "total_pages": {
1179 "type": "number"
1180 },
1181 "current_page": {
1182 "type": "number"
1183 },
1184 "total_items": {
1185 "type": "number"
1186 }
1187 },
1188 "required": [
1189 "items",
1190 "total_pages",
1191 "current_page",
1192 "total_items"
1193 ]
1194 },
1195 "ToolDetails": {
1196 "type": "object",
1197 "properties": {
1198 "slug": {
1199 "type": "string",
1200 "description": "Unique identifier for the tool",
1201 "example": "GITHUB_CREATE_A_WORKFLOW_DISPATCH_EVENT"
1202 },
1203 "name": {
1204 "type": "string",
1205 "description": "Human-readable display name of the tool",
1206 "example": "GitHub Actions"
1207 },
1208 "description": {
1209 "type": "string",
1210 "description": "Detailed explanation of the tool's functionality and purpose",
1211 "example": "Automate GitHub workflows including CI/CD, issue management, and release processes"
1212 },
1213 "toolkit": {
1214 "type": "object",
1215 "properties": {
1216 "slug": {
1217 "type": "string",
1218 "description": "Unique identifier of the parent toolkit",
1219 "example": "github"
1220 },
1221 "name": {
1222 "type": "string",
1223 "description": "Human-readable name of the parent toolkit",
1224 "example": "GitHub"
1225 },
1226 "logo": {
1227 "type": "string",
1228 "description": "URL to the toolkit logo image",
1229 "example": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
1230 }
1231 },
1232 "required": [
1233 "slug",
1234 "name",
1235 "logo"
1236 ]
1237 },
1238 "input_parameters": {
1239 "type": "object",
1240 "additionalProperties": {},
1241 "description": "Schema definition of required input parameters for the tool",
1242 "example": {
1243 "repo_name": {
1244 "type": "string",
1245 "description": "GitHub repository name in owner/repo format",
1246 "required": true,
1247 "example": "octocat/Hello-World"
1248 },
1249 "workflow_id": {
1250 "type": "string",
1251 "description": "ID or filename of the workflow to trigger",
1252 "required": true,
1253 "example": "main.yml"
1254 }
1255 }
1256 },
1257 "no_auth": {
1258 "type": "boolean",
1259 "description": "Indicates if the tool can be used without authentication",
1260 "example": false
1261 },
1262 "available_versions": {
1263 "type": "array",
1264 "items": {
1265 "type": "string"
1266 },
1267 "description": "List of all available versions for this tool",
1268 "example": [
1269 "20250905_00",
1270 "20250906_00"
1271 ]
1272 },
1273 "version": {
1274 "type": "string",
1275 "description": "Current version of the tool",
1276 "example": "20250905_00"
1277 },
1278 "instant": {
1279 "$ref": "#/components/schemas/InstantAccount"
1280 },
1281 "output_parameters": {
1282 "type": "object",
1283 "additionalProperties": {},
1284 "description": "Schema definition of return values from the tool",
1285 "example": {
1286 "run_id": {
1287 "type": "number",
1288 "description": "ID of the workflow run that was triggered",
1289 "example": 12345678
1290 },
1291 "status": {
1292 "type": "string",
1293 "description": "Status of the workflow run",
1294 "example": "completed",
1295 "enum": [
1296 "queued",
1297 "in_progress",
1298 "completed",
1299 "failed"
1300 ]
1301 }
1302 }
1303 },
1304 "scopes": {
1305 "type": "array",
1306 "items": {
1307 "type": "string"
1308 },
1309 "description": "List of scopes associated with the tool",
1310 "example": [
1311 "https://www.googleapis.com/auth/gmail.modify"
1312 ]
1313 },
1314 "scope_requirements": {
1315 "type": "object",
1316 "nullable": true,
1317 "properties": {
1318 "all_of": {
1319 "type": "array",
1320 "items": {
1321 "anyOf": [
1322 {
1323 "type": "string"
1324 },
1325 {
1326 "type": "object",
1327 "properties": {
1328 "any_of": {
1329 "type": "array",
1330 "items": {
1331 "anyOf": [
1332 {
1333 "type": "string"
1334 },
1335 {
1336 "type": "object",
1337 "properties": {
1338 "all_of": {
1339 "type": "array",
1340 "items": {
1341 "type": "string"
1342 },
1343 "minItems": 1
1344 },
1345 "source": {
1346 "type": "array",
1347 "items": {
1348 "type": "string",
1349 "minLength": 1
1350 },
1351 "minItems": 1
1352 }
1353 },
1354 "required": [
1355 "all_of"
1356 ]
1357 }
1358 ]
1359 },
1360 "minItems": 1
1361 },
1362 "when": {
1363 "type": "object",
1364 "additionalProperties": {
1365 "type": "array",
1366 "items": {
1367 "type": "string"
1368 },
1369 "minItems": 1
1370 }
1371 },
1372 "source": {
1373 "type": "array",
1374 "items": {
1375 "type": "string",
1376 "minLength": 1
1377 },
1378 "minItems": 1
1379 }
1380 },
1381 "required": [
1382 "any_of"
1383 ]
1384 }
1385 ]
1386 }
1387 },
1388 "source": {
1389 "type": "array",
1390 "items": {
1391 "type": "string",
1392 "minLength": 1
1393 },
1394 "minItems": 1
1395 }
1396 },
1397 "required": [
1398 "all_of"
1399 ],
1400 "description": "Structured scope requirements for the tool. Null means the tool is legacy and only exposes flat scopes.",
1401 "example": {
1402 "all_of": [
1403 "read:user",
1404 {
1405 "any_of": [
1406 "repo",
1407 "public_repo"
1408 ]
1409 }
1410 ]
1411 }
1412 },
1413 "tags": {
1414 "type": "array",
1415 "items": {
1416 "type": "string"
1417 },
1418 "description": "List of tags associated with the tool for categorization and filtering",
1419 "example": [
1420 "ci-cd",
1421 "github",
1422 "automation",
1423 "devops"
1424 ]
1425 },
1426 "human_description": {
1427 "type": "string",
1428 "description": "Human-friendly description of the tool, if available",
1429 "example": "Create a new issue in a GitHub repository"
1430 },
1431 "is_deprecated": {
1432 "type": "boolean",
1433 "description": "Indicates if this tool is deprecated and may be removed in the future",
1434 "example": false
1435 },
1436 "deprecated": {
1437 "type": "object",
1438 "properties": {
1439 "displayName": {
1440 "type": "string",
1441 "description": "The display name of the tool",
1442 "example": "GitHub Actions"
1443 },
1444 "version": {
1445 "type": "string",
1446 "description": "Current version identifier of the tool",
1447 "example": "20250905_00"
1448 },
1449 "available_versions": {
1450 "type": "array",
1451 "items": {
1452 "type": "string"
1453 },
1454 "description": "List of all available versions for this tool",
1455 "example": [
1456 "20250905_00",
1457 "20250906_00"
1458 ]
1459 },
1460 "is_deprecated": {
1461 "type": "boolean",
1462 "description": "Indicates if this tool is deprecated and may be removed in the future",
1463 "example": false
1464 },
1465 "toolkit": {
1466 "type": "object",
1467 "properties": {
1468 "logo": {
1469 "type": "string",
1470 "description": "URL to the toolkit logo image",
1471 "example": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
1472 }
1473 },
1474 "required": [
1475 "logo"
1476 ]
1477 }
1478 },
1479 "required": [
1480 "displayName",
1481 "version",
1482 "available_versions",
1483 "is_deprecated",
1484 "toolkit"
1485 ]
1486 }
1487 },
1488 "required": [
1489 "slug",
1490 "name",
1491 "description",
1492 "toolkit",
1493 "input_parameters",
1494 "no_auth",
1495 "available_versions",
1496 "version",
1497 "output_parameters",
1498 "scopes",
1499 "scope_requirements",
1500 "tags",
1501 "is_deprecated",
1502 "deprecated"
1503 ]
1504 },
1505 "HookResult": {
1506 "oneOf": [
1507 {
1508 "type": "object",
1509 "properties": {
1510 "id": {
1511 "type": "string",
1512 "description": "The hook id"
1513 },
1514 "status": {
1515 "type": "string",
1516 "enum": [
1517 "evaluated"
1518 ]
1519 },
1520 "outcome": {
1521 "type": "string",
1522 "enum": [
1523 "continue",
1524 "block"
1525 ],
1526 "description": "What the hook decided"
1527 }
1528 },
1529 "required": [
1530 "id",
1531 "status",
1532 "outcome"
1533 ]
1534 },
1535 {
1536 "type": "object",
1537 "properties": {
1538 "id": {
1539 "type": "string",
1540 "description": "The hook id"
1541 },
1542 "status": {
1543 "type": "string",
1544 "enum": [
1545 "unavailable"
1546 ],
1547 "description": "The hook could not be evaluated"
1548 }
1549 },
1550 "required": [
1551 "id",
1552 "status"
1553 ]
1554 }
1555 ]
1556 },
1557 "ExecuteCompleted": {
1558 "type": "object",
1559 "properties": {
1560 "result_type": {
1561 "type": "string",
1562 "enum": [
1563 "completed"
1564 ],
1565 "description": "The tool ran and succeeded",
1566 "x-experimental": true
1567 },
1568 "instant_charge": {
1569 "type": "object",
1570 "properties": {
1571 "amount": {
1572 "type": "string",
1573 "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
1574 "description": "Instant charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
1575 },
1576 "currency": {
1577 "type": "string",
1578 "enum": [
1579 "USD"
1580 ],
1581 "description": "Currency of the instant charge. Always USD."
1582 },
1583 "charged_by": {
1584 "type": "string",
1585 "enum": [
1586 "composio"
1587 ],
1588 "description": "Entity charging for instant usage. Always composio."
1589 }
1590 },
1591 "required": [
1592 "amount",
1593 "currency",
1594 "charged_by"
1595 ],
1596 "description": "Returned only when the session enables instant.return_instant_charge and a charge is available. Failed individual tool calls omit it. Multi-execute returns one aggregate of reported charges from eligible successful calls, even if another call fails."
1597 },
1598 "data": {
1599 "type": "object",
1600 "additionalProperties": {},
1601 "description": "The data returned by the tool execution",
1602 "example": {
1603 "message": "Hello, World!",
1604 "status": "success"
1605 }
1606 },
1607 "error": {
1608 "type": "string",
1609 "nullable": true,
1610 "description": "Error message if the execution failed, null otherwise"
1611 },
1612 "log_id": {
1613 "type": "string",
1614 "description": "Unique identifier for the execution log",
1615 "example": "log_abc123xyz"
1616 },
1617 "hook_results": {
1618 "type": "array",
1619 "items": {
1620 "$ref": "#/components/schemas/HookResult"
1621 },
1622 "description": "Every session hook that applied to this call. Omitted when none applied."
1623 }
1624 },
1625 "required": [
1626 "result_type",
1627 "data",
1628 "error",
1629 "log_id"
1630 ]
1631 },
1632 "ExecuteFailed": {
1633 "type": "object",
1634 "properties": {
1635 "result_type": {
1636 "type": "string",
1637 "enum": [
1638 "failed"
1639 ],
1640 "description": "The tool ran and failed, or the user did not approve it",
1641 "x-experimental": true
1642 },
1643 "instant_charge": {
1644 "type": "object",
1645 "properties": {
1646 "amount": {
1647 "type": "string",
1648 "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
1649 "description": "Instant charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
1650 },
1651 "currency": {
1652 "type": "string",
1653 "enum": [
1654 "USD"
1655 ],
1656 "description": "Currency of the instant charge. Always USD."
1657 },
1658 "charged_by": {
1659 "type": "string",
1660 "enum": [
1661 "composio"
1662 ],
1663 "description": "Entity charging for instant usage. Always composio."
1664 }
1665 },
1666 "required": [
1667 "amount",
1668 "currency",
1669 "charged_by"
1670 ],
1671 "description": "Returned only when the session enables instant.return_instant_charge and a charge is available. Failed individual tool calls omit it. Multi-execute returns one aggregate of reported charges from eligible successful calls, even if another call fails."
1672 },
1673 "data": {
1674 "type": "object",
1675 "additionalProperties": {},
1676 "description": "The data returned by the tool execution",
1677 "example": {
1678 "message": "Hello, World!",
1679 "status": "success"
1680 }
1681 },
1682 "error": {
1683 "type": "string",
1684 "nullable": true,
1685 "description": "Error message if the execution failed, null otherwise"
1686 },
1687 "log_id": {
1688 "type": "string",
1689 "description": "Unique identifier for the execution log",
1690 "example": "log_abc123xyz"
1691 },
1692 "hook_results": {
1693 "type": "array",
1694 "items": {
1695 "$ref": "#/components/schemas/HookResult"
1696 },
1697 "description": "Every session hook that applied to this call. Omitted when none applied."
1698 }
1699 },
1700 "required": [
1701 "result_type",
1702 "data",
1703 "error",
1704 "log_id"
1705 ]
1706 },
1707 "BlockReason": {
1708 "oneOf": [
1709 {
1710 "type": "object",
1711 "properties": {
1712 "type": {
1713 "type": "string",
1714 "enum": [
1715 "request_blocked"
1716 ],
1717 "description": "A before_execute hook stopped the call. The tool did not run."
1718 },
1719 "hook_id": {
1720 "type": "string"
1721 }
1722 },
1723 "required": [
1724 "type",
1725 "hook_id"
1726 ]
1727 },
1728 {
1729 "type": "object",
1730 "properties": {
1731 "type": {
1732 "type": "string",
1733 "enum": [
1734 "response_blocked"
1735 ],
1736 "description": "An after_execute hook stopped the call. The tool ran; its response was withheld."
1737 },
1738 "hook_id": {
1739 "type": "string"
1740 }
1741 },
1742 "required": [
1743 "type",
1744 "hook_id"
1745 ]
1746 }
1747 ]
1748 },
1749 "ExecuteBlocked": {
1750 "type": "object",
1751 "properties": {
1752 "result_type": {
1753 "type": "string",
1754 "enum": [
1755 "blocked"
1756 ],
1757 "description": "A session hook stopped the call"
1758 },
1759 "reason": {
1760 "$ref": "#/components/schemas/BlockReason"
1761 },
1762 "message": {
1763 "type": "string",
1764 "description": "A message for the agent. It includes the hook's name, when it has one; the hook id is in `reason`.",
1765 "example": "Blocked by session policy: No external email"
1766 },
1767 "log_id": {
1768 "type": "string",
1769 "description": "The execution log ID. Only set when the tool ran and its response was blocked."
1770 },
1771 "instant_charge": {
1772 "type": "object",
1773 "properties": {
1774 "amount": {
1775 "type": "string",
1776 "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
1777 "description": "Instant charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
1778 },
1779 "currency": {
1780 "type": "string",
1781 "enum": [
1782 "USD"
1783 ],
1784 "description": "Currency of the instant charge. Always USD."
1785 },
1786 "charged_by": {
1787 "type": "string",
1788 "enum": [
1789 "composio"
1790 ],
1791 "description": "Entity charging for instant usage. Always composio."
1792 }
1793 },
1794 "required": [
1795 "amount",
1796 "currency",
1797 "charged_by"
1798 ],
1799 "description": "Returned only when the session enables instant.return_instant_charge and a charge is available. Only set when the tool ran and its response was blocked."
1800 },
1801 "hook_results": {
1802 "type": "array",
1803 "items": {
1804 "$ref": "#/components/schemas/HookResult"
1805 },
1806 "description": "Every session hook that applied to this call. Omitted when none applied."
1807 }
1808 },
1809 "required": [
1810 "result_type",
1811 "reason",
1812 "message"
1813 ]
1814 },
1815 "UserInputRequest": {
1816 "type": "object",
1817 "properties": {
1818 "type": {
1819 "type": "string",
1820 "enum": [
1821 "elicitation"
1822 ],
1823 "description": "Always `elicitation`"
1824 },
1825 "mode": {
1826 "type": "string",
1827 "enum": [
1828 "form"
1829 ],
1830 "description": "Always `form`: collect the answer with a form built from `requested_schema`"
1831 },
1832 "message": {
1833 "type": "string",
1834 "description": "Text to show the user",
1835 "example": "Your agent wants to run the following tool:\n\nGITHUB_DELETE_A_REPOSITORY({\"owner\": \"acme\", \"repo\": \"old-api\"})"
1836 },
1837 "requested_schema": {
1838 "type": "object",
1839 "additionalProperties": {},
1840 "description": "JSON Schema for the answer. As in MCP form mode, it is a flat object whose fields are strings, numbers, booleans, or single- or multi-select enums."
1841 }
1842 },
1843 "required": [
1844 "type",
1845 "mode",
1846 "message",
1847 "requested_schema"
1848 ],
1849 "description": "A question for the user, in the shape of an MCP `elicitation/create` request in form mode (https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Show `message` to the user and collect an answer that matches `requested_schema`."
1850 },
1851 "ExecuteRequiresUserInput": {
1852 "type": "object",
1853 "properties": {
1854 "result_type": {
1855 "type": "string",
1856 "enum": [
1857 "input_required"
1858 ],
1859 "description": "The call needs the user's input before it runs",
1860 "x-experimental": true
1861 },
1862 "input_requests": {
1863 "type": "object",
1864 "additionalProperties": {
1865 "$ref": "#/components/schemas/UserInputRequest"
1866 },
1867 "description": "Questions for the user, keyed by an ID the answers must reuse",
1868 "x-experimental": true
1869 },
1870 "request_state": {
1871 "type": "string",
1872 "description": "Send this back unchanged in `request_state` with the answers",
1873 "x-experimental": true
1874 }
1875 },
1876 "required": [
1877 "result_type",
1878 "input_requests"
1879 ],
1880 "description": "The call needs the user's input before it runs. Returned only when the session is configured to ask for user approval before tool execution. Show each question in `input_requests` to the user, then repeat the same call with their answers in `input_responses`, along with this `request_state` if present.",
1881 "x-experimental": true
1882 },
1883 "UserInputResponse": {
1884 "type": "object",
1885 "properties": {
1886 "action": {
1887 "type": "string",
1888 "enum": [
1889 "accept",
1890 "decline",
1891 "cancel"
1892 ],
1893 "description": "`accept` when the user submitted the form, `decline` when they said no, `cancel` when they dismissed it"
1894 },
1895 "content": {
1896 "type": "object",
1897 "additionalProperties": {},
1898 "description": "With `accept`, the user's answer: fields matching the question's `requested_schema`"
1899 }
1900 },
1901 "required": [
1902 "action"
1903 ],
1904 "description": "The user's answer to one question, in the shape of an MCP elicitation result (https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation)."
1905 },
1906 "ProxyExecuteCompleted": {
1907 "type": "object",
1908 "properties": {
1909 "result_type": {
1910 "type": "string",
1911 "enum": [
1912 "completed"
1913 ],
1914 "description": "The request was sent and the proxied API responded",
1915 "x-experimental": true
1916 },
1917 "data": {
1918 "nullable": true,
1919 "description": "The response data returned from the proxied API",
1920 "example": {
1921 "id": "123",
1922 "name": "Resource Name",
1923 "created_at": "2023-01-01T00:00:00Z"
1924 },
1925 "type": "object"
1926 },
1927 "binary_data": {
1928 "type": "object",
1929 "properties": {
1930 "url": {
1931 "type": "string",
1932 "description": "URL to download binary content"
1933 },
1934 "content_type": {
1935 "type": "string",
1936 "description": "Content-Type of the binary data"
1937 },
1938 "size": {
1939 "type": "number",
1940 "description": "File size in bytes"
1941 },
1942 "expires_at": {
1943 "type": "string",
1944 "description": "ISO 8601 timestamp when the URL expires"
1945 }
1946 },
1947 "required": [
1948 "url",
1949 "content_type",
1950 "size"
1951 ],
1952 "description": "Binary body response data. Present when the response is a binary file."
1953 },
1954 "status": {
1955 "type": "number",
1956 "description": "The HTTP status code returned from the proxied API",
1957 "example": 200
1958 },
1959 "headers": {
1960 "type": "object",
1961 "additionalProperties": {
1962 "type": "string"
1963 },
1964 "description": "The HTTP headers returned from the proxied API",
1965 "example": {
1966 "content-type": "application/json",
1967 "cache-control": "no-cache"
1968 }
1969 },
1970 "hook_results": {
1971 "type": "array",
1972 "items": {
1973 "$ref": "#/components/schemas/HookResult"
1974 },
1975 "description": "Every session hook that applied to this request. Omitted when none applied."
1976 }
1977 },
1978 "required": [
1979 "result_type",
1980 "status"
1981 ]
1982 },
1983 "ProxyExecuteBlocked": {
1984 "type": "object",
1985 "properties": {
1986 "result_type": {
1987 "type": "string",
1988 "enum": [
1989 "blocked"
1990 ],
1991 "description": "A session hook stopped the call"
1992 },
1993 "reason": {
1994 "$ref": "#/components/schemas/BlockReason"
1995 },
1996 "message": {
1997 "type": "string",
1998 "description": "A message for the agent. It includes the hook's name, when it has one; the hook id is in `reason`.",
1999 "example": "Blocked by session policy: No external email"
2000 },
2001 "hook_results": {
2002 "type": "array",
2003 "items": {
2004 "$ref": "#/components/schemas/HookResult"
2005 },
2006 "description": "Every session hook that applied to this call. Omitted when none applied."
2007 }
2008 },
2009 "required": [
2010 "result_type",
2011 "reason",
2012 "message"
2013 ]
2014 },
2015 "ToolRouterToolkitsListResponse": {
2016 "type": "object",
2017 "properties": {
2018 "items": {
2019 "type": "array",
2020 "items": {
2021 "type": "object",
2022 "properties": {
2023 "name": {
2024 "type": "string",
2025 "description": "Display name of the toolkit"
2026 },
2027 "slug": {
2028 "type": "string",
2029 "description": "Unique slug identifier"
2030 },
2031 "enabled": {
2032 "type": "boolean",
2033 "description": "Whether the toolkit is enabled"
2034 },
2035 "is_no_auth": {
2036 "type": "boolean",
2037 "description": "Whether the toolkit is no-auth"
2038 },
2039 "composio_managed_auth_schemes": {
2040 "type": "array",
2041 "items": {
2042 "type": "string"
2043 },
2044 "description": "Available Composio-managed auth schemes"
2045 },
2046 "meta": {
2047 "type": "object",
2048 "properties": {
2049 "logo": {
2050 "type": "string",
2051 "format": "uri",
2052 "description": "URL to the toolkit logo"
2053 },
2054 "description": {
2055 "type": "string",
2056 "description": "Description of the toolkit"
2057 },
2058 "isNoAuth": {
2059 "type": "boolean",
2060 "description": "Duplicates the top-level is_no_auth field. Kept for backward compatibility with existing readers; use is_no_auth instead.",
2061 "deprecated": true
2062 }
2063 },
2064 "required": [
2065 "logo",
2066 "description"
2067 ],
2068 "description": "Toolkit metadata"
2069 },
2070 "connected_account": {
2071 "type": "object",
2072 "nullable": true,
2073 "properties": {
2074 "id": {
2075 "type": "string",
2076 "format": "connectedAccountId",
2077 "description": "Connected account identifier"
2078 },
2079 "user_id": {
2080 "type": "string",
2081 "description": "User identifier"
2082 },
2083 "status": {
2084 "type": "string",
2085 "description": "Connection status"
2086 },
2087 "created_at": {
2088 "type": "string",
2089 "format": "date-time",
2090 "description": "Creation timestamp"
2091 },
2092 "auth_config": {
2093 "type": "object",
2094 "properties": {
2095 "id": {
2096 "type": "string",
2097 "description": "Auth config identifier"
2098 },
2099 "auth_scheme": {
2100 "type": "string",
2101 "description": "Authentication scheme type"
2102 },
2103 "is_composio_managed": {
2104 "type": "boolean",
2105 "description": "Whether this is a Composio-managed auth config"
2106 }
2107 },
2108 "required": [
2109 "id",
2110 "auth_scheme",
2111 "is_composio_managed"
2112 ],
2113 "description": "Auth config details"
2114 }
2115 },
2116 "required": [
2117 "id",
2118 "user_id",
2119 "status",
2120 "created_at",
2121 "auth_config"
2122 ],
2123 "description": "Connected account if available"
2124 }
2125 },
2126 "required": [
2127 "name",
2128 "slug",
2129 "enabled",
2130 "is_no_auth",
2131 "composio_managed_auth_schemes",
2132 "meta",
2133 "connected_account"
2134 ]
2135 }
2136 },
2137 "next_cursor": {
2138 "type": "string",
2139 "nullable": true
2140 },
2141 "total_pages": {
2142 "type": "number"
2143 },
2144 "current_page": {
2145 "type": "number"
2146 },
2147 "total_items": {
2148 "type": "number"
2149 }
2150 },
2151 "required": [
2152 "items",
2153 "total_pages",
2154 "current_page",
2155 "total_items"
2156 ]
2157 }
2158 },
2159 "parameters": {}
2160 },
2161 "paths": {
2162 "/api/v3/auth/session/info": {
2163 "get": {
2164 "summary": "Get current user session information",
2165 "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.",
2166 "tags": [
2167 "Authentication"
2168 ],
2169 "operationId": "getAuthSessionInfo",
2170 "security": [
2171 {
2172 "UserApiKeyAuth": []
2173 }
2174 ],
2175 "responses": {
2176 "200": {
2177 "description": "Session is valid and active. Returns detailed information about the authenticated user, their project, and organization.",
2178 "content": {
2179 "application/json": {
2180 "schema": {
2181 "type": "object",
2182 "properties": {
2183 "project": {
2184 "type": "object",
2185 "nullable": true,
2186 "properties": {
2187 "auto_id": {
2188 "type": "number",
2189 "description": "Internal auto-incrementing ID for the project",
2190 "example": 12345
2191 },
2192 "id": {
2193 "type": "string",
2194 "description": "UUID identifier for the project",
2195 "example": "550e8400-e29b-41d4-a716-446655440000"
2196 },
2197 "org_id": {
2198 "type": "string",
2199 "description": "Organization UUID that this project belongs to",
2200 "example": "550e8400-e29b-41d4-a716-446655440001"
2201 },
2202 "name": {
2203 "type": "string",
2204 "description": "User-defined name for the project",
2205 "example": "Production API"
2206 },
2207 "email": {
2208 "type": "string",
2209 "description": "Email address used for project notifications",
2210 "example": "project-123@composio.dev"
2211 },
2212 "nano_id": {
2213 "type": "string",
2214 "format": "projectId",
2215 "description": "Short, URL-friendly unique identifier for the project",
2216 "example": "pr_1a2b3c4d5e6f"
2217 },
2218 "created_at": {
2219 "type": "string",
2220 "description": "Date and time when the project was created",
2221 "example": "2023-05-16T14:30:00.000Z"
2222 },
2223 "updated_at": {
2224 "type": "string",
2225 "description": "Date and time when the project was last modified",
2226 "example": "2023-05-18T09:15:30.000Z"
2227 },
2228 "webhook_url": {
2229 "type": "string",
2230 "nullable": true,
2231 "description": "Endpoint URL for trigger webhook notifications",
2232 "example": "https://example.com/webhook"
2233 },
2234 "event_webhook_url": {
2235 "type": "string",
2236 "nullable": true,
2237 "description": "Endpoint URL for event webhook notifications",
2238 "example": "https://example.com/events"
2239 },
2240 "webhook_secret": {
2241 "type": "string",
2242 "nullable": true,
2243 "description": "Secret used to verify webhook signatures",
2244 "example": "whsec_a1b2c3d4e5f6g7h8i9j0"
2245 },
2246 "triggers_enabled": {
2247 "type": "boolean",
2248 "description": "Flag indicating if triggers are enabled for this project",
2249 "example": true
2250 },
2251 "last_subscribed_at": {
2252 "type": "string",
2253 "nullable": true,
2254 "description": "Date and time when the project last subscribed to updates",
2255 "example": "2023-05-17T10:00:00.000Z"
2256 },
2257 "deleted": {
2258 "type": "boolean",
2259 "description": "Flag indicating if the project has been deleted",
2260 "example": false
2261 },
2262 "is_new_webhook": {
2263 "type": "boolean",
2264 "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)",
2265 "example": true,
2266 "deprecated": true
2267 },
2268 "webhook_version": {
2269 "type": "string",
2270 "enum": [
2271 "V1",
2272 "V2",
2273 "V3"
2274 ],
2275 "description": "Version of the webhook configuration",
2276 "example": "V2"
2277 },
2278 "org": {
2279 "type": "object",
2280 "properties": {
2281 "id": {
2282 "type": "string",
2283 "format": "orgId",
2284 "description": "Short, URL-friendly unique identifier for the organization",
2285 "example": "ok_1a2b3c4d5e6f"
2286 },
2287 "name": {
2288 "type": "string",
2289 "description": "User-defined name for the organization",
2290 "example": "Acme Corp"
2291 },
2292 "plan": {
2293 "type": "string",
2294 "description": "Current subscription plan level",
2295 "example": "BUSINESS"
2296 }
2297 },
2298 "required": [
2299 "id",
2300 "name",
2301 "plan"
2302 ],
2303 "description": "Organization details"
2304 }
2305 },
2306 "required": [
2307 "auto_id",
2308 "id",
2309 "org_id",
2310 "name",
2311 "email",
2312 "nano_id",
2313 "created_at",
2314 "updated_at",
2315 "webhook_url",
2316 "event_webhook_url",
2317 "webhook_secret",
2318 "triggers_enabled",
2319 "last_subscribed_at",
2320 "deleted",
2321 "is_new_webhook",
2322 "webhook_version",
2323 "org"
2324 ],
2325 "description": "Details of the current active project (null if accessing with org-level credentials)"
2326 },
2327 "api_key": {
2328 "type": "object",
2329 "nullable": true,
2330 "properties": {
2331 "auto_id": {
2332 "type": "number",
2333 "description": "Internal auto-incrementing ID for the API key",
2334 "example": 7890
2335 },
2336 "id": {
2337 "type": "string",
2338 "description": "UUID identifier for the API key",
2339 "example": "550e8400-e29b-41d4-a716-446655440003"
2340 },
2341 "name": {
2342 "type": "string",
2343 "description": "User-defined name for the API key",
2344 "example": "Development Key"
2345 },
2346 "project_id": {
2347 "type": "string",
2348 "format": "projectId",
2349 "description": "Short, URL-friendly unique identifier for the associated project",
2350 "example": "pr_1a2b3c4d5e6f"
2351 },
2352 "org_member_id": {
2353 "type": "string",
2354 "description": "UUID identifier for the organization member who owns this API key",
2355 "example": "550e8400-e29b-41d4-a716-446655440002"
2356 },
2357 "created_at": {
2358 "type": "string",
2359 "description": "Date and time when the API key was created",
2360 "example": "2023-05-01T10:00:00.000Z"
2361 },
2362 "updated_at": {
2363 "type": "string",
2364 "description": "Date and time when the API key was last modified",
2365 "example": "2023-05-01T10:00:00.000Z"
2366 },
2367 "deleted_at": {
2368 "type": "string",
2369 "nullable": true,
2370 "description": "Date and time when the API key was deleted (if applicable)"
2371 },
2372 "key": {
2373 "type": "string",
2374 "description": "The actual API key value (usually only shown once during creation)",
2375 "example": "ak_a1b2c3d4e5f6g7h8i9j0"
2376 },
2377 "deleted": {
2378 "type": "boolean",
2379 "description": "Flag indicating if the API key has been deleted",
2380 "example": false
2381 }
2382 },
2383 "required": [
2384 "auto_id",
2385 "id",
2386 "name",
2387 "project_id",
2388 "org_member_id",
2389 "created_at",
2390 "updated_at",
2391 "deleted_at",
2392 "key",
2393 "deleted"
2394 ],
2395 "description": "Details of the API key used for authentication (null if using session auth)"
2396 },
2397 "org_member": {
2398 "type": "object",
2399 "properties": {
2400 "id": {
2401 "type": "string",
2402 "description": "UUID identifier for the organization member",
2403 "example": "550e8400-e29b-41d4-a716-446655440002"
2404 },
2405 "email": {
2406 "type": "string",
2407 "description": "Email address of the authenticated user",
2408 "example": "user@example.com"
2409 },
2410 "name": {
2411 "type": "string",
2412 "description": "Display name of the authenticated user",
2413 "example": "John Doe"
2414 },
2415 "role": {
2416 "type": "string",
2417 "description": "Access role of the authenticated user within the organization",
2418 "example": "admin"
2419 },
2420 "metadata": {
2421 "type": "object",
2422 "properties": {
2423 "prefers_old_dashboard": {
2424 "type": "boolean",
2425 "description": "If true, the user will be redirected to the legacy dashboard at platform.composio.dev."
2426 },
2427 "onboarding_platform": {
2428 "type": "string",
2429 "enum": [
2430 "consumer",
2431 "developer"
2432 ],
2433 "description": "Platform the user onboarded on."
2434 },
2435 "seen_flow_consumer": {
2436 "type": "boolean",
2437 "description": "True once the user has completed the consumer onboarding flow."
2438 },
2439 "seen_flow_developer": {
2440 "type": "boolean",
2441 "description": "True once the user has completed the developer onboarding flow."
2442 },
2443 "seen_flow_cli": {
2444 "type": "boolean",
2445 "description": "True once the user has completed the CLI onboarding flow."
2446 },
2447 "seen_connect_announcement": {
2448 "type": "boolean",
2449 "description": "True once the user has dismissed the Composio For You announcement modal in the developer dashboard."
2450 }
2451 },
2452 "additionalProperties": {
2453 "anyOf": [
2454 {
2455 "type": "string"
2456 },
2457 {
2458 "type": "boolean"
2459 },
2460 {
2461 "type": "number"
2462 }
2463 ]
2464 },
2465 "description": "User metadata (JSONB). Typed keys are shown; additional keys pass through unchanged."
2466 }
2467 },
2468 "required": [
2469 "id",
2470 "email",
2471 "name",
2472 "role",
2473 "metadata"
2474 ],
2475 "description": "Information about the authenticated user",
2476 "example": {
2477 "id": "550e8400-e29b-41d4-a716-446655440002",
2478 "email": "user@example.com",
2479 "name": "John Doe",
2480 "role": "admin",
2481 "metadata": {
2482 "prefers_old_dashboard": false
2483 }
2484 }
2485 }
2486 },
2487 "required": [
2488 "project",
2489 "api_key",
2490 "org_member"
2491 ],
2492 "description": "Response containing user session information"
2493 }
2494 }
2495 }
2496 },
2497 "400": {
2498 "description": "Bad request. The request format may be invalid or missing required parameters.",
2499 "content": {
2500 "application/json": {
2501 "schema": {
2502 "$ref": "#/components/schemas/Error"
2503 }
2504 }
2505 }
2506 },
2507 "401": {
2508 "description": "Unauthorized. Authentication is required or the provided credentials are invalid or expired.",
2509 "content": {
2510 "application/json": {
2511 "schema": {
2512 "$ref": "#/components/schemas/Error"
2513 }
2514 }
2515 }
2516 },
2517 "403": {
2518 "description": "Forbidden. The authenticated user does not have permission to access this resource.",
2519 "content": {
2520 "application/json": {
2521 "schema": {
2522 "$ref": "#/components/schemas/Error"
2523 }
2524 }
2525 }
2526 },
2527 "404": {
2528 "description": "Not found. The requested project, organization, or member resource could not be found.",
2529 "content": {
2530 "application/json": {
2531 "schema": {
2532 "$ref": "#/components/schemas/Error"
2533 }
2534 }
2535 }
2536 },
2537 "500": {
2538 "description": "Internal server error. An unexpected error occurred while processing the request.",
2539 "content": {
2540 "application/json": {
2541 "schema": {
2542 "$ref": "#/components/schemas/Error"
2543 }
2544 }
2545 }
2546 }
2547 },
2548 "x-api-version": "3.0"
2549 }
2550 },
2551 "/api/v3/auth_configs": {
2552 "post": {
2553 "summary": "Create new authentication configuration",
2554 "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.",
2555 "tags": [
2556 "Auth Configs"
2557 ],
2558 "operationId": "postAuthConfigs",
2559 "security": [
2560 {
2561 "ApiKeyAuth": []
2562 },
2563 {
2564 "UserApiKeyAuth": []
2565 }
2566 ],
2567 "requestBody": {
2568 "required": true,
2569 "content": {
2570 "application/json": {
2571 "schema": {
2572 "type": "object",
2573 "properties": {
2574 "toolkit": {
2575 "type": "object",
2576 "properties": {
2577 "slug": {
2578 "type": "string",
2579 "description": "Toolkit slug to create auth config for"
2580 }
2581 },
2582 "required": [
2583 "slug"
2584 ]
2585 },
2586 "auth_config": {
2587 "oneOf": [
2588 {
2589 "$ref": "#/components/schemas/ComposioManagedAuthConfigCreate"
2590 },
2591 {
2592 "$ref": "#/components/schemas/CustomAuthConfigCreate"
2593 }
2594 ],
2595 "discriminator": {
2596 "propertyName": "type",
2597 "mapping": {
2598 "use_composio_managed_auth": "#/components/schemas/ComposioManagedAuthConfigCreate",
2599 "use_custom_auth": "#/components/schemas/CustomAuthConfigCreate"
2600 }
2601 },
2602 "default": {
2603 "type": "use_composio_managed_auth",
2604 "credentials": {},
2605 "restrict_to_following_tools": []
2606 }
2607 }
2608 },
2609 "required": [
2610 "toolkit"
2611 ]
2612 }
2613 }
2614 }
2615 },
2616 "responses": {
2617 "201": {
2618 "description": "Successfully created auth config",
2619 "content": {
2620 "application/json": {
2621 "schema": {
2622 "type": "object",
2623 "properties": {
2624 "toolkit": {
2625 "type": "object",
2626 "properties": {
2627 "slug": {
2628 "type": "string",
2629 "description": "The unique key of the toolkit"
2630 }
2631 },
2632 "required": [
2633 "slug"
2634 ]
2635 },
2636 "auth_config": {
2637 "type": "object",
2638 "properties": {
2639 "id": {
2640 "type": "string",
2641 "format": "authConfigId",
2642 "description": "The auth config id of the toolkit (must be a valid auth config id)"
2643 },
2644 "auth_scheme": {
2645 "type": "string",
2646 "description": "The authentication mode of the toolkit"
2647 },
2648 "is_composio_managed": {
2649 "type": "boolean",
2650 "description": "Whether the auth config is managed by Composio"
2651 },
2652 "managed_app_id": {
2653 "type": "string",
2654 "nullable": true,
2655 "description": "The Composio-managed app this auth config uses, as composio_managed_auth[].managed_app_id from GET /api/v3/toolkits/{toolkit_slug}. Null when the auth config is not linked to a managed app. Use is_composio_managed to tell managed from custom."
2656 },
2657 "restrict_to_following_tools": {
2658 "type": "array",
2659 "items": {
2660 "type": "string"
2661 },
2662 "default": [],
2663 "description": "The tools that the user can use with the auth config. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
2664 "deprecated": true
2665 }
2666 },
2667 "required": [
2668 "id",
2669 "auth_scheme",
2670 "is_composio_managed",
2671 "managed_app_id"
2672 ]
2673 }
2674 },
2675 "required": [
2676 "toolkit",
2677 "auth_config"
2678 ]
2679 }
2680 }
2681 }
2682 },
2683 "400": {
2684 "description": "Bad request",
2685 "content": {
2686 "application/json": {
2687 "schema": {
2688 "$ref": "#/components/schemas/Error"
2689 }
2690 }
2691 }
2692 },
2693 "401": {
2694 "description": "Unauthorized",
2695 "content": {
2696 "application/json": {
2697 "schema": {
2698 "$ref": "#/components/schemas/Error"
2699 }
2700 }
2701 }
2702 },
2703 "403": {
2704 "description": "Forbidden - Your role does not allow modifying auth configs",
2705 "content": {
2706 "application/json": {
2707 "schema": {
2708 "$ref": "#/components/schemas/Error"
2709 }
2710 }
2711 }
2712 },
2713 "404": {
2714 "description": "Not found",
2715 "content": {
2716 "application/json": {
2717 "schema": {
2718 "$ref": "#/components/schemas/Error"
2719 }
2720 }
2721 }
2722 },
2723 "500": {
2724 "description": "Internal server error",
2725 "content": {
2726 "application/json": {
2727 "schema": {
2728 "$ref": "#/components/schemas/Error"
2729 }
2730 }
2731 }
2732 }
2733 },
2734 "x-api-version": "3.0"
2735 },
2736 "get": {
2737 "summary": "List authentication configurations with optional filters",
2738 "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.",
2739 "tags": [
2740 "Auth Configs"
2741 ],
2742 "operationId": "getAuthConfigs",
2743 "security": [
2744 {
2745 "ApiKeyAuth": []
2746 },
2747 {
2748 "UserApiKeyAuth": []
2749 }
2750 ],
2751 "parameters": [
2752 {
2753 "schema": {
2754 "anyOf": [
2755 {
2756 "type": "string"
2757 },
2758 {
2759 "type": "boolean"
2760 }
2761 ],
2762 "description": "Whether to filter by composio managed auth configs"
2763 },
2764 "required": false,
2765 "description": "Whether to filter by composio managed auth configs",
2766 "name": "is_composio_managed",
2767 "in": "query"
2768 },
2769 {
2770 "schema": {
2771 "type": "string"
2772 },
2773 "required": false,
2774 "description": "Comma-separated list of toolkit slugs to filter auth configs by",
2775 "in": "query",
2776 "name": "toolkit_slug"
2777 },
2778 {
2779 "schema": {
2780 "type": "string",
2781 "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_slug instead.",
2782 "deprecated": true
2783 },
2784 "required": false,
2785 "description": "The app id to filter by",
2786 "name": "deprecated_app_id",
2787 "in": "query"
2788 },
2789 {
2790 "schema": {
2791 "type": "string",
2792 "description": "DEPRECATED: This parameter will be removed in a future version.",
2793 "deprecated": true
2794 },
2795 "required": false,
2796 "name": "deprecated_status",
2797 "in": "query"
2798 },
2799 {
2800 "schema": {
2801 "type": "boolean",
2802 "nullable": true,
2803 "default": false,
2804 "description": "Show disabled auth configs"
2805 },
2806 "required": false,
2807 "description": "Show disabled auth configs",
2808 "name": "show_disabled",
2809 "in": "query"
2810 },
2811 {
2812 "schema": {
2813 "type": "string",
2814 "description": "Search auth configs by name or id"
2815 },
2816 "required": false,
2817 "description": "Search auth configs by name or id",
2818 "name": "search",
2819 "in": "query"
2820 },
2821 {
2822 "schema": {
2823 "type": "number",
2824 "nullable": true
2825 },
2826 "required": false,
2827 "description": "Number of items per page, max allowed is 200",
2828 "name": "limit",
2829 "in": "query"
2830 },
2831 {
2832 "schema": {
2833 "type": "string"
2834 },
2835 "required": false,
2836 "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.",
2837 "name": "cursor",
2838 "in": "query"
2839 }
2840 ],
2841 "responses": {
2842 "200": {
2843 "description": "Successfully fetched auth configs",
2844 "content": {
2845 "application/json": {
2846 "schema": {
2847 "type": "object",
2848 "properties": {
2849 "items": {
2850 "type": "array",
2851 "items": {
2852 "type": "object",
2853 "properties": {
2854 "id": {
2855 "type": "string",
2856 "format": "authConfigId",
2857 "description": "The unique ID of the authentication configuration"
2858 },
2859 "uuid": {
2860 "type": "string",
2861 "description": "The UUID of the authentication configuration (for backward compatibility)",
2862 "deprecated": true
2863 },
2864 "type": {
2865 "type": "string",
2866 "enum": [
2867 "default",
2868 "custom"
2869 ],
2870 "description": "The type of the authentication configuration (custom or default)"
2871 },
2872 "toolkit": {
2873 "type": "object",
2874 "properties": {
2875 "slug": {
2876 "type": "string",
2877 "description": "The unique identifier of the integration app"
2878 },
2879 "logo": {
2880 "type": "string",
2881 "description": "The URL to the integration app's logo image"
2882 },
2883 "auth_guide_url": {
2884 "type": "string",
2885 "nullable": true,
2886 "description": "URL to a guide page with authentication setup instructions"
2887 },
2888 "auth_hint_url": {
2889 "type": "string",
2890 "nullable": true,
2891 "description": "URL to a page where users can obtain or configure credentials"
2892 }
2893 },
2894 "required": [
2895 "slug",
2896 "logo"
2897 ],
2898 "description": "Information about the associated integration"
2899 },
2900 "name": {
2901 "type": "string",
2902 "description": "The display name of the authentication configuration"
2903 },
2904 "auth_scheme": {
2905 "type": "string",
2906 "enum": [
2907 "OAUTH2",
2908 "OAUTH1",
2909 "API_KEY",
2910 "BASIC",
2911 "BILLCOM_AUTH",
2912 "BEARER_TOKEN",
2913 "GOOGLE_SERVICE_ACCOUNT",
2914 "NO_AUTH",
2915 "BASIC_WITH_JWT",
2916 "CALCOM_AUTH",
2917 "SERVICE_ACCOUNT",
2918 "SAML",
2919 "DCR_OAUTH",
2920 "CIMD_OAUTH",
2921 "S2S_OAUTH2"
2922 ],
2923 "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"
2924 },
2925 "is_composio_managed": {
2926 "type": "boolean",
2927 "description": "Whether this authentication configuration is managed by Composio or the user"
2928 },
2929 "managed_app_id": {
2930 "type": "string",
2931 "nullable": true,
2932 "description": "The Composio-managed app this auth config uses, as composio_managed_auth[].managed_app_id from GET /api/v3/toolkits/{toolkit_slug}. Null when the auth config is not linked to a managed app. Use is_composio_managed to tell managed from custom."
2933 },
2934 "credentials": {
2935 "type": "object",
2936 "additionalProperties": {},
2937 "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"
2938 },
2939 "proxy_config": {
2940 "type": "object",
2941 "nullable": true,
2942 "properties": {
2943 "proxy_url": {
2944 "type": "string",
2945 "format": "uri",
2946 "description": "The url of the auth proxy"
2947 },
2948 "proxy_auth_key": {
2949 "type": "string",
2950 "description": "The auth key for the auth proxy"
2951 }
2952 },
2953 "required": [
2954 "proxy_url"
2955 ]
2956 },
2957 "status": {
2958 "type": "string",
2959 "enum": [
2960 "ENABLED",
2961 "DISABLED"
2962 ],
2963 "description": "Current status of the authentication configuration"
2964 },
2965 "created_by": {
2966 "type": "string",
2967 "description": "The identifier of the user who created the auth config"
2968 },
2969 "created_at": {
2970 "type": "string",
2971 "description": "ISO 8601 date-time when the auth config was created"
2972 },
2973 "last_updated_at": {
2974 "type": "string",
2975 "description": "ISO 8601 date-time when the auth config was last updated"
2976 },
2977 "no_of_connections": {
2978 "type": "number",
2979 "description": "The number of active connections using this auth config"
2980 },
2981 "expected_input_fields": {
2982 "type": "array",
2983 "items": {
2984 "type": "object",
2985 "properties": {
2986 "name": {
2987 "type": "string"
2988 },
2989 "displayName": {
2990 "type": "string"
2991 },
2992 "default": {
2993 "type": "string",
2994 "nullable": true
2995 },
2996 "type": {
2997 "type": "string"
2998 },
2999 "description": {
3000 "type": "string"
3001 },
3002 "required": {
3003 "type": "boolean"
3004 },
3005 "is_secret": {
3006 "type": "boolean",
3007 "description": "Whether this field holds a secret/credential value. Clients use it to decide whether to mask the input."
3008 },
3009 "legacy_template_name": {
3010 "type": "string"
3011 },
3012 "user_visible": {
3013 "type": "boolean",
3014 "description": "Whether this field is shown to the end user in the hosted connect flow. Fields with `false` are never required — the field's `default` applies unless the developer supplies a value on the auth config (e.g. as a shared credential)."
3015 },
3016 "is_available_as_shared_credentials": {
3017 "type": "boolean"
3018 }
3019 },
3020 "required": [
3021 "name",
3022 "displayName",
3023 "type",
3024 "description",
3025 "required",
3026 "user_visible"
3027 ]
3028 },
3029 "description": "Fields expected during connection initialization"
3030 },
3031 "restrict_to_following_tools": {
3032 "type": "array",
3033 "items": {
3034 "type": "string"
3035 },
3036 "description": "List of tool slugs this auth config is restricted to use with. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
3037 "deprecated": true
3038 },
3039 "tool_access_config": {
3040 "type": "object",
3041 "properties": {
3042 "tools_for_connected_account_creation": {
3043 "type": "array",
3044 "items": {
3045 "type": "string"
3046 },
3047 "default": [],
3048 "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
3049 "deprecated": true
3050 },
3051 "tools_available_for_execution": {
3052 "type": "array",
3053 "items": {
3054 "type": "string"
3055 },
3056 "default": [],
3057 "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. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
3058 "deprecated": true
3059 }
3060 },
3061 "description": "DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
3062 "deprecated": true
3063 },
3064 "shared_credentials": {
3065 "type": "object",
3066 "additionalProperties": {},
3067 "description": "Shared credentials that will be inherited by all connected accounts using this auth config. DEPRECATED: use `shared_connection_fields` instead. It takes the same value and behaves the same way.",
3068 "deprecated": true
3069 },
3070 "shared_connection_fields": {
3071 "type": "object",
3072 "additionalProperties": {},
3073 "description": "Connection field values inherited by every connected account created under this auth config. Same value as shared_credentials; secret values are redacted."
3074 },
3075 "is_enabled_for_tool_router": {
3076 "type": "boolean",
3077 "description": "Whether this auth config is enabled for tool router"
3078 }
3079 },
3080 "required": [
3081 "id",
3082 "uuid",
3083 "type",
3084 "toolkit",
3085 "name",
3086 "managed_app_id",
3087 "status",
3088 "no_of_connections",
3089 "tool_access_config"
3090 ]
3091 }
3092 },
3093 "next_cursor": {
3094 "type": "string",
3095 "nullable": true
3096 },
3097 "total_pages": {
3098 "type": "number"
3099 },
3100 "current_page": {
3101 "type": "number"
3102 },
3103 "total_items": {
3104 "type": "number"
3105 }
3106 },
3107 "required": [
3108 "items",
3109 "total_pages",
3110 "current_page",
3111 "total_items"
3112 ]
3113 }
3114 }
3115 }
3116 },
3117 "400": {
3118 "description": "Bad request",
3119 "content": {
3120 "application/json": {
3121 "schema": {
3122 "$ref": "#/components/schemas/Error"
3123 }
3124 }
3125 }
3126 },
3127 "401": {
3128 "description": "Unauthorized",
3129 "content": {
3130 "application/json": {
3131 "schema": {
3132 "$ref": "#/components/schemas/Error"
3133 }
3134 }
3135 }
3136 },
3137 "404": {
3138 "description": "Not found",
3139 "content": {
3140 "application/json": {
3141 "schema": {
3142 "$ref": "#/components/schemas/Error"
3143 }
3144 }
3145 }
3146 },
3147 "500": {
3148 "description": "Internal server error",
3149 "content": {
3150 "application/json": {
3151 "schema": {
3152 "$ref": "#/components/schemas/Error"
3153 }
3154 }
3155 }
3156 }
3157 },
3158 "x-api-version": "3.0"
3159 }
3160 },
3161 "/api/v3/auth_configs/{nanoid}": {
3162 "get": {
3163 "summary": "Get single authentication configuration by ID",
3164 "description": "Retrieves detailed information about a specific authentication configuration using its unique identifier.",
3165 "tags": [
3166 "Auth Configs"
3167 ],
3168 "operationId": "getAuthConfigsByNanoid",
3169 "security": [
3170 {
3171 "ApiKeyAuth": []
3172 },
3173 {
3174 "UserApiKeyAuth": []
3175 }
3176 ],
3177 "parameters": [
3178 {
3179 "schema": {
3180 "type": "string",
3181 "format": "authConfigId",
3182 "description": "The unique identifier of the authentication configuration to retrieve"
3183 },
3184 "required": true,
3185 "description": "The unique identifier of the authentication configuration to retrieve",
3186 "name": "nanoid",
3187 "in": "path"
3188 }
3189 ],
3190 "responses": {
3191 "200": {
3192 "description": "Successfully fetched auth config",
3193 "content": {
3194 "application/json": {
3195 "schema": {
3196 "type": "object",
3197 "properties": {
3198 "id": {
3199 "type": "string",
3200 "format": "authConfigId",
3201 "description": "The unique ID of the authentication configuration"
3202 },
3203 "uuid": {
3204 "type": "string",
3205 "description": "The UUID of the authentication configuration (for backward compatibility)",
3206 "deprecated": true
3207 },
3208 "type": {
3209 "type": "string",
3210 "enum": [
3211 "default",
3212 "custom"
3213 ],
3214 "description": "The type of the authentication configuration (custom or default)"
3215 },
3216 "toolkit": {
3217 "type": "object",
3218 "properties": {
3219 "slug": {
3220 "type": "string",
3221 "description": "The unique identifier of the integration app"
3222 },
3223 "logo": {
3224 "type": "string",
3225 "description": "The URL to the integration app's logo image"
3226 },
3227 "auth_guide_url": {
3228 "type": "string",
3229 "nullable": true,
3230 "description": "URL to a guide page with authentication setup instructions"
3231 },
3232 "auth_hint_url": {
3233 "type": "string",
3234 "nullable": true,
3235 "description": "URL to a page where users can obtain or configure credentials"
3236 }
3237 },
3238 "required": [
3239 "slug",
3240 "logo"
3241 ],
3242 "description": "Information about the associated integration"
3243 },
3244 "name": {
3245 "type": "string",
3246 "description": "The display name of the authentication configuration"
3247 },
3248 "auth_scheme": {
3249 "type": "string",
3250 "enum": [
3251 "OAUTH2",
3252 "OAUTH1",
3253 "API_KEY",
3254 "BASIC",
3255 "BILLCOM_AUTH",
3256 "BEARER_TOKEN",
3257 "GOOGLE_SERVICE_ACCOUNT",
3258 "NO_AUTH",
3259 "BASIC_WITH_JWT",
3260 "CALCOM_AUTH",
3261 "SERVICE_ACCOUNT",
3262 "SAML",
3263 "DCR_OAUTH",
3264 "CIMD_OAUTH",
3265 "S2S_OAUTH2"
3266 ],
3267 "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)"
3268 },
3269 "is_composio_managed": {
3270 "type": "boolean",
3271 "description": "Whether this authentication configuration is managed by Composio or the user"
3272 },
3273 "managed_app_id": {
3274 "type": "string",
3275 "nullable": true,
3276 "description": "The Composio-managed app this auth config uses, as composio_managed_auth[].managed_app_id from GET /api/v3/toolkits/{toolkit_slug}. Null when the auth config is not linked to a managed app. Use is_composio_managed to tell managed from custom."
3277 },
3278 "credentials": {
3279 "type": "object",
3280 "additionalProperties": {},
3281 "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security"
3282 },
3283 "proxy_config": {
3284 "type": "object",
3285 "nullable": true,
3286 "properties": {
3287 "proxy_url": {
3288 "type": "string",
3289 "format": "uri",
3290 "description": "The url of the auth proxy"
3291 },
3292 "proxy_auth_key": {
3293 "type": "string",
3294 "description": "The auth key for the auth proxy"
3295 }
3296 },
3297 "required": [
3298 "proxy_url"
3299 ]
3300 },
3301 "status": {
3302 "type": "string",
3303 "enum": [
3304 "ENABLED",
3305 "DISABLED"
3306 ],
3307 "description": "Current status of the authentication configuration"
3308 },
3309 "created_by": {
3310 "type": "string",
3311 "description": "The identifier of the user who created the auth config"
3312 },
3313 "created_at": {
3314 "type": "string",
3315 "description": "ISO 8601 date-time when the auth config was created"
3316 },
3317 "last_updated_at": {
3318 "type": "string",
3319 "description": "ISO 8601 date-time when the auth config was last updated"
3320 },
3321 "no_of_connections": {
3322 "type": "number",
3323 "description": "The number of active connections using this auth config"
3324 },
3325 "expected_input_fields": {
3326 "type": "array",
3327 "items": {
3328 "type": "object",
3329 "properties": {
3330 "name": {
3331 "type": "string"
3332 },
3333 "displayName": {
3334 "type": "string"
3335 },
3336 "default": {
3337 "type": "string",
3338 "nullable": true
3339 },
3340 "type": {
3341 "type": "string"
3342 },
3343 "description": {
3344 "type": "string"
3345 },
3346 "required": {
3347 "type": "boolean"
3348 },
3349 "is_secret": {
3350 "type": "boolean",
3351 "description": "Whether this field holds a secret/credential value. Clients use it to decide whether to mask the input."
3352 },
3353 "legacy_template_name": {
3354 "type": "string"
3355 },
3356 "user_visible": {
3357 "type": "boolean",
3358 "description": "Whether this field is shown to the end user in the hosted connect flow. Fields with `false` are never required — the field's `default` applies unless the developer supplies a value on the auth config (e.g. as a shared credential)."
3359 },
3360 "is_available_as_shared_credentials": {
3361 "type": "boolean"
3362 }
3363 },
3364 "required": [
3365 "name",
3366 "displayName",
3367 "type",
3368 "description",
3369 "required",
3370 "user_visible"
3371 ]
3372 },
3373 "description": "Fields expected during connection initialization"
3374 },
3375 "restrict_to_following_tools": {
3376 "type": "array",
3377 "items": {
3378 "type": "string"
3379 },
3380 "description": "List of tool slugs this auth config is restricted to use with. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
3381 "deprecated": true
3382 },
3383 "tool_access_config": {
3384 "type": "object",
3385 "properties": {
3386 "tools_for_connected_account_creation": {
3387 "type": "array",
3388 "items": {
3389 "type": "string"
3390 },
3391 "default": [],
3392 "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
3393 "deprecated": true
3394 },
3395 "tools_available_for_execution": {
3396 "type": "array",
3397 "items": {
3398 "type": "string"
3399 },
3400 "default": [],
3401 "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. DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
3402 "deprecated": true
3403 }
3404 },
3405 "description": "DEPRECATED: use [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) to resolve the scopes for the tools you need, then pass those scopes in `credentials.scopes`.",
3406 "deprecated": true
3407 },
3408 "shared_credentials": {
3409 "type": "object",
3410 "additionalProperties": {},
3411 "description": "Shared credentials that will be inherited by all connected accounts using this auth config. DEPRECATED: use `shared_connection_fields` instead. It takes the same value and behaves the same way.",
3412 "deprecated": true
3413 },
3414 "shared_connection_fields": {
3415 "type": "object",
3416 "additionalProperties": {},
3417 "description": "Connection field values inherited by every connected account created under this auth config. Same value as shared_credentials; secret values are redacted."
3418 },
3419 "is_enabled_for_tool_router": {
3420 "type": "boolean",
3421 "description": "Whether this auth config is enabled for tool router"
3422 },
3423 "keyring_routed": {
3424 "type": "boolean",
3425 "description": "[EXPERIMENTAL] Whether the auth config is bound to a keyring encryption key, customer-hosted or Composio-operated.",
3426 "x-experimental": true
3427 }
3428 },
3429 "required": [
3430 "id",
3431 "uuid",
3432 "type",
3433 "toolkit",
3434 "name",
3435 "managed_app_id",
3436 "status",
3437 "no_of_connections",
3438 "tool_access_config",
3439 "keyring_routed"
3440 ]
3441 }
3442 }
3443 }
3444 },
3445 "400": {
3446 "description": "Bad request - Invalid auth config ID format",
3447 "content": {
3448 "application/json": {
3449 "schema": {
3450 "$ref": "#/components/schemas/Error"
3451 }
3452 }
3453 }
3454 },
3455 "401": {
3456 "description": "Unauthorized - Authentication required",
3457 "content": {
3458 "application/json": {
3459 "schema": {
3460 "$ref": "#/components/schemas/Error"
3461 }
3462 }
3463 }
3464 },
3465 "404": {
3466 "description": "Not found - Auth configuration does not exist",
3467 "content": {
3468 "application/json": {
3469 "schema": {
3470 "$ref": "#/components/schemas/Error"
3471 }
3472 }
3473 }
3474 },
3475 "500": {
3476 "description": "Internal server error - Something went wrong on the server",
3477 "content": {
3478 "application/json": {
3479 "schema": {
3480 "$ref": "#/components/schemas/Error"
3481 }
3482 }
3483 }
3484 }
3485 },
3486 "x-api-version": "3.0"
3487 },
3488 "patch": {
3489 "summary": "Update an authentication configuration",
3490 "description": "Modifies an existing authentication configuration with new credentials or other settings. Only specified fields will be updated.",
3491 "tags": [
3492 "Auth Configs"
3493 ],
3494 "operationId": "patchAuthConfigsByNanoid",
3495 "security": [
3496 {
3497 "ApiKeyAuth": []
3498 },
3499 {
3500 "UserApiKeyAuth": []
3501 }
3502 ],
3503 "parameters": [
3504 {
3505 "schema": {
3506 "type": "string",
3507 "format": "authConfigId",
3508 "description": "The unique identifier of the authentication configuration to update"
3509 },
3510 "required": true,
3511 "description": "The unique identifier of the authentication configuration to update",
3512 "name": "nanoid",
3513 "in": "path"
3514 }
3515 ],
3516 "requestBody": {
3517 "content": {
3518 "application/json": {
3519 "schema": {
3520 "oneOf": [
3521 {
3522 "$ref": "#/components/schemas/CustomAuthConfigUpdate"
3523 },
3524 {
3525 "$ref": "#/components/schemas/DefaultAuthConfigUpdate"
3526 }
3527 ],
3528 "discriminator": {
3529 "propertyName": "type",
3530 "mapping": {
3531 "custom": "#/components/schemas/CustomAuthConfigUpdate",
3532 "default": "#/components/schemas/DefaultAuthConfigUpdate"
3533 }
3534 }
3535 },
3536 "examples": {
3537 "standardUpdate": {
3538 "summary": "Standard credential update",
3539 "value": {
3540 "auth_config": {
3541 "credentials": {
3542 "api_key": "YOUR_NEW_API_KEY",
3543 "client_secret": "YOUR_NEW_CLIENT_SECRET"
3544 }
3545 }
3546 }
3547 }
3548 }
3549 }
3550 }
3551 },
3552 "responses": {
3553 "200": {
3554 "description": "Successfully updated auth config",
3555 "content": {
3556 "application/json": {
3557 "schema": {
3558 "type": "object",
3559 "properties": {
3560 "success": {
3561 "type": "boolean",
3562 "description": "Whether the auth config was updated"
3563 },
3564 "message": {
3565 "type": "string",
3566 "description": "A human-readable result message"
3567 }
3568 },
3569 "required": [
3570 "success",
3571 "message"
3572 ]
3573 }
3574 }
3575 }
3576 },
3577 "400": {
3578 "description": "Bad request - Invalid input or credentials format",
3579 "content": {
3580 "application/json": {
3581 "schema": {
3582 "$ref": "#/components/schemas/Error"
3583 }
3584 }
3585 }
3586 },
3587 "401": {
3588 "description": "Unauthorized - Authentication required",
3589 "content": {
3590 "application/json": {
3591 "schema": {
3592 "$ref": "#/components/schemas/Error"
3593 }
3594 }
3595 }
3596 },
3597 "403": {
3598 "description": "Forbidden - Your role does not allow modifying auth configs",
3599 "content": {
3600 "application/json": {
3601 "schema": {
3602 "$ref": "#/components/schemas/Error"
3603 }
3604 }
3605 }
3606 },
3607 "404": {
3608 "description": "Not found - Auth configuration does not exist",
3609 "content": {
3610 "application/json": {
3611 "schema": {
3612 "$ref": "#/components/schemas/Error"
3613 }
3614 }
3615 }
3616 },
3617 "500": {
3618 "description": "Internal server error - Something went wrong on the server",
3619 "content": {
3620 "application/json": {
3621 "schema": {
3622 "$ref": "#/components/schemas/Error"
3623 }
3624 }
3625 }
3626 }
3627 },
3628 "x-api-version": "3.0"
3629 },
3630 "delete": {
3631 "summary": "Delete an authentication configuration",
3632 "description": "Deletes an authentication configuration. This operation cannot be undone. Pass `?revoke_on_delete=true` to also revoke the upstream credentials of every connection using this auth config.",
3633 "tags": [
3634 "Auth Configs"
3635 ],
3636 "operationId": "deleteAuthConfigsByNanoid",
3637 "security": [
3638 {
3639 "ApiKeyAuth": []
3640 },
3641 {
3642 "UserApiKeyAuth": []
3643 }
3644 ],
3645 "parameters": [
3646 {
3647 "schema": {
3648 "type": "string",
3649 "format": "authConfigId",
3650 "description": "The unique identifier of the authentication configuration to delete"
3651 },
3652 "required": true,
3653 "description": "The unique identifier of the authentication configuration to delete",
3654 "name": "nanoid",
3655 "in": "path"
3656 },
3657 {
3658 "schema": {
3659 "type": "boolean",
3660 "nullable": true,
3661 "default": false,
3662 "description": "When `true`, the delete also starts a background job that revokes the upstream credentials of every connected account in scope, and the response carries a `revoke_job_id`. Defaults to `false`. Revocation is irreversible — recovering a deleted entity does not restore working credentials."
3663 },
3664 "required": false,
3665 "description": "When `true`, the delete also starts a background job that revokes the upstream credentials of every connected account in scope, and the response carries a `revoke_job_id`. Defaults to `false`. Revocation is irreversible — recovering a deleted entity does not restore working credentials.",
3666 "name": "revoke_on_delete",
3667 "in": "query"
3668 }
3669 ],
3670 "responses": {
3671 "200": {
3672 "description": "Successfully deleted auth config",
3673 "content": {
3674 "application/json": {
3675 "schema": {
3676 "type": "object",
3677 "properties": {
3678 "success": {
3679 "type": "boolean",
3680 "description": "Whether the auth config was deleted"
3681 },
3682 "message": {
3683 "type": "string",
3684 "description": "A human-readable result message"
3685 },
3686 "revoke_job_id": {
3687 "type": "string",
3688 "description": "Identifier of the background revoke job started for this delete. Present only when `revoke_on_delete=true`. Track the job and its per-connection results from the Composio dashboard — a programmatic endpoint to poll this job is not yet generally available.",
3689 "example": "pj_1a2b3c4d5e6f"
3690 }
3691 },
3692 "required": [
3693 "success",
3694 "message"
3695 ]
3696 }
3697 }
3698 }
3699 },
3700 "400": {
3701 "description": "Bad request - Invalid auth config ID format",
3702 "content": {
3703 "application/json": {
3704 "schema": {
3705 "$ref": "#/components/schemas/Error"
3706 }
3707 }
3708 }
3709 },
3710 "401": {
3711 "description": "Unauthorized - Authentication required",
3712 "content": {
3713 "application/json": {
3714 "schema": {
3715 "$ref": "#/components/schemas/Error"
3716 }
3717 }
3718 }
3719 },
3720 "403": {
3721 "description": "Forbidden - Your role does not allow modifying auth configs",
3722 "content": {
3723 "application/json": {
3724 "schema": {
3725 "$ref": "#/components/schemas/Error"
3726 }
3727 }
3728 }
3729 },
3730 "404": {
3731 "description": "Auth config not found - The specified configuration does not exist or was already deleted",
3732 "content": {
3733 "application/json": {
3734 "schema": {
3735 "$ref": "#/components/schemas/Error"
3736 }
3737 }
3738 }
3739 },
3740 "500": {
3741 "description": "Internal server error - Something went wrong on the server",
3742 "content": {
3743 "application/json": {
3744 "schema": {
3745 "$ref": "#/components/schemas/Error"
3746 }
3747 }
3748 }
3749 }
3750 },
3751 "x-api-version": "3.0"
3752 }
3753 },
3754 "/api/v3/auth_configs/{nanoid}/{status}": {
3755 "patch": {
3756 "summary": "Enable or disable an authentication configuration (DEPRECATED)",
3757 "description": "DEPRECATED: We are controlling the API surface and the dependencies between endpoints, and enabling or disabling an auth config is covered by existing endpoints. To stop new connections through an auth config, stop creating connected accounts with it; to remove it, delete it with `DELETE /api/v3/auth_configs/{nanoid}` (pass `?revoke_on_delete=true` to also revoke the upstream credentials of its connections). This endpoint still works for existing integrations but may be removed in a future release. It sets the auth config to ENABLED or DISABLED; disabled auth configs cannot be used for new connections.",
3758 "deprecated": true,
3759 "tags": [
3760 "Auth Configs"
3761 ],
3762 "operationId": "patchAuthConfigsByNanoidByStatus",
3763 "security": [
3764 {
3765 "ApiKeyAuth": []
3766 }
3767 ],
3768 "parameters": [
3769 {
3770 "schema": {
3771 "type": "string",
3772 "format": "authConfigId",
3773 "description": "The unique identifier of the authentication configuration to update"
3774 },
3775 "required": true,
3776 "description": "The unique identifier of the authentication configuration to update",
3777 "name": "nanoid",
3778 "in": "path"
3779 },
3780 {
3781 "schema": {
3782 "type": "string",
3783 "enum": [
3784 "ENABLED",
3785 "DISABLED"
3786 ],
3787 "description": "The new status to set for the auth configuration"
3788 },
3789 "required": true,
3790 "description": "The new status to set for the auth configuration",
3791 "name": "status",
3792 "in": "path"
3793 }
3794 ],
3795 "responses": {
3796 "200": {
3797 "description": "Successfully updated auth config status",
3798 "content": {
3799 "application/json": {
3800 "schema": {
3801 "type": "object",
3802 "properties": {
3803 "success": {
3804 "type": "boolean",
3805 "description": "Whether the status update succeeded"
3806 },
3807 "message": {
3808 "type": "string",
3809 "description": "A human-readable result message"
3810 }
3811 },
3812 "required": [
3813 "success",
3814 "message"
3815 ]
3816 }
3817 }
3818 }
3819 },
3820 "400": {
3821 "description": "Bad request - Invalid auth config ID or status value",
3822 "content": {
3823 "application/json": {
3824 "schema": {
3825 "$ref": "#/components/schemas/Error"
3826 }
3827 }
3828 }
3829 },
3830 "401": {
3831 "description": "Unauthorized - Authentication required",
3832 "content": {
3833 "application/json": {
3834 "schema": {
3835 "$ref": "#/components/schemas/Error"
3836 }
3837 }
3838 }
3839 },
3840 "403": {
3841 "description": "Forbidden - Your role does not allow modifying auth configs",
3842 "content": {
3843 "application/json": {
3844 "schema": {
3845 "$ref": "#/components/schemas/Error"
3846 }
3847 }
3848 }
3849 },
3850 "404": {
3851 "description": "Not found - Auth configuration does not exist",
3852 "content": {
3853 "application/json": {
3854 "schema": {
3855 "$ref": "#/components/schemas/Error"
3856 }
3857 }
3858 }
3859 },
3860 "500": {
3861 "description": "Internal server error - Something went wrong on the server",
3862 "content": {
3863 "application/json": {
3864 "schema": {
3865 "$ref": "#/components/schemas/Error"
3866 }
3867 }
3868 }
3869 }
3870 },
3871 "x-api-version": "3.0"
3872 }
3873 },
3874 "/api/v3/connected_accounts": {
3875 "get": {
3876 "summary": "List connected accounts with optional filters",
3877 "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.",
3878 "tags": [
3879 "Connected Accounts"
3880 ],
3881 "operationId": "getConnectedAccounts",
3882 "security": [
3883 {
3884 "ApiKeyAuth": []
3885 },
3886 {
3887 "UserApiKeyAuth": []
3888 }
3889 ],
3890 "parameters": [
3891 {
3892 "schema": {
3893 "type": "array",
3894 "nullable": true,
3895 "items": {
3896 "type": "string"
3897 },
3898 "description": "The toolkit slugs of the connected accounts"
3899 },
3900 "required": false,
3901 "description": "The toolkit slugs of the connected accounts",
3902 "name": "toolkit_slugs",
3903 "in": "query"
3904 },
3905 {
3906 "schema": {
3907 "type": "array",
3908 "nullable": true,
3909 "items": {
3910 "type": "string",
3911 "enum": [
3912 "INITIALIZING",
3913 "INITIATED",
3914 "ACTIVE",
3915 "FAILED",
3916 "EXPIRED",
3917 "INACTIVE",
3918 "REVOKED"
3919 ]
3920 },
3921 "description": "The status of the connected account"
3922 },
3923 "required": false,
3924 "description": "The status of the connected account",
3925 "name": "statuses",
3926 "in": "query"
3927 },
3928 {
3929 "schema": {
3930 "type": "string",
3931 "nullable": true,
3932 "description": "The cursor to paginate through the connected accounts"
3933 },
3934 "required": false,
3935 "description": "The cursor to paginate through the connected accounts",
3936 "name": "cursor",
3937 "in": "query"
3938 },
3939 {
3940 "schema": {
3941 "type": "number",
3942 "nullable": true,
3943 "description": "The limit of the connected accounts to return"
3944 },
3945 "required": false,
3946 "description": "The limit of the connected accounts to return",
3947 "name": "limit",
3948 "in": "query"
3949 },
3950 {
3951 "schema": {
3952 "type": "array",
3953 "nullable": true,
3954 "items": {
3955 "type": "string"
3956 },
3957 "description": "The user ids of the connected accounts"
3958 },
3959 "required": false,
3960 "description": "The user ids of the connected accounts",
3961 "name": "user_ids",
3962 "in": "query"
3963 },
3964 {
3965 "schema": {
3966 "type": "array",
3967 "nullable": true,
3968 "items": {
3969 "type": "string",
3970 "format": "authConfigId"
3971 },
3972 "description": "The auth config ids of the connected accounts"
3973 },
3974 "required": false,
3975 "description": "The auth config ids of the connected accounts",
3976 "name": "auth_config_ids",
3977 "in": "query"
3978 },
3979 {
3980 "schema": {
3981 "type": "array",
3982 "nullable": true,
3983 "items": {
3984 "type": "string",
3985 "format": "connectedAccountId"
3986 },
3987 "description": "The connected account ids to filter by"
3988 },
3989 "required": false,
3990 "description": "The connected account ids to filter by",
3991 "name": "connected_account_ids",
3992 "in": "query"
3993 },
3994 {
3995 "schema": {
3996 "type": "string",
3997 "enum": [
3998 "created_at",
3999 "updated_at"
4000 ],
4001 "default": "created_at",
4002 "description": "The order by of the connected accounts"
4003 },
4004 "required": false,
4005 "description": "The order by of the connected accounts",
4006 "name": "order_by",
4007 "in": "query"
4008 },
4009 {
4010 "schema": {
4011 "type": "string",
4012 "enum": [
4013 "asc",
4014 "desc"
4015 ],
4016 "default": "desc",
4017 "description": "The order direction of the connected accounts"
4018 },
4019 "required": false,
4020 "description": "The order direction of the connected accounts",
4021 "name": "order_direction",
4022 "in": "query"
4023 },
4024 {
4025 "schema": {
4026 "type": "string",
4027 "enum": [
4028 "PRIVATE",
4029 "SHARED",
4030 "ALL"
4031 ],
4032 "description": "[Experimental] Filter by sharing model. Default (omitted) returns PRIVATE only — shared accounts must be requested explicitly. Pass SHARED for only shared accounts, or ALL for PRIVATE + SHARED.",
4033 "x-experimental": true
4034 },
4035 "required": false,
4036 "description": "[Experimental] Filter by sharing model. Default (omitted) returns PRIVATE only — shared accounts must be requested explicitly. Pass SHARED for only shared accounts, or ALL for PRIVATE + SHARED.",
4037 "name": "account_type",
4038 "in": "query"
4039 }
4040 ],
4041 "responses": {
4042 "200": {
4043 "description": "Successfully retrieved connected accounts",
4044 "content": {
4045 "application/json": {
4046 "schema": {
4047 "type": "object",
4048 "properties": {
4049 "items": {
4050 "type": "array",
4051 "items": {
4052 "type": "object",
4053 "properties": {
4054 "toolkit": {
4055 "type": "object",
4056 "properties": {
4057 "slug": {
4058 "type": "string",
4059 "description": "The slug of the toolkit"
4060 }
4061 },
4062 "required": [
4063 "slug"
4064 ]
4065 },
4066 "auth_config": {
4067 "type": "object",
4068 "properties": {
4069 "id": {
4070 "type": "string",
4071 "format": "authConfigId",
4072 "description": "The id of the auth config"
4073 },
4074 "auth_scheme": {
4075 "type": "string",
4076 "enum": [
4077 "OAUTH2",
4078 "OAUTH1",
4079 "API_KEY",
4080 "BASIC",
4081 "BILLCOM_AUTH",
4082 "BEARER_TOKEN",
4083 "GOOGLE_SERVICE_ACCOUNT",
4084 "NO_AUTH",
4085 "BASIC_WITH_JWT",
4086 "CALCOM_AUTH",
4087 "SERVICE_ACCOUNT",
4088 "SAML",
4089 "DCR_OAUTH",
4090 "CIMD_OAUTH",
4091 "S2S_OAUTH2"
4092 ],
4093 "description": "the authScheme is part of the connection state use it there",
4094 "deprecated": true
4095 },
4096 "is_composio_managed": {
4097 "type": "boolean",
4098 "description": "Whether the auth config is managed by Composio"
4099 },
4100 "is_disabled": {
4101 "type": "boolean",
4102 "description": "Whether the auth config is disabled"
4103 }
4104 },
4105 "required": [
4106 "id",
4107 "auth_scheme",
4108 "is_composio_managed",
4109 "is_disabled"
4110 ]
4111 },
4112 "id": {
4113 "type": "string",
4114 "format": "connectedAccountId",
4115 "description": "The id of the connection"
4116 },
4117 "authScheme": {
4118 "type": "string",
4119 "enum": [
4120 "OAUTH2",
4121 "OAUTH1",
4122 "API_KEY",
4123 "BASIC",
4124 "BILLCOM_AUTH",
4125 "BEARER_TOKEN",
4126 "GOOGLE_SERVICE_ACCOUNT",
4127 "NO_AUTH",
4128 "BASIC_WITH_JWT",
4129 "CALCOM_AUTH",
4130 "SERVICE_ACCOUNT",
4131 "SAML",
4132 "DCR_OAUTH",
4133 "CIMD_OAUTH",
4134 "S2S_OAUTH2"
4135 ],
4136 "description": "Duplicates state.authScheme. Kept for backward compatibility with existing readers; use state.authScheme instead.",
4137 "deprecated": true
4138 },
4139 "word_id": {
4140 "type": "string",
4141 "nullable": true,
4142 "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")"
4143 },
4144 "alias": {
4145 "type": "string",
4146 "nullable": true,
4147 "description": "A user-defined alias for the connected account"
4148 },
4149 "user_id": {
4150 "type": "string",
4151 "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",
4152 "deprecated": true
4153 },
4154 "status": {
4155 "type": "string",
4156 "enum": [
4157 "INITIALIZING",
4158 "INITIATED",
4159 "ACTIVE",
4160 "FAILED",
4161 "EXPIRED",
4162 "INACTIVE",
4163 "REVOKED"
4164 ],
4165 "description": "The status of the connection"
4166 },
4167 "experimental": {
4168 "type": "object",
4169 "properties": {
4170 "account_type": {
4171 "type": "string",
4172 "enum": [
4173 "PRIVATE",
4174 "SHARED"
4175 ],
4176 "description": "Sharing model for this connected account. PRIVATE is usable only by the owning user_id. SHARED is reachable from a tool-router session only when explicitly pinned in the session config.",
4177 "x-experimental": true
4178 },
4179 "acl_config_for_shared": {
4180 "type": "object",
4181 "properties": {
4182 "allow_all_users": {
4183 "type": "boolean"
4184 },
4185 "allowed_user_ids": {
4186 "type": "array",
4187 "items": {
4188 "type": "string"
4189 }
4190 },
4191 "not_allowed_user_ids": {
4192 "type": "array",
4193 "items": {
4194 "type": "string"
4195 }
4196 }
4197 },
4198 "required": [
4199 "allow_all_users",
4200 "allowed_user_ids",
4201 "not_allowed_user_ids"
4202 ],
4203 "description": "Access control for SHARED connections. Visible only to the connection creator and project/org API key callers; non-creator cookie callers receive the response without this block.",
4204 "x-experimental": true
4205 }
4206 },
4207 "required": [
4208 "account_type"
4209 ],
4210 "description": "Experimental features - not stable, may be modified or removed in future versions.",
4211 "x-experimental": true
4212 },
4213 "created_at": {
4214 "type": "string",
4215 "description": "The created at of the connection"
4216 },
4217 "updated_at": {
4218 "type": "string",
4219 "description": "The updated at of the connection"
4220 },
4221 "state": {
4222 "description": "The state of the connection",
4223 "type": "object",
4224 "properties": {
4225 "authScheme": {
4226 "type": "string",
4227 "enum": [
4228 "OAUTH1",
4229 "OAUTH2",
4230 "API_KEY",
4231 "BASIC",
4232 "BEARER_TOKEN",
4233 "GOOGLE_SERVICE_ACCOUNT",
4234 "NO_AUTH",
4235 "CALCOM_AUTH",
4236 "BILLCOM_AUTH",
4237 "BASIC_WITH_JWT",
4238 "SERVICE_ACCOUNT",
4239 "SAML",
4240 "DCR_OAUTH",
4241 "CIMD_OAUTH",
4242 "S2S_OAUTH2"
4243 ]
4244 },
4245 "val": {
4246 "type": "object",
4247 "properties": {
4248 "subdomain": {
4249 "type": "string"
4250 },
4251 "your-domain": {
4252 "type": "string"
4253 },
4254 "region": {
4255 "type": "string"
4256 },
4257 "shop": {
4258 "type": "string"
4259 },
4260 "account_url": {
4261 "type": "string"
4262 },
4263 "COMPANYDOMAIN": {
4264 "type": "string"
4265 },
4266 "extension": {
4267 "type": "string"
4268 },
4269 "form_api_base_url": {
4270 "type": "string"
4271 },
4272 "instanceEndpoint": {
4273 "type": "string"
4274 },
4275 "api_url": {
4276 "type": "string"
4277 },
4278 "borneo_dashboard_url": {
4279 "type": "string"
4280 },
4281 "proxy_username": {
4282 "type": "string"
4283 },
4284 "proxy_password": {
4285 "type": "string"
4286 },
4287 "domain": {
4288 "type": "string"
4289 },
4290 "version": {
4291 "type": "string"
4292 },
4293 "dc": {
4294 "type": "string"
4295 },
4296 "site_name": {
4297 "type": "string"
4298 },
4299 "instanceName": {
4300 "type": "string"
4301 },
4302 "account_id": {
4303 "type": "string"
4304 },
4305 "your_server": {
4306 "type": "string"
4307 },
4308 "server_location": {
4309 "type": "string"
4310 },
4311 "base_url": {
4312 "type": "string"
4313 },
4314 "displayName": {
4315 "type": "string"
4316 },
4317 "status": {
4318 "type": "string",
4319 "enum": [
4320 "INITIALIZING",
4321 "INITIATED",
4322 "ACTIVE",
4323 "FAILED",
4324 "EXPIRED",
4325 "INACTIVE"
4326 ]
4327 },
4328 "oauth_token": {
4329 "type": "string"
4330 },
4331 "authUri": {
4332 "type": "string"
4333 },
4334 "oauth_token_secret": {
4335 "type": "string"
4336 },
4337 "redirectUrl": {
4338 "type": "string"
4339 },
4340 "callbackUrl": {
4341 "type": "string"
4342 },
4343 "oauth_verifier": {
4344 "type": "string"
4345 },
4346 "consumer_key": {
4347 "type": "string"
4348 },
4349 "callback_url": {
4350 "type": "string"
4351 },
4352 "error": {
4353 "type": "string"
4354 },
4355 "error_description": {
4356 "type": "string"
4357 },
4358 "expired_at": {
4359 "type": "string"
4360 }
4361 },
4362 "additionalProperties": true,
4363 "required": [
4364 "status"
4365 ]
4366 }
4367 },
4368 "additionalProperties": true,
4369 "required": [
4370 "authScheme",
4371 "val"
4372 ]
4373 },
4374 "data": {
4375 "type": "object",
4376 "additionalProperties": {},
4377 "description": "This is deprecated, use `state` instead",
4378 "deprecated": true
4379 },
4380 "status_reason": {
4381 "type": "string",
4382 "nullable": true,
4383 "description": "The reason the connection status changed."
4384 },
4385 "is_disabled": {
4386 "type": "boolean",
4387 "description": "Whether the connection is disabled"
4388 },
4389 "test_request_endpoint": {
4390 "type": "string",
4391 "description": "The endpoint to make test request for verification"
4392 }
4393 },
4394 "required": [
4395 "toolkit",
4396 "auth_config",
4397 "id",
4398 "word_id",
4399 "alias",
4400 "user_id",
4401 "status",
4402 "created_at",
4403 "updated_at",
4404 "state",
4405 "data",
4406 "status_reason",
4407 "is_disabled"
4408 ]
4409 }
4410 },
4411 "next_cursor": {
4412 "type": "string",
4413 "nullable": true
4414 },
4415 "total_pages": {
4416 "type": "number"
4417 },
4418 "current_page": {
4419 "type": "number"
4420 },
4421 "total_items": {
4422 "type": "number"
4423 }
4424 },
4425 "required": [
4426 "items",
4427 "total_pages",
4428 "current_page",
4429 "total_items"
4430 ]
4431 }
4432 }
4433 }
4434 },
4435 "400": {
4436 "description": "Bad request",
4437 "content": {
4438 "application/json": {
4439 "schema": {
4440 "$ref": "#/components/schemas/Error"
4441 }
4442 }
4443 }
4444 },
4445 "401": {
4446 "description": "Unauthorized",
4447 "content": {
4448 "application/json": {
4449 "schema": {
4450 "$ref": "#/components/schemas/Error"
4451 }
4452 }
4453 }
4454 },
4455 "404": {
4456 "description": "Not found",
4457 "content": {
4458 "application/json": {
4459 "schema": {
4460 "$ref": "#/components/schemas/Error"
4461 }
4462 }
4463 }
4464 },
4465 "422": {
4466 "description": "Unprocessable entity",
4467 "content": {
4468 "application/json": {
4469 "schema": {
4470 "$ref": "#/components/schemas/Error"
4471 }
4472 }
4473 }
4474 },
4475 "500": {
4476 "description": "Internal server error",
4477 "content": {
4478 "application/json": {
4479 "schema": {
4480 "$ref": "#/components/schemas/Error"
4481 }
4482 }
4483 }
4484 }
4485 },
4486 "x-api-version": "3.0"
4487 },
4488 "post": {
4489 "summary": "Create a new connected account",
4490 "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.\n\n**Deprecated for Composio-managed OAuth:** For Composio-managed auth configs on OAuth1, OAuth2, or DCR_OAUTH schemes, this endpoint is being retired and will start returning `400 BadRequest` on **2026-05-08** for new organizations and **2026-07-03** for all remaining organizations. Migrate those calls to `POST /api/v3/connected_accounts/link`. Custom auth configs and non-OAuth schemes (API key, bearer, basic) continue to be supported here. Responses on the retiring path carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) for client-side detection.\n\n**Credential check:** where the toolkit supports it, submitted API key, basic, and bearer credentials are checked against the provider before the connection is stored — no opt-in required. For toolkits with the check enabled, credentials the provider rejects fail the request with `ConnectedAccount_CredentialValidationRejected`. If the provider is unreachable, times out, or returns an error of its own, the connection is created as normal.",
4491 "tags": [
4492 "Connected Accounts"
4493 ],
4494 "operationId": "postConnectedAccounts",
4495 "security": [
4496 {
4497 "ApiKeyAuth": []
4498 }
4499 ],
4500 "requestBody": {
4501 "required": true,
4502 "content": {
4503 "application/json": {
4504 "schema": {
4505 "type": "object",
4506 "properties": {
4507 "auth_config": {
4508 "type": "object",
4509 "properties": {
4510 "id": {
4511 "type": "string",
4512 "format": "authConfigId",
4513 "description": "The auth config id of the app (must be a valid auth config id)"
4514 }
4515 },
4516 "required": [
4517 "id"
4518 ]
4519 },
4520 "connection": {
4521 "type": "object",
4522 "properties": {
4523 "state": {
4524 "description": "The state of the connected account",
4525 "type": "object",
4526 "properties": {
4527 "authScheme": {
4528 "type": "string",
4529 "enum": [
4530 "OAUTH1",
4531 "OAUTH2",
4532 "API_KEY",
4533 "BASIC",
4534 "BEARER_TOKEN",
4535 "GOOGLE_SERVICE_ACCOUNT",
4536 "NO_AUTH",
4537 "CALCOM_AUTH",
4538 "BILLCOM_AUTH",
4539 "BASIC_WITH_JWT",
4540 "SERVICE_ACCOUNT",
4541 "SAML",
4542 "DCR_OAUTH",
4543 "CIMD_OAUTH",
4544 "S2S_OAUTH2"
4545 ]
4546 },
4547 "val": {
4548 "type": "object",
4549 "properties": {
4550 "subdomain": {
4551 "type": "string"
4552 },
4553 "your-domain": {
4554 "type": "string"
4555 },
4556 "region": {
4557 "type": "string"
4558 },
4559 "shop": {
4560 "type": "string"
4561 },
4562 "account_url": {
4563 "type": "string"
4564 },
4565 "COMPANYDOMAIN": {
4566 "type": "string"
4567 },
4568 "extension": {
4569 "type": "string"
4570 },
4571 "form_api_base_url": {
4572 "type": "string"
4573 },
4574 "instanceEndpoint": {
4575 "type": "string"
4576 },
4577 "api_url": {
4578 "type": "string"
4579 },
4580 "borneo_dashboard_url": {
4581 "type": "string"
4582 },
4583 "proxy_username": {
4584 "type": "string"
4585 },
4586 "proxy_password": {
4587 "type": "string"
4588 },
4589 "domain": {
4590 "type": "string"
4591 },
4592 "version": {
4593 "type": "string"
4594 },
4595 "dc": {
4596 "type": "string"
4597 },
4598 "site_name": {
4599 "type": "string"
4600 },
4601 "instanceName": {
4602 "type": "string"
4603 },
4604 "account_id": {
4605 "type": "string"
4606 },
4607 "your_server": {
4608 "type": "string"
4609 },
4610 "server_location": {
4611 "type": "string"
4612 },
4613 "base_url": {
4614 "type": "string"
4615 },
4616 "displayName": {
4617 "type": "string"
4618 },
4619 "status": {
4620 "type": "string",
4621 "enum": [
4622 "INITIALIZING",
4623 "INITIATED",
4624 "ACTIVE",
4625 "FAILED",
4626 "EXPIRED",
4627 "INACTIVE"
4628 ]
4629 },
4630 "oauth_token": {
4631 "type": "string"
4632 },
4633 "authUri": {
4634 "type": "string"
4635 },
4636 "oauth_token_secret": {
4637 "type": "string"
4638 },
4639 "redirectUrl": {
4640 "type": "string"
4641 },
4642 "callbackUrl": {
4643 "type": "string"
4644 },
4645 "oauth_verifier": {
4646 "type": "string"
4647 },
4648 "consumer_key": {
4649 "type": "string"
4650 },
4651 "callback_url": {
4652 "type": "string"
4653 },
4654 "error": {
4655 "type": "string"
4656 },
4657 "error_description": {
4658 "type": "string"
4659 },
4660 "expired_at": {
4661 "type": "string"
4662 }
4663 },
4664 "additionalProperties": true,
4665 "required": [
4666 "status"
4667 ]
4668 }
4669 },
4670 "additionalProperties": true,
4671 "required": [
4672 "authScheme",
4673 "val"
4674 ]
4675 },
4676 "data": {
4677 "type": "object",
4678 "additionalProperties": {},
4679 "description": "DEPRECATED: This parameter will be removed in a future version. Please use state instead.",
4680 "deprecated": true
4681 },
4682 "user_id": {
4683 "type": "string",
4684 "default": "default",
4685 "description": "The user id of the connected account"
4686 },
4687 "alias": {
4688 "type": "string",
4689 "maxLength": 255,
4690 "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project."
4691 },
4692 "callback_url": {
4693 "type": "string",
4694 "format": "uri",
4695 "description": "The URL to redirect to after connection completion"
4696 },
4697 "redirect_uri": {
4698 "type": "string",
4699 "format": "uri",
4700 "description": "DEPRECATED: This parameter will be removed in a future version. Please use callback_url instead.",
4701 "deprecated": true
4702 },
4703 "deprecated_is_v1_rerouted": {
4704 "type": "boolean",
4705 "default": false,
4706 "description": "DEPRECATED: This parameter will be removed in a future version.",
4707 "deprecated": true
4708 },
4709 "experimental": {
4710 "type": "object",
4711 "properties": {
4712 "account_type": {
4713 "type": "string",
4714 "enum": [
4715 "PRIVATE",
4716 "SHARED"
4717 ],
4718 "description": "Sharing model for this connected account. PRIVATE (default) is usable only by the owning user_id. SHARED is reachable from a tool-router session ONLY when explicitly pinned in the session config — at most one SHARED connection per toolkit per session. Sessions never use a SHARED connection implicitly. Every use of a SHARED connection must pass the acting user_id, which is checked against its ACL.",
4719 "x-experimental": true
4720 },
4721 "acl_config_for_shared": {
4722 "type": "object",
4723 "properties": {
4724 "allow_all_users": {
4725 "type": "boolean",
4726 "description": "Wildcard \"any user_id in the project\" allow toggle. Only valid on SHARED connections."
4727 },
4728 "allowed_user_ids": {
4729 "type": "array",
4730 "items": {
4731 "type": "string",
4732 "minLength": 1,
4733 "maxLength": 256
4734 },
4735 "maxItems": 1000,
4736 "description": "Explicit allow list of user_ids who can use this SHARED connection."
4737 },
4738 "not_allowed_user_ids": {
4739 "type": "array",
4740 "items": {
4741 "type": "string",
4742 "minLength": 1,
4743 "maxLength": 256
4744 },
4745 "maxItems": 1000,
4746 "description": "Explicit deny list. Wins on conflict with allow_all_users and allowed_user_ids."
4747 }
4748 },
4749 "description": "Access control for SHARED connections. Resolution rule (only fires when caller != creator): user in not_allowed_user_ids → DENY; allow_all_users=true → ALLOW; user in allowed_user_ids → ALLOW; else DENY. Default state (omitted or {}) is deny-by-default — only the creator can use.",
4750 "x-experimental": true
4751 }
4752 },
4753 "description": "Experimental features - not stable, may be modified or removed in future versions.",
4754 "x-experimental": true
4755 }
4756 }
4757 }
4758 },
4759 "required": [
4760 "auth_config",
4761 "connection"
4762 ]
4763 }
4764 }
4765 }
4766 },
4767 "responses": {
4768 "201": {
4769 "description": "Successfully created connected account",
4770 "content": {
4771 "application/json": {
4772 "schema": {
4773 "type": "object",
4774 "properties": {
4775 "id": {
4776 "type": "string",
4777 "format": "connectedAccountId",
4778 "description": "The id of the connected account"
4779 },
4780 "connectionData": {
4781 "description": "The connection data of the connected account",
4782 "type": "object",
4783 "properties": {
4784 "authScheme": {
4785 "type": "string",
4786 "enum": [
4787 "OAUTH1",
4788 "OAUTH2",
4789 "API_KEY",
4790 "BASIC",
4791 "BEARER_TOKEN",
4792 "GOOGLE_SERVICE_ACCOUNT",
4793 "NO_AUTH",
4794 "CALCOM_AUTH",
4795 "BILLCOM_AUTH",
4796 "BASIC_WITH_JWT",
4797 "SERVICE_ACCOUNT",
4798 "SAML",
4799 "DCR_OAUTH",
4800 "CIMD_OAUTH",
4801 "S2S_OAUTH2"
4802 ]
4803 },
4804 "val": {
4805 "type": "object",
4806 "properties": {
4807 "subdomain": {
4808 "type": "string"
4809 },
4810 "your-domain": {
4811 "type": "string"
4812 },
4813 "region": {
4814 "type": "string"
4815 },
4816 "shop": {
4817 "type": "string"
4818 },
4819 "account_url": {
4820 "type": "string"
4821 },
4822 "COMPANYDOMAIN": {
4823 "type": "string"
4824 },
4825 "extension": {
4826 "type": "string"
4827 },
4828 "form_api_base_url": {
4829 "type": "string"
4830 },
4831 "instanceEndpoint": {
4832 "type": "string"
4833 },
4834 "api_url": {
4835 "type": "string"
4836 },
4837 "borneo_dashboard_url": {
4838 "type": "string"
4839 },
4840 "proxy_username": {
4841 "type": "string"
4842 },
4843 "proxy_password": {
4844 "type": "string"
4845 },
4846 "domain": {
4847 "type": "string"
4848 },
4849 "version": {
4850 "type": "string"
4851 },
4852 "dc": {
4853 "type": "string"
4854 },
4855 "site_name": {
4856 "type": "string"
4857 },
4858 "instanceName": {
4859 "type": "string"
4860 },
4861 "account_id": {
4862 "type": "string"
4863 },
4864 "your_server": {
4865 "type": "string"
4866 },
4867 "server_location": {
4868 "type": "string"
4869 },
4870 "base_url": {
4871 "type": "string"
4872 },
4873 "displayName": {
4874 "type": "string"
4875 },
4876 "status": {
4877 "type": "string",
4878 "enum": [
4879 "INITIALIZING",
4880 "INITIATED",
4881 "ACTIVE",
4882 "FAILED",
4883 "EXPIRED",
4884 "INACTIVE"
4885 ]
4886 },
4887 "oauth_token": {
4888 "type": "string"
4889 },
4890 "authUri": {
4891 "type": "string"
4892 },
4893 "oauth_token_secret": {
4894 "type": "string"
4895 },
4896 "redirectUrl": {
4897 "type": "string"
4898 },
4899 "callbackUrl": {
4900 "type": "string"
4901 },
4902 "oauth_verifier": {
4903 "type": "string"
4904 },
4905 "consumer_key": {
4906 "type": "string"
4907 },
4908 "callback_url": {
4909 "type": "string"
4910 },
4911 "error": {
4912 "type": "string"
4913 },
4914 "error_description": {
4915 "type": "string"
4916 },
4917 "expired_at": {
4918 "type": "string"
4919 }
4920 },
4921 "additionalProperties": true,
4922 "required": [
4923 "status"
4924 ]
4925 }
4926 },
4927 "additionalProperties": true,
4928 "required": [
4929 "authScheme",
4930 "val"
4931 ]
4932 },
4933 "status": {
4934 "type": "string",
4935 "enum": [
4936 "INITIALIZING",
4937 "INITIATED",
4938 "ACTIVE",
4939 "FAILED",
4940 "EXPIRED",
4941 "INACTIVE",
4942 "REVOKED"
4943 ],
4944 "description": "DEPRECATED: This field will be removed in a future version",
4945 "deprecated": true
4946 },
4947 "redirect_url": {
4948 "type": "string",
4949 "nullable": true,
4950 "description": "DEPRECATED: This field will be removed in a future version",
4951 "deprecated": true
4952 },
4953 "redirect_uri": {
4954 "type": "string",
4955 "nullable": true,
4956 "description": "DEPRECATED: This field will be removed in a future version",
4957 "deprecated": true
4958 },
4959 "experimental": {
4960 "type": "object",
4961 "properties": {
4962 "account_type": {
4963 "type": "string",
4964 "enum": [
4965 "PRIVATE",
4966 "SHARED"
4967 ],
4968 "description": "Sharing model for this connected account. PRIVATE is usable only by the owning user_id. SHARED is reachable from a tool-router session only when explicitly pinned in the session config.",
4969 "x-experimental": true
4970 },
4971 "acl_config_for_shared": {
4972 "type": "object",
4973 "properties": {
4974 "allow_all_users": {
4975 "type": "boolean"
4976 },
4977 "allowed_user_ids": {
4978 "type": "array",
4979 "items": {
4980 "type": "string"
4981 }
4982 },
4983 "not_allowed_user_ids": {
4984 "type": "array",
4985 "items": {
4986 "type": "string"
4987 }
4988 }
4989 },
4990 "required": [
4991 "allow_all_users",
4992 "allowed_user_ids",
4993 "not_allowed_user_ids"
4994 ],
4995 "description": "Access control for SHARED connections. Visible only to the connection creator and project/org API key callers; non-creator cookie callers receive the response without this block.",
4996 "x-experimental": true
4997 }
4998 },
4999 "required": [
5000 "account_type"
Showing first 5,000 of 26,610 lines. View raw