Folders

Folders keep assets organized inside a project. Folder paths use / between each level.

Valid examples:

• brand
• brand/launch
• users/123/avatars

Folders always belong to a project. There is no workspace-level upload folder.

Dashboard Folders

Create folders from the dashboard while viewing a project. The project root shown in the dashboard is the root of the selected project, not the root of the whole workspace.

Folder Names

Paths cannot:

• start or end with /
• include empty segments
• use . or .. as folder names

API Uploads

When uploading through the API, send the project slug and optional folder path:

{
  "projectSlug": "website",
  "folderPath": "brand/launch"
}

Send this object in the upload's metadata JSON part. Intermediate folders are created automatically when needed.

List folders with GET /api/v1/folders?projectSlug=website. Read one listed folder with GET /api/v1/folders/{folderId}?projectSlug=website, or use PATCH /api/v1/folders/{folderId} to update its path, name, or description.

Recursive Deletes

API integrations can delete a folder and all descendants with:

const baseUrl = "https://stashr.dev";
const apiKey = process.env.STASHR_API_KEY;
const projectId = process.env.STASHR_PROJECT_ID || "";
const folderId = process.env.STASHR_FOLDER_ID || "";
const assetId = process.env.STASHR_ASSET_ID || "";
const authHeaders = { Authorization: "Bearer " + apiKey };

const response = await fetch(baseUrl + "/api/v1/folders?projectSlug=website&path=brand%2Flaunch&recursive=true", {
  method: "DELETE",
  headers: authHeaders
});
if (!response.ok) throw new Error(await response.text());

Without recursive=true, deletion only succeeds when the folder is empty.