From 52683bdb4d426750306faad33cc4249066a6a895 Mon Sep 17 00:00:00 2001 From: VipinDevelops Date: Tue, 18 Aug 2026 17:44:41 +0530 Subject: [PATCH 1/4] docs: document page and collection APIs (WIKI-1068) Amp-Thread-ID: https://ampcode.com/threads/T-01a01474-ee79-71e2-8c99-05d2b6b0cddf Co-authored-by: Amp --- docs/.vitepress/config.mts | 75 +++++++- .../assets/create-workspace-asset-upload.md | 26 ++- .../collection/add-collection-member.md | 76 ++++++++ .../collection/add-collection-pages.md | 86 +++++++++ .../collection/create-collection.md | 87 +++++++++ .../collection/delete-collection.md | 62 ++++++ .../collection/list-collection-members.md | 66 +++++++ .../collection/list-collection-pages.md | 108 +++++++++++ .../collection/list-collections.md | 81 ++++++++ .../move-or-reorder-collection-page.md | 81 ++++++++ docs/api-reference/collection/overview.md | 45 +++++ .../collection/remove-collection-member.md | 55 ++++++ .../collection/remove-collection-page.md | 56 ++++++ .../collection/retrieve-collection.md | 71 +++++++ .../collection/search-collection-pages.md | 66 +++++++ .../collection/update-collection-member.md | 74 ++++++++ .../collection/update-collection.md | 83 ++++++++ docs/api-reference/page/add-workspace-page.md | 27 ++- .../page/archive-project-page.md | 51 +++++ .../page/archive-workspace-page.md | 51 +++++ ...onfirm-workspace-page-attachment-upload.md | 59 ++++++ .../api-reference/page/delete-project-page.md | 51 +++++ .../page/delete-workspace-page-attachment.md | 51 +++++ .../page/delete-workspace-page.md | 51 +++++ .../download-workspace-page-attachment.md | 53 ++++++ .../page/get-workspace-page-attachment.md | 69 +++++++ docs/api-reference/page/overview.md | 22 ++- docs/api-reference/page/page-content-html.md | 177 ++++++++++++++++++ .../page/restore-project-page.md | 51 +++++ .../page/restore-workspace-page.md | 51 +++++ .../api-reference/page/update-project-page.md | 75 ++++++++ .../page/update-workspace-page.md | 81 ++++++++ 32 files changed, 2108 insertions(+), 10 deletions(-) create mode 100644 docs/api-reference/collection/add-collection-member.md create mode 100644 docs/api-reference/collection/add-collection-pages.md create mode 100644 docs/api-reference/collection/create-collection.md create mode 100644 docs/api-reference/collection/delete-collection.md create mode 100644 docs/api-reference/collection/list-collection-members.md create mode 100644 docs/api-reference/collection/list-collection-pages.md create mode 100644 docs/api-reference/collection/list-collections.md create mode 100644 docs/api-reference/collection/move-or-reorder-collection-page.md create mode 100644 docs/api-reference/collection/overview.md create mode 100644 docs/api-reference/collection/remove-collection-member.md create mode 100644 docs/api-reference/collection/remove-collection-page.md create mode 100644 docs/api-reference/collection/retrieve-collection.md create mode 100644 docs/api-reference/collection/search-collection-pages.md create mode 100644 docs/api-reference/collection/update-collection-member.md create mode 100644 docs/api-reference/collection/update-collection.md create mode 100644 docs/api-reference/page/archive-project-page.md create mode 100644 docs/api-reference/page/archive-workspace-page.md create mode 100644 docs/api-reference/page/confirm-workspace-page-attachment-upload.md create mode 100644 docs/api-reference/page/delete-project-page.md create mode 100644 docs/api-reference/page/delete-workspace-page-attachment.md create mode 100644 docs/api-reference/page/delete-workspace-page.md create mode 100644 docs/api-reference/page/download-workspace-page-attachment.md create mode 100644 docs/api-reference/page/get-workspace-page-attachment.md create mode 100644 docs/api-reference/page/page-content-html.md create mode 100644 docs/api-reference/page/restore-project-page.md create mode 100644 docs/api-reference/page/restore-workspace-page.md create mode 100644 docs/api-reference/page/update-project-page.md create mode 100644 docs/api-reference/page/update-workspace-page.md 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..2b4711cf 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 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..badcb16d --- /dev/null +++ b/docs/api-reference/collection/add-collection-member.md @@ -0,0 +1,76 @@ +--- +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). + +### OAuth scope + +`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..e5745d42 --- /dev/null +++ b/docs/api-reference/collection/add-collection-pages.md @@ -0,0 +1,86 @@ +--- +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`. + +### OAuth scope + +`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..f0651b98 --- /dev/null +++ b/docs/api-reference/collection/create-collection.md @@ -0,0 +1,87 @@ +--- +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. + +### OAuth scope + +`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..be17c23b --- /dev/null +++ b/docs/api-reference/collection/delete-collection.md @@ -0,0 +1,62 @@ +--- +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`. + +### OAuth scope + +`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..e2393a8c --- /dev/null +++ b/docs/api-reference/collection/list-collection-members.md @@ -0,0 +1,66 @@ +--- +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. + +### OAuth scope + +`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..c0aa3c09 --- /dev/null +++ b/docs/api-reference/collection/list-collection-pages.md @@ -0,0 +1,108 @@ +--- +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. + +### OAuth scope + +`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..d67efada --- /dev/null +++ b/docs/api-reference/collection/list-collections.md @@ -0,0 +1,81 @@ +--- +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. + +### OAuth scope + +`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..f5271789 --- /dev/null +++ b/docs/api-reference/collection/move-or-reorder-collection-page.md @@ -0,0 +1,81 @@ +--- +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`. + +### OAuth scope + +`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..86d8c748 --- /dev/null +++ b/docs/api-reference/collection/overview.md @@ -0,0 +1,45 @@ +--- +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. 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..c6b12e83 --- /dev/null +++ b/docs/api-reference/collection/remove-collection-member.md @@ -0,0 +1,55 @@ +--- +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. + +### OAuth scope + +`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..4653aa33 --- /dev/null +++ b/docs/api-reference/collection/remove-collection-page.md @@ -0,0 +1,56 @@ +--- +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. + +### OAuth scope + +`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..ced696a5 --- /dev/null +++ b/docs/api-reference/collection/retrieve-collection.md @@ -0,0 +1,71 @@ +--- +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. + +### OAuth scope + +`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..73e238b8 --- /dev/null +++ b/docs/api-reference/collection/search-collection-pages.md @@ -0,0 +1,66 @@ +--- +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. + +### OAuth scope + +`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..24035839 --- /dev/null +++ b/docs/api-reference/collection/update-collection-member.md @@ -0,0 +1,74 @@ +--- +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). + +### OAuth scope + +`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..50a2701f --- /dev/null +++ b/docs/api-reference/collection/update-collection.md @@ -0,0 +1,83 @@ +--- +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. + +### OAuth scope + +`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..93bc2c3b --- /dev/null +++ b/docs/api-reference/page/archive-project-page.md @@ -0,0 +1,51 @@ +--- +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..8905dc28 --- /dev/null +++ b/docs/api-reference/page/archive-workspace-page.md @@ -0,0 +1,51 @@ +--- +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..e30a9204 --- /dev/null +++ b/docs/api-reference/page/confirm-workspace-page-attachment-upload.md @@ -0,0 +1,59 @@ +--- +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..c9ded493 --- /dev/null +++ b/docs/api-reference/page/delete-project-page.md @@ -0,0 +1,51 @@ +--- +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..00927425 --- /dev/null +++ b/docs/api-reference/page/delete-workspace-page-attachment.md @@ -0,0 +1,51 @@ +--- +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..2aded9bd --- /dev/null +++ b/docs/api-reference/page/delete-workspace-page.md @@ -0,0 +1,51 @@ +--- +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..c91a7de7 --- /dev/null +++ b/docs/api-reference/page/download-workspace-page-attachment.md @@ -0,0 +1,53 @@ +--- +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..9299fdf3 --- /dev/null +++ b/docs/api-reference/page/get-workspace-page-attachment.md @@ -0,0 +1,69 @@ +--- +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..5a4e4189 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 +
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..d103ec22 --- /dev/null +++ b/docs/api-reference/page/restore-project-page.md @@ -0,0 +1,51 @@ +--- +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..528a8965 --- /dev/null +++ b/docs/api-reference/page/restore-workspace-page.md @@ -0,0 +1,51 @@ +--- +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..e34bc199 --- /dev/null +++ b/docs/api-reference/page/update-project-page.md @@ -0,0 +1,75 @@ +--- +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. 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 replaces 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..ebc112db --- /dev/null +++ b/docs/api-reference/page/update-workspace-page.md @@ -0,0 +1,81 @@ +--- +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

