project-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Management

项目管理

Overview

概述

Spuree is an agent-friendly cloud storage. Projects contain folders (nestable) and files at any level. This skill manages the top-level container: projects. In the API, projects and folders are both called sessions (

sessionType

creative_project

= project,

session

= folder).

Use this skill when an agent needs to:

List, create, update, or delete projects
Share or unshare projects with other users
Browse a project's immediate contents (folders, entities, files)

For managing invitations to non-workspace members, see the project-invitation skill.

Spuree是一款对Agent友好的云存储服务。项目包含可嵌套的文件夹和任意层级的文件。本Skill用于管理顶层容器：项目。在API中，项目和文件夹都被称为sessions（

sessionType

creative_project

= 项目，

session

= 文件夹）。

当Agent需要执行以下操作时，请使用本Skill：

列出、创建、更新或删除项目
与其他用户共享或取消共享项目
浏览项目的直接内容（文件夹、实体、文件）

如需管理对非工作区成员的邀请，请查看project-invitation Skill。

Authentication

认证

Authorization: Bearer $SPUREE_ACCESS_TOKEN

Or:

X-API-Key: $SPUREE_API_KEY

. See the authentication skill.

Authorization: Bearer $SPUREE_ACCESS_TOKEN

或：

X-API-Key: $SPUREE_API_KEY

。请查看authentication Skill。

Base URL

基础URL

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

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

Data Model

数据模型

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

Project
├── Folder                    (查看folder-management Skill)
│   ├── Sub-folder
│   ├── Entity (asset)        角色、动作、道具、环境、视觉开发、姿态
│   │   └── Files
│   └── Files
├── Entity (asset)
│   └── Files
└── Files

Endpoints

接口

GET /v1/projects

List projects accessible to the authenticated user, with workspace/organization lookup tables.

Query Parameters:

Parameter	Type	Default	Description
`sortBy`	string	`updatedAt`	Sort field: `updatedAt` , `createdAt` , `name`
`sortOrder`	string	`desc`	Sort order: `asc` , `desc`
`limit`	integer	500	Results per page (1–1000)
`offset`	integer	0	Items to skip

Response:

json

{
  "projects": [
    {
      "id": "...", "name": "My Project", "description": "...",
      "workspaceId": "...", "createdBy": "user@example.com",
      "sharedWith": ["collaborator@example.com"],
      "status": "active", "visibility": "private",
      "createdAt": "...", "updatedAt": "..."
    }
  ],
  "workspaces": { "{workspaceId}": { "id": "...", "name": "...", "organizationId": "..." } },
  "organizations": { "{orgId}": { "id": "...", "name": "..." } },
  "total": 12, "limit": 500, "offset": 0
}

To resolve a project's workspace/org:

workspaces[project.workspaceId]

→

organizations[workspace.organizationId]

bash

curl "https://data.spuree.com/api/v1/projects" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

列出认证用户可访问的项目，附带工作区/组织查询表。

查询参数：

参数	类型	默认值	描述
`sortBy`	string	`updatedAt`	排序字段： `updatedAt` 、 `createdAt` 、 `name`
`sortOrder`	string	`desc`	排序顺序： `asc` 、 `desc`
`limit`	integer	500	每页结果数（1–1000）
`offset`	integer	0	跳过的条目数

响应：

json

{
  "projects": [
    {
      "id": "...", "name": "My Project", "description": "...",
      "workspaceId": "...", "createdBy": "user@example.com",
      "sharedWith": ["collaborator@example.com"],
      "status": "active", "visibility": "private",
      "createdAt": "...", "updatedAt": "..."
    }
  ],
  "workspaces": { "{workspaceId}": { "id": "...", "name": "...", "organizationId": "..." } },
  "organizations": { "{orgId}": { "id": "...", "name": "..." } },
  "total": 12, "limit": 500, "offset": 0
}

要解析项目的工作区/组织：

workspaces[project.workspaceId]

→

organizations[workspace.organizationId]

。

bash

curl "https://data.spuree.com/api/v1/projects" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/projects

Create a new project. Name must be Windows filesystem-compatible.

Where to get
workspaceId
: From auth response

