diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index d9402339..3b5747df 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -762,12 +762,85 @@ export default extendConfig( collapsed: true, items: [ { text: "Overview", link: "/api-reference/page/overview" }, + { text: "Page Content HTML", link: "/api-reference/page/page-content-html" }, { text: "List Workspace Pages", link: "/api-reference/page/list-workspace-pages" }, { text: "Add Workspace Page", link: "/api-reference/page/add-workspace-page" }, + { text: "Get Workspace Page", link: "/api-reference/page/get-workspace-page" }, + { text: "Update Workspace Page", link: "/api-reference/page/update-workspace-page" }, + { text: "Archive Workspace Page", link: "/api-reference/page/archive-workspace-page" }, + { text: "Restore Workspace Page", link: "/api-reference/page/restore-workspace-page" }, + { text: "Delete Workspace Page", link: "/api-reference/page/delete-workspace-page" }, + { + text: "Get Workspace Page Attachment", + link: "/api-reference/page/get-workspace-page-attachment", + }, + { + text: "Confirm Workspace Page Attachment Upload", + link: "/api-reference/page/confirm-workspace-page-attachment-upload", + }, + { + text: "Download Workspace Page Attachment", + link: "/api-reference/page/download-workspace-page-attachment", + }, + { + text: "Delete Workspace Page Attachment", + link: "/api-reference/page/delete-workspace-page-attachment", + }, { text: "List Project Pages", link: "/api-reference/page/list-project-pages" }, { text: "Add Project Page", link: "/api-reference/page/add-project-page" }, - { text: "Get Workspace Page", link: "/api-reference/page/get-workspace-page" }, { text: "Get Project Page", link: "/api-reference/page/get-project-page" }, + { text: "Update Project Page", link: "/api-reference/page/update-project-page" }, + { text: "Archive Project Page", link: "/api-reference/page/archive-project-page" }, + { text: "Restore Project Page", link: "/api-reference/page/restore-project-page" }, + { text: "Delete Project Page", link: "/api-reference/page/delete-project-page" }, + ], + }, + { + text: "Collections", + collapsed: true, + items: [ + { text: "Overview", link: "/api-reference/collection/overview" }, + { text: "List Collections", link: "/api-reference/collection/list-collections" }, + { text: "Create Collection", link: "/api-reference/collection/create-collection" }, + { text: "Retrieve Collection", link: "/api-reference/collection/retrieve-collection" }, + { text: "Update Collection", link: "/api-reference/collection/update-collection" }, + { text: "Delete Collection", link: "/api-reference/collection/delete-collection" }, + { + text: "List Collection Members", + link: "/api-reference/collection/list-collection-members", + }, + { + text: "Add Collection Member", + link: "/api-reference/collection/add-collection-member", + }, + { + text: "Update Collection Member", + link: "/api-reference/collection/update-collection-member", + }, + { + text: "Remove Collection Member", + link: "/api-reference/collection/remove-collection-member", + }, + { + text: "List Collection Pages", + link: "/api-reference/collection/list-collection-pages", + }, + { + text: "Search Collection Pages", + link: "/api-reference/collection/search-collection-pages", + }, + { + text: "Add Collection Pages", + link: "/api-reference/collection/add-collection-pages", + }, + { + text: "Move or Reorder Collection Page", + link: "/api-reference/collection/move-or-reorder-collection-page", + }, + { + text: "Remove Collection Page", + link: "/api-reference/collection/remove-collection-page", + }, ], }, { diff --git a/docs/api-reference/assets/create-workspace-asset-upload.md b/docs/api-reference/assets/create-workspace-asset-upload.md index f5e18f13..981081cf 100644 --- a/docs/api-reference/assets/create-workspace-asset-upload.md +++ b/docs/api-reference/assets/create-workspace-asset-upload.md @@ -14,7 +14,8 @@ keywords: plane, plane api, rest api, api integration, assets, create workspace
-Generate presigned URL for generic asset upload +Generate a presigned URL for a workspace asset upload. To attach a file to a workspace page, set `entity_type` to +`PAGE_DESCRIPTION` and pass the page UUID as `entity_identifier`. The page must be editable, unlocked, and active.
@@ -61,6 +62,18 @@ UUID of the project to associate with the asset + + +Asset context. Use `PAGE_DESCRIPTION` for a workspace page attachment. + + + + + +UUID of the workspace page. This value is required when `entity_type` is `PAGE_DESCRIPTION`. + + + External identifier for the asset (for integration tracking) @@ -101,7 +114,8 @@ curl -X POST \ "name": "Example Name", "type": "image/jpeg", "size": 1024000, - "project_id": "550e8400-e29b-41d4-a716-446655440000", + "entity_type": "PAGE_DESCRIPTION", + "entity_identifier": "4d2f6f7e-9b4a-4d6a-8f4a-1c3f7c0f4a10", "external_id": "550e8400-e29b-41d4-a716-446655440000", "external_source": "github" }' @@ -120,7 +134,8 @@ response = requests.post( "name": "Example Name", "type": "image/jpeg", "size": 1024000, - "project_id": "550e8400-e29b-41d4-a716-446655440000", + "entity_type": "PAGE_DESCRIPTION", + "entity_identifier": "4d2f6f7e-9b4a-4d6a-8f4a-1c3f7c0f4a10", "external_id": "550e8400-e29b-41d4-a716-446655440000", "external_source": "github" } @@ -142,7 +157,8 @@ const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspac name: "Example Name", type: "image/jpeg", size: 1024000, - project_id: "550e8400-e29b-41d4-a716-446655440000", + entity_type: "PAGE_DESCRIPTION", + entity_identifier: "4d2f6f7e-9b4a-4d6a-8f4a-1c3f7c0f4a10", external_id: "550e8400-e29b-41d4-a716-446655440000", external_source: "github", }), @@ -158,7 +174,7 @@ const data = await response.json(); ```json { "asset_id": "550e8400-e29b-41d4-a716-446655440000", - "asset_url": "/api/assets/v2/workspaces/my-workspace/projects/None/issues/None/attachments/550e8400-e29b-41d4-a716-446655440000/", + "asset_url": "/api/v1/workspaces/my-workspace/pages/4d2f6f7e-9b4a-4d6a-8f4a-1c3f7c0f4a10/attachments/550e8400-e29b-41d4-a716-446655440000/", "upload_data": { "url": "https://uploads.example.com/plane-bucket", "fields": { diff --git a/docs/api-reference/collection/add-collection-member.md b/docs/api-reference/collection/add-collection-member.md new file mode 100644 index 00000000..1b0e896e --- /dev/null +++ b/docs/api-reference/collection/add-collection-member.md @@ -0,0 +1,124 @@ +--- +title: Add a collection member +description: Grant a workspace user access to a private Plane collection. +keywords: plane, plane api, rest api, collection members, add member, private collection +--- + +# Add a collection member + +
+ POST + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/members/ +
+ +
+
+ +Adds an explicit member to a private collection. The caller must be able to manage the collection. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +The workspace user's ID. + + + + +`0` (view, default), `1` (comment), or `2` (edit). + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```json +{ + "id": "4edec253-26f4-4667-8f52-9488dca1c620", + "collection": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "member": "6f356c85-bb22-47e0-b8b1-cf18aa6adad3", + "access": 0, + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:00:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" +} +``` + + + +
+ +
diff --git a/docs/api-reference/collection/add-collection-pages.md b/docs/api-reference/collection/add-collection-pages.md new file mode 100644 index 00000000..a5035373 --- /dev/null +++ b/docs/api-reference/collection/add-collection-pages.md @@ -0,0 +1,138 @@ +--- +title: Add pages to a collection +description: Add one or more Plane workspace page trees to a collection. +keywords: plane, plane api, rest api, collection pages, add pages, page placement +--- + +# Add pages to a collection + +
+ POST + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/pages/ +
+ +
+
+ +Adds each selected page and its sub-pages. Adding to a private collection makes the page tree private; adding an owned +private page to a public collection makes it public. Private collections accept only root pages. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The destination collection ID. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +One or more workspace page IDs. + + + + +Page-ID keys mapped to numeric sort orders. Every key must occur in `page_ids`. + + + + +Placement with `type`: `append`, `before`, or `after`; optional `parent_id`; and required `target_page_id` for `before` or `after`. Before/after accepts exactly one page. + + + +`placement` takes precedence over `sort_orders`. An `append` placement accepts multiple pages and preserves their order +from `page_ids`. + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```json +[ + { + "id": "55ebf2cc-61ba-478a-b88c-88db969e29dc", + "collection": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "page": "ea8ccdab-1cf4-448b-8205-51e4b98d82b8", + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "sort_order": 65535.0, + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:00:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" + } +] +``` + + + +
+ +
diff --git a/docs/api-reference/collection/create-collection.md b/docs/api-reference/collection/create-collection.md new file mode 100644 index 00000000..13f09e1c --- /dev/null +++ b/docs/api-reference/collection/create-collection.md @@ -0,0 +1,134 @@ +--- +title: Create a collection +description: Create a public or private collection in a Plane workspace. +keywords: plane, plane api, rest api, collections, create collection, private collection +--- + +# Create a collection + +
+ POST + /api/v1/workspaces/{workspace_slug}/collections/ +
+ +
+
+ +Creates a collection. Private collections can only be created by workspace admins when the feature is available. The +creator of a private collection is automatically added as a member with edit access. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +The collection name. Defaults to an empty string. + + + + +`0` for public (default) or `1` for private. + + + + +Logo or emoji properties. Defaults to an empty object. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```json +{ + "id": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "name": "Product docs", + "owned_by_id": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "access": 0, + "current_user_access": null, + "has_pages": false, + "is_default": false, + "is_global": true, + "logo_props": { "emoji": "📚" }, + "sort_order": 65535.0, + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:00:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" +} +``` + + + +
+ +
diff --git a/docs/api-reference/collection/delete-collection.md b/docs/api-reference/collection/delete-collection.md new file mode 100644 index 00000000..e5b8365e --- /dev/null +++ b/docs/api-reference/collection/delete-collection.md @@ -0,0 +1,106 @@ +--- +title: Delete a collection +description: Delete a non-default Plane collection and optionally preserve its pages. +keywords: plane, plane api, rest api, collections, delete collection, archive pages +--- + +# Delete a collection + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/ +
+ +
+
+ +Deletes a non-default collection. Pages are archived by default. Set `archive_pages=false` to preserve pages when +deleting a public collection; pages in a private collection are always archived. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Whether to archive contained pages. Defaults to `true`. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```text +No response body +``` + + + +
+ +
diff --git a/docs/api-reference/collection/list-collection-members.md b/docs/api-reference/collection/list-collection-members.md new file mode 100644 index 00000000..2a31d2cc --- /dev/null +++ b/docs/api-reference/collection/list-collection-members.md @@ -0,0 +1,99 @@ +--- +title: List collection members +description: List users who have explicit access to a Plane collection. +keywords: plane, plane api, rest api, collection members, list members +--- + +# List collection members + +
+ GET + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/members/ +
+ +
+
+ +Returns explicit collection memberships. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
+ +### Scopes + +`read` or `wiki.pages:read` + +
+ +
+ +
+ + + + + + + +```json +[ + { + "id": "4edec253-26f4-4667-8f52-9488dca1c620", + "collection": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "member": "6f356c85-bb22-47e0-b8b1-cf18aa6adad3", + "access": 0, + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:00:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" + } +] +``` + + + +
+ +
diff --git a/docs/api-reference/collection/list-collection-pages.md b/docs/api-reference/collection/list-collection-pages.md new file mode 100644 index 00000000..59da6dfc --- /dev/null +++ b/docs/api-reference/collection/list-collection-pages.md @@ -0,0 +1,196 @@ +--- +title: List collection pages +description: List and filter a branch of pages in a Plane collection. +keywords: plane, plane api, rest api, collection pages, list pages, page filters +--- + +# List collection pages + +
+ GET + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/pages/ +
+ +
+
+ +Returns a paginated branch of visible pages. By default, it returns the collection's root pages. +Pass `next_cursor` back as `cursor` to continue until `next_page_results` is `false`. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Return direct children of this page. + + + + +Case-insensitive page-name search. + + + + +Comma-separated creator IDs. + + + + +Filter by the current user's favorite status. + + + + +Comma-separated label IDs. + + + + +Created on or after this date. + + + + +Created on or before this date. + + + + +Filter by owner. + + + + +Comma-separated owner IDs. + + + + +Comma-separated parent IDs. + + + + +Results per page. Defaults to 50; maximum 100. + + + + +Cursor returned by a previous page. + + + +
+
+ +
+ +### Scopes + +`read` or `wiki.pages:read` + +
+ +
+ +
+ + + + + + + +```json +{ + "next_cursor": "50:50:0", + "prev_cursor": "50:0:0", + "next_page_results": false, + "prev_page_results": false, + "count": 1, + "total_pages": 1, + "total_results": 1, + "extra_stats": null, + "results": [ + { + "page_collection_id": "55ebf2cc-61ba-478a-b88c-88db969e29dc", + "collection_id": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "parent_id": null, + "sort_order": 65535.0, + "page": { + "id": "ea8ccdab-1cf4-448b-8205-51e4b98d82b8", + "name": "API guide", + "access": 0, + "logo_props": {}, + "parent_id": null, + "collection_id": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "sub_pages_count": 2, + "is_shared": false, + "owned_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_at": "2026-08-18T10:00:00Z", + "created_at": "2026-08-18T10:00:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "is_favorite": false, + "label_ids": [] + } + } + ] +} +``` + + + +
+ +
diff --git a/docs/api-reference/collection/list-collections.md b/docs/api-reference/collection/list-collections.md new file mode 100644 index 00000000..936c0d0d --- /dev/null +++ b/docs/api-reference/collection/list-collections.md @@ -0,0 +1,109 @@ +--- +title: List collections +description: List the collections visible to the authenticated user in a Plane workspace. +keywords: plane, plane api, rest api, collections, list collections, wiki +--- + +# List collections + +
+ GET + /api/v1/workspaces/{workspace_slug}/collections/ +
+ +
+
+ +Returns all public and permitted private collections in sort order. A private collection is included when the caller +owns it, is a workspace admin, or is an explicit collection member. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + +
+
+ +
+ +### Scopes + +`read` or `wiki.pages:read` + +
+ +
+ +
+ + + + + + + + + +```json +[ + { + "id": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "name": "Product docs", + "owned_by_id": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "access": 0, + "current_user_access": null, + "has_pages": true, + "is_default": false, + "is_global": true, + "logo_props": {}, + "sort_order": 65535.0, + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:00:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" + } +] +``` + + + +
+ +
diff --git a/docs/api-reference/collection/move-or-reorder-collection-page.md b/docs/api-reference/collection/move-or-reorder-collection-page.md new file mode 100644 index 00000000..f94a69ae --- /dev/null +++ b/docs/api-reference/collection/move-or-reorder-collection-page.md @@ -0,0 +1,137 @@ +--- +title: Move or reorder a collection page +description: Move a Plane page tree to another collection or change its collection order. +keywords: plane, plane api, rest api, collection pages, move page, reorder page +--- + +# Move or reorder a collection page + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/pages/{page_collection_id}/ +
+ +
+
+ +Reorders a page or moves its page tree to another visible collection. A private collection's sub-page cannot be moved +independently. Moving a private page to a public collection makes its tree public when permitted. Moving a root page +out of a private collection requires workspace admin access, or ownership of the page tree together with edit access +to the source collection. Moving into a private collection also requires access to the destination collection. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The source collection ID. + + + + +The page membership ID returned as `page_collection_id` by the list endpoint. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +A destination collection ID. Omit or use the source ID to reorder in place. + + + + +An explicit ordering value. + + + + +Placement with `type`: `append`, `before`, or `after`; optional `parent_id`; and required `target_page_id` for before/after. Overrides `sort_order`. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```json +{ + "id": "55ebf2cc-61ba-478a-b88c-88db969e29dc", + "collection": "82c72604-2019-43b7-930f-692af61f3ea7", + "page": "ea8ccdab-1cf4-448b-8205-51e4b98d82b8", + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "sort_order": 65535.0, + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:05:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" +} +``` + + + +
+ +
diff --git a/docs/api-reference/collection/overview.md b/docs/api-reference/collection/overview.md new file mode 100644 index 00000000..825c02dc --- /dev/null +++ b/docs/api-reference/collection/overview.md @@ -0,0 +1,53 @@ +--- +title: Collection API overview +description: Organize Plane workspace pages into public or private collections and manage collection membership. +keywords: plane, plane api, rest api, collections, wiki pages, collection members +--- + +# Collection API overview + +Collections organize workspace wiki pages. Public collections are visible according to workspace permissions; private +collections are visible only to permitted users. A page and its sub-pages move together when the page is added, moved, +or removed. + +## Collection object + + + +```json +{ + "id": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "name": "Product docs", + "owned_by_id": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "access": 0, + "current_user_access": null, + "has_pages": true, + "is_default": false, + "is_global": true, + "logo_props": { "emoji": "📚" }, + "sort_order": 65535.0, + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:00:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" +} +``` + + + +`access` is `0` for public or `1` for private. `current_user_access` is `null` for a public collection. For a private +collection, member access is `0` (view), `1` (comment), or `2` (edit). Collection access cannot be changed after +creation. Private collections require the private collections feature, and only workspace admins can create them. The +creator of a private collection is automatically added with edit access. + +Collection edit access allows a member to edit content and arrange pages, but it does not grant collection ownership. +Only the collection owner or a workspace admin can add, update, or remove collection members. + +## Common errors + +| Status | Cause | +| ------ | -------------------------------------------------------------------------------------------------------------- | +| `400` | Invalid request payload or page placement, or an attempt to modify or delete the protected default collection. | +| `403` | Insufficient collection or workspace permissions, or unavailable private-collection feature access. | +| `404` | The collection, page, membership, or other requested resource is unavailable or inaccessible to the caller. | diff --git a/docs/api-reference/collection/remove-collection-member.md b/docs/api-reference/collection/remove-collection-member.md new file mode 100644 index 00000000..d4c52f43 --- /dev/null +++ b/docs/api-reference/collection/remove-collection-member.md @@ -0,0 +1,92 @@ +--- +title: Remove a collection member +description: Revoke a user's explicit access to a private Plane collection. +keywords: plane, plane api, rest api, collection members, remove member +--- + +# Remove a collection member + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/members/{member_id}/ +
+ +
+
+ +Removes an explicit collection membership. `member_id` identifies the membership record, not the user. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + + +The collection membership ID. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```text +No response body +``` + + + +
+ +
diff --git a/docs/api-reference/collection/remove-collection-page.md b/docs/api-reference/collection/remove-collection-page.md new file mode 100644 index 00000000..419f7be4 --- /dev/null +++ b/docs/api-reference/collection/remove-collection-page.md @@ -0,0 +1,93 @@ +--- +title: Remove a page from a collection +description: Remove a Plane page tree from its collection. +keywords: plane, plane api, rest api, collection pages, remove page +--- + +# Remove a page from a collection + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/pages/{page_collection_id}/ +
+ +
+
+ +Removes the page and its descendants from the collection. A sub-page cannot be removed independently from a private +collection. Removing a private collection root requires permission to move that page tree out of the collection. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + + +The page membership ID returned as `page_collection_id` by the list endpoint. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```text +No response body +``` + + + +
+ +
diff --git a/docs/api-reference/collection/retrieve-collection.md b/docs/api-reference/collection/retrieve-collection.md new file mode 100644 index 00000000..cf1a2e22 --- /dev/null +++ b/docs/api-reference/collection/retrieve-collection.md @@ -0,0 +1,104 @@ +--- +title: Retrieve a collection +description: Retrieve a visible Plane workspace collection by ID. +keywords: plane, plane api, rest api, collections, retrieve collection +--- + +# Retrieve a collection + +
+ GET + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/ +
+ +
+
+ +Returns a collection if the authenticated user can view it. An inaccessible private collection returns `404 Not Found`. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
+ +### Scopes + +`read` or `wiki.pages:read` + +
+ +
+ +
+ + + + + + + +```json +{ + "id": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "name": "Product docs", + "owned_by_id": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "access": 0, + "current_user_access": null, + "has_pages": true, + "is_default": false, + "is_global": true, + "logo_props": {}, + "sort_order": 65535.0, + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:00:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" +} +``` + + + +
+ +
diff --git a/docs/api-reference/collection/search-collection-pages.md b/docs/api-reference/collection/search-collection-pages.md new file mode 100644 index 00000000..530467fa --- /dev/null +++ b/docs/api-reference/collection/search-collection-pages.md @@ -0,0 +1,110 @@ +--- +title: Search addable collection pages +description: Search for workspace pages that can be added to a Plane collection. +keywords: plane, plane api, rest api, collection pages, search pages, addable pages +--- + +# Search addable collection pages + +
+ GET + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/pages-search/ +
+ +
+
+ +Returns eligible root pages that are not already assigned to the collection. Results respect page and private +collection permissions. Without `search`, the endpoint returns at most 10 results. With `search`, it performs a +case-insensitive page-name search without that limit. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The destination collection ID. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +A page-name search string. + + + +
+
+ +
+ +### Scopes + +`read` or `wiki.pages:read` + +
+ +
+ +
+ + + + + + + +```json +[ + { + "id": "ea8ccdab-1cf4-448b-8205-51e4b98d82b8", + "name": "API guide", + "logo_props": { "emoji": "📘" } + } +] +``` + + + +
+ +
diff --git a/docs/api-reference/collection/update-collection-member.md b/docs/api-reference/collection/update-collection-member.md new file mode 100644 index 00000000..905d817e --- /dev/null +++ b/docs/api-reference/collection/update-collection-member.md @@ -0,0 +1,122 @@ +--- +title: Update a collection member +description: Change a Plane collection member's access level. +keywords: plane, plane api, rest api, collection members, update member access +--- + +# Update a collection member + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/members/{member_id}/ +
+ +
+
+ +Changes an explicit collection membership's access level. `member_id` identifies the membership record, not the user. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + + +The collection membership ID. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +`0` (view), `1` (comment), or `2` (edit). + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```json +{ + "id": "4edec253-26f4-4667-8f52-9488dca1c620", + "collection": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "member": "6f356c85-bb22-47e0-b8b1-cf18aa6adad3", + "access": 2, + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:05:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" +} +``` + + + +
+ +
diff --git a/docs/api-reference/collection/update-collection.md b/docs/api-reference/collection/update-collection.md new file mode 100644 index 00000000..a75e0253 --- /dev/null +++ b/docs/api-reference/collection/update-collection.md @@ -0,0 +1,135 @@ +--- +title: Update a collection +description: Update a Plane collection's name, logo, or sort order. +keywords: plane, plane api, rest api, collections, update collection +--- + +# Update a collection + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/ +
+ +
+
+ +Partially updates a collection. Its public or private access cannot be changed after creation. + +
+ +### Path Parameters + +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +A new collection name. + + + + +New logo or emoji properties. + + + + +The collection's ordering value. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +```json +{ + "id": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "name": "API docs", + "owned_by_id": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "access": 0, + "current_user_access": null, + "has_pages": true, + "is_default": false, + "is_global": true, + "logo_props": {}, + "sort_order": 25000.0, + "workspace": "95d1f03f-16e5-4807-a8c5-ec0c7cf0e4ab", + "created_at": "2026-08-18T10:00:00Z", + "updated_at": "2026-08-18T10:05:00Z", + "created_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f", + "updated_by": "d2f1b470-55e8-4e7a-8a61-7fc695bc1a4f" +} +``` + + + +
+ +
diff --git a/docs/api-reference/page/add-workspace-page.md b/docs/api-reference/page/add-workspace-page.md index eb258fa3..c0c8b6f8 100644 --- a/docs/api-reference/page/add-workspace-page.md +++ b/docs/api-reference/page/add-workspace-page.md @@ -14,7 +14,8 @@ keywords: plane, plane api, rest api, api integration, page, create a wiki page
-Create a workspace page +Create a workspace page. To create a child page, pass `parent_id`; Plane creates the page and inserts a page embed into +the parent document. The parent must be visible, editable, unlocked, and active.
@@ -94,7 +95,13 @@ External source. -Description html. +HTML content for the page body. Plane sanitizes the HTML before storing it. + + + + + +UUID of the parent workspace page. Do not combine `parent_id` with `collection_id`. @@ -105,7 +112,7 @@ Description html. ### Scopes -`wiki.pages:write` +`write` or `wiki.pages:write`
@@ -132,6 +139,7 @@ curl -X POST \ "logo_props": "example-value", "external_id": "550e8400-e29b-41d4-a716-446655440000", "external_source": "github", + "parent_id": "4d2f6f7e-9b4a-4d6a-8f4a-1c3f7c0f4a10", "description_html": "

