Projects

Projects are the primary container for canvas state, sessions, files, and memory. Every project belongs to one workspace and may be additionally shared into more workspaces. Visibility is either team (everyone in the workspace) or private (creator only).

Endpoints

List projects

GET /api/v1/projects returns non-deleted projects in the caller's org, filtered by workspace scope and visibility. Side effect: project file folders are ensured to exist on first list.

Response item: project record with id, orgId, workspaceId, userId, name, description, prompt, emoji, visibility, status, tags, metadata, createdAt, updatedAt.

Create project

POST /api/v1/projects

When only description is supplied, the server generates a project name with the LLM and falls back to Untitled project on failure.

Response (201): the created project record. The matching project folder is provisioned in the file tree, and the project is linked to the active workspace.

curl -X POST https://alumia.com/api/v1/projects \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "Q3 launch", "visibility": "team" }'

Get project

GET /api/v1/projects/:id

Returns the project record plus:

• spend: total usage cost for this project.
• sharedWorkspaces: workspaces this project is linked into beyond its primary one.

:id accepts either UUID or slug.

Update project

PATCH /api/v1/projects/:id

Accepts any subset of: name, description, prompt, emoji, status ("active" | "archived" | "completed"), visibility ("team" | "private"), tags (max 30, each ≤80 chars), metadata (max 32 KB, max depth 12). Renaming the project also renames its protected folder.

Delete project

DELETE /api/v1/projects/:id — Soft-deletes the project, its folder tree, and project-owned records (transactionally). Returns:

{ "success": true, "data": { "deleted": true } }

Errors