user.workspaces[].workspaceId

or from

GET /v1/projects

Field	Type	Required	Description
`name`	string	Yes	Project name
`workspaceId`	string	Yes	Workspace ObjectId
`description`	string	No	Project description
`sharedWith`	string[]	No	Emails to share with

Response (201):

{ messageCode, message, projectId }

Code	Description
201	Created
403	Not a workspace member
409	Name already exists in workspace

bash

curl -X POST "https://data.spuree.com/api/v1/projects" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Project", "workspaceId": "..."}'

创建新项目。项目名称必须符合Windows文件系统规范。

获取
workspaceId
的途径：从认证响应

user.workspaces[].workspaceId

或

GET /v1/projects

接口获取。

字段	类型	是否必填	描述
`name`	string	是	项目名称
`workspaceId`	string	是	工作区ObjectId
`description`	string	否	项目描述
`sharedWith`	string[]	否	要共享的用户邮箱列表

响应（201）：

{ messageCode, message, projectId }

代码	描述
201	创建成功
403	非工作区成员
409	工作区内已存在同名项目

bash

curl -X POST "https://data.spuree.com/api/v1/projects" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Project", "workspaceId": "..."}'

PATCH /v1/projects/{projectId}

Rename a project.

Field	Type	Required	Description
`name`	string	Yes	New project name

Response:

{ messageCode, message, projectId }

bash

curl -X PATCH "https://data.spuree.com/api/v1/projects/{projectId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Project"}'

重命名项目。

字段	类型	是否必填	描述
`name`	string	是	新项目名称

响应：

{ messageCode, message, projectId }

bash

curl -X PATCH "https://data.spuree.com/api/v1/projects/{projectId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Project"}'

DELETE /v1/projects/{projectId}

Soft-delete a project.

Response:

{ messageCode, message, projectId }

bash

curl -X DELETE "https://data.spuree.com/api/v1/projects/{projectId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

软删除项目。

响应：

{ messageCode, message, projectId }

bash

curl -X DELETE "https://data.spuree.com/api/v1/projects/{projectId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/projects/{projectId}/children

Browse a project's immediate contents: folders, entities (assets), and files. Use folder-management skill's

GET /v1/sessions/{folderId}/children

to navigate deeper.

Parameter	Type	Default	Description
`limit`	integer	100	Results per category (max 500)
`offset`	integer	0	Items to skip

Response:

{ sessions: [...], entities: [...], files: [...] }

```
sessions
```
— folders (
```
sessionType: "session"
```
)
```
entities
```
— assets with preview images (character, motion, prop, etc.)
```
files
```
— files with presigned download URLs

bash

curl "https://data.spuree.com/api/v1/projects/{projectId}/children" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

浏览项目的直接内容：文件夹、实体（资产）和文件。如需深入浏览，请使用folder-management Skill中的

GET /v1/sessions/{folderId}/children

接口。

参数	类型	默认值	描述
`limit`	integer	100	每个分类的结果数（最大500）
`offset`	integer	0	跳过的条目数

响应：

{ sessions: [...], entities: [...], files: [...] }

```
sessions
```
— 文件夹（
```
sessionType: "session"
```
）
```
entities
```
— 带预览图的资产（角色、动作、道具等）
```
files
```
— 带预签名下载链接的文件

bash

curl "https://data.spuree.com/api/v1/projects/{projectId}/children" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/projects/{projectId}/share

Share a project with another user. Behaves differently based on target's workspace membership:

Direct (target is workspace member) → immediately added. Response:
```
type: "direct"
```
Invitation (target is NOT a member) → pending invitation created (7-day expiry). Response:
```
type: "invitation"
```
. See project-invitation skill.

Field	Type	Required	Description
`email`	string	Yes	Target user's email

Response:

{ messageCode, message, projectId, type }

Code	Description
200	Shared or invitation created
400	Cannot share with owner
409	Already shared or invitation pending

bash

curl -X POST "https://data.spuree.com/api/v1/projects/{projectId}/share" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "collaborator@example.com"}'

与其他用户共享项目。根据目标用户是否为工作区成员，行为有所不同：

