Folder Management

Folder Management

Overview

Spuree is an agent-friendly cloud storage. Projects contain folders (nestable) and files at any level. This skill manages folders — they can be nested to any depth within a project.

Use this skill when an agent needs to:

• List recently created or updated folders across all accessible projects
• Find a named folder with bounded search rather than project-tree traversal
• Create, rename, move, or delete folders in a project
• Browse a folder's contents (sub-folders, entities, files)
• List assets or files within a folder
• Get download URLs for files in bulk

API terminology: In the API, folders are called sessions (sessionType: "session"). All API fields use sessionId, parentSessionId, etc. This document uses folder for clarity.

Authentication

Authorization: Bearer $SPUREE_ACCESS_TOKEN

Or use an API key:

X-API-Key: $SPUREE_API_KEY

See the authentication skill for obtaining tokens and managing API keys.

Base URL

Data Model

Folder Hierarchy

Project (creative_project)          ← see project-management skill
├── Folder (session)
│   ├── Sub-folder (session)
│   │   └── ...
│   ├── Entity (asset)              character, motion, prop, environment, visdev, pose
│   │   └── Files
│   └── Files
├── Entity (asset)
│   └── Files
└── Files

Session Types

Entity Types

Entities represent assets and have one of these types:

character, motion, prop, environment, visdev, pose

Endpoints

GET /v1/search/folders

Find existing project folders in one bounded request. The Search service runs direct folder-name and contained-file evidence branches concurrently under the same caller scope and eight-second ceiling, then returns deduplicated canonical folders. Use this endpoint first for a named-folder request; do not enumerate projects or recursively browse children to reproduce it client-side.

Query Parameters:

Response:

{
  "data": [
    {
      "folder": { "id": "64a7b8c9d1e2f3a4b5c6d7e8", "name": "Phase 0" },
      "project": { "id": "64a7b8c9d1e2f3a4b5c6d7d0", "name": "PLOCAN" },
      "breadcrumb": [
        { "id": "64a7b8c9d1e2f3a4b5c6d7d0", "name": "PLOCAN", "sessionType": "creative_project" },
        { "id": "64a7b8c9d1e2f3a4b5c6d7d8", "name": "Works", "sessionType": "session" },
        { "id": "64a7b8c9d1e2f3a4b5c6d7e8", "name": "Phase 0", "sessionType": "session" }
      ],
      "matchStrength": "strong",
      "reasonCodes": ["direct_folder_name", "path_token_match"],
      "evidence": {
        "directMatchCount": 1,
        "childFileCount": 0,
        "childFilenameCount": 0,
        "childContentCount": 0
      }
    }
  ],
  "count": 1,
  "status": "complete",
  "partial": false,
  "degradedBranches": [],
  "branchStatus": [
    { "branch": "direct_folder_name", "status": "ok" },
    { "branch": "file_evidence", "status": "ok" }
  ]
}

The documented response schema is exact:

The response enums are also closed sets:

breadcrumb is ordered from the creative-project root through the matched folder. matchStrength is exactly exact, strong, or supporting; it is a stable qualitative tier, not a probability. reasonCodes may contain exact_folder_name, direct_folder_name, path_token_match, child_filename, and child_content.

Evidence is count-only. CheehooData does not return matching child file names, file IDs, snippets, bodies, raw Atlas scores, or navigation URLs from this endpoint. A hosted Studio tool may add webUrl fields; otherwise construct https://studio.spuree.com/folders/{folderId} and https://studio.spuree.com/projects/{projectId} from the canonical IDs.

status: "partial" and partial: true mean exactly one search branch degraded; inspect degradedBranches and branchStatus, and present the surviving candidates as partial. Each branchStatus[].status is exactly ok, timeout, error, or skipped: ok means the bounded branch completed (even with no matches), timeout/error identify degradation, and skipped means no search ran because the caller's narrowed scope was empty. Service construction, scope resolution, both evidence branches, and canonical hydration share one eight-second ceiling. If that request budget expires, both branches are unavailable, or canonical hydration fails, the request returns 503 instead of silently traversing project trees.

Status Codes:

Example:

curl "https://data.spuree.com/api/v1/search/folders?q=PLOCAN%20Phase%200%20and%20A%20Works&limit=5" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/folders

List all folders the authenticated user can access across projects, globally sorted with containing project and workspace context. Use this for requests such as “show my recently created folders”; do not substitute projects for folders.