" +} +``` + + +
From b290070cc98d403870b300fff8734edff45f2d67 Mon Sep 17 00:00:00 2001 From: VipinDevelops Date: Tue, 18 Aug 2026 19:08:20 +0530 Subject: [PATCH 2/4] docs: align page API docs with site conventions Amp-Thread-ID: https://ampcode.com/threads/T-01a01474-ee79-71e2-8c99-05d2b6b0cddf Co-authored-by: Amp --- .../assets/create-workspace-asset-upload.md | 2 +- .../collection/add-collection-member.md | 74 ++++++++-- .../collection/add-collection-pages.md | 80 +++++++++-- .../collection/create-collection.md | 71 +++++++-- .../collection/delete-collection.md | 68 +++++++-- .../collection/list-collection-members.md | 55 +++++-- .../collection/list-collection-pages.md | 136 ++++++++++++++---- .../collection/list-collections.md | 46 ++++-- .../move-or-reorder-collection-page.md | 86 +++++++++-- docs/api-reference/collection/overview.md | 8 ++ .../collection/remove-collection-member.md | 61 ++++++-- .../collection/remove-collection-page.md | 61 ++++++-- .../collection/retrieve-collection.md | 55 +++++-- .../collection/search-collection-pages.md | 68 +++++++-- .../collection/update-collection-member.md | 74 ++++++++-- .../collection/update-collection.md | 80 +++++++++-- .../page/archive-project-page.md | 63 ++++++-- .../page/archive-workspace-page.md | 57 ++++++-- ...onfirm-workspace-page-attachment-upload.md | 76 ++++++++-- .../api-reference/page/delete-project-page.md | 63 ++++++-- .../page/delete-workspace-page-attachment.md | 63 ++++++-- .../page/delete-workspace-page.md | 57 ++++++-- .../download-workspace-page-attachment.md | 63 ++++++-- .../page/get-workspace-page-attachment.md | 57 ++++++-- docs/api-reference/page/overview.md | 7 +- .../page/restore-project-page.md | 63 ++++++-- .../page/restore-workspace-page.md | 57 ++++++-- .../api-reference/page/update-project-page.md | 81 +++++++++-- .../page/update-workspace-page.md | 67 +++++++-- 29 files changed, 1476 insertions(+), 323 deletions(-) diff --git a/docs/api-reference/assets/create-workspace-asset-upload.md b/docs/api-reference/assets/create-workspace-asset-upload.md index 2b4711cf..981081cf 100644 --- a/docs/api-reference/assets/create-workspace-asset-upload.md +++ b/docs/api-reference/assets/create-workspace-asset-upload.md @@ -70,7 +70,7 @@ Asset context. Use `PAGE_DESCRIPTION` for a workspace page attachment. -UUID of the workspace page when `entity_type` is `PAGE_DESCRIPTION`. +UUID of the workspace page. This value is required when `entity_type` is `PAGE_DESCRIPTION`. diff --git a/docs/api-reference/collection/add-collection-member.md b/docs/api-reference/collection/add-collection-member.md index badcb16d..1b0e896e 100644 --- a/docs/api-reference/collection/add-collection-member.md +++ b/docs/api-reference/collection/add-collection-member.md @@ -6,28 +6,69 @@ keywords: plane, plane api, rest api, collection members, add member, private co # Add a collection member -
POST/api/v1/workspaces/{workspace_slug}/collections/{collection_id}/members/
+
+ 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. +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
### Body Parameters -The workspace user's ID. -`0` (view, default), `1` (comment), or `2` (edit). +
+ + + +The workspace user's ID. -### OAuth scope + + + +`0` (view, default), `1` (comment), or `2` (edit). + + + +
+
+ +
+ +### Scopes `write` or `wiki.pages:write` -
- + ```json @@ -73,4 +117,8 @@ console.log(await response.json()); } ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/add-collection-pages.md b/docs/api-reference/collection/add-collection-pages.md index e5745d42..a5035373 100644 --- a/docs/api-reference/collection/add-collection-pages.md +++ b/docs/api-reference/collection/add-collection-pages.md @@ -6,33 +6,78 @@ keywords: plane, plane api, rest api, collection pages, add pages, page placemen # Add pages to a collection -
POST/api/v1/workspaces/{workspace_slug}/collections/{collection_id}/pages/
+
+ 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. +
+ + + +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. +
+ + + +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`. -### OAuth scope +
+
+ +
+ +### Scopes `write` or `wiki.pages:write` -
- + ```json @@ -83,4 +131,8 @@ console.log(await response.json()); ] ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/create-collection.md b/docs/api-reference/collection/create-collection.md index f0651b98..13f09e1c 100644 --- a/docs/api-reference/collection/create-collection.md +++ b/docs/api-reference/collection/create-collection.md @@ -6,28 +6,68 @@ keywords: plane, plane api, rest api, collections, create collection, private co # Create a collection -
POST/api/v1/workspaces/{workspace_slug}/collections/
+
+ 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. +
+ + + +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. +
+ + + +The collection name. Defaults to an empty string. + + + + +`0` for public (default) or `1` for private. -### OAuth scope + + + +Logo or emoji properties. Defaults to an empty object. + + + +
+
+ +
+ +### Scopes `write` or `wiki.pages:write` -
+
+ +
+ +
+ + + + ```json @@ -84,4 +127,8 @@ console.log(await response.json()); } ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/delete-collection.md b/docs/api-reference/collection/delete-collection.md index be17c23b..e5b8365e 100644 --- a/docs/api-reference/collection/delete-collection.md +++ b/docs/api-reference/collection/delete-collection.md @@ -6,35 +6,73 @@ keywords: plane, plane api, rest api, collections, delete collection, archive pa # Delete a collection -
DELETE/api/v1/workspaces/{workspace_slug}/collections/{collection_id}/
+
+ 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. +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
### Query Parameters -Whether to archive contained pages. Defaults to `true`. +
+ + -### OAuth scope +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 index e2393a8c..2a31d2cc 100644 --- a/docs/api-reference/collection/list-collection-members.md +++ b/docs/api-reference/collection/list-collection-members.md @@ -6,29 +6,56 @@ keywords: plane, plane api, rest api, collection members, list members # List collection members -
GET/api/v1/workspaces/{workspace_slug}/collections/{collection_id}/members/
+
+ GET + /api/v1/workspaces/{workspace_slug}/collections/{collection_id}/members/ +
-
+
+
Returns explicit collection memberships. +
+ ### Path Parameters -The workspace slug. -The collection ID. +
+ + + +The workspace slug. + + + + +The collection ID. + + -### OAuth scope +
+
+ +
+ +### Scopes `read` or `wiki.pages:read` -
- + ```json @@ -63,4 +92,8 @@ console.log(await response.json()); ] ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/list-collection-pages.md b/docs/api-reference/collection/list-collection-pages.md index c0aa3c09..59da6dfc 100644 --- a/docs/api-reference/collection/list-collection-pages.md +++ b/docs/api-reference/collection/list-collection-pages.md @@ -6,46 +6,128 @@ 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/
+
+ 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. +
+ + + +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. - -### OAuth scope +
+ + + +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 @@ -105,4 +189,8 @@ console.log(await response.json()); } ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/list-collections.md b/docs/api-reference/collection/list-collections.md index d67efada..936c0d0d 100644 --- a/docs/api-reference/collection/list-collections.md +++ b/docs/api-reference/collection/list-collections.md @@ -6,22 +6,43 @@ keywords: plane, plane api, rest api, collections, list collections, wiki # List collections -
GET/api/v1/workspaces/{workspace_slug}/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. +
+ + + +The workspace slug. + + + +
+
-### OAuth scope +
+ +### Scopes `read` or `wiki.pages:read` -
+
+ +
+ +
+ + + + @@ -78,4 +102,8 @@ console.log(await response.json()); ] ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/move-or-reorder-collection-page.md b/docs/api-reference/collection/move-or-reorder-collection-page.md index f5271789..f94a69ae 100644 --- a/docs/api-reference/collection/move-or-reorder-collection-page.md +++ b/docs/api-reference/collection/move-or-reorder-collection-page.md @@ -6,33 +6,82 @@ 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}/
+
+ 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. +
+ + + +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`. +
+ + + +A destination collection ID. Omit or use the source ID to reorder in place. -### OAuth scope + + + +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 @@ -78,4 +130,8 @@ console.log(await response.json()); } ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/overview.md b/docs/api-reference/collection/overview.md index 86d8c748..825c02dc 100644 --- a/docs/api-reference/collection/overview.md +++ b/docs/api-reference/collection/overview.md @@ -43,3 +43,11 @@ 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 index c6b12e83..d4c52f43 100644 --- a/docs/api-reference/collection/remove-collection-member.md +++ b/docs/api-reference/collection/remove-collection-member.md @@ -6,30 +6,61 @@ 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}/
+
+ 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. +
+ + + +The workspace slug. + + + + +The collection ID. + + + + +The collection membership ID. -### OAuth scope + + +
+
+ +
+ +### 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 index 4653aa33..419f7be4 100644 --- a/docs/api-reference/collection/remove-collection-page.md +++ b/docs/api-reference/collection/remove-collection-page.md @@ -6,31 +6,62 @@ 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}/
+
+ 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. +
+ + + +The workspace slug. + + + + +The collection ID. + + + + +The page membership ID returned as `page_collection_id` by the list endpoint. -### OAuth scope + + +
+
+ +
+ +### 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 index ced696a5..cf1a2e22 100644 --- a/docs/api-reference/collection/retrieve-collection.md +++ b/docs/api-reference/collection/retrieve-collection.md @@ -6,30 +6,57 @@ keywords: plane, plane api, rest api, collections, retrieve collection # Retrieve a collection -
GET/api/v1/workspaces/{workspace_slug}/collections/{collection_id}/
+
+ 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. +
+ + + +The workspace slug. + + + + +The collection ID. + + -### OAuth scope +
+
+ +
+ +### Scopes `read` or `wiki.pages:read` -
- + ```json @@ -68,4 +97,8 @@ console.log(await response.json()); } ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/search-collection-pages.md b/docs/api-reference/collection/search-collection-pages.md index 73e238b8..530467fa 100644 --- a/docs/api-reference/collection/search-collection-pages.md +++ b/docs/api-reference/collection/search-collection-pages.md @@ -6,35 +6,73 @@ keywords: plane, plane api, rest api, collection pages, search pages, addable pa # Search addable collection pages -
GET/api/v1/workspaces/{workspace_slug}/collections/{collection_id}/pages-search/
+
+ 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. +
+ + + +The workspace slug. + + + + +The destination collection ID. + + + +
+
+ +
### Query Parameters -A page-name search string. +
+ + -### OAuth scope +A page-name search string. + + + +
+
+ +
+ +### Scopes `read` or `wiki.pages:read` -
- + ```json @@ -63,4 +103,8 @@ console.log(await response.json()); ] ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/update-collection-member.md b/docs/api-reference/collection/update-collection-member.md index 24035839..905d817e 100644 --- a/docs/api-reference/collection/update-collection-member.md +++ b/docs/api-reference/collection/update-collection-member.md @@ -6,35 +6,77 @@ 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}/
+
+ 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. +
+ + + +The workspace slug. + + + + +The collection ID. + + + + +The collection membership ID. + + + +
+
+ +
### Body Parameters -`0` (view), `1` (comment), or `2` (edit). +
-### OAuth scope + + +`0` (view), `1` (comment), or `2` (edit). + + + +
+
+ +
+ +### Scopes `write` or `wiki.pages:write` -
- + ```json @@ -71,4 +115,8 @@ console.log(await response.json()); } ``` -
+ + +
+ +
diff --git a/docs/api-reference/collection/update-collection.md b/docs/api-reference/collection/update-collection.md index 50a2701f..a75e0253 100644 --- a/docs/api-reference/collection/update-collection.md +++ b/docs/api-reference/collection/update-collection.md @@ -6,29 +6,74 @@ keywords: plane, plane api, rest api, collections, update collection # Update a collection -
PATCH/api/v1/workspaces/{workspace_slug}/collections/{collection_id}/
+
+ 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. +
+ + + +The workspace slug. + + + + +The collection ID. + + + +
+
+ +
### Body Parameters -A new collection name. -New logo or emoji properties. -The collection's ordering value. +
+ + + +A new collection name. + + + -### OAuth scope +New logo or emoji properties. + + + + +The collection's ordering value. + + + +
+
+ +
+ +### Scopes `write` or `wiki.pages:write` -
- + ```json @@ -80,4 +128,8 @@ console.log(await response.json()); } ``` -
+ + +
+ +
diff --git a/docs/api-reference/page/archive-project-page.md b/docs/api-reference/page/archive-project-page.md index 93bc2c3b..fe9e2a93 100644 --- a/docs/api-reference/page/archive-project-page.md +++ b/docs/api-reference/page/archive-project-page.md @@ -6,30 +6,61 @@ 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/
+
+ 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. +
+ + + +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 index 8905dc28..3de6685b 100644 --- a/docs/api-reference/page/archive-workspace-page.md +++ b/docs/api-reference/page/archive-workspace-page.md @@ -6,29 +6,56 @@ keywords: plane, plane api, workspace page, archive wiki page # Archive a workspace page -
POST/api/v1/workspaces/{workspace_slug}/pages/{page_id}/archive/
+
+ 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. +
+ + + +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 index e30a9204..9eaf8293 100644 --- a/docs/api-reference/page/confirm-workspace-page-attachment-upload.md +++ b/docs/api-reference/page/confirm-workspace-page-attachment-upload.md @@ -6,34 +6,76 @@ 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}/
+
+ 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. +
+ + + +The workspace's unique slug. + + + + +The workspace page UUID. + + + + +The attachment asset UUID. + + + +
+
+ +
### Body Parameters -Whether the attachment was uploaded successfully. Defaults to `true`. +
+ + + +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 index c9ded493..aa200ec6 100644 --- a/docs/api-reference/page/delete-project-page.md +++ b/docs/api-reference/page/delete-project-page.md @@ -6,30 +6,61 @@ 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 + /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. +
+ + + +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 index 00927425..d79555e0 100644 --- a/docs/api-reference/page/delete-workspace-page-attachment.md +++ b/docs/api-reference/page/delete-workspace-page-attachment.md @@ -6,30 +6,61 @@ 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}/
+
+ 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. +
+ + + +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 index 2aded9bd..6e759b64 100644 --- a/docs/api-reference/page/delete-workspace-page.md +++ b/docs/api-reference/page/delete-workspace-page.md @@ -6,29 +6,56 @@ keywords: plane, plane api, workspace page, delete wiki page # Delete a workspace page -
DELETE/api/v1/workspaces/{workspace_slug}/pages/{page_id}/
+
+ 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. +
+ + + +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 index c91a7de7..a23161cb 100644 --- a/docs/api-reference/page/download-workspace-page-attachment.md +++ b/docs/api-reference/page/download-workspace-page-attachment.md @@ -6,30 +6,61 @@ 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/
+
+ 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. +
+ + + +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 index 9299fdf3..b568d91a 100644 --- a/docs/api-reference/page/get-workspace-page-attachment.md +++ b/docs/api-reference/page/get-workspace-page-attachment.md @@ -6,30 +6,61 @@ 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}/
+
+ 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. +
+ + + +The workspace's unique slug. + + + + +The workspace page UUID. + + + + +The attachment asset UUID. + + + +
+
+ +
### Scopes `read` or `wiki.pages:read` -
- + ```json @@ -66,4 +99,6 @@ const data = await response.json(); ``` -
+
+ +
diff --git a/docs/api-reference/page/overview.md b/docs/api-reference/page/overview.md index 5a4e4189..c088d5cb 100644 --- a/docs/api-reference/page/overview.md +++ b/docs/api-reference/page/overview.md @@ -78,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/restore-project-page.md b/docs/api-reference/page/restore-project-page.md index d103ec22..8326b426 100644 --- a/docs/api-reference/page/restore-project-page.md +++ b/docs/api-reference/page/restore-project-page.md @@ -6,30 +6,61 @@ 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/
+
+ 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. +
+ + + +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 index 528a8965..76111b09 100644 --- a/docs/api-reference/page/restore-workspace-page.md +++ b/docs/api-reference/page/restore-workspace-page.md @@ -6,29 +6,56 @@ keywords: plane, plane api, workspace page, restore wiki page, unarchive # Restore a workspace page -
DELETE/api/v1/workspaces/{workspace_slug}/pages/{page_id}/archive/
+
+ 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. +
+ + + +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 index e34bc199..3a58c73e 100644 --- a/docs/api-reference/page/update-project-page.md +++ b/docs/api-reference/page/update-project-page.md @@ -6,31 +6,79 @@ keywords: plane, plane api, project page, update page # Update a project page -
PUT/api/v1/workspaces/{workspace_slug}/projects/{project_id}/pages/{page_id}/
+
+ PUT + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/pages/{page_id}/ +
-
+
+
-Send `name`, `description_html`, or both. `description_html` replaces the current content. Locked or archived pages return `400`; document-service failures return `502`, and an unconfigured service returns `503`. +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. +
+ + + +The workspace's unique slug. + + + + +The project UUID. + + + + +The page UUID. + + + +
+
+ +
### Body Parameters -The new page title. -HTML that replaces the current page content. +
+ + + +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 @@ -72,4 +123,6 @@ const data = await response.json(); ``` -
+
+ +
diff --git a/docs/api-reference/page/update-workspace-page.md b/docs/api-reference/page/update-workspace-page.md index ebc112db..32b3a319 100644 --- a/docs/api-reference/page/update-workspace-page.md +++ b/docs/api-reference/page/update-workspace-page.md @@ -6,31 +6,71 @@ keywords: plane, plane api, rest api, workspace page, update wiki page # Update a workspace page -
PUT/api/v1/workspaces/{workspace_slug}/pages/{page_id}/
+
+ 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. +
+ + + +The workspace's unique slug. + + + + +The page UUID. + + + +
+
+ +
### Body Parameters -The new page title. -HTML that replaces the current page content. +
+ + + +The new page title. + + + + +HTML that replaces the current page content. + + At least one body parameter is required. +
+
+ +
+ ### Scopes `write` or `wiki.pages:write` -
+
+ +
+ +
+ + + + @@ -78,4 +121,6 @@ const data = await response.json(); ``` -
+
+ +
From c8e8c2f4d5646a15d74daee33e78668d65aceab0 Mon Sep 17 00:00:00 2001 From: VipinDevelops Date: Thu, 20 Aug 2026 18:59:03 +0530 Subject: [PATCH 3/4] docs: address page API review feedback Amp-Thread-ID: https://ampcode.com/threads/T-01a01474-ee79-71e2-8c99-05d2b6b0cddf Co-authored-by: Amp --- .../assets/create-workspace-asset-upload.md | 5 ++- .../collection/add-collection-member.md | 3 +- .../collection/add-collection-pages.md | 3 ++ .../collection/create-collection.md | 3 +- .../collection/delete-collection.md | 3 +- .../collection/list-collection-members.md | 3 +- docs/api-reference/page/add-workspace-page.md | 3 +- .../download-workspace-page-attachment.md | 41 ++++++++++++++++--- .../page/get-workspace-page-attachment.md | 3 +- docs/api-reference/page/page-content-html.md | 2 +- .../page/restore-project-page.md | 3 +- .../page/restore-workspace-page.md | 3 +- .../api-reference/page/update-project-page.md | 3 +- .../page/update-workspace-page.md | 3 +- 14 files changed, 63 insertions(+), 18 deletions(-) diff --git a/docs/api-reference/assets/create-workspace-asset-upload.md b/docs/api-reference/assets/create-workspace-asset-upload.md index 981081cf..f704e691 100644 --- a/docs/api-reference/assets/create-workspace-asset-upload.md +++ b/docs/api-reference/assets/create-workspace-asset-upload.md @@ -64,13 +64,14 @@ UUID of the project to associate with the asset -Asset context. Use `PAGE_DESCRIPTION` for a workspace page attachment. +Asset context. Use `PAGE_DESCRIPTION` for a workspace page attachment; when you do, `entity_identifier` is also +required. -UUID of the workspace page. This value is required when `entity_type` is `PAGE_DESCRIPTION`. +UUID of the workspace page. This value and `entity_type` are required together for a `PAGE_DESCRIPTION` attachment. diff --git a/docs/api-reference/collection/add-collection-member.md b/docs/api-reference/collection/add-collection-member.md index 1b0e896e..c3f38a2a 100644 --- a/docs/api-reference/collection/add-collection-member.md +++ b/docs/api-reference/collection/add-collection-member.md @@ -90,10 +90,11 @@ print(response.json())