---
title: "List workspace folders"
method: GET
path: "/v1/workspaces/{workspace_id}/folders"
tags: ["workspaces"]
---

# List workspace folders

`GET /v1/workspaces/{workspace_id}/folders`

## Request

- Base URL: `https://api.lovable.dev`
- URL: `https://api.lovable.dev/v1/workspaces/{workspace_id}/folders`
- Auth: one of:
  - API key in header `Lovable-API-Key`
  - HTTP bearer

**Plan:** `Business or higher`

**Scope:** `workspaces:read`

Returns the workspace's folders, sorted by name then id. Each project belongs to at most one folder; match a folder's id against the folder_id of GET /v1/projects and GET /v1/workspaces/{workspace_id}/security-center/insights/projects to group projects by folder, and filter either list with folder_id or is_in_folder. Restricted folders are returned only when the caller created them, was given access to them, or may manage every member's restricted folders. Reads are eventually consistent: recent changes may not appear immediately. Retry the read with backoff if an expected change is missing.

## Path parameters

- `workspace_id` string, required: Workspace ID.

## Query parameters

- `limit` integer: Maximum number of items to return per page.
- `cursor` string: Pass pagination.next_cursor from the previous response to fetch the next page. Omit for the first page; keep the same filters and sort order across pages.

## Headers

- `Lovable-Version` string
- `Lovable-Beta` string

## Response `200`

OK

- WorkspaceFolderPage
  - `data` WorkspaceFolder[], required: Items in this page. Empty when there are none.
    - `created_at` string, date-time, required: When the folder was created.
    - `id` string, required: Folder ID. Matches the folder_id of projects in the folder.
    - `name` string, required: Folder name.
    - `parent_id` string, nullable, required: ID of the folder this folder is nested in; null for a top-level folder.
    - `updated_at` string, date-time, required: When the folder was last renamed, moved, or had its visibility changed.
  - `pagination` Pagination, required
    - `has_more` boolean, required: Whether more results are available beyond this page.
    - `next_cursor` string, nullable, required: Pass this value as the cursor query parameter to fetch the next page. Treat it as an opaque string; null when there are no more results.

## Other responses

- `400`: The request body or parameters are malformed or fail validation. Each failing field is listed in errors.
- `401`: Missing or invalid API key, session token, or OAuth access token.
- `402`: Public API access requires Business or higher. Some operations or configurations require an additional feature entitlement.
- `403`: The key or caller lacks the required scope or permission. For email_not_verified, verify the account email before retrying.
- `404`: The workspace does not exist, has been deleted, or is outside the credential's workspace scope.
- `406`: The Accept header excludes every media type this endpoint produces.
- `429`: Too many requests. Retry after the interval in Retry-After when present.
- `503`: The service is temporarily unavailable, or the processing deadline expired (request_timeout). A mutation may still complete; check resource state before retrying.
- `default`: Error. The response body uses the standard error envelope; status matches the HTTP status code and type is a machine-readable error code.

## Changes

- **2026-11-05** `247d08b1bc5b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lovable/apis/lovable-api/changes/v1/workspaces/:workspace_id/folders/get.md)

---

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