The default query returns the newest-created folders first. Nested folders are included at every depth, so no recursive project browsing is required.

Query Parameters:

Response:

{
  "folders": [
    {
      "id": "64a7b8c9d1e2f3a4b5c6d7e8",
      "name": "Shot 010",
      "sessionType": "session",
      "description": "Latest shot work",
      "createdBy": "artist@example.com",
      "status": "active",
      "tags": ["shot"],
      "parentSessions": ["64a7b8c9d1e2f3a4b5c6d7e0"],
      "projectId": "64a7b8c9d1e2f3a4b5c6d7d0",
      "projectName": "Feature Film",
      "workspaceId": "64a7b8c9d1e2f3a4b5c6d7c0",
      "createdAt": "2026-07-15T17:00:00Z",
      "updatedAt": "2026-07-15T17:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

projectId, projectName, and workspaceId identify each folder's container. An optional filter that selects no readable project returns an empty page rather than revealing whether an inaccessible folder exists.

Status Codes:

Example:

curl "https://data.spuree.com/api/v1/folders?sortBy=createdAt&sortOrder=desc&limit=20" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/sessions

Create a new folder.

Description: Creates a folder under a parent (project, folder, animation, or entity). The name must be compatible with Windows file system naming rules.

Request Body:

Response:

{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}

Status Codes:

Nesting rules:

• Allowed parents: creative_project, session, animation, entity
• Entity sessions allow only 1 level of sub-folders. Creating a folder under a folder that is already inside an entity is rejected.

Example:

curl -X POST "https://data.spuree.com/api/v1/sessions" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Characters",
    "parentSessionId": "64a7b8c9d1e2f3a4b5c6d7e8",
    "description": "All character assets",
    "tags": ["characters"]
  }'

PATCH /v1/sessions/{sessionId}

Update a folder (rename, move, or edit tags).

Description: Updates folder metadata. Supports renaming, moving to a different parent, and updating description/tags. Only folders (sessionType: "session") can be updated via this endpoint.

Path Parameters:

Request Body (all fields optional, at least one required):

Response:

{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}

Status Codes:

Move notes:

• Moving a folder automatically inherits workspace and project IDs from the new parent.
• Circular references are detected and rejected (cannot move a folder into its own descendant).

Examples:

# Rename a folder
curl -X PATCH "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Folder"}'

# Move a folder to a different parent
curl -X PATCH "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parentSessionId": "64a7b8c9d1e2f3a4b5c6d7f0"}'

DELETE /v1/sessions/{sessionId}

Delete a folder (soft delete).

Description: Soft-deletes a folder by setting its status to "deleted". Only folders (sessionType: "session") can be deleted via this endpoint.

Path Parameters:

Response:

{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}

Status Codes:

Example:

curl -X DELETE "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/sessions/{sessionId}/children

List a folder's immediate contents — sub-folders, asset entities, and files. Use this to browse into a folder when you have its ID and want to see everything inside.

Description: Returns the direct children of a folder: sub-folders, entities (assets), and files. Same response format as GET /v1/projects/{projectId}/children.

Path Parameters:

Query Parameters:

Response: { items: [...] } — one flat array mixing sub-folders, entities, and files, sorted by the chosen key. Each item carries a type discriminator ("session", "entity", or "file") that selects its fields. An empty folder returns { "items": [] }.

{
  "items": [
    {
      "type": "session",
      "id": "64a7b8c9d1e2f3a4b5c6d7e8",
      "name": "Sub-folder",
      "sessionType": "session",
      "status": "active",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    },
    {
      "type": "entity",
      "id": "64a7b8c9d1e2f3a4b5c6d7e9",
      "name": "Hero Character",
      "entityType": "character",
      "description": "Main character",
      "entityPreview": {
        "presignedUrl": "https://s3.amazonaws.com/...",
        "key": "previews/hero_low.jpg",
        "fileFormat": "jpg"
      },
      "highResEntityPreview": {
        "presignedUrl": "https://s3.amazonaws.com/...",
        "key": "previews/hero_high.jpg",
        "fileFormat": "jpg"
      }
    },
    {
      "type": "file",
      "id": "64a7b8c9d1e2f3a4b5c6d7ea",
      "name": "reference_sheet",
      "fileFormat": "png",
      "fileSize": 20480,
      "key": "works_abc/sess_def/file_ghi",
      "sourceCharacter": null,
      "presignedUrl": "https://s3.amazonaws.com/...",
      "annotationMetaData": {}
    }
  ]
}

