| title | List teamsApp |
|---|---|
| description | List apps from the Microsoft Teams app catalog. |
| author | MSFTRickyCastaneda |
| ms.localizationpriority | medium |
| ms.subservice | teams |
| doc_type | apiPageType |
| ms.date | 10/17/2024 |
Namespace: microsoft.graph
List apps from the Microsoft Teams app catalog, including apps from the Microsoft Teams store and apps from your organization's app catalog (the tenant app catalog). To get apps from your organization's app catalog only, specify organization as the distributionMethod in the request.
Note
In general, the id of a teamsApp resource is generated by the server. It is not the same as the id specified in a Teams app manifest, unless its distributionMethod is store. For other cases, the id provided by the developer as part of the Teams app manifest is stamped as the externalId in the teamsApp resource.
Important
- Currently, this API is only supported in the user context and not in the admin view.
- The Teams Apps that this API returns comply with the app management policies established by the admin.
- After the Teams apps are published, it typically takes 24-48 hours for the policies to be applied, so some apps might not appear in the API results immediately.
- For more information, see App management policies.
[!INCLUDE national-cloud-support]
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
[!INCLUDE permissions-table]
Note
The Directory.Read.All and Directory.ReadWrite.All permissions are supported only for backward compatibility. We recommend that you update your solutions to use an alternative permission and avoid using these permissions going forward.
GET /appCatalogs/teamsAppsThis method supports the $filter, $select, and $expand OData query parameters to help customize the response.
Using $expand=AppDefinitions returns more information about the state of the app, such as the publishingState, which reflects the app submission review status and returns whether an app is approved, rejected, or remains under review.
Note: You can filter on any of the fields of the teamsApp object to shorten the list of results. You can use any of the following filter operations: Equal, not-equal, and, or, and not.
| Header | Value |
|---|---|
| Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
Don't supply a request body for this method.
If successful, this method returns a 200 OK response code and a list of teamsApp objects in the response body.
The following example lists all applications that are specific to your tenant.
The following example shows a request.
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=distributionMethod eq 'organization'
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"value": [
{
"id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
"externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
"displayName": "Test App",
"distributionMethod": "organization"
}
]
}The following example lists applications with a given ID.
The following example shows a request.
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=id eq 'b1c5353a-7aca-41b3-830f-27d5218fe0e5'
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"value": [
{
"id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
"externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
"displayName": "Test App",
"distributionMethod": "organization"
}
]
}The following example lists applications that match the id specified in the Teams app manifest. In the example, the manifest ID of the Teams app is cf1ba4c7-f94e-4d80-ba90-5594b641a8ee.
The following example shows a request.
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq 'cf1ba4c7-f94e-4d80-ba90-5594b641a8ee'
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#appCatalogs/teamsApps",
"value": [
{
"id": "22f73bbe-f67a-4dea-bd54-54cac718cb2b",
"externalId": "cf1ba4c7-f94e-4d80-ba90-5594b641a8ee",
"displayName": "YPA",
"distributionMethod": "organization"
}
]
}The following example lists applications with a given ID, and expands appDefinitions to return the publishingState, which reflects the app's submission review state. Submitted means the review is pending, published means the admin approved the app, and rejected means the admin rejected the app.
The following example shows a request.
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=id eq '876df28f-2e78-423b-94a5-44181bd0e225'&$expand=appDefinitions
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"value": [
{
"id": "876df28f-2e78-423b-94a5-44181bd0e225",
"externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
"displayName": "Test App",
"distributionMethod": "Organization",
"appDefinitions": [
{
"id": "NGQyMGNiNDUtZWViYS00ZTEyLWE3YzktMGQ0NDgzYjYxNzU2IyMxLjAuMA==",
"teamsAppId": "876df28f-2e78-423b-94a5-44181bd0e225",
"displayName": "Test App",
"version": "1.0.1",
"publishingState": "published",
"shortDescription": "Types Of Cards.",
"description": "This sample shows the feature where user can send different types of cards using bot.",
"lastModifiedDateTime": "2020-11-23T21:36:00.9437445Z",
"createdBy": null
}
]
}
]
}The following example lists only those apps in the catalog that contain a bot.
The following example shows a request.
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$expand=appDefinitions($expand=bot)&$filter=appDefinitions/any(a:a/bot ne null)
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#appCatalogs/teamsApps(appDefinitions(bot()))",
"value": [
{
"id": "8a1ed7a3-5c78-46b2-8504-f9da00a1d1a6",
"externalId": "3CAB7543-216D-47C6-986C-6247670F4663",
"displayName": "Ducks-3",
"distributionMethod": "organization",
"appDefinitions": [
{
"@odata.etag": "ImNOTW1CR2V1VzgwczlEblVidU00UHc9PSI=",
"id": "OGExZWQ3YTMtNWM3OC00NmIyLTg1MDQtZjlkYTAwYTFkMWE2IyMxLjAuOSMjUmVqZWN0ZWQ=",
"teamsAppId": "8a1ed7a3-5c78-46b2-8504-f9da00a1d1a6",
"displayName": "Ducks-3",
"version": "1.0.9",
"publishingState": "rejected",
"shortDescription": "quaerat quasi magnam. slight change. 5",
"description": "Aliquid placeat animi debitis accusamus. Non perferendis ullam. Quis est consequuntur vitae provident. Sunt laudantium id aut. slight change 5",
"lastModifiedDateTime": "2020-11-23T21:36:00.9437445Z",
"createdBy": {
"application": null,
"device": null,
"conversation": null,
"user": {
"id": "70292a90-d2a7-432c-857e-55db6d8f5cd0",
"displayName": null,
"userIdentityType": "aadUser"
}
},
"authorization": {
"clientAppId": null,
"requiredPermissionSet": {
"resourceSpecificPermissions": []
}
},
"bot": {
"id": "bb9f67a4-893b-48d7-ab17-40ed466c0f16"
}
}
]
},
{
"id": "30909dee-f7dd-4f89-8b3b-55de2e32489c",
"externalId": "0ebd3f4d-ca91-495b-a227-a17d298e22cc",
"displayName": "Self-Install-App-E2E-Tests",
"distributionMethod": "organization",
"appDefinitions": [
{
"@odata.etag": "IkwzVDlMOTBSSEdTMFducHUyYkpjVmc9PSI=",
"id": "MzA5MDlkZWUtZjdkZC00Zjg5LThiM2ItNTVkZTJlMzI0ODljIyM2LjAuMCMjU3VibWl0dGVk",
"teamsAppId": "30909dee-f7dd-4f89-8b3b-55de2e32489c",
"displayName": "Self-Install-App-E2E-Tests",
"version": "6.0.0",
"publishingState": "submitted",
"shortDescription": "A conversational smart assistant from MSX that surfaces real-time insights.",
"description": "For MSX Users: A conversational role-based smart assistant that will enable Enterprise sellers (AE, ATS, SSP, TSP) to be more productive by surfacing real-time insights, recommendations, actions and notifications, and by automating repetitive tasks.",
"lastModifiedDateTime": "2020-08-25T18:40:13.035341Z",
"createdBy": {
"application": null,
"device": null,
"conversation": null,
"user": {
"id": "c071a180-a220-43a1-adaf-e8db95c4a7d6",
"displayName": null,
"userIdentityType": "aadUser"
}
},
"authorization": {
"clientAppId": null,
"requiredPermissionSet": {
"resourceSpecificPermissions": []
}
},
"bot": {
"id": "da7d471b-de7d-4152-8556-1cdf7a564f6c"
}
}
]
}
]
}Example 6: List applications with a given ID and return only the resource specific permissions required by the app
The following example lists the apps with a given ID and returns the resource-specific permissions that are associated with it.
The following example shows a request.
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=id+eq+'a5228c26-a9ae-4702-90e0-79a5246d2f7d'&$expand=appDefinitions($select=id,authorization)
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#appCatalogs/teamsApps(appDefinitions(id,authorization))",
"value": [
{
"id": "a5228c26-a9ae-4702-90e0-79a5246d2f7d",
"externalId": "a55ec032-36e9-4b60-b604-34b2fe55abf1",
"displayName": "teamsDelegatedRscTests",
"distributionMethod": "organization",
"appDefinitions@odata.context": "https://graph.microsoft.com/v1.0/$metadata#appCatalogs/teamsApps('a5228c26-a9ae-4702-90e0-79a5246d2f7d')/appDefinitions(id,authorization)",
"appDefinitions": [
{
"id": "YTUyMjhjMjYtYTlhZS00NzAyLTkwZTAtNzlhNTI0NmQyZjdkIyMxLjAuMCMjUHVibGlzaGVk",
"authorization": {
"clientAppId": "6ed63604-0ba7-4a28-bb3a-dda03ea18d54",
"requiredPermissionSet": {
"resourceSpecificPermissions": [
{
"permissionValue": "Channel.Create.Group",
"permissionType": "application"
},
{
"permissionValue": "Channel.Delete.Group",
"permissionType": "application"
},
{
"permissionValue": "ChannelMeeting.ReadBasic.Group",
"permissionType": "delegated"
}
]
}
}
}
]
}
]
}