# Projects

## List workspace projects

`client.projects.list(ProjectListParamsquery, RequestOptionsoptions?): ProjectsCursorPage<ProjectListResponse>`

**get** `/projects`

Returns projects in the requested workspace that are accessible to the authenticated public API key, ordered by recent activity.

### Parameters

- `query: ProjectListParams`

  - `workspace_id: string`

    Workspace identifier

  - `cursor?: string`

    Opaque cursor for fetching the next page

  - `limit?: number`

    Maximum number of results to return

  - `query?: string`

    Search query

### Returns

- `ProjectListResponse`

  - `created_at: number`

  - `last_modified: number | null`

  - `name: string`

    Project name

  - `origin: string | null`

    Project origin

  - `project_id: string`

    Project identifier

  - `workspace_id: string`

    Workspace identifier

### Example

```typescript
import Flora from '@flora-ai/flora';

const client = new Flora({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const projectListResponse of client.projects.list({ workspace_id: 'ws_abc123' })) {
  console.log(projectListResponse.project_id);
}
```

#### Response

```json
{
  "meta": {
    "next_cursor": "eyJvZmZzZXQiOjIwfQ",
    "total_estimate": 0
  },
  "projects": [
    {
      "created_at": 0,
      "last_modified": 0,
      "name": "Spring Campaign",
      "origin": "api",
      "project_id": "prj_abc123",
      "workspace_id": "ws_abc123"
    }
  ]
}
```

## Create a project

`client.projects.create(ProjectCreateParamsbody, RequestOptionsoptions?): ProjectCreateResponse`

**post** `/projects`

Creates a new Flora project in the requested workspace. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

### Parameters

- `body: ProjectCreateParams`

  - `name: string`

    Project name

  - `workspace_id: string`

    Workspace identifier

### Returns

- `ProjectCreateResponse`

  - `created_at: number`

  - `last_modified: number | null`

  - `name: string`

    Project name

  - `origin: string | null`

    Project origin

  - `project_id: string`

    Project identifier

  - `workspace_id: string`

    Workspace identifier

### Example

```typescript
import Flora from '@flora-ai/flora';

const client = new Flora({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

const project = await client.projects.create({
  name: 'Spring Campaign',
  workspace_id: 'ws_abc123',
});

console.log(project.project_id);
```

#### Response

```json
{
  "created_at": 0,
  "last_modified": 0,
  "name": "Spring Campaign",
  "origin": "api",
  "project_id": "prj_abc123",
  "workspace_id": "ws_abc123"
}
```

## Get a project

`client.projects.retrieve(stringprojectID, RequestOptionsoptions?): ProjectRetrieveResponse`

**get** `/projects/{projectId}`

Returns metadata for a single project when it is accessible to the authenticated public API key. Missing and inaccessible projects both return 404.

### Parameters

- `projectID: string`

  Project identifier

### Returns

- `ProjectRetrieveResponse`

  - `created_at: number`

  - `last_modified: number | null`

  - `name: string`

    Project name

  - `origin: string | null`

    Project origin

  - `project_id: string`

    Project identifier

  - `workspace_id: string`

    Workspace identifier

### Example

```typescript
import Flora from '@flora-ai/flora';

const client = new Flora({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

const project = await client.projects.retrieve('prj_abc123');

console.log(project.project_id);
```

#### Response

```json
{
  "created_at": 0,
  "last_modified": 0,
  "name": "Spring Campaign",
  "origin": "api",
  "project_id": "prj_abc123",
  "workspace_id": "ws_abc123"
}
```

## List project canvas nodes

`client.projects.listNodes(stringprojectID, ProjectListNodesParamsquery?, RequestOptionsoptions?): CanvasNodesCursorPage<ProjectListNodesResponse>`

**get** `/projects/{projectId}/nodes`

Returns sanitized visible media nodes on a project canvas. The response omits raw graph documents, Liveblocks internals, raw Convex IDs, and unbounded node data blobs.

### Parameters

- `projectID: string`

  Project identifier

- `query: ProjectListNodesParams`

  - `cursor?: string`

    Opaque cursor for fetching the next page

  - `limit?: number`

    Maximum number of results to return

