3369
"type": "object",
3370
"properties": {
3371
"connected_account_id": {
3372
- "type": "string",
3373
- "description": "Unique identifier for the connected account to use for authentication",
3372
+ "anyOf": [
3373
+ {
3374
+ "type": "string",
3375
+ "enum": [
3376
+ "hosted_account"
3377
+ ]
3378
+ },
3379
+ {
3380
+ "type": "string",
3381
+ "format": "connectedAccountId"
3382
+ }
3383
+ ],
3384
+ "description": "Unique identifier for the connected account to use for authentication. Pass `hosted_account` to run the tool on the Composio hosted account for its toolkit, even when the user has connected the toolkit themselves; the request fails rather than falling back to another credential.",
3385
"example": "ca_1a2b3c4d5e6f"
3386
},
3387
"entity_id": {
3820
}
3821
}
3822
},
3823
+ "402": {
3824
+ "description": "Payment required - Wallet balance is exhausted; add credits to resume premium tool calls or connect your account",
3825
+ "content": {
3826
+ "application/json": {
3827
+ "schema": {
3828
+ "$ref": "#/components/schemas/Error"
3829
+ }
3830
+ }
3831
+ }
3832
+ },
3833
"403": {
3834
"description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource",
3835
"content": {
5506
"tools"
5507
],
5508
"x-experimental": true
5509
+ },
5510
+ "examples": {
5511
+ "googlecalendar": {
5512
+ "summary": "Google Calendar: list and create events",
5513
+ "value": {
5514
+ "tools": [
5515
+ "GOOGLECALENDAR_EVENTS_LIST",
5516
+ "GOOGLECALENDAR_CREATE_EVENT"
5517
+ ]
5518
+ }
5519
+ }
5520
}
5521
}
5522
}
5611
"scopes"
5612
],
5613
"x-experimental": true
5614
+ },
5615
+ "examples": {
5616
+ "googlecalendar": {
5617
+ "summary": "Google Calendar: list and create events",
5618
+ "value": {
5619
+ "auth_scheme": "OAUTH2",
5620
+ "toolkit_version": "20260915_00",
5621
+ "grant_context": {},
5622
+ "scopes": {
5623
+ "least_privilege": [
5624
+ "https://www.googleapis.com/auth/calendar.calendars.readonly",
5625
+ "https://www.googleapis.com/auth/calendar.events"
5626
+ ],
5627
+ "fewest": [
5628
+ "https://www.googleapis.com/auth/calendar"
5629
+ ],
5630
+ "conditional": [
5631
+ {
5632
+ "scope": "https://www.googleapis.com/auth/calendar.calendars.readonly",
5633
+ "when": {
5634
+ "param.eventType": [
5635
+ "default"
5636
+ ],
5637
+ "param.exclude_organizer": [
5638
+ "falsy"
5639
+ ]
5640
+ },
5641
+ "for": [
5642
+ "GOOGLECALENDAR_CREATE_EVENT"
5643
+ ]
5644
+ }
5645
+ ]
5646
+ }
5647
+ }
5648
+ }
5649
}
5650
}
5651
}
5717
"/api/v3.1/toolkits/{toolkit_slug}/scopes/grant_context": {
5718
"get": {
5719
"summary": "List grant contexts",
5653
- "description": "Experimental: this endpoint is in beta and its contract may change.\n\nList of contexts in which you want to grant scopes to your user. Pass a dimension and its selected value in the `grant_context` field of the [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) request to tailor the scope recommendation.",
5720
+ "description": "Experimental: this endpoint is in beta and its contract may change.\n\nList of contexts in which you want to grant scopes to your user. Pass a dimension and its selected value in the `grant_context` field of the [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) request to tailor the scope recommendation.\n\nIn the Jira example, `default_grant_context` is `{\"scope_family\": \"classic\"}`, so a recommendation with no `grant_context` uses classic scopes. Pass `{\"scope_family\": \"granular\"}` to get granular scopes instead.",
5721
"tags": [
5722
"Toolkits"
5723
],
5840
"default_grant_context"
5841
],
5842
"x-experimental": true
5843
+ },
5844
+ "examples": {
5845
+ "jira": {
5846
+ "summary": "Jira: classic or granular scopes",
5847
+ "value": {
5848
+ "auth_scheme": "OAUTH2",
5849
+ "toolkit_version": "20260917_00",
5850
+ "grant_context_dimensions": [
5851
+ {
5852
+ "dimension": "scope_family",
5853
+ "description": "Which Atlassian OAuth scope catalog to draw from: classic scopes cover broad product areas, granular scopes name individual operations. Defaults to classic, matching the scopes our Jira OAuth app requests today.",
5854
+ "values": [
5855
+ "classic",
5856
+ "granular"
5857
+ ]
5858
+ }
5859
+ ],
5860
+ "default_grant_context": {
5861
+ "scope_family": "classic"
5862
+ }
5863
+ }
5864
+ }
5865
}
5866
}
5867
}
11316
],
11317
"description": "When \"required\", the agent must specify which account to use. Present only when multiple accounts exist."
11318
},
11230
- "composio_managed": {
11319
+ "hosted_account": {
11320
"type": "object",
11321
"properties": {
11322
"allowed_tool_slugs": {
11324
"items": {
11325
"type": "string"
11326
},
11238
- "description": "Tools of this toolkit that run on the Composio managed account"
11327
+ "description": "Tools of this toolkit that run on the Composio hosted account"
11328
}
11329
},
11330
"required": [
11331
"allowed_tool_slugs"
11332
],
11244
- "description": "Present when the toolkit is connected through the Composio managed account rather than a connected account of the user."
11333
+ "description": "Present when the toolkit is connected through the Composio hosted account rather than a connected account of the user."
11334
},
11335
"status_message": {
11336
"type": "string",
11510
}
11511
}
11512
},
11513
+ "402": {
11514
+ "description": "Payment required",
11515
+ "content": {
11516
+ "application/json": {
11517
+ "schema": {
11518
+ "$ref": "#/components/schemas/Error"
11519
+ }
11520
+ }
11521
+ }
11522
+ },
11523
"403": {
11524
"description": "Forbidden",
11525
"content": {
11953
"schema": {
11954
"type": "object",
11955
"properties": {
11956
+ "premium_charge": {
11957
+ "type": "object",
11958
+ "properties": {
11959
+ "amount": {
11960
+ "type": "string",
11961
+ "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
11962
+ "description": "Premium charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
11963
+ },
11964
+ "currency": {
11965
+ "type": "string",
11966
+ "enum": [
11967
+ "USD"
11968
+ ],
11969
+ "description": "Currency of the premium charge. Always USD."
11970
+ },
11971
+ "charged_by": {
11972
+ "type": "string",
11973
+ "enum": [
11974
+ "composio"
11975
+ ],
11976
+ "description": "Entity charging for premium usage. Always composio."
11977
+ }
11978
+ },
11979
+ "required": [
11980
+ "amount",
11981
+ "currency",
11982
+ "charged_by"
11983
+ ],
11984
+ "description": "Returned only when the session enables premium_usage.return_premium_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."
11985
+ },
11986
"data": {
11987
"type": "object",
11988
"additionalProperties": {},
12032
}
12033
}
12034
},
12035
+ "402": {
12036
+ "description": "Payment required",
12037
+ "content": {
12038
+ "application/json": {
12039
+ "schema": {
12040
+ "$ref": "#/components/schemas/Error"
12041
+ }
12042
+ }
12043
+ }
12044
+ },
12045
"403": {
12046
"description": "Forbidden",
12047
"content": {
12368
"schema": {
12369
"type": "object",
12370
"properties": {
12371
+ "premium_charge": {
12372
+ "type": "object",
12373
+ "properties": {
12374
+ "amount": {
12375
+ "type": "string",
12376
+ "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
12377
+ "description": "Premium charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
12378
+ },
12379
+ "currency": {
12380
+ "type": "string",
12381
+ "enum": [
12382
+ "USD"
12383
+ ],
12384
+ "description": "Currency of the premium charge. Always USD."
12385
+ },
12386
+ "charged_by": {
12387
+ "type": "string",
12388
+ "enum": [
12389
+ "composio"
12390
+ ],
12391
+ "description": "Entity charging for premium usage. Always composio."
12392
+ }
12393
+ },
12394
+ "required": [
12395
+ "amount",
12396
+ "currency",
12397
+ "charged_by"
12398
+ ],
12399
+ "description": "Returned only when the session enables premium_usage.return_premium_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."
12400
+ },
12401
"data": {
12402
"type": "object",
12403
"additionalProperties": {},
12447
}
12448
}
12449
},
12450
+ "402": {
12451
+ "description": "Payment required",
12452
+ "content": {
12453
+ "application/json": {
12454
+ "schema": {
12455
+ "$ref": "#/components/schemas/Error"
12456
+ }
12457
+ }
12458
+ }
12459
+ },
12460
"403": {
12461
"description": "Forbidden",
12462
"content": {
12624
"event_count": {
12625
"type": "integer",
12626
"minimum": 0
12627
+ },
12628
+ "premium_usage_charge": {
12629
+ "type": "string",
12630
+ "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12631
}
12632
},
12633
"required": [
12634
"unit",
12635
"total_quantity",
12453
- "event_count"
12636
+ "event_count",
12637
+ "premium_usage_charge"
12638
]
12639
}
12640
}
12824
"type": "integer",
12825
"minimum": 0
12826
},
12827
+ "premium_usage_charge": {
12828
+ "type": "string",
12829
+ "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12830
+ },
12831
"groups": {
12832
"type": "array",
12833
"items": {
12842
"event_count": {
12843
"type": "integer",
12844
"minimum": 0
12845
+ },
12846
+ "premium_usage_charge": {
12847
+ "type": "string",
12848
+ "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12849
}
12850
},
12851
"required": [
12852
"key",
12853
"total_quantity",
12662
- "event_count"
12854
+ "event_count",
12855
+ "premium_usage_charge"
12856
]
12857
}
12858
}
12862
"unit",
12863
"total_quantity",
12864
"event_count",
12865
+ "premium_usage_charge",
12866
"groups"
12867
]
12868
}
13007
"event_count": {
13008
"type": "integer",
13009
"minimum": 0
13010
+ },
13011
+ "premium_usage_charge": {
13012
+ "type": "string",
13013
+ "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13014
}
13015
},
13016
"required": [
13017
"unit",
13018
"total_quantity",
12821
- "event_count"
13019
+ "event_count",
13020
+ "premium_usage_charge"
13021
]
13022
}
13023
}
13198
"type": "integer",
13199
"minimum": 0
13200
},
13201
+ "premium_usage_charge": {
13202
+ "type": "string",
13203
+ "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13204
+ },
13205
"groups": {
13206
"type": "array",
13207
"items": {
13216
"event_count": {
13217
"type": "integer",
13218
"minimum": 0
13219
+ },
13220
+ "premium_usage_charge": {
13221
+ "type": "string",
13222
+ "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13223
}
13224
},
13225
"required": [
13226
"key",
13227
"total_quantity",
13021
- "event_count"
13228
+ "event_count",
13229
+ "premium_usage_charge"
13230
]
13231
}
13232
}
13236
"unit",
13237
"total_quantity",
13238
"event_count",
13239
+ "premium_usage_charge",
13240
"groups"
13241
]
13242
}
27673
}
27674
}
27675
},
27676
+ "402": {
27677
+ "description": "Payment required",
27678
+ "content": {
27679
+ "application/json": {
27680
+ "schema": {
27681
+ "$ref": "#/components/schemas/Error"
27682
+ }
27683
+ }
27684
+ }
27685
+ },
27686
"403": {
27687
"description": "Forbidden",
27688
"content": {