Back to Details

folder-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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:
  • 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.
Spuree是一款对Agent友好的云存储服务。项目中包含可嵌套的文件夹和任意层级的文件。本Skill用于管理文件夹——它们可以在项目内嵌套至任意深度。
当Agent需要执行以下操作时，可使用本Skill：
  • 在项目中创建、重命名、移动或删除文件夹
  • 浏览文件夹内容（子文件夹、实体、文件）
  • 列出文件夹内的资源或文件
  • 批量获取文件的下载URL
API术语说明： 在API中，文件夹被称为会话（
sessionType: "session"
）。所有API字段均使用
sessionId
、
parentSessionId
等。为便于理解，本文档统一使用文件夹一词。

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.
Authorization: Bearer $SPUREE_ACCESS_TOKEN
或使用API密钥：
X-API-Key: $SPUREE_API_KEY
有关获取令牌和管理API密钥的内容，请查看身份验证Skill。

Base URL

基础URL

https://data.spuree.com/api/v1/sessions
https://data.spuree.com/api/v1/sessions

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
Project (creative_project)          ← 查看project-management skill
├── Folder (session)
│   ├── Sub-folder (session)
│   │   └── ...
│   ├── Entity (asset)              character, motion, prop, environment, visdev, pose
│   │   └── Files
│   └── Files
├── Entity (asset)
│   └── Files
└── Files

Session Types

会话类型

sessionType
This document calls itDescription
creative_project
ProjectTop-level container (managed via project-management skill)
session
FolderOrganizes content hierarchically
entity
Entity / AssetAsset container (character, motion, prop, etc.)
animation
AnimationAnimation session
sessionType
本文档称呼描述
creative_project
项目顶层容器（通过project-management skill管理）
session
文件夹按层级组织内容
entity
实体/资源资源容器（角色、动作、道具等）
animation
动画动画会话

Entity Types

实体类型

Entities represent assets and have one of these types:
character
, 
motion
, 
prop
, 
environment
, 
visdev
, 
pose
实体代表资源，分为以下类型：
character
, 
motion
, 
prop
, 
environment
, 
visdev
, 
pose

Endpoints

接口

POST /v1/sessions

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:
FieldTypeRequiredDescription
name
stringYesFolder name (Windows filesystem-compatible)
parentSessionId
stringYesParent ObjectId (project, folder, animation, or entity)
description
stringNoFolder description
tags
string[]NoTags for the folder
Response:
json
{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}
Status Codes:
CodeDescription
200Folder created
400Invalid name, invalid parent ID, parent type not allowed, or entity nesting limit exceeded
401Invalid or expired token
403Not authorized to create in this parent
404Parent not found or deleted
409Folder name already exists in the parent
500Internal server error
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:
bash
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"]
  }'
创建新文件夹。
描述： 在父对象（项目、文件夹、动画或实体）下创建文件夹。文件夹名称必须符合Windows文件系统命名规则。
请求体：
字段类型必填描述
name
string是文件夹名称（兼容Windows文件系统）
parentSessionId
string是父对象ObjectId（项目、文件夹、动画或实体）
description
string否文件夹描述
tags
string[]否文件夹标签
响应：
json
{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}
状态码：
代码描述
200文件夹创建成功
400名称无效、父ID无效、父类型不允许或实体嵌套限制超出
401令牌无效或已过期
403无权在此父对象下创建文件夹
404父对象不存在或已被删除
409父对象下已存在同名文件夹
500服务器内部错误
嵌套规则：
  • 允许的父对象：
    creative_project
    , 
    session
    , 
    animation
    , 
    entity
  • 实体会话仅允许1级子文件夹。在已位于实体内部的文件夹下创建文件夹会被拒绝。