### Returns

- `ProjectListNodesResponse`

  - `node_id: string`

    Canvas node identifier

  - `type: "image" | "video" | "audio" | "text"`

    Canvas node media type

    - `"image"`

    - `"video"`

    - `"audio"`

    - `"text"`

  - `asset_id?: string | null`

    Asset identifier

  - `height?: number | null`

  - `label?: string | null`

    Canvas node label

  - `url?: string | null`

    Canvas node output URL or text content

  - `width?: number | null`

### Example

```typescript
import Flora from '@flora-ai/flora';

const client = new Flora({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const projectListNodesResponse of client.projects.listNodes('prj_abc123')) {
  console.log(projectListNodesResponse.node_id);
}
```

#### Response

```json
{
  "canvas_url": "https://example.com",
  "meta": {
    "next_cursor": "eyJvZmZzZXQiOjIwfQ",
    "total_estimate": 0
  },
  "nodes": [
    {
      "node_id": "node_abc123",
      "type": "image",
      "asset_id": "asset_abc123",
      "height": 0,
      "label": "Logo",
      "url": "https://media.flora.ai/output.png",
      "width": 0
    }
  ],
  "project_id": "prj_abc123"
}
```

## Domain Types

### Project List Response

- `ProjectListResponse`

  - `created_at: number`

  - `last_modified: number | null`

  - `name: string`

    Project name

  - `origin: string | null`

    Project origin

  - `project_id: string`

    Project identifier

  - `workspace_id: string`

    Workspace identifier

### Project Create Response

- `ProjectCreateResponse`

  - `created_at: number`

  - `last_modified: number | null`

  - `name: string`

    Project name

  - `origin: string | null`

    Project origin

  - `project_id: string`

    Project identifier

  - `workspace_id: string`

    Workspace identifier

### Project Retrieve Response

- `ProjectRetrieveResponse`

  - `created_at: number`

  - `last_modified: number | null`

  - `name: string`

    Project name

  - `origin: string | null`

    Project origin

  - `project_id: string`

    Project identifier

  - `workspace_id: string`

    Workspace identifier

### Project List Nodes Response

- `ProjectListNodesResponse`

  - `node_id: string`

    Canvas node identifier

  - `type: "image" | "video" | "audio" | "text"`

    Canvas node media type

    - `"image"`

    - `"video"`

    - `"audio"`

    - `"text"`

  - `asset_id?: string | null`

    Asset identifier

  - `height?: number | null`

  - `label?: string | null`

    Canvas node label

  - `url?: string | null`

    Canvas node output URL or text content

  - `width?: number | null`

# Assets

## Attach an asset to a canvas

`client.projects.assets.attachAsset(stringassetID, AssetAttachAssetParamsparams, RequestOptionsoptions?): AssetAttachAssetResponse`

**post** `/projects/{projectId}/assets/{assetId}/attach`

Attaches an existing ready asset to a project canvas as a static media node. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

### Parameters

- `assetID: string`

  Asset identifier

- `params: AssetAttachAssetParams`

  - `projectId: string`

    Project identifier

### Returns

- `AssetAttachAssetResponse`

  - `asset_id: string`

    Asset identifier

  - `canvas_url: string`

    Project canvas URL

  - `node_id: string`

    Canvas node identifier

  - `project_id: string`

    Project identifier

### Example

```typescript
import Flora from '@flora-ai/flora';

const client = new Flora({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

const response = await client.projects.assets.attachAsset('asset_abc123', {
  projectId: 'prj_abc123',
});

console.log(response.asset_id);
```

#### Response

```json
{
  "asset_id": "asset_abc123",
  "canvas_url": "https://example.com",
  "node_id": "node_abc123",
  "project_id": "prj_abc123"
}
```

## Domain Types

### Asset Attach Asset Response

- `AssetAttachAssetResponse`

  - `asset_id: string`

    Asset identifier

  - `canvas_url: string`

    Project canvas URL

  - `node_id: string`

    Canvas node identifier

  - `project_id: string`

    Project identifier