Projects

CRUD for projects, the canvas-and-session containers that scope agent work.

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

Method	Path	Description
`GET`	`/api/v1/projects`	List projects visible to the caller.
`POST`	`/api/v1/projects`	Create a project.
`GET`	`/api/v1/projects/:id`	Fetch one project with spend totals and shared workspaces.
`PATCH`	`/api/v1/projects/:id`	Update project fields.
`DELETE`	`/api/v1/projects/:id`	Soft-delete a project and its owned records.
`GET`	`/api/v1/projects/:id/blocks`	List canvas blocks for the project. Opt-in cursor pagination via `limit` (1–500) + opaque `cursor`; without `limit` the full list is returned.
`POST`	`/api/v1/projects/:id/blocks`	Create a project-scoped block.
`PATCH`	`/api/v1/projects/:id/blocks/positions`	Bulk-update block positions (atomic — all IDs must belong to the project).
`POST`	`/api/v1/projects/:id/share`	Create/update share link — browser session + step-up.
`DELETE`	`/api/v1/projects/:id/share`	Revoke share link — browser session + step-up.
`POST`	`/api/v1/projects/:id/share/invite`	Create/update invite link — browser session + step-up.
`POST`	`/api/v1/projects/:id/duplicate`	Clone canvas blocks and project files (not chat sessions).
`GET`	`/api/v1/projects/:id/navigator`	Lab sidebar navigator spec (files + canvas structure).
`GET`	`/api/v1/projects/:id/export`	Export a checksummed manifest for CLI backup/restore.
`POST`	`/api/v1/projects/:id/restore`	Plan (`dryRun=true`) or apply a restore from an export manifest.
`POST`	`/api/v1/projects/:id/restore-last-run`	Restore blocks touched by the last failed agent run.

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

Field	Type	Required	Description
`name`	string	one of `name`/`description`	1–255 chars. If omitted, a name is generated from the description.
`description`	string \| null	one of `name`/`description`	Up to 5,000 chars.
`prompt`	string \| null	no	Up to 12,000 chars. Project-wide system prompt.
`emoji`	string \| null	no	Up to 16 chars.
`visibility`	`"team"` \| `"private"`	no	Defaults to the user's `defaultProjectVisibility`, then `team`.

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.

bash

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.

Duplicate, export, and restore

curl -X POST "https://alumia.com/api/v1/projects/$ID/duplicate" -H "Authorization: Bearer $KEY"
curl "https://alumia.com/api/v1/projects/$ID/export" -H "Authorization: Bearer $KEY"
curl -X POST "https://alumia.com/api/v1/projects/$ID/restore?dryRun=true" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d @manifest.json

GET /projects/:id/navigator returns the lab sidebar file + canvas structure spec.

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

Code	When
`UNAUTHORIZED`	No valid key.
`BAD_REQUEST`	Body missing, both `name` and `description` empty on create, oversized field, invalid status/visibility, metadata too large or too deep.
`FORBIDDEN`	Caller has no workspace access.
`NOT_FOUND`	Project does not exist, is soft-deleted, or is invisible to the caller (workspace + visibility).

Search docs