---
title: "List projects"
method: GET
path: "/v1/projects"
tags: ["projects"]
---

# List projects

`GET /v1/projects`

**Plan:** `All plans`

Returns projects in a workspace, sorted by last edited time descending then project ID ascending. Pass workspace_id as a query parameter.

## Query parameters

- `workspace_id` string, required — Workspace ID
- `user_id` string — Filter by project creator user ID
- `visibility` 'personal' | 'workspace' | 'public' | 'all' — Filter by visibility
- `publish_status` 'any' | 'published' | 'internal' | 'external' | 'not_published' — Filter by publish status
- `folder_id` string — Filter by folder ID
- `folder_ids` string — Filter by multiple folder IDs (comma-separated, takes precedence over folder_id)
- `type` '' | 'project' | 'library' | 'template' | 'all' — Filter by project type. library returns design-system libraries; template returns non-library templates.
- `q` string — Search query
- `limit` integer — Maximum number of projects to return
- `cursor` string — Opaque pagination cursor returned by the previous page
- `viewed_by_me` boolean — Only return projects viewed by the current user
- `search_fields` '' | 'name' — Which fields to search: empty for all (default), 'name' for project name only

## Response `200`

OK

- CursorListResponsePublicV1ProjectListItem
  - `data` PublicV1ProjectListItem[], nullable, required
    - `created_at` string, date-time — When the project was created.
    - `description` string — Description supplied by the caller on create or update.
    - `display_name` string — Human-readable project name.
    - `folder_id` string — Folder the project belongs to, if any.
    - `generated_description` string — AI-written summary of what the project does. Absent until the agent has completed a response for the project.
    - `id` string, required — Project ID.
    - `is_published` boolean — Whether the project is published.
    - `last_edited_at` string, date-time — When the project was last edited.
    - `latest_screenshot_url` string — URL of the latest screenshot.
    - `name` string — Project slug.
    - `og_image_url` string — Open Graph image URL.
    - `project_type` string — Project type. One of: project, library. Absent on older projects. More values may be added; clients must tolerate unknown values.
    - `publish_visibility` string — Published visibility. One of: public, private. More values may be added; clients must tolerate unknown values.
    - `status` string — Provisioning status of the project, not agent build progress. 'completed' means the project scaffold was created, and is set before the agent has finished the initial message, so the code at that point is often an empty starter page. To check whether the agent finished building, poll GET /v1/messages/{message_id}. One of: in_progress, completed, failed. More values may be added; clients must tolerate unknown values.
    - `tech_stack` string — Project tech stack.
    - `updated_at` string, date-time — When the project was last updated.
    - `url` string — Published project URL.
    - `user_id` string — Project owner user ID.
    - `visibility` string — Project visibility: draft, private, workspace_view, or public.
    - `workspace_id` string, required — Workspace the project belongs to.
  - `pagination` Pagination, required
    - `has_more` boolean, required — Whether more results are available beyond this page
    - `next_cursor` string, nullable, required — Cursor for the next page; null when there are no more results

## Other responses

- `401` — Missing or invalid API key.
- `403` — The key or caller lacks the required scope or permission.
- `406` — The Accept header excludes every media type this endpoint produces.
- `429` — Too many requests. Retry after the interval in Retry-After when present.
- `default` — Error. The response body uses the standard error envelope; status matches the HTTP status code and type is a machine-readable error code.

---

[API](https://skmtc.net/lovable/apis/lovable-api.md) · [All operations](https://skmtc.net/lovable/apis/lovable-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lovable/lovable-api/revisions/aa8d44585147/schema)