示例：
bash
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}

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:
ParameterTypeDescription
sessionId
stringFolder ObjectId
Request Body (all fields optional, at least one required):
FieldTypeDescription
name
stringNew folder name
description
stringNew description
tags
string[]New tags
parentSessionId
stringMove to a new parent (project, folder, animation, or entity)
Response:
json
{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}
Status Codes:
CodeDescription
200Folder updated
400No fields provided, circular reference, or nesting limit exceeded
401Invalid or expired token
403Not authorized, or session is not a folder
404Folder not found, or target parent not found
409Name conflict in target parent
500Internal server error
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:
bash
undefined
更新文件夹（重命名、移动或编辑标签）。
描述： 更新文件夹元数据。支持重命名、移动至新父对象以及更新描述/标签。仅文件夹（
sessionType: "session"
）可通过此接口更新。
路径参数：
参数类型描述
sessionId
string文件夹ObjectId
请求体（所有字段可选，至少需提供一个）：
字段类型描述
name
string新文件夹名称
description
string新描述
tags
string[]新标签
parentSessionId
string移动至新父对象（项目、文件夹、动画或实体）
响应：
json
{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}
状态码：
代码描述
200文件夹更新成功
400未提供任何字段、存在循环引用或超出嵌套限制
401令牌无效或已过期
403无权限，或会话并非文件夹
404文件夹不存在，或目标父对象不存在
409目标父对象下已存在同名文件夹
500服务器内部错误
移动说明：
  • 移动文件夹后会自动继承新父对象的工作区和项目ID。
  • 系统会检测并拒绝循环引用（无法将文件夹移动至自身的子文件夹中）。
示例：
bash
undefined

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"}'
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"}'

---
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 /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:
ParameterTypeDescription
sessionId
stringFolder ObjectId
Response:
json
{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}
Status Codes:
CodeDescription
200Folder soft-deleted
400Invalid folder ID format
401Invalid or expired token
403Not authorized, or session is not a folder
404Folder not found or already deleted
500Internal server error
Example:
bash
curl -X DELETE "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
删除文件夹（软删除）。
描述： 通过将状态设置为"deleted"来软删除文件夹。仅文件夹（
sessionType: "session"
）可通过此接口删除。
路径参数：
参数类型描述
sessionId
string文件夹ObjectId
响应：
json
{
  "messageCode": "success",
  "sessionId": "64a7b8c9d1e2f3a4b5c6d7e8"
}
状态码：
代码描述
200文件夹软删除成功
400文件夹ID格式无效
401令牌无效或已过期
403无权限，或会话并非文件夹
404文件夹不存在或已被删除
500服务器内部错误
示例：
bash
curl -X DELETE "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/sessions/{sessionId}/children

GET /v1/sessions/{sessionId}/children