Parsing note: Read the required top-level items array. Do not parse this endpoint as separate collections; an empty folder is exactly { "items": [] }.

Item Types (selected by type):

Entity Item Fields (type: "entity"):

File Item Fields (type: "file"):

Status Codes:

Example:

curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/children?limit=50" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/sessions/{sessionId}/assets

List the published asset entities (character, motion, prop, etc.) in a folder with their preview images. Use this when you need assets only, not raw files or sub-folders.

Description: Returns entity sessions and their associated files for a given folder.

Path Parameters:

Query Parameters:

Response:

{
  "assets": [
    {
      "id": "64a7b8c9d1e2f3a4b5c6d7e9",
      "name": "Hero Character",
      "entityType": "character",
      "description": "Main character",
      "entityPreview": { "presignedUrl": "...", "key": "...", "fileFormat": "jpg" },
      "highResEntityPreview": { "presignedUrl": "...", "key": "...", "fileFormat": "jpg" }
    }
  ],
  "files": [
    {
      "id": "64a7b8c9d1e2f3a4b5c6d7ea",
      "fileName": "hero_model",
      "fileFormat": "fbx",
      "key": "works_abc/sess_def/file_ghi",
      "sourceCharacter": "Hero",
      "presignedUrl": "https://s3.amazonaws.com/...",
      "annotationMetaData": { "fileSize": "1048576" }
    }
  ]
}

Status Codes:

Example:

curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/assets" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/sessions/{sessionId}/files

List the files directly in a folder (optionally flattened to include sub-folder files). Use this when you need file records for a known folder without browsing sub-folders.

Description: Returns files associated with a folder. By default, flattens results to include files from sub-folders via entity session linkage.

Path Parameters:

Query Parameters:

Response:

{
  "files": [
    {
      "id": "64a7b8c9d1e2f3a4b5c6d7ea",
      "fileName": "hero_walk",
      "fileFormat": "fbx",
      "key": "works_abc/sess_def/file_ghi",
      "sourceCharacter": "Hero",
      "presignedUrl": "https://s3.amazonaws.com/...",
      "annotationMetaData": {
        "fps": 30,
        "frameCount": 300,
        "durationSeconds": 10.0,
        "fileSize": "1048576"
      }
    }
  ]
}

Status Codes:

Example:

# Get all files (flattened, including sub-folders)
curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/files" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

# Get only direct files in this folder
curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/files?flatten=false" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/sessions/files/download/urls

Get download URLs for multiple files in bulk.

Description: Generates presigned S3 download URLs for a batch of files. Validates access permissions for each file.

Request Body:

Response:

{
  "downloads": [
    {
      "fileId": "64a7b8c9d1e2f3a4b5c6d7ea",
      "fileName": "hero_walk.fbx",
      "fileSize": 1048576,
      "format": "fbx",
      "downloadUrl": "https://s3.amazonaws.com/...",
      "expiresAt": "2024-01-15T11:00:00Z",
      "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8",
      "entitySessionId": "64a7b8c9d1e2f3a4b5c6d7e9",
      "metadata": {
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z"
      }
    }
  ],
  "totalFiles": 1,
  "totalSize": 1048576,
  "unauthorizedFiles": [],
  "notFoundFiles": []
}

Status Codes:

Example:

curl -X POST "https://data.spuree.com/api/v1/sessions/files/download/urls" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileIds": ["64a7b8c9d1e2f3a4b5c6d7ea", "64a7b8c9d1e2f3a4b5c6d7eb"],
    "expiresIn": 7200,
    "includeMetadata": true
  }'

Common Patterns

List Recently Created Folders Across Projects

Call the global folder list directly; do not list projects and label them as folders, and do not recurse through every project's children.

GET /v1/folders?sortBy=createdAt&sortOrder=desc&limit=20

Find a Named Folder (Bounded Search-First Recipe)

Use search for requests such as “find the PLOCAN Phase 0 and A Works folder.” Do not list every project or walk child endpoints to discover a folder by name.

1. Make the preferred one-call discovery request with the user's concise natural-language folder intent:

   GET /v1/search/folders?q={encodedNaturalLanguageQuery}&limit=5
   

   Use the returned canonical folder, project, and root-to-folder breadcrumb. Preserve explicit partial status. Return or ask the user to choose among those candidates; do not perform client-side traversal.

