File Management

File Management

Overview

Spuree is an agent-friendly cloud storage. Projects contain folders (nestable) and files at any level. This skill manages files — they can live directly under a project or inside any folder. In the API, projects and folders are both called sessions (sessionType: creative_project = project, session = folder).

Use this skill when an agent needs to:

• Search for files and folders by name across all projects
• Get a file by ID with download URL
• Upload new files to a project or folder
• Update file metadata (rename, move) or content (with conflict detection)
• Delete files (soft delete)

Authentication

Authorization: Bearer $SPUREE_ACCESS_TOKEN

Or: X-API-Key: $SPUREE_API_KEY. See the authentication skill.

Base URLs

Endpoints

GET /v1/search

Full-text search across files, folders, projects, and assets. Backed by the content_index collection (Atlas $search), kept in sync via MongoDB Change Streams.

Search is Atlas analyzer-based rather than substring matching. It returns one grouped item per source object, with the matching indexed rows in matches[], and uses an opaque cursor for pagination.

Query Parameters:

Response: { "data": [...], "count": N, "cursor": "<opaque token or null>" }

Continue pagination whenever cursor is non-null, even when count is smaller than the requested limit; canonical validation can suppress stale hits and produce a short page that still has another page.

Each data item is one matched source object. Common fields:

Canonical context objects use these exact wire shapes:

The container, project, and breadcrumb keys are required on every search item but nullable as one all-or-nothing context unit. Project and asset results use null context. File and folder results always carry a complete canonical context unit; hits whose current lineage is missing, deleted, malformed, stale, or unauthorized are omitted rather than returned with null or partial hierarchy metadata. For file and folder results, use these canonical names and IDs instead of deriving hierarchy from snippets or denormalized index fields.

container has the exact shape { id, name, kind }, where kind is folder or project. Only a folder container ID belongs in a /folders/{containerId} URL; a project container is the project root and belongs in /projects/{containerId}.

File / folder / project items may additionally carry fileName, fileFormat (file only), sessionId, and entitySessionId (owning entity, if any). For a file, sessionId is its current canonical containing folder or project. For a folder or project result, sessionId identifies the matched session itself; determine parentage only from container and breadcrumb. Folder / project items also carry sessionName — the clean display name. Use it for display rather than deriving a name from snippets/row text, which mix the name with tags (folders) or description + tags (projects).

Asset items instead carry asset-specific fields (no fileName/fileFormat):

Each entry in matches[]:

# Find files with any analyzed term from "hero"
curl "https://data.spuree.com/api/v1/search?q=hero&type=file" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

# Search file names for an exact analyzed phrase, restricted to one project
curl "https://data.spuree.com/api/v1/search?q=quarterly%20report&type=file&searchIn=name&matchMode=phrase&projectId=...&format=txt,md&limit=50" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

# Next page: replay the original query and corpus-shaping parameters
curl "https://data.spuree.com/api/v1/search?q=hero&type=file&cursor=<token>" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

Newly issued HMAC-signed v1 cursors also bind the caller's current permission scope. Treat a cursor as opaque; do not edit or reuse it with a different query, source type, filter set, or caller. A malformed, tampered, or mismatched bound cursor returns 422. If a previously valid cursor returns 422 after the caller's permission scope changes, discard it and restart from page one with the same query and filters; do not retry the rejected cursor.

Unsigned pre-v1 cursors are treated as unbound any-mode compatibility tokens, regardless of a re-sent matchMode, only until 2026-09-07 00:00 UTC. During that bounded migration window, a fully stripped and re-encoded modern payload is statelessly indistinguishable from a genuine v0 token, so keep any unsigned cursor only within its original pagination sequence. At and after the sunset, every unsigned cursor is rejected; only a valid signed v1 envelope is accepted.

Status Codes:

GET /v1/files/{fileId}

Get file metadata and presigned download URL.

Response: { "data": { id, fileName, fileFormat, mimeType, size, workspaceId, sessionId, entitySessionId, downloadUrl, createdAt, updatedAt } }

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

GET /v1/files/{fileId}/content

Get inline UTF-8 text content for a small text-like file. Use this when an agent needs to read markdown, text, JSON, CSV, YAML, XML, subtitles, logs, or source files directly instead of following a short-lived CloudFront download URL.

This endpoint is not a replacement for file downloads. Binary files and large files should still use GET /v1/files/{fileId} and its downloadUrl.

Response: { "data": { id, fileName, fileFormat, mimeType, size, encoding, content, truncated } }

truncated is reserved: oversize files return 413 rather than a partial body, so it is currently always false.

curl "https://data.spuree.com/api/v1/files/{fileId}/content" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/files

Create a file record and get presigned upload URL(s). Automatically selects upload mode based on file size:

• < 100 MB → single presigned PUT URL (mode: "single")
• ≥ 100 MB → multipart upload with per-part presigned URLs (mode: "multipart")

The caller must then upload to S3 and call POST /v1/files/{fileId}/upload/complete. Without the complete call, the file remains pending and unusable.

Request Body:

Response (single mode): { messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }

Response (multipart mode): { messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }

curl -X POST "https://data.spuree.com/api/v1/files" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"hero_walk","fileFormat":"fbx","fileSize":5242880,"sessionId":"...","checksum":"AAAAAA=="}'

POST /v1/files/{fileId}/upload/complete

Mark a file upload as completed. Works for both single and multipart uploads — the server auto-detects by checking whether the file has an active multipart uploadId. For multipart, the server calls S3 ListParts to collect ETags and then CompleteMultipartUpload.

Request Body:

Response: { messageCode, fileId, checksum, checksumCRC32 }