Browse a folder's immediate contents.
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:
ParameterTypeDescription
sessionId
stringFolder ObjectId
Query Parameters:
ParameterTypeDefaultDescription
limit
integer100Results per page (max: 500)
offset
integer0Number of items to skip
Response:
json
{
  "sessions": [
    {
      "id": "64a7b8c9d1e2f3a4b5c6d7e8",
      "name": "Sub-folder",
      "sessionType": "session",
      "status": "active",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "entities": [
    {
      "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"
      }
    }
  ],
  "files": [
    {
      "id": "64a7b8c9d1e2f3a4b5c6d7ea",
      "fileName": "reference_sheet",
      "fileFormat": "png",
      "key": "works_abc/sess_def/file_ghi",
      "sourceCharacter": null,
      "presignedUrl": "https://s3.amazonaws.com/...",
      "annotationMetaData": {}
    }
  ]
}
Children Types:
ArrayContainsDescription
sessions
FoldersSub-folders — navigate deeper with this same endpoint
entities
AssetsEntity sessions with preview images
files
FilesFiles with presigned download URLs
Entity Fields:
FieldTypeDescription
id
stringEntity ObjectId
name
stringEntity name
entityType
string
character
, 
motion
, 
prop
, 
environment
, 
visdev
, 
pose
description
string?Entity description
entityPreview
object?Low-res preview (
presignedUrl
, 
key
, 
fileFormat
)
highResEntityPreview
object?High-res preview
File Fields:
FieldTypeDescription
id
stringFile ObjectId
fileName
stringFile name (without extension)
fileFormat
stringFile extension (lowercase)
key
stringS3 object key
sourceCharacter
string?Associated character name
presignedUrl
stringS3 presigned download URL
annotationMetaData
objectMetadata (fps, frameCount, durationSeconds, ueAssetType, etc.)
Status Codes:
CodeDescription
200Children returned
400Invalid folder ID format
401Invalid or expired token
403Not authorized to access this folder
404Folder not found or deleted
500Internal server error
Example:
bash
curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/children?limit=50" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
浏览文件夹的直接内容。
描述： 返回文件夹的直接子对象：子文件夹、实体（资源）和文件。响应格式与
GET /v1/projects/{projectId}/children
一致。
路径参数：
参数类型描述
sessionId
string文件夹ObjectId
查询参数：
参数类型默认值描述
limit
integer100每页结果数（最大值：500）
offset
integer0跳过的条目数
响应：
json
{
  "sessions": [
    {
      "id": "64a7b8c9d1e2f3a4b5c6d7e8",
      "name": "Sub-folder",
      "sessionType": "session",
      "status": "active",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "entities": [
    {
      "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"
      }
    }
  ],
  "files": [
    {
      "id": "64a7b8c9d1e2f3a4b5c6d7ea",
      "fileName": "reference_sheet",
      "fileFormat": "png",
      "key": "works_abc/sess_def/file_ghi",
      "sourceCharacter": null,
      "presignedUrl": "https://s3.amazonaws.com/...",
      "annotationMetaData": {}
    }
  ]
}
子对象类型：
数组包含内容描述
sessions
文件夹子文件夹——可通过同一接口深入浏览
entities
资源带预览图的实体会话
files
文件带预签名下载URL的文件
实体字段：
字段类型描述
id
string实体ObjectId
name
string实体名称
entityType
string
character
, 
motion
, 
prop
, 
environment
, 
visdev
, 
pose
description
string?实体描述
entityPreview
object?低分辨率预览图（
presignedUrl
, 
key
, 
fileFormat
）
highResEntityPreview
object?高分辨率预览图
文件字段：
字段类型描述
id
string文件ObjectId
fileName
string文件名（不含扩展名）
fileFormat
string文件扩展名（小写）
key
stringS3对象键
sourceCharacter
string?关联角色名称
presignedUrl
stringS3预签名下载URL
annotationMetaData
object元数据（fps、frameCount、durationSeconds、ueAssetType等）
状态码：
代码描述
200返回子对象成功
400文件夹ID格式无效
401令牌无效或已过期
403无权访问此文件夹
404文件夹不存在或已被删除
500服务器内部错误
示例：
bash
curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/children?limit=50" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/sessions/{sessionId}/assets

GET /v1/sessions/{sessionId}/assets

Get assets (entities) in a folder.
Description: Returns entity sessions and their associated files for a given folder.
Path Parameters:
ParameterTypeDescription
sessionId
stringFolder ObjectId
Query Parameters:
ParameterTypeDefaultDescription
include
string
files
Comma-separated: 
files
limit
integer100Results per page (max: 500)
offset
integer0Number of items to skip
Response:
json
{
  "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:
CodeDescription
200Assets and files returned
400Invalid folder ID format
401Invalid or expired token
403Not authorized
404Folder not found
500Internal server error
Example:
bash
curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/assets" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
获取文件夹内的资源（实体）。
描述： 返回指定文件夹下的实体会话及其关联文件。
路径参数：
参数类型描述
sessionId
string文件夹ObjectId
查询参数：
参数类型默认值描述
include
string
files
逗号分隔值：
files
limit
integer100每页结果数（最大值：500）
offset
integer0跳过的条目数
响应：
json
{
  "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" }
    }
  ]
}
状态码：
代码描述
200返回资源和文件成功
400文件夹ID格式无效
401令牌无效或已过期
403无权限
404文件夹不存在
500服务器内部错误
示例：
bash
curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/assets" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/sessions/{sessionId}/files