2. Compatibility fallback only: use the following fixed legacy sequence only when the client tool registry does not contain folder_find, or an HTTP request to GET /v1/search/folders returns 404, 405, or 501. Those conditions confirm that the endpoint is absent. Do not fall back after a 400, 401, 403, 422, 500, or 503 response, a timeout, or a network failure; surface that error instead.

   A deployment old enough to lack folder_find also lacks matchMode and may not return canonical container, project, or breadcrumb context from generic search. First separate the likely leaf-folder stem and requested leaf labels from hierarchy qualifiers. In the example above, search for Phase, retain the requested labels 0 and A, and keep PLOCAN / Works only as user-provided qualifiers. Do not claim that a result is beneath PLOCAN / Works unless the response itself supplies canonical context, and do not treat Works as the leaf. Do not send request verbs or the entire natural-language sentence as {encodedQuery}.

   Search folder name rows directly:

   GET /v1/search?q={encodedQuery}&type=folder&searchIn=name&limit=50
   

   Read the grouped { data, count, cursor } response. Each direct folder result proves that its sourceId is a folder ID. Rank an exact case-insensitive sessionName match first, then normalized requested-label matches, then the API relevance order. A folder result's canonical Studio URL is https://studio.spuree.com/folders/{sourceId}. Treat a legacy projectId as an opaque identifier; do not invent a project name or folder path when canonical context is absent.

   Only when the direct search returned at least two plausible folder candidates, the result is still ambiguous, and the request contains useful file/content terms, make one evidence fallback request. If direct search returned no folder candidates, stop and ask for a narrower name or project; file evidence cannot establish a folder identity by itself.

   GET /v1/search?q={encodedQuery}&type=file&searchIn=all&limit=50
   

   Use concise evidence terms, not request verbs. Build a set of the direct folder results' sourceId values, then group returned file results by their containing sessionId. Count a file group only when its sessionId is in that direct-folder ID set. File evidence may re-rank an already-proven direct folder candidate, but it must never introduce a new folder candidate or establish hierarchy. This intersection also excludes project-root files, because a project ID was not returned as a direct folder sourceId. Nested descendant files are a known blind spot of this legacy evidence step: without canonical lineage, they cannot safely count toward an ancestor folder candidate. Treat zero direct-file evidence as inconclusive, not as proof that a folder is empty or irrelevant, and do not traverse descendants to compensate.

   Return the best candidates with only the context actually present and the supporting evidence counts. If the result is still ambiguous, ask the user to choose. Stop after the direct search and the single fallback: do not enumerate projects, call child endpoints, or recursively traverse folders for named-folder discovery.

GET /v1/folders is for globally sorted listing such as “recent folders”; it is not the fallback for a name query.

Browse a Known Folder

Use child endpoints only after the user supplied or selected an ID. They are for inspecting a known container, not for finding a named folder.

1. Get project children (via project-management skill):

   GET /v1/projects/{projectId}/children → { items: [...] }
   

2. Navigate into a folder:

   GET /v1/sessions/{folderId}/children → { items: [...] }
   

3. Follow a returned sub-folder ID only when the user asks to inspect it.

Create a Folder Structure

# Create a top-level folder in a project
POST /v1/sessions { name: "Characters", parentSessionId: "{projectId}" }
→ { sessionId: "folder1" }

# Create a sub-folder
POST /v1/sessions { name: "Heroes", parentSessionId: "folder1" }
→ { sessionId: "folder2" }

Download All Files in a Folder

1. List files in the folder:

   GET /v1/sessions/{folderId}/files?flatten=true → { files: [...] }
   

2. Get download URLs in bulk:

   POST /v1/sessions/files/download/urls { fileIds: [...] }
   → { downloads: [{ downloadUrl, ... }] }
   

3. Download each file using its downloadUrl.

Agent Workflow: Asset Discovery

1. Find the folder → use the bounded search-first recipe above
2. Get assets → GET /v1/sessions/{folderId}/assets
3. Get files → for each asset, list its files
4. Download → batch download with POST /v1/sessions/files/download/urls

Studio URLs

After creating or finding resources, you can give the user a clickable link to view them in the browser:

Studio resource URLs use only the target ID, regardless of folder depth.

Error Handling