Example content

" }' ``` @@ -155,6 +163,7 @@ response = requests.post( "logo_props": "example-value", "external_id": "550e8400-e29b-41d4-a716-446655440000", "external_source": "github", + "parent_id": "4d2f6f7e-9b4a-4d6a-8f4a-1c3f7c0f4a10", "description_html": "

Example content

" } ) @@ -181,6 +190,7 @@ const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspac logo_props: "example-value", external_id: "550e8400-e29b-41d4-a716-446655440000", external_source: "github", + parent_id: "4d2f6f7e-9b4a-4d6a-8f4a-1c3f7c0f4a10", description_html: "

Example content

", }), }); @@ -215,3 +225,14 @@ const data = await response.json();
+ +## Child-page responses + +- `201 Created`: the child was created and linked in the parent document. +- `202 Accepted`: the child was created, but Plane is still retrying the parent link. Store the returned page ID and + check the parent later. +- `400 Bad Request`: the parent is locked or archived, or `parent_id` conflicts with `collection_id`. +- `403 Forbidden`: the caller cannot edit the parent. +- `404 Not Found`: the parent is unavailable in this workspace. +- `502 Bad Gateway`: the parent link was rejected and the new child was removed. +- `503 Service Unavailable`: the collaborative document service is not configured. diff --git a/docs/api-reference/page/archive-project-page.md b/docs/api-reference/page/archive-project-page.md new file mode 100644 index 00000000..fe9e2a93 --- /dev/null +++ b/docs/api-reference/page/archive-project-page.md @@ -0,0 +1,92 @@ +--- +title: Archive a project page +description: Archive a project page via the Plane API before deleting it. +keywords: plane, plane api, project page, archive page +--- + +# Archive a project page + +
+ POST + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/pages/{page_id}/archive/ +
+ +
+
+ +Archive a project page and its subpages. A page must be archived before it can be deleted. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The project UUID. + + + + +The page UUID. + + + +
+
+ +
+ +### Scopes + +`write` or `projects.pages:write` + +
+ +
+ +
+ + + + + + + + +No response body. + + + +
+ +
diff --git a/docs/api-reference/page/archive-workspace-page.md b/docs/api-reference/page/archive-workspace-page.md new file mode 100644 index 00000000..3de6685b --- /dev/null +++ b/docs/api-reference/page/archive-workspace-page.md @@ -0,0 +1,86 @@ +--- +title: Archive a workspace page +description: Archive a workspace page via the Plane API before deleting it. +keywords: plane, plane api, workspace page, archive wiki page +--- + +# Archive a workspace page + +
+ POST + /api/v1/workspaces/{workspace_slug}/pages/{page_id}/archive/ +
+ +
+
+ +Archive a workspace page and its subpages. A page must be archived before it can be deleted. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The page UUID. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +No response body. + + + +
+ +
diff --git a/docs/api-reference/page/confirm-workspace-page-attachment-upload.md b/docs/api-reference/page/confirm-workspace-page-attachment-upload.md new file mode 100644 index 00000000..9eaf8293 --- /dev/null +++ b/docs/api-reference/page/confirm-workspace-page-attachment-upload.md @@ -0,0 +1,111 @@ +--- +title: Confirm a workspace page attachment upload +description: Confirm the upload status of an attachment linked to a workspace page. +keywords: plane, plane api, workspace page, confirm attachment upload +--- + +# Confirm a workspace page attachment upload + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/pages/{page_id}/attachments/{attachment_id}/ +
+ +
+
+ +Set an attachment's upload status after uploading it through the generic asset upload flow. This operation queues storage metadata extraction when needed. The page must be editable and cannot be locked or archived. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The workspace page UUID. + + + + +The attachment asset UUID. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Whether the attachment was uploaded successfully. Defaults to `true`. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + + +No response body. + + + +
+ +
diff --git a/docs/api-reference/page/delete-project-page.md b/docs/api-reference/page/delete-project-page.md new file mode 100644 index 00000000..aa200ec6 --- /dev/null +++ b/docs/api-reference/page/delete-project-page.md @@ -0,0 +1,92 @@ +--- +title: Delete a project page +description: Delete an archived project page via the Plane API. +keywords: plane, plane api, project page, delete page +--- + +# Delete a project page + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/pages/{page_id}/ +
+ +
+
+ +Delete a project page. Archive the page first; deleting an active page returns `400`. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The project UUID. + + + + +The page UUID. + + + +
+
+ +
+ +### Scopes + +`write` or `projects.pages:write` + +
+ +
+ +
+ + + + + + + + +No response body. + + + +
+ +
diff --git a/docs/api-reference/page/delete-workspace-page-attachment.md b/docs/api-reference/page/delete-workspace-page-attachment.md new file mode 100644 index 00000000..d79555e0 --- /dev/null +++ b/docs/api-reference/page/delete-workspace-page-attachment.md @@ -0,0 +1,92 @@ +--- +title: Delete a workspace page attachment +description: Delete an attachment linked to a workspace page via the Plane API. +keywords: plane, plane api, workspace page, delete attachment +--- + +# Delete a workspace page attachment + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/pages/{page_id}/attachments/{attachment_id}/ +
+ +
+
+ +Soft-delete an attachment from an editable workspace page. Later metadata and download requests return `404`. Locked or archived pages cannot be changed. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The workspace page UUID. + + + + +The attachment asset UUID. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + + +No response body. + + + +
+ +
diff --git a/docs/api-reference/page/delete-workspace-page.md b/docs/api-reference/page/delete-workspace-page.md new file mode 100644 index 00000000..6e759b64 --- /dev/null +++ b/docs/api-reference/page/delete-workspace-page.md @@ -0,0 +1,86 @@ +--- +title: Delete a workspace page +description: Delete an archived workspace page via the Plane API. +keywords: plane, plane api, workspace page, delete wiki page +--- + +# Delete a workspace page + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/pages/{page_id}/ +
+ +
+
+ +Delete a workspace page. Archive the page before calling this operation; deleting an active page returns `400`. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The page UUID. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +No response body. + + + +
+ +
diff --git a/docs/api-reference/page/download-workspace-page-attachment.md b/docs/api-reference/page/download-workspace-page-attachment.md new file mode 100644 index 00000000..a23161cb --- /dev/null +++ b/docs/api-reference/page/download-workspace-page-attachment.md @@ -0,0 +1,92 @@ +--- +title: Download a workspace page attachment +description: Download an uploaded workspace page attachment through a presigned redirect. +keywords: plane, plane api, workspace page, download attachment +--- + +# Download a workspace page attachment + +
+ GET + /api/v1/workspaces/{workspace_slug}/pages/{page_id}/attachments/{attachment_id}/download/ +
+ +
+
+ +Validate access and receive a `302` redirect to a temporary presigned download URL. An attachment that has not been confirmed as uploaded returns `400`. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The workspace page UUID. + + + + +The attachment asset UUID. + + + +
+
+ +
+ +### Scopes + +`read` or `wiki.pages:read` + +
+ +
+ +
+ + + + + + + +The `Location` header contains the temporary presigned download URL. + + + +
+ +
diff --git a/docs/api-reference/page/get-workspace-page-attachment.md b/docs/api-reference/page/get-workspace-page-attachment.md new file mode 100644 index 00000000..b568d91a --- /dev/null +++ b/docs/api-reference/page/get-workspace-page-attachment.md @@ -0,0 +1,104 @@ +--- +title: Retrieve workspace page attachment metadata +description: Retrieve metadata for an attachment linked to a workspace page. +keywords: plane, plane api, workspace page, attachment metadata +--- + +# Retrieve workspace page attachment metadata + +
+ GET + /api/v1/workspaces/{workspace_slug}/pages/{page_id}/attachments/{attachment_id}/ +
+ +
+
+ +Retrieve metadata and links for an existing workspace page attachment. The caller must be able to view the page. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The workspace page UUID. + + + + +The attachment asset UUID. + + + +
+
+ +
+ +### Scopes + +`read` or `wiki.pages:read` + +
+ +
+ +
+ + + + + + + +```json +{ + "id": "attachment-uuid", + "page_id": "page-uuid", + "name": "diagram.png", + "type": "image/png", + "size": 24576, + "is_uploaded": true, + "asset_url": "https://api.plane.so/api/v1/workspaces/my-workspace/pages/page-uuid/attachments/attachment-uuid/", + "_links": { + "download": "https://api.plane.so/api/v1/workspaces/my-workspace/pages/page-uuid/attachments/attachment-uuid/download/" + } +} +``` + + +
+ +
diff --git a/docs/api-reference/page/overview.md b/docs/api-reference/page/overview.md index f3bb7938..c088d5cb 100644 --- a/docs/api-reference/page/overview.md +++ b/docs/api-reference/page/overview.md @@ -6,7 +6,7 @@ keywords: plane, plane api, rest api, api integration, pages, documentation, not # Overview -Pages allow you to create and manage documentation at both workspace and project levels. Workspace pages are accessible across all projects, while project pages are specific to individual projects. +Pages allow you to create and manage documentation at both workspace and project levels. Workspace pages are accessible across all projects, while project pages are specific to individual projects. Page body mutations are applied to Plane's collaborative document so API updates remain consistent with active editor sessions. **Documentation**: [Wiki](https://docs.plane.so/core-concepts/pages/wiki), [Pages](https://docs.plane.so/core-concepts/pages/overview) @@ -45,6 +45,26 @@ Pages allow you to create and manage documentation at both workspace and project ID of the user who last updated the page +- `parent_id` _uuid or null_ + + ID of the parent page for a child page + +- `collection_id` _uuid or null_ + + ID of the collection containing a workspace page + +- `page_collection_id` _uuid or null_ + + ID of the page's placement record within its collection + +- `archived_at` _timestamp or null_ + + Time the page was archived + +- `is_locked` _boolean_ + + Whether content mutations are blocked +
@@ -58,7 +78,12 @@ Pages allow you to create and manage documentation at both workspace and project "name": "Getting Started", "description_html": "

