List Sidebar Section Pages

When to use

Use this group of endpoints to reconstruct what a person sees in their sidebar. Typical uses are providing entry points to an automation, or locating a page when the user gave no link and only said "the one I favorited".

Compared with List Child Pages: that endpoint walks the directory level by level, while these return the top-level entry points grouped as the sidebar groups them.

Endpoint

Use GET /v2/workspace/pages when you need the whole sidebar directory. It returns favorites, team, shared, and private together. Each field is an independent paginated page-node list with its own has_more and next_cursor values.

The four section-specific endpoints remain available when only one section is needed. They share an identical response shape.

Permissions

Requires pages.read and a workspace-scoped credential. A page-scoped integration has no sidebar view and receives 403; after obtaining a known authorized page id, it may use List Child Pages to walk that granted subtree.

Call Get Workspace Overview first and read credential.resource_scope to determine which kind of credential you hold.

Request parameters

What each section means

The classification matches the product sidebar exactly; it is not a second set of rules.

For a general request such as "list the workspace directory" or "show the sidebar", use the grouped endpoint rather than GET /v2/pages without a parent. GET /v2/pages is the child-navigation operation and should be used with a known parent page.

Response

The grouped endpoint wraps four ordinary list responses:

{
  "object": "workspace_directory",
  "favorites": {
    "object": "list",
    "results": [],
    "next_cursor": null,
    "has_more": false
  },
  "team": {
    "object": "list",
    "results": [],
    "next_cursor": null,
    "has_more": false
  },
  "shared": {
    "object": "list",
    "results": [],
    "next_cursor": null,
    "has_more": false
  },
  "private": {
    "object": "list",
    "results": [],
    "next_cursor": null,
    "has_more": false
  }
}

Each section-specific endpoint returns one list directly:

{
  "object": "list",
  "results": [
    {
      "object": "page",
      "id": "11111111-1111-4111-8111-111111111111",
      "page_type": "page",
      "title": "Product docs",
      "icon": { "type": "emoji", "emoji": "📄" },
      "parent": { "type": "workspace", "workspace": true },
      "url": "https://buildin.ai/11111111-1111-4111-8111-111111111111",
      "created_time": "2026-04-09T09:30:00.000Z",
      "last_edited_time": "2026-04-10T02:15:00.000Z",
      "has_children": true
    }
  ],
  "next_cursor": null,
  "has_more": false
}

The node shape is the same as List Child Pages.

Behavior

• Sections answer "what does this person see", not "what exists in the workspace". Identity resolves to the user the integration acts for; a credential without one returns an empty list rather than an error.
• Guests have no team section. A guest identity calling team receives an empty list; the pages they can reach appear under shared.
• shared follows the user's own sidebar ordering first, with the remainder appended.
• favorites reflects the user's favorite ordering directly.
• Every returned page is checked for read access individually.
• Sections are entry views and do not drill down. To see a page's children, use List Child Pages.

Errors

• 400 validation_error: the section name is not one of the four values.
• 401 unauthorized: the token is invalid or expired.
• 403 forbidden: this credential is page-scoped and has no sidebar view.

Related

Prerequisites

• Authentication and Scopes
• Get Workspace Overview

Next steps

• List Child Pages
• Search Content

Reference

• Object Models
• Error Codes