> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/guides/projects.md).

# Projects

Create, list, read and rename FLORA projects with the API, list the nodes on a project's canvas, and attach assets to it.

Projects group work inside a workspace: each one is a canvas where generations and assets appear as nodes. Pass a project's `project_id` (`prj_...`) when you start a [generation](https://docs.flora.ai/api/guides/generations.md) or upload an [asset](https://docs.flora.ai/api/guides/assets.md) so the results land together in FLORA.

## List projects

```bash
curl "https://app.flora.ai/api/v1/projects?workspace_id=ws_abc123&limit=10" \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

Response:

```json
{
  "projects": [
    {
      "project_id": "prj_abc123",
      "name": "Campaign concepts",
      "workspace_id": "ws_abc123",
      "is_private": false,
      "created_at": 1760000000000
    }
  ],
  "meta": { "next_cursor": null }
}
```

`workspace_id` is required. By default you get the projects you created; `visibility` narrows to your private projects or widens to every member's shared canvases, and `query` filters by name. Page with `cursor`.

## Create a project

```bash
curl -X POST https://app.flora.ai/api/v1/workspaces/ws_abc123/projects \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Campaign concepts" }'
```

`POST /workspaces/{workspaceId}/projects` names the workspace in the path, which is clearer when your key reaches several workspaces. `POST /projects` with `workspace_id` and `name` in the body does the same. To file the project in a folder, use `POST /workspaces/{workspaceId}/folders/{folderId}/projects`.

Creating a project needs **write** permission on the workspace; without it the API returns `403 forbidden`.

With the TypeScript SDK:

```ts
import { FloraClient } from "@flora-ai/flora"

const client = new FloraClient()

const project = await client.projects.create({ workspace_id: "ws_abc123", name: "Campaign concepts" })
console.log(project.project_id)
```

## Retrieve or rename a project

```bash
curl https://app.flora.ai/api/v1/projects/prj_abc123 \
  -H "Authorization: Bearer $FLORA_API_KEY"

curl -X PATCH https://app.flora.ai/api/v1/projects/prj_abc123 \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Campaign concepts v2" }'
```

`name` is the only field `PATCH` changes. Missing projects and projects your key can't see both return `404`.

Every project has a `copy_status`. A project copied in the app to another workspace is `copying` while its canvas and media are still being written, and can't be opened yet. It becomes `ready` when the copy finishes, or `failed` if it didn't; retry or delete a failed copy in the app. Every other project is `ready`.

## List the nodes on a canvas

```bash
curl https://app.flora.ai/api/v1/projects/prj_abc123/nodes \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

This returns the visible media nodes on the project's canvas, with their IDs. Use a node's ID in `reference_node_ids` to feed its output into a [generation](https://docs.flora.ai/api/guides/generations.md).

## Attach an asset to a project

After you upload an asset, attach it so it appears on the canvas:

```bash
curl -X POST https://app.flora.ai/api/v1/projects/prj_abc123/assets/asset_abc123/attach \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

You can skip this step by passing `project_id` when you create the asset.

## Common endpoints

| Method | Path                                            | Description                                                                                               |
| ------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| GET    | `/projects?workspace_id={workspace_id}`         | [List projects](https://docs.flora.ai/api/reference/projects/listprojects.md)                             |
| POST   | `/workspaces/{workspaceId}/projects`            | [Create a project in a workspace](https://docs.flora.ai/api/reference/projects/createworkspaceproject.md) |
| POST   | `/projects`                                     | [Create a project (workspace in the body)](https://docs.flora.ai/api/reference/projects/createproject.md) |
| GET    | `/projects/{projectId}`                         | [Retrieve a project](https://docs.flora.ai/api/reference/projects/getproject.md)                          |
| PATCH  | `/projects/{projectId}`                         | [Rename a project](https://docs.flora.ai/api/reference/projects/updateproject.md)                         |
| GET    | `/projects/{projectId}/nodes`                   | [List canvas nodes](https://docs.flora.ai/api/reference/canvas/listcanvasnodes.md)                        |
| POST   | `/projects/{projectId}/assets/{assetId}/attach` | [Attach an asset](https://docs.flora.ai/api/reference/canvas/attachcanvasasset.md)                        |

Sharing, comments and canvas editing endpoints are in the [FLORA API reference](https://docs.flora.ai/api/reference.md).

## Notes

* Project IDs start with `prj_`.
* Permission-sensitive operations can return `403 forbidden`; see [Errors](https://docs.flora.ai/api/platform/errors.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/guides/projects.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