直接共享（目标用户是工作区成员）→ 立即添加。响应：
```
type: "direct"
```
邀请共享（目标用户非工作区成员）→ 创建待处理邀请（7天有效期）。响应：
```
type: "invitation"
```
。请查看project-invitation Skill。

字段	类型	是否必填	描述
`email`	string	是	目标用户的邮箱

响应：

{ messageCode, message, projectId, type }

代码	描述
200	共享成功或邀请已创建
400	无法与所有者共享
409	已共享或邀请待处理

bash

curl -X POST "https://data.spuree.com/api/v1/projects/{projectId}/share" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "collaborator@example.com"}'

DELETE /v1/projects/{projectId}/share/{email}

Remove a user from a shared project. Owner only.

Response:

{ messageCode, message, projectId }

bash

curl -X DELETE "https://data.spuree.com/api/v1/projects/{projectId}/share/{email}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

移除项目的共享用户。仅所有者可操作。

响应：

{ messageCode, message, projectId }

bash

curl -X DELETE "https://data.spuree.com/api/v1/projects/{projectId}/share/{email}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

GET /v1/projects/{projectId}/share

List the project's sharing info. Owner or shared user.

Response:

{ owner: "owner@example.com", sharedWith: ["..."] }

bash

curl "https://data.spuree.com/api/v1/projects/{projectId}/share" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

列出项目的共享信息。所有者或共享用户可操作。

响应：

{ owner: "owner@example.com", sharedWith: ["..."] }

bash

curl "https://data.spuree.com/api/v1/projects/{projectId}/share" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/projects/{projectId}/leave

Leave a project shared with you. Owner cannot leave.

Response:

{ messageCode, message, projectId }

bash

curl -X POST "https://data.spuree.com/api/v1/projects/{projectId}/leave" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

退出共享给你的项目。所有者无法退出。

响应：

{ messageCode, message, projectId }

bash

curl -X POST "https://data.spuree.com/api/v1/projects/{projectId}/leave" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

Common Patterns

常见模式

Browse a Project

浏览项目

```
GET /v1/projects
```
→ find the target project
```
GET /v1/projects/{id}/children
```
→ see contents
```
GET /v1/sessions/{folderId}/children
```
→ navigate deeper (folder-management skill)

```
GET /v1/projects
```
→ 找到目标项目
```
GET /v1/projects/{id}/children
```
→ 查看内容
```
GET /v1/sessions/{folderId}/children
```
→ 深入浏览（folder-management Skill）

Agent Workflow: Project Discovery

Agent工作流：项目发现

List projects → find the target
Get children → browse recursively
Use IDs with: folder-management, file-management

列出项目 → 找到目标项目
获取子内容 → 递归浏览
将ID用于：folder-management、file-management

Studio URLs

Studio链接

Resource	URL Pattern
Project	`https://studio.spuree.com/projects/{projectId}`
Folder (top-level)	`https://studio.spuree.com/projects/{projectId}/folders/{folderId}`
Folder (nested)	`.../folders/{parentId}/{childId}` (up to 5 levels)
File	`https://studio.spuree.com/file/{fileId}`

资源	URL格式
项目	`https://studio.spuree.com/projects/{projectId}`
文件夹（顶层）	`https://studio.spuree.com/projects/{projectId}/folders/{folderId}`
文件夹（嵌套）	`.../folders/{parentId}/{childId}` （最多5层）
文件	`https://studio.spuree.com/file/{fileId}`

Error Handling

错误处理

Code	Cause	Resolution
400	Invalid name (filesystem chars) or malformed ObjectId	Use Windows-compatible names, 24-char hex IDs
401	Expired or invalid token	Refresh via authentication skill
403	Not a workspace member or project owner	Check user permissions
409	Name conflict or duplicate share	Use different name or check existing shares

代码	原因	解决方法
400	名称无效（不符合文件系统字符规范）或ObjectId格式错误	使用Windows兼容的名称，24位十六进制ID
401	令牌过期或无效	通过authentication Skill刷新令牌
403	非工作区成员或项目所有者	检查用户权限
409	名称冲突或重复共享	使用不同名称或检查现有共享状态