workspace

List workspace files

Changed on

List files in the user's workspace.

When session_id is provided, only files for that session are returned. Otherwise, all files across sessions are listed. Results are paginated via limit/offset; has_more indicates whether additional pages exist.

The Artifacts page uses q for name search and origin to filter between Uploaded (user-uploaded) and Generated (agent/block output) files.

session_id (a per-session view) and the folder filters (folder_id / root_only) are distinct, mutually exclusive axes, and folder_id and root_only likewise conflict; passing conflicting filters returns a 400 rather than silently yielding an empty list.

expert_id narrows the listing to that hired expert's own conversations. It conflicts with session_id — both name which conversations to show — but composes with the folder filters, which select across the whole workspace. An expert the caller does not own (or no longer has) yields an empty list.

include_user_files widens an expert_id listing with the user's own files, which an expert may read but which are nobody's conversation. It is opt-in so that a view already filtered to one expert keeps showing that expert's files and nothing else; the composer's picker sends it when its "only this expert" filter is switched off.

The listing is of the user's files: skill packages and Otto's working files (isInternal, decided when each file is written) are left out in the query, so paging stays correct. include_internal lists them too, for a view that shows them apart.

get/api/workspace/files

Request

  • The document declares no server URL.
  • Auth
    HTTP bearer

Query parameters

session_idstring nullable
limitinteger
offsetinteger
qstring nullable

Case-insensitive substring search on file name. Applied in the database for fresh results without waiting on embedding generation.

origin'uploaded' | 'generated' nullable

Filter by file origin. uploaded matches files the user uploaded (metadata.origin == 'user-upload', set by the upload endpoint for both Builder and CoPilot uploads); generated matches everything else (agent/block output). Ignored when session_id is set.

folder_idstring nullable

Only return files in this folder.

root_onlyboolean

Only return root-level files (not in any folder).

expert_idstring nullable

Only return files from this hired expert's own conversations. Combines with folder_id, root_only and include_user_files; cannot be combined with session_id.

include_user_filesboolean

With expert_id, also return the user's own files — everything outside /sessions/, /experts/ and /skills/ — which the expert may read but which are not its own. Requires expert_id.

include_internalboolean

Also return the files the Files page leaves out: the skill packages hired experts read (under /skills/ and /experts/{id}/skills/) and Otto's own working files. Each such file is listed with is_internal set.

Response

Successful Response

offsetinteger
has_moreboolean

Changes

    • info

      added the new optional query request parameter include_internal

    • info

      added the optional property // to the response with the status

    • info

      added the new optional query request parameter include_user_files