Welcome

This is a getting started guide.

", "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", - "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430" + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "parent_id": null, + "collection_id": "0a8a3e6a-3c32-49c7-bbb5-b7a8e32c2f10", + "page_collection_id": "1d9b4f7b-56e8-4c63-9ff4-e24b508c162d", + "archived_at": null, + "is_locked": false } ``` diff --git a/docs/api-reference/page/page-content-html.md b/docs/api-reference/page/page-content-html.md new file mode 100644 index 00000000..b1540ae9 --- /dev/null +++ b/docs/api-reference/page/page-content-html.md @@ -0,0 +1,177 @@ +--- +title: Page content HTML +description: Format page body HTML, use Plane editor components, and attach files through the Workspace Page API. +keywords: plane, plane api, wiki page, description html, page editor, page attachments +--- + +# Page content HTML + +Send page body content in `description_html` when you create or update a page. Plane sanitizes the HTML, converts it +to the editor document format, and replaces the complete page body during an update. + +> Unsupported tags, attributes, and unsafe URLs can be removed. Fetch the page after a write if your integration +> needs to inspect the final stored HTML. The maximum HTML payload is 10 MB. + +## Standard HTML + +The following shapes are suitable for API-created page content: + +| Content | HTML shape | +| --------------- | ----------------------------------------------------------------- | +| Paragraph | `

