Files, workspaces and projects

Work produces and consumes documents. Snaga keeps them in three places, each with a different job:

Files

An uploaded file is a stored record with an id. You can attach it to a run (input.file_ids), ingest it into an agent's memory, or add it to a knowledge base. Files are kept until you delete them.

curl -X POST https://api.snaga.ai/api/v1/files \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -F "[email protected]"

The answer is 201 with file_id, filename, mime_type, size_bytes and sha256. Instead of a form upload you can send JSON with base64 data and a mime_type.

Workspaces

A workspace is a small file system: folders and files that agents read and write with their file tools. It can belong to an agent, a team or the whole company, or stand alone until you assign it.

curl -X POST https://api.snaga.ai/api/v1/workspaces \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Quarterly reports" }'

Your plan sets how many workspaces you can have; past that, creation answers 403.

• POST /api/v1/workspaces/{workspaceId}/assign binds it to one agent_id, team_id or company_id. Assigning an agent also gives that agent the workspace file tools.
• POST /api/v1/workspaces/{workspaceId}/share lets one more agent read and write here; DELETE /api/v1/workspaces/{workspaceId}/share/{agentId} takes that access back.
• GET /api/v1/agents/{agentId}/workspace/files lists an agent's own workspace, and creates one if the agent has none yet.

Working with files in a workspace

Files are addressed by path.

# list a folder (add recursive=true for the whole tree)
curl "https://api.snaga.ai/api/v1/workspaces/<workspace_id>/files?path=drafts" \
  -H "Authorization: Bearer $SNAGA_API_KEY"

# write a file
curl -X PUT "https://api.snaga.ai/api/v1/workspaces/<workspace_id>/files?path=drafts/plan.md" \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @plan.md

Each write creates a new record with a new file_id, and the previous content moves into the file's history, so nothing is overwritten silently. GET /api/v1/workspaces/{workspaceId}/files/history?path=… lists earlier versions, newest first. To avoid overwriting someone else's change, send the file's etag back as If-Match.

All of these sit under /api/v1/workspaces/{workspaceId}. Search is bounded rather than exhaustive: it looks at up to 500 paths and returns up to 300 matches, so a missing hit may mean the limit was reached.

When a person deletes a file in the web app it goes to the workspace trash and can be restored. A delete made with an API key is permanent. Deleting a whole workspace with DELETE /api/v1/workspaces/{workspaceId} removes every file in it and cannot be undone.

Sharing a page

POST /api/v1/workspaces/{workspaceId}/publish takes a self-contained HTML page (up to 3 MB) and returns a token for a public link that lasts seven days. The page is shown in a sandboxed viewer, not run as a live site.

Projects

A project groups chats that belong together — a client, a launch, a research topic — and gives all of them the same context.

curl -X POST https://api.snaga.ai/api/v1/projects \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring launch",
    "instructions": "Our audience is small retailers. Keep copy under 100 words.",
    "knowledge_base_ids": ["<kb_id>"],
    "file_ids": ["<file_id>"]
  }'

instructions are added to the agent's own instructions in every chat of the project. visibility is tenant (everyone in the company, the default) or private, with shared_with naming who else may open it. A private project you cannot open answers 404, so its existence stays private too.

A chat joins a project through its project_id: pass it in metadata.project_id when creating the session, or set it later on the session; null takes the chat out. See Sessions.

To archive a project, PATCH it with an archived_at timestamp; send archived_at: null to bring it back. Deleting a project never deletes its chats — they are simply no longer filed under it, and chats_kept says how many.

Knowledge bases are covered in Memory and knowledge; every field is in the API reference.