GET /v1/sessions/{sessionId}/files

Get files in a folder.
Description: Returns files associated with a folder. By default, flattens results to include files from sub-folders via entity session linkage.
Path Parameters:
ParameterTypeDescription
sessionId
stringFolder ObjectId
Query Parameters:
ParameterTypeDefaultDescription
flatten
boolean
true
true
: files by 
entitySessionId
(includes sub-folders). 
false
: files by direct 
sessionId
only
limit
integer100Results per page (max: 500)
offset
integer0Number of items to skip
Response:
json
{
  "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:
CodeDescription
200Files returned
400Invalid folder ID format
401Invalid or expired token
403Not authorized
404Folder not found
500Internal server error
Example:
bash
undefined
获取文件夹内的文件。
描述： 返回与文件夹关联的文件。默认会通过实体会话关联展开结果，包含子文件夹中的文件。
路径参数：
参数类型描述
sessionId
string文件夹ObjectId
查询参数：
参数类型默认值描述
flatten
boolean
true
true
：按
entitySessionId
返回文件（包含子文件夹）；
false
：仅返回直接关联
sessionId
的文件
limit
integer100每页结果数（最大值：500）
offset
integer0跳过的条目数
响应：
json
{
  "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"
      }
    }
  ]
}
状态码：
代码描述
200返回文件成功
400文件夹ID格式无效
401令牌无效或已过期
403无权限
404文件夹不存在
500服务器内部错误
示例：
bash
undefined

Get all files (flattened, including sub-folders)

获取所有文件（展开，包含子文件夹）

curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/files"
-H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"
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"

---
curl "https://data.spuree.com/api/v1/sessions/64a7b8c9d1e2f3a4b5c6d7e8/files?flatten=false"
-H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

---

POST /v1/sessions/files/download/urls

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:
FieldTypeRequiredDescription
fileIds
string[]YesFile ObjectIds to download
expiresIn
integerNoURL expiry in seconds (60–86400, default: 3600)
includeMetadata
booleanNoInclude file metadata (default: 
false
)
Response:
json
{
  "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:
CodeDescription
200Download URLs generated
400Invalid input
401Invalid or expired token
403Not authorized for some files (listed in 
unauthorizedFiles
)
503AWS credentials error
500Internal server error
Example:
bash
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
  }'
批量获取多个文件的下载URL。
描述： 为一批文件生成S3预签名下载URL。会验证每个文件的访问权限。
请求体：
字段类型必填描述
fileIds
string[]是要下载的文件ObjectId列表
expiresIn
integer否URL过期时间（秒，范围60–86400，默认：3600）
includeMetadata
boolean否是否包含文件元数据（默认：
false
）
响应：
json
{
  "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": []
}
状态码：
代码描述
200生成下载URL成功
400输入无效
401令牌无效或已过期
403无权访问部分文件（列于
unauthorizedFiles
）
503AWS凭证错误
500服务器内部错误
示例：
bash
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

常见模式

Navigate a Project's Folder Structure

浏览项目的文件夹结构

  1. Get project children (via project-management skill):
    GET /v1/projects/{projectId}/children → { sessions, entities, files }
  2. Navigate into a folder:
    GET /v1/sessions/{folderId}/children → { sessions, entities, files }
  3. Repeat to go deeper into sub-folders.
  1. 获取项目子对象（通过project-management skill）：
    GET /v1/projects/{projectId}/children → { sessions, entities, files }
  2. 进入文件夹：
    GET /v1/sessions/{folderId}/children → { sessions, entities, files }
  3. 重复操作以深入浏览子文件夹。

