Workspace Files API

The Files API manages canonical workspace files, including querio.toml, memory, skills, datasource catalogs, knowledge files, and uploaded data files. It does not manage notebook state, conversation state, or execution-process temporary files.

Requests use the app's authenticated session and the workspace's file permissions. Select the workspace with the Querio-Workspace-Id header. The header does not grant access by itself.

GET /api/v3/files/read?path=memory/MEMORY.md
Querio-Workspace-Id: YOUR_WORKSPACE_ID

Paths are workspace-relative. Absolute paths, parent traversal, .git, .gitignore, and upload staging files are not accessible. The workspace root cannot be renamed or deleted.

Operations

File metadata includes path, type, size, ctime, mtime, and revision. Times are milliseconds. Revisions are opaque change tokens, not content hashes. Reads return raw bytes and a quoted revision in the ETag header. HTTP reads and writes are limited to 100 MiB per file.

Directory listing returns { "entries": [...], "cursor": null }. A non-null cursor identifies the next page; send it with the same directory path. The default page size is 200, with a maximum of 1,000. Pagination does not create a frozen directory snapshot.

Live environment files

The same operations are available at /api/v3/environments/ENVIRONMENT_ID/files/* for a live execution environment. Include both Querio-Workspace-Id and Querio-Session-Id. The notebook's session-ready message supplies environment_id; it is not the session or conversation ID. The selected session must belong to the workspace and be bound to that environment.

These requests execute through the environment client and service inside the environment process. They do not access its filesystem from the CEE server or fall back to canonical storage when the environment is unavailable. Event subscriptions end when the selected session closes. Failed in-flight mutations are not automatically replayed after a service restart.

Explore's file browser uses these environment endpoints. The workspace Context screen continues to use canonical Files. Both targets currently may share underlying storage; the endpoint determines which process owns the operation.

Write intent

Choose one form:

• If-None-Match: *: create a new file; reject an existing destination.
• If-Match: "REVISION": replace an existing file only if its revision matches.
• If-Match: *: explicitly replace an existing file without checking its revision.
• Query parameters create=true|false and overwrite=true|false: explicitly control creation and replacement. For example, both true means create or replace without a revision check. Omitted flags default to false.

Do not combine write flags with revision headers. Missing write intent returns 428, an existing create-only destination returns 409, and a stale revision returns 412. The parent directory must already exist.

Writes replace individual files atomically: interrupted or rejected uploads do not publish partial content. Renames reject ancestor/descendant moves, mismatched destination types, and replacement of nonempty directories.

For removal and rename, use a quoted If-Match revision or If-Match: * for an unconditional operation. On rename, the revision refers to the source.

Changes and coordination

The event stream reports live change batches. It has no durable replay cursor; refresh the directory listing after reconnecting.

Revision checks coordinate cooperating writers within the process serving that filesystem. They do not coordinate independent CEE processes or direct mount writers. Workload ownership and deployment coordination remain separate responsibilities. File operations do not provide a multi-file transaction or an atomic workspace snapshot.

The former /api/cee/workspace/fs/* endpoints have been removed.