Text

` | +| Headings | `

Title

` through `
Title
` | +| Bold | `Bold` | +| Italic | `Italic` | +| Underline | `Underline` | +| Strikethrough | `Strike` | +| Inline code | `const value = 1` | +| Link | `Plane` | +| Blockquote | `

Quote

` | +| Code block | `
const value = 1;
` | +| Bullet list | `
  • Item
` | +| Ordered list | `
  1. Item
` | +| Task list | `
  • Done
` | +| Horizontal rule | `
` | +| Table | `
Cell
` | +| Image | `Image` | + +URL attributes support safe protocols such as `http`, `https`, `mailto`, and `tel`. + +```html +

Project brief

+

This page was updated through the API.

+
    +
  • Write the brief
    • +
  • Review with the team
    • +
+ + + + + + + + + + + +
OwnerStatus
DesignIn progress
+``` + +## Plane editor components + +Entity-backed components must reference existing Plane entities. Use UUIDs, not human-readable work item keys, and do +not include private user data in page content. + +### User mention + +```html + +``` + +### Work item embed + +```html + + +``` + +### Page embed + +```html + + +``` + +### Image component + +```html + + +``` + +### Callout + +```html +
+

This is a callout created through the API.

+
+``` + +### External embed + +```html + + +``` + +### Math and dates + +```html +