• checksum: S3-verified CRC32 (base64) for both single and multipart uploads
• checksumCRC32: S3 FULL_OBJECT CRC32 (multipart only)

curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/complete" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "..."}'

PATCH /v1/files/{fileId}

Update file metadata. At least one field required.

Move: Only creative_project (project) and session (folder) targets supported.

Response: { messageCode, fileId }

curl -X PATCH "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "hero_run_cycle"}'

PUT /v1/files/{fileId}

Prepare a content update with optimistic concurrency. Acquires an upload lock. Like POST /v1/files, automatically selects single or multipart mode based on fileSize.

Request Body:

Response (single): { messageCode, fileId, mode: "single", uploadUrl, checksumBase64, contentType }

Response (multipart): { messageCode, fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }

After receiving the response, upload to S3 then call POST /v1/files/{fileId}/upload/complete.

Upload lock: Single uploads lock for 1 hour. Multipart uploads lock for 6 hours. Same user can re-acquire. Expired locks auto-release.

curl -X PUT "https://data.spuree.com/api/v1/files/{fileId}" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedChecksum": "a1b2...","newChecksum": "f6e5..."}'

GET /v1/files/{fileId}/upload

Resume a multipart upload. Returns which parts are already in S3 and fresh presigned URLs for remaining parts.

Query Parameters:

Response: { messageCode, fileId, completedParts: [{partNumber, etag, size}, ...], remainingParts: [{partNumber, startByte, endByte, url}, ...], totalParts }

curl "https://data.spuree.com/api/v1/files/{fileId}/upload" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN"

POST /v1/files/{fileId}/upload/urls

Refresh presigned URLs for specific parts of a multipart upload. Use when URLs have expired before upload completes.

Request Body: { "partNumbers": [1, 3, 5] } (1-indexed, min 1 part)

Response: { messageCode, urls: [{partNumber, startByte, endByte, url}, ...] }

curl -X POST "https://data.spuree.com/api/v1/files/{fileId}/upload/urls" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"partNumbers": [1, 3, 5]}'

DELETE /v1/files/{fileId}/upload

Abort a multipart upload. Cleans up S3 parts and marks the file as failed. Idempotent — safe to call on already-aborted uploads.

Response: { messageCode, fileId, message }

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

DELETE /v1/files/{fileId}

Soft-delete a file.

Response: { messageCode, fileId }

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

Common Patterns

Single Upload Flow (< 100 MB)

1. Compute CRC32 checksum (base64):

   CHECKSUM=$(python3 -c "import base64, zlib, sys; print(base64.b64encode(zlib.crc32(open('$FILE_PATH','rb').read()).to_bytes(4,'big')).decode())")
   

2. Create file record — sessionId is the target project or folder:

   POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
   → { fileId, mode: "single", uploadUrl, checksumBase64, contentType }
   

3. Upload binary to S3:

   PUT {uploadUrl}
   Content-Type: {contentType}
   x-amz-checksum-crc32: {checksumBase64}
   Body: <file binary>
   

4. Complete the upload — REQUIRED (file is not visible until this is called):

   POST /v1/files/{fileId}/upload/complete
   

Important: All three steps (create → S3 upload → complete) must be performed. Skipping complete leaves the file in a pending state.

Multipart Upload Flow (≥ 100 MB)

1. Create file record with fileSize ≥ 100 MB:

   POST /v1/files { fileName, fileFormat, fileSize, sessionId, checksum }
   → { fileId, mode: "multipart", parts: [{partNumber, startByte, endByte, url}, ...], totalParts, expiresAt }
   

2. Upload each part to its presigned URL:

   PUT {part.url}
   Content-Length: {part.endByte - part.startByte + 1}
   Body: <file slice from startByte to endByte>
   

3. If interrupted, resume with GET /v1/files/{fileId}/upload to get completed parts and fresh URLs for remaining parts.

4. If URLs expire, refresh with POST /v1/files/{fileId}/upload/urls for specific parts.

5. Complete — server auto-detects multipart and calls S3 CompleteMultipartUpload:

   POST /v1/files/{fileId}/upload/complete
   

6. To abort, call DELETE /v1/files/{fileId}/upload to clean up S3 parts.

Content Update Flow

1. PUT /v1/files/{fileId} with checksums (and fileSize for multipart) → get upload URL(s)
2. Upload new content to S3 (single or multipart, same as above)
3. POST /v1/files/{fileId}/upload/complete — REQUIRED

Viewing / Previewing a File

When a user wants to view, preview, or see a file:

1. If the agent has browser tools (e.g., Chrome DevTools MCP), open the Studio preview URL directly:

   navigate_page → https://studio.spuree.com/files/{fileId}
   

2. Otherwise, return the Studio preview URL for the user to click:

   https://studio.spuree.com/files/{fileId}
   

Do not download the file or attempt to open it locally. The Studio URL is permanent, permission-aware, and renders images, video, 3D, and other supported formats inline in the browser.

Rule of thumb: after POST /v1/files (upload) build the Studio URL from the returned fileId; after GET /v1/search use the result's sourceId (the file id, for sourceType: "file" items). Return that URL to the user. Only fetch downloadUrl when the agent itself needs the bytes.

Search Then Download

1. GET /v1/search?q=hero_walk&type=file → take sourceId from a sourceType: "file" result
2. GET /v1/files/{sourceId} → get downloadUrl
3. Download from the presigned URL

File Organization

Projects and folders are both sessions. sessionId always refers to a session. Session types: creative_project (project), session (folder). Folders nest inside projects or other folders.

S3 key: works_{workspaceId}/sess_{sessionId}/file_{fileId}

Studio URLs

Error Handling