Skip to content

Commit 7891301

Browse files
author
jsinghmokha
committed
Add teamworkSectionItem resource and section item management APIs (beta)
Add documentation for section item operations including list, add, remove, and move APIs with permissions, TOC entries, changelog, and enum definitions. Document community ID normalization behavior.
1 parent 1fc8e51 commit 7891301

15 files changed

Lines changed: 643 additions & 2 deletions

‎api-reference/beta/api/teamworksection-delete-items.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: "Remove item from section"
3+
description: "Remove an item from a section in a user's teamwork."
4+
author: "jsinghmokha"
5+
ms.localizationpriority: medium
6+
ms.subservice: "teams"
7+
doc_type: apiPageType
8+
ms.date: 03/08/2026
9+
---
10+
11+
# Remove item from section
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Remove an [item](../resources/teamworksectionitem.md) from a [section](../resources/teamworksection.md) in a user's [teamwork](../resources/userteamwork.md). This doesn't delete the underlying chat, channel, meeting, or community; it only removes the item from the section.
18+
19+
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
20+
21+
## Permissions
22+
23+
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](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
24+
25+
<!-- { "blockType": "permissions", "name": "teamworksection_delete_items" } -->
26+
[!INCLUDE [permissions-table](../includes/permissions/teamworksection-delete-items-permissions.md)]
27+
28+
## HTTP request
29+
30+
<!-- { "blockType": "ignored" } -->
31+
```http
32+
DELETE /users/{user-id}/teamwork/sections/{teamworkSection-id}/items/{teamworkSectionItem-id}
33+
```
34+
35+
## Request headers
36+
37+
| Header | Value |
38+
|:-------|:------|
39+
| Authorization | Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts). |
40+
| If-Match | The ETag value of a previously retrieved **teamworkSection**. Required for optimistic concurrency control. |
41+
42+
## Request body
43+
44+
Don't supply a request body for this method.
45+
46+
## Response
47+
48+
If successful, this method returns a `204 No Content` response code. It doesn't return anything in the response body.
49+
50+
## Examples
51+
52+
### Request
53+
54+
The following example shows a request.
55+
56+
<!-- {
57+
"blockType": "request",
58+
"name": "delete_teamworksectionitem",
59+
"sampleKeys": ["10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "19:d5b2c3a4-e6f7-8901-abcd-ef3456789012@thread.v2"]
60+
}-->
61+
```http
62+
DELETE https://graph.microsoft.com/beta/users/10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f/teamwork/sections/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/19:d5b2c3a4-e6f7-8901-abcd-ef3456789012@thread.v2
63+
If-Match: W/"123456"
64+
```
65+
66+
### Response
67+
68+
The following example shows the response.
69+
70+
<!-- {
71+
"blockType": "response",
72+
"truncated": true
73+
}-->
74+
```http
75+
HTTP/1.1 204 No Content
76+
```
77+
78+
<!-- uuid: f7a8b901-2345-6789-cdef-678901234567
79+
2026-03-08 00:00:00 UTC -->
80+
<!--
81+
{
82+
"type": "#page.annotation",
83+
"description": "Remove item from section",
84+
"keywords": "",
85+
"section": "documentation",
86+
"tocPath": ""
87+
}
88+
-->

‎api-reference/beta/api/teamworksection-list-items.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: "List section items"
3+
description: "Get the list of items in a section."
4+
author: "jsinghmokha"
5+
ms.localizationpriority: medium
6+
ms.subservice: "teams"
7+
doc_type: apiPageType
8+
ms.date: 03/08/2026
9+
---
10+
11+
# List section items
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Get the list of [items](../resources/teamworksectionitem.md) in a [section](../resources/teamworksection.md) of a user's [teamwork](../resources/userteamwork.md).
18+
19+
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
20+
21+
## Permissions
22+
23+
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](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
24+
25+
<!-- { "blockType": "permissions", "name": "teamworksection_list_items" } -->
26+
[!INCLUDE [permissions-table](../includes/permissions/teamworksection-list-items-permissions.md)]
27+
28+
## HTTP request
29+
30+
<!-- { "blockType": "ignored" } -->
31+
```http
32+
GET /users/{user-id}/teamwork/sections/{teamworkSection-id}/items
33+
```
34+
35+
## Optional query parameters
36+
37+
This method doesn't support [OData query parameters](/graph/query-parameters) to customize the response.
38+
39+
## Request headers
40+
41+
| Header | Value |
42+
|:-------|:------|
43+
| Authorization | Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts). |
44+
45+
## Request body
46+
47+
Don't supply a request body for this method.
48+
49+
## Response
50+
51+
If successful, this method returns a `200 OK` response code and a collection of [teamworkSectionItem](../resources/teamworksectionitem.md) objects in the response body.
52+
53+
## Examples
54+
55+
### Request
56+
57+
The following example shows a request.
58+
59+
<!-- {
60+
"blockType": "request",
61+
"name": "list_teamworksectionitems",
62+
"sampleKeys": ["10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
63+
}-->
64+
```msgraph-interactive
65+
GET https://graph.microsoft.com/beta/users/10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f/teamwork/sections/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items
66+
```
67+
68+
### Response
69+
70+
The following example shows the response.
71+
72+
>**Note:** The response object shown here might be shortened for readability.
73+
74+
<!-- {
75+
"blockType": "response",
76+
"truncated": true,
77+
"@odata.type": "Collection(microsoft.graph.teamworkSectionItem)"
78+
}-->
79+
```http
80+
HTTP/1.1 200 OK
81+
Content-type: application/json
82+
83+
{
84+
"value": [
85+
{
86+
"@odata.type": "#microsoft.graph.teamworkSectionItem",
87+
"id": "19:d5b2c3a4-e6f7-8901-abcd-ef3456789012@thread.v2",
88+
"itemType": "chat",
89+
"createdDateTime": "2025-02-10T09:15:00Z",
90+
"lastModifiedDateTime": "2025-03-05T11:30:00Z"
91+
},
92+
{
93+
"@odata.type": "#microsoft.graph.teamworkSectionItem",
94+
"id": "19:e6f7a8b9-0123-4567-89ab-cdef01234567@thread.tacv2",
95+
"itemType": "channel",
96+
"createdDateTime": "2025-01-20T14:00:00Z",
97+
"lastModifiedDateTime": "2025-03-01T08:45:00Z"
98+
},
99+
{
100+
"@odata.type": "#microsoft.graph.teamworkSectionItem",
101+
"id": "19:meeting_ZmY3NTg2ODEtYTFiNi00OTI4LWFmZTctODRhMTI1NjRkNWRm@thread.v2",
102+
"itemType": "meeting",
103+
"createdDateTime": "2025-03-01T16:00:00Z",
104+
"lastModifiedDateTime": "2025-03-01T16:00:00Z"
105+
}
106+
]
107+
}
108+
```
109+
110+
<!-- uuid: c4d5e6f7-a8b9-0123-cdef-345678901234
111+
2026-03-08 00:00:00 UTC -->
112+
<!--
113+
{
114+
"type": "#page.annotation",
115+
"description": "List teamworkSectionItems",
116+
"keywords": "",
117+
"section": "documentation",
118+
"tocPath": ""
119+
}
120+
-->

‎api-reference/beta/api/teamworksection-post-items.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: "Add item to section"
3+
description: "Add an item to a section in a user's teamwork."
4+
author: "jsinghmokha"
5+
ms.localizationpriority: medium
6+
ms.subservice: "teams"
7+
doc_type: apiPageType
8+
ms.date: 03/08/2026
9+
---
10+
11+
# Add item to section
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Add an [item](../resources/teamworksectionitem.md) such as a chat, channel, meeting, or community to a [section](../resources/teamworksection.md) in a user's [teamwork](../resources/userteamwork.md). Each item can belong to only one section at a time. If the item is already associated with another section, use the [move](teamworksectionitem-move.md) action instead.
18+
19+
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
20+
21+
## Permissions
22+
23+
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](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
24+
25+
<!-- { "blockType": "permissions", "name": "teamworksection_post_items" } -->
26+
[!INCLUDE [permissions-table](../includes/permissions/teamworksection-post-items-permissions.md)]
27+
28+
## HTTP request
29+
30+
<!-- { "blockType": "ignored" } -->
31+
```http
32+
POST /users/{user-id}/teamwork/sections/{teamworkSection-id}/items
33+
```
34+
35+
## Request headers
36+
37+
| Header | Value |
38+
|:-------|:------|
39+
| Authorization | Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts). |
40+
| Content-Type | application/json. Required. |
41+
| If-Match | The ETag value of a previously retrieved **teamworkSection**. Required for optimistic concurrency control. |
42+
43+
## Request body
44+
45+
In the request body, supply a JSON representation of a [teamworkSectionItem](../resources/teamworksectionitem.md) object.
46+
47+
The following table lists the properties that you can set when you add a **teamworkSectionItem**.
48+
49+
| Property | Type | Description |
50+
|:---------|:-----|:------------|
51+
| id | String | The conversation ID of the chat, channel, meeting, or community to add to the section. For community items, the service automatically normalizes the ID to the `19:{id}@EngageCommunity` format. Required. |
52+
53+
## Response
54+
55+
If successful, this method returns a `201 Created` response code and a [teamworkSectionItem](../resources/teamworksectionitem.md) object in the response body.
56+
57+
The following errors can occur:
58+
59+
| Scenario | HTTP code | Error code | Message |
60+
|:---------|:----------|:-----------|:--------|
61+
| Item already exists in this section | `409 Conflict` | `conflict` | This item is already in this section. |
62+
| Item already exists in another section | `409 Conflict` | `conflict` | This item is already associated with another section. Use the move API to relocate it. |
63+
| Maximum items per section reached | `400 Bad Request` | `badRequest` | The maximum number of items in this section has been reached. |
64+
| Invalid item ID | `400 Bad Request` | `badRequest` | The specified item ID is not valid. Provide a valid chat, channel, meeting, or community ID. |
65+
| ETag version mismatch | `412 Precondition Failed` | `preconditionFailed` | The resource has been modified since it was last read. Read the latest version and retry. |
66+
67+
## Examples
68+
69+
### Request
70+
71+
The following example shows a request to add a chat to a section.
72+
73+
<!-- {
74+
"blockType": "request",
75+
"name": "add_teamworksectionitem",
76+
"sampleKeys": ["10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
77+
}-->
78+
```http
79+
POST https://graph.microsoft.com/beta/users/10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f/teamwork/sections/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items
80+
Content-type: application/json
81+
If-Match: W/"123456"
82+
83+
{
84+
"id": "19:d5b2c3a4-e6f7-8901-abcd-ef3456789012@thread.v2"
85+
}
86+
```
87+
88+
### Response
89+
90+
The following example shows the response.
91+
92+
>**Note:** The response object shown here might be shortened for readability.
93+
94+
<!-- {
95+
"blockType": "response",
96+
"truncated": true,
97+
"@odata.type": "microsoft.graph.teamworkSectionItem"
98+
}-->
99+
```http
100+
HTTP/1.1 201 Created
101+
Content-type: application/json
102+
Location: https://graph.microsoft.com/beta/users/10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f/teamwork/sections/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/19:d5b2c3a4-e6f7-8901-abcd-ef3456789012@thread.v2
103+
104+
{
105+
"@odata.type": "#microsoft.graph.teamworkSectionItem",
106+
"@odata.etag": "W/\"123457\"",
107+
"id": "19:d5b2c3a4-e6f7-8901-abcd-ef3456789012@thread.v2",
108+
"itemType": "chat",
109+
"createdDateTime": "2026-03-08T10:00:00Z",
110+
"lastModifiedDateTime": null
111+
}
112+
```
113+
114+
<!-- uuid: e6f7a8b9-0123-4567-cdef-567890123456
115+
2026-03-08 00:00:00 UTC -->
116+
<!--
117+
{
118+
"type": "#page.annotation",
119+
"description": "Add item to section",
120+
"keywords": "",
121+
"section": "documentation",
122+
"tocPath": ""
123+
}
124+
-->

0 commit comments

Comments
 (0)