---
title: "Browse datasource folders"
method: POST
path: "/api/v3/workspaces/datasource/browse"
tags: ["Workspaces"]
---

# Browse datasource folders

`POST /api/v3/workspaces/datasource/browse`

## Request

- Base URL: `https://api.lighton.ai`
- URL: `https://api.lighton.ai/api/v3/workspaces/datasource/browse`
- Auth: HTTP bearer

⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments.

Browse the remote folder hierarchy of a datasource without persisting anything.

Connects to the external provider using the credentials in the payload and returns the immediate subfolders of ``parent_id`` (or the top-level entries when ``parent_id`` is ``null``). Use this to power a visual folder picker before submitting a datasource configuration via `PATCH /api/v3/workspaces/{id}` with a `datasource` payload.

**Access:** any authenticated user.

Supported providers and credentials:
- **googledrive**: `service_account_file` (JSON string of the service account key file). When ``parent_id`` is omitted, returns the folders explicitly shared with the service account.
- **sharepoint**: `client_id`, `client_secret`, `tenant_id`, `instance_url`, `site_name`. When both ``drive_id`` and ``parent_id`` are ``null``, returns the site's document libraries as ``kind="library"`` entries (each entry's ``id`` is the drive id). Pass that ``id`` back as ``drive_id`` (with ``parent_id=null``) to list the library root; pass it as ``drive_id`` together with a folder's ``id`` as ``parent_id`` to descend into a folder.

## Request body

- WorkspaceDatasourceBrowseV3Request: Pydantic request model for browsing the remote folder hierarchy of a datasource. Only browsable providers (Google Drive, SharePoint) are accepted. Credentials are validated against the same models as the credential test endpoint.
  - `type` 'googledrive' | 'sharepoint', required
  - `credentials` object
  - `drive_id` string, nullable
  - `parent_id` string, nullable

## Response `200`

Folder listing

- WorkspaceDatasourceBrowseV3Response: V3 Response serializer for the datasource folder browse endpoint.
  - `folders` BrowseFolderItem[], required
    - `id` string, required: Provider folder identifier (SharePoint item id or Google Drive file id).
    - `name` string, required: Folder display name.
    - `has_children` boolean, required: Best-effort hint for the tree UI: True when the folder is known or assumed to contain subfolders.
    - `path` string, nullable: Full path from the drive root (SharePoint only). Null for Google Drive.
    - `drive_id` string, nullable: SharePoint drive containing the folder. Set for items returned inside a document library; null for library entries themselves and for Google Drive.
    - `kind` 'library' | 'folder': * `library` - library * `folder` - folder

## Other responses

- `400`: Bad Request - Invalid credentials or connection failure to the external datasource
- `401`: Authentication credentials were not provided or are invalid
- `422`: Request body is valid JSON but one or more fields failed validation
- `503`: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry.

## Changes

- **2026-11-03** `63ecbc61b6a9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lighton/apis/lighton-api/changes/api/v3/workspaces/datasource/browse/post.md)

---

[API](https://skmtc.dev/lighton/apis/lighton-api.md) - [All operations](https://skmtc.dev/lighton/apis/lighton-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lighton/apis/lighton-api/revisions/63ecbc61b6a9?raw)