Projects

Create, copy, list, read & rename projects. A project is a single Snaptrude model, identified by its projectId (floorkey). Accessed via snaptrude.workspace.projects.

All methods are host API calls that return Promises. Reads never throw for a miss (get returns null). Create/copy/rename go through the backend, which enforces plan limits — a rejection surfaces as a normal host error.

Types

PluginProjectRef

A conservative projection of a project — never the raw backend payload.

Property	Type	Description
id	string	The project's projectId (floorkey)
name	string	Display name
teamId	string?	Owning team id (absent for personal projects)
createdAt	string?	Creation timestamp (ISO 8601) when known
modifiedAt	string?	Last-modified timestamp (ISO 8601) when known

Functions

create(name, options?)

Create a new, empty BIM project on the backend and return its projectId (floorkey). Pass options.teamId to create it inside a team (otherwise it lands in the user's personal workspace) and options.unit to set the default length unit.

• Parameters:
  • name: string — Display name of the new project
  • options: object (optional) — unit?: string (default length unit), teamId?: string (owning team)
• Returns: { projectId: string } — the new project's id
• Throws: If the backend rejects the create (e.g. a plan project limit)

const { projectId } = await snaptrude.workspace.projects.create("Tower Study", {
  teamId: "team_1",
  unit: "mm",
});

---

copy(name, options?)

Copy the current project into a new project — the dashboard's "Save As". Duplicates the project that is currently open into a new project with the given name and returns the new projectId. Pass options.teamId to place the copy in a specific team.

• Parameters:
  • name: string — Display name for the copy
  • options: object (optional) — teamId?: string (team to place the copy in)
• Returns: { projectId: string } — the copied project's id
• Throws: If the backend rejects the copy (e.g. a plan project limit)

const { projectId } = await snaptrude.workspace.projects.copy("Tower Study v2");

---

list(options?)

List the projects the user can access. Pass options.teamId to scope the list to a single team; omit it for all accessible projects.

• Parameters:
  • options: object (optional) — teamId?: string (scope to one team)
• Returns: { projects: PluginProjectRef[] } — accessible projects (empty when none)

const { projects } = await snaptrude.workspace.projects.list({ teamId: "team_1" });
for (const p of projects) console.log(p.id, p.name);

---

get(projectId)

Get a single project by id.

• Parameters:
  • projectId: string — The project's projectId (floorkey)
• Returns: PluginProjectRef | null — the project, or null if no project has that id / the user cannot access it

const project = await snaptrude.workspace.projects.get("floorkey_123");
if (project) console.log(project.name);

---

rename(projectId, name)

Rename a project.

• Parameters:
  • projectId: string — The project's projectId (floorkey)
  • name: string — The project's new display name
• Returns: { projectId: string } — the renamed project's id
• Throws: If no project has the given id or the rename is rejected

const { projectId } = await snaptrude.workspace.projects.rename(
  "floorkey_123",
  "Tower Study Final",
);

Errors

Failed calls reject with a typed PluginError — see Error Handling. Reads (list, get) never throw for a missing project — get returns null and list returns []. Create/copy/rename surface backend rejections (e.g. a plan project limit) as normal host errors.