Create a Folder Structure

创建文件夹结构

bash
undefined
bash
undefined

Create a top-level folder in a project

在项目中创建顶层文件夹

POST /v1/sessions { name: "Characters", parentSessionId: "{projectId}" } → { sessionId: "folder1" }
POST /v1/sessions { name: "Characters", parentSessionId: "{projectId}" } → { sessionId: "folder1" }

Create a sub-folder

创建子文件夹

POST /v1/sessions { name: "Heroes", parentSessionId: "folder1" } → { sessionId: "folder2" }
undefined
POST /v1/sessions { name: "Heroes", parentSessionId: "folder1" } → { sessionId: "folder2" }
undefined

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
    .
  1. 列出文件夹内的文件：
    GET /v1/sessions/{folderId}/files?flatten=true → { files: [...] }
  2. 批量获取下载URL：
    POST /v1/sessions/files/download/urls { fileIds: [...] }
→ { downloads: [{ downloadUrl, ... }] }
  3. 下载每个文件对应的
    downloadUrl
    。

Agent Workflow: Asset Discovery

Agent工作流：资源发现

  1. Browse project → find the folder containing assets
  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
  1. 浏览项目 → 找到包含资源的文件夹
  2. 获取资源 → 
    GET /v1/sessions/{folderId}/assets
  3. 获取文件 → 为每个资源列出其文件
  4. 下载 → 通过
    POST /v1/sessions/files/download/urls
    批量下载

Studio URLs

Studio链接

After creating or finding resources, you can give the user a clickable link to view them in the browser:
ResourceURL Pattern
Project
https://studio.spuree.com/projects/{projectId}
Folder (top-level)
https://studio.spuree.com/projects/{projectId}/folders/{folderId}
Folder (nested)
https://studio.spuree.com/projects/{projectId}/folders/{parentId}/{childId}
File
https://studio.spuree.com/file/{fileId}
Folders support up to 5 levels of nesting. Each level appends another ID segment: 
.../folders/{level1}/{level2}/{level3}/...
创建或找到资源后，可向用户提供可点击链接，在浏览器中查看：
资源URL格式
项目
https://studio.spuree.com/projects/{projectId}
顶层文件夹
https://studio.spuree.com/projects/{projectId}/folders/{folderId}
嵌套文件夹
https://studio.spuree.com/projects/{projectId}/folders/{parentId}/{childId}
文件
https://studio.spuree.com/file/{fileId}
文件夹最多支持5级嵌套。每一级都会追加一个ID段：
.../folders/{level1}/{level2}/{level3}/...

Error Handling

错误处理

ErrorCauseResolution
400 (invalid name)Name contains invalid filesystem charactersUse Windows-compatible names
400 (nesting limit)Trying to nest more than 1 level under an entityRestructure: entities allow only 1 sub-folder level
400 (circular ref)Moving a folder into its own descendantChoose a different target parent
401 (unauthorized)Expired or invalid JWTRefresh token via authentication skill
403 (not a folder)Trying to update/delete a non-folder sessionOnly 
sessionType: "session"
can be modified here
404 (not found)Folder doesn't exist or was deletedVerify the folder ID
409 (name conflict)Folder name already exists in the parentUse a different name
错误原因解决方法
400（名称无效）名称包含文件系统不允许的字符使用兼容Windows的名称
400（嵌套限制）尝试在实体下嵌套超过1级文件夹调整结构：实体仅允许1级子文件夹
400（循环引用）尝试将文件夹移动至自身的子文件夹中选择其他目标父对象
401（未授权）JWT令牌过期或无效通过身份验证Skill刷新令牌
403（非文件夹）尝试更新/删除非文件夹类型的会话仅
sessionType: "session"
可在此修改
404（未找到）文件夹不存在或已被删除验证文件夹ID
409（名称冲突）父对象下已存在同名文件夹使用其他名称