Files

The Files API lets you manage files and folders within a workspace.

Listing files

# List files in the root directory
curl "https://api.arg.ai/api/workspaces/ws_123/files?path=/" \
  -H "X-API-Key: YOUR_API_KEY"

# Get the full recursive file tree
curl https://api.arg.ai/api/workspaces/ws_123/files/tree \
  -H "X-API-Key: YOUR_API_KEY"

Uploading files

Upload a file using multipart form data:

curl -X POST "https://api.arg.ai/api/workspaces/ws_123/files/upload?path=/src" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]"

For large files, the API also supports a multipart upload (/files/upload/initiate, /part, /complete, /abort).

The TypeScript SDK handles this for you: files.upload() automatically switches to a resilient multipart upload for large files (chunking, bounded concurrency, per-part retry, and progress), downloadStream() streams without buffering, and move / copy / delete work in batches.

Downloading files

# Download a single file
curl "https://api.arg.ai/api/workspaces/ws_123/files/download?path=/src/main.py" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o main.py

# Download a folder as zip
curl "https://api.arg.ai/api/workspaces/ws_123/files/download-folder?path=/src" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o src.zip

Reading and writing file content

For text files, you can read and write content directly without downloading:

Read file content

curl "https://api.arg.ai/api/workspaces/ws_123/files/content?path=/src/main.py" \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "path": "/src/main.py",
  "name": "main.py",
  "content": "print('hello world')\n",
  "encoding": "utf-8",
  "mime_type": "text/x-python",
  "size": 21,
  "revision": "…",
  "fileId": "argfile_…",
  "protection": null
}

Binary files come back with "encoding": "base64". Very large files must be downloaded instead. protection is non-null when the file is locked, and revision is what you pass back on a conditional write.

Update file content

curl -X PUT "https://api.arg.ai/api/workspaces/ws_123/files/content?path=/src/main.py" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "print(\"updated\")\n",
    "encoding": "utf-8"
  }'

Writing without clobbering someone else

A plain write overwrites whatever is there. When an agent, a collaborator, or another job might be editing the same file, write conditionally instead:

Field	Effect
`baseRevision`	Write only if the file is still at that revision. A mismatch returns `409` with the current revision, so you can re-read and retry.
`createOnly`	Write only if the file does not exist yet.

curl -X PUT "https://api.arg.ai/api/workspaces/ws_123/files/content?path=/data/ledger.csv" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "…", "baseRevision": "REVISION_FROM_YOUR_READ"}'

The two cannot be combined.

File management

Create a folder

curl -X POST https://api.arg.ai/api/workspaces/ws_123/files/mkdir \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/src/utils"}'

Move or rename

curl -X POST https://api.arg.ai/api/workspaces/ws_123/files/move \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_path": "/old-name.py",
    "destination_path": "/new-name.py"
  }'

Delete files

curl -X DELETE https://api.arg.ai/api/workspaces/ws_123/files \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/temp.py", "/old-folder"]}'

Versions

When versioning is on for the workspace, every write keeps the previous copy.

# List versions of a file
curl "https://api.arg.ai/api/workspaces/ws_123/files/versions?path=/data/ledger.csv" \
  -H "X-API-Key: YOUR_API_KEY"

# Read one version's content
curl "https://api.arg.ai/api/workspaces/ws_123/files/versions/VERSION_ID/content" \
  -H "X-API-Key: YOUR_API_KEY"

# Restore it
curl -X POST "https://api.arg.ai/api/workspaces/ws_123/files/versions/VERSION_ID/restore" \
  -H "X-API-Key: YOUR_API_KEY"

Referring to a file that might move

Paths change; ids do not. Ask for a file’s stable id once and store that instead, then resolve it back to a path when you need to read the file.

# Get (or mint) the id for a file path; pass kind: folder for a folder
curl -X POST https://api.arg.ai/api/workspaces/ws_123/files/get-id \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"path": "/reports/august.mdx"}'

# Resolve an id back to its current path
curl "https://api.arg.ai/api/workspaces/ws_123/files/resolve-id?id=argfile_…" \
  -H "X-API-Key: YOUR_API_KEY"

Ids look like argfile_… and survive renames and moves. Documents that embed other files use them for exactly this reason - see list references and what points at a file. The optional kind is file by default. Send {"path":"/sites/portfolio","kind":"folder"} when the referenced node is a folder.

Locking a file

Lock a file to stop writes while something else owns it - a long import, a review window. The lock is enforced on every write path, agents included.

curl -X POST https://api.arg.ai/api/workspaces/ws_123/files/lock \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"path": "/data/ledger.csv", "reason": "Month-end close"}'

Release it with /files/unlock, and list active locks with /files/protections. Create a public download link for a file:

curl -X POST https://api.arg.ai/api/workspaces/ws_123/files/share \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/report.pdf",
    "expires_hours": 48,
    "password": "optional-password"
  }'

Shared files can be accessed without authentication. See the Sharing API for details.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Listing files

Uploading files

Downloading files

Reading and writing file content

Read file content

Update file content

Writing without clobbering someone else

File management

Create a folder

Move or rename

Delete files

Versions

Referring to a file that might move

Locking a file

​Listing files

​Uploading files

​Downloading files

​Reading and writing file content

​Read file content

​Update file content

​Writing without clobbering someone else

​File management

​Create a folder

​Move or rename

​Delete files

​Versions

​Referring to a file that might move

​Locking a file

​File sharing

Listing files

Uploading files

Downloading files

Reading and writing file content

Read file content

Update file content

Writing without clobbering someone else

File management

Create a folder

Move or rename

Delete files

Versions

Referring to a file that might move

Locking a file

File sharing