Files and projects
Work with durable project metadata and files in a user's Agent workspace.
Workspace projects and files use the /v1/agent/* routes. They belong to the authenticated user's durable workspace, outside disposable runtime compute.
Agents bind new chats to one of these projects by name.
List projects
/v1/agent/projectsReturns workspace projects and their thread summaries.
curl "$FLUSO_API/v1/agent/projects?includeArchived=false" \
-H "Authorization: Bearer $FLUSO_TOKEN"{
"projects": [
{
"name": "Release Review",
"goal": "Decide launch readiness",
"createdAt": "2026-08-31T09:00:00Z",
"updatedAt": "2026-08-31T09:00:00Z",
"threads": []
}
]
}Create a project
/v1/agent/projectsCreates a workspace project and its context file.
curl "$FLUSO_API/v1/agent/projects" \
-X POST \
-H "Authorization: Bearer $FLUSO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "Release Review",
"goal": "Decide launch readiness",
"instructions": "Keep evidence and decisions in this project."
}'{
"name": "Release Review",
"goal": "Decide launch readiness",
"instructions": "Keep evidence and decisions in this project.",
"createdAt": "2026-08-31T09:00:00Z",
"updatedAt": "2026-08-31T09:00:00Z",
"threads": []
}Update a project
/v1/agent/projectsUpdates the project named in the request body.
curl "$FLUSO_API/v1/agent/projects" \
-X PATCH \
-H "Authorization: Bearer $FLUSO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "Release Review",
"goal": "Decide launch readiness and record follow-up owners"
}'{
"name": "Release Review",
"goal": "Decide launch readiness and record follow-up owners",
"updatedAt": "2026-08-31T09:05:00Z",
"threads": []
}Export a project
/v1/agent/projects/exportStreams the named project as a ZIP archive.
curl -G "$FLUSO_API/v1/agent/projects/export" \
-H "Authorization: Bearer $FLUSO_TOKEN" \
--data-urlencode 'name=Release Review' \
-o release-review.zipHTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="Release Review.zip"; filename*=UTF-8''Release%20Review.zipList files
/v1/agent/filesLists files or directories under a workspace path.
curl "$FLUSO_API/v1/agent/files?path=/files&recursive=false&includeStats=true" \
-H "Authorization: Bearer $FLUSO_TOKEN"{
"path": "/files",
"recursive": false,
"entries": [
{
"path": "/files/release-brief.md",
"name": "release-brief.md",
"type": "file",
"size": 1240,
"modifiedAt": "2026-08-31T09:00:00Z",
"mimeType": "text/markdown"
}
]
}Read a text file
/v1/agent/files/readReturns a UTF-8 text file as JSON.
curl -G "$FLUSO_API/v1/agent/files/read" \
-H "Authorization: Bearer $FLUSO_TOKEN" \
--data-urlencode 'path=/files/release-brief.md'{
"path": "/files/release-brief.md",
"content": "# Release candidate\n\nKnown issue: ...\n",
"encoding": "utf-8"
}Upload a file
/v1/agent/files/uploadUploads one file with an optional destination and conflict policy.
curl "$FLUSO_API/v1/agent/files/upload" \
-H "Authorization: Bearer $FLUSO_TOKEN" \
-F 'file=@release-brief.md' \
-F 'path=/files/release-brief.md' \
-F 'onConflict=overwrite'{
"success": true,
"path": "/files/release-brief.md",
"size": 1240,
"mimeType": "text/markdown"
}onConflict accepts error, overwrite, or uuid. The default is error.
Download a file
/v1/agent/files/downloadStreams a file with attachment headers.
curl -G "$FLUSO_API/v1/agent/files/download" \
-H "Authorization: Bearer $FLUSO_TOKEN" \
--data-urlencode 'path=/files/release-report.pdf' \
-o release-report.pdfHTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="release-report.pdf"; filename*=UTF-8''release-report.pdfDelete a file
/v1/agent/filesDeletes one file, or a directory when recursive=true.
curl -G "$FLUSO_API/v1/agent/files" \
-X DELETE \
-H "Authorization: Bearer $FLUSO_TOKEN" \
--data-urlencode 'path=/files/release-brief.md' \
--data 'recursive=false'{
"success": true,
"path": "/files/release-brief.md"
}A recursive directory delete removes every child path. List the target first when its contents are not already known.
Next
Read Projects for the product workflow, attach project context to Agents and versions, or create project-bound Threads and messages.