Inline formula:

+ +

Target date:

+``` + +## Attach a file + +Page attachments use the workspace asset upload flow; there is no multipart page-attachment endpoint. + +1. Create upload credentials with + [`POST /workspaces/{workspace_slug}/assets/`](/api-reference/assets/create-workspace-asset-upload): + + ```json + { + "name": "requirements.pdf", + "type": "application/pdf", + "size": 12345, + "entity_type": "PAGE_DESCRIPTION", + "entity_identifier": "PAGE_UUID" + } + ``` + +2. Upload the file bytes to `upload_data.url` using the returned form fields. +3. Confirm the upload with the + [page attachment endpoint](/api-reference/page/confirm-workspace-page-attachment-upload). +4. Include the attachment in the complete page body sent through `description_html`: + + ```html + + + ``` + +Use the asset ID returned by Plane. Attachment metadata and downloads remain subject to page visibility; confirming or +deleting an attachment requires edit access to an unlocked, active page. diff --git a/docs/api-reference/page/restore-project-page.md b/docs/api-reference/page/restore-project-page.md new file mode 100644 index 00000000..8326b426 --- /dev/null +++ b/docs/api-reference/page/restore-project-page.md @@ -0,0 +1,92 @@ +--- +title: Restore a project page +description: Restore an archived project page via the Plane API. +keywords: plane, plane api, project page, restore page, unarchive +--- + +# Restore a project page + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/pages/{page_id}/archive/ +
+ +
+
+ +Restore an archived project page. Restore an archived parent before restoring its child; otherwise the API returns `400`. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The project UUID. + + + + +The page UUID. + + + +
+
+ +
+ +### Scopes + +`write` or `projects.pages:write` + +
+ +
+ +
+ + + + + + + + +No response body. + + + +
+ +
diff --git a/docs/api-reference/page/restore-workspace-page.md b/docs/api-reference/page/restore-workspace-page.md new file mode 100644 index 00000000..76111b09 --- /dev/null +++ b/docs/api-reference/page/restore-workspace-page.md @@ -0,0 +1,86 @@ +--- +title: Restore a workspace page +description: Restore an archived workspace page via the Plane API. +keywords: plane, plane api, workspace page, restore wiki page, unarchive +--- + +# Restore a workspace page + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/pages/{page_id}/archive/ +
+ +
+
+ +Restore an archived workspace page. If its parent is archived, restore the parent before restoring the child; otherwise the API returns `400`. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The page UUID. + + + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + +No response body. + + + +
+ +
diff --git a/docs/api-reference/page/update-project-page.md b/docs/api-reference/page/update-project-page.md new file mode 100644 index 00000000..3a58c73e --- /dev/null +++ b/docs/api-reference/page/update-project-page.md @@ -0,0 +1,128 @@ +--- +title: Update a project page +description: Update the title or content of a project page via the Plane API. +keywords: plane, plane api, project page, update page +--- + +# Update a project page + +
+ PUT + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/pages/{page_id}/ +
+ +
+
+ +Send `name`, `description_html`, or both. `description_html` replaces the current content, and Plane sanitizes it before +storing it. See [Page content HTML](/api-reference/page/page-content-html) for supported HTML and Plane editor +components. Locked or archived pages return `400`; document-service failures return `502`, and an unconfigured service +returns `503`. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The project UUID. + + + + +The page UUID. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +The new page title. + + + + +HTML that Plane sanitizes and uses to replace the current page content. + + + +At least one body parameter is required. + +
+
+ +
+ +### Scopes + +`write` or `projects.pages:write` + +
+ +
+ +
+ + + + + + + +```json +{ + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "Release notes", + "description_html": "

Current release notes

" +} +``` + + +
+ +
diff --git a/docs/api-reference/page/update-workspace-page.md b/docs/api-reference/page/update-workspace-page.md new file mode 100644 index 00000000..32b3a319 --- /dev/null +++ b/docs/api-reference/page/update-workspace-page.md @@ -0,0 +1,126 @@ +--- +title: Update a workspace page +description: Update the title or content of a workspace page via the Plane API. +keywords: plane, plane api, rest api, workspace page, update wiki page +--- + +# Update a workspace page + +
+ PUT + /api/v1/workspaces/{workspace_slug}/pages/{page_id}/ +
+ +
+
+ +Update a workspace page. Send `name`, `description_html`, or both. `description_html` replaces the page's current content rather than appending to it. Plane applies the mutation through its collaborative document service so API writes remain consistent with active editor sessions. Locked or archived pages cannot be updated. The API returns `502` when the collaborative document service cannot complete the update and `503` when that service is not configured. + +See [Page content HTML](/api-reference/page/page-content-html) for supported HTML and Plane editor components. + +
+ +### Path Parameters + +
+ + + +The workspace's unique slug. + + + + +The page UUID. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +The new page title. + + + + +HTML that replaces the current page content. + + + +At least one body parameter is required. + +
+
+ +
+ +### Scopes + +`write` or `wiki.pages:write` + +
+ +
+ +
+ + + + + + + + + +```json +{ + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "Release notes", + "description_html": "

Current release notes

" +} +``` + + +
+ +