List workspace folders

1. 1

   Create an API key with the workspaces:read scope in your Lovable workspace settings.

   This endpoint requires permission to read workspace data, or it will return an error.

2. 2

   Find your workspace ID and add it to the URL path /v1/workspaces/{workspace_id}/folders.

   Each API key is tied to a specific workspace, and the request must target that exact workspace.

3. 3

   Send a GET request to the URL including your API key in the Lovable-API-Key header or Authorization Bearer header.

   Authentication is mandatory to access your workspace's folders.

4. 4

   Use the cursor from pagination.next_cursor in your next request if pagination.has_more is true.

   The API returns results in pages of up to 100 items, so you must use cursors to fetch any remaining folders.

5. 5

   Match each folder's id to the folder_id field on your projects.

   Projects belong to at most one folder, allowing you to group or filter them accurately in your app.

Create a function to fetch workspace folders from the Lovable API using the GET /v1/workspaces/{workspace_id}/folders endpoint. Include the Lovable-API-Key header, handle pagination using the cursor query parameter and pagination.next_cursor, and display the retrieved folders sorted by name with their folder IDs.

Scope

A specific permission assigned to an API key determining what data it is allowed to view or change.

Cursor

A unique marker returned by the API that points to the start of the next page of results.

Eventually consistent

A delay where newly created or updated items take a few moments to appear in read requests.

• Your workspace must be on a Business plan or higher, or the request will fail with a 402 payment required error.
• Restricted folders will not appear in the response unless you created them, were granted access, or have permission to manage restricted folders.
• Newly created folders may not appear immediately due to eventual consistency; wait and retry if a fresh folder is missing.
• Passing an API key without the workspaces:read or workspaces:write scope will result in a 403 insufficient scope error.