Sign in
workspace

List workspace files

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.

get/api/workspace/files

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.

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.

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.

Only return files in this folder.

root_onlyboolean

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

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.

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.

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.

Response

Successful Response

offsetinteger
has_moreboolean

Changes

Changed in 6 of the 165 revisions of this API.3512

  • 7c34110a30721See the full diff
    • ○

      added the new optional query request parameter include_user_files

      new-optional-request-parameter

  • aed958578b4c3See the full diff
    • ○

      added the new optional query request parameter expert_id

      new-optional-request-parameter

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

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

      response-optional-property-added

  • 8b99899127183See the full diff
    • ○

      added the new optional query request parameter folder_id

      new-optional-request-parameter

    • ○

      added the new optional query request parameter root_only

      new-optional-request-parameter

    • ○

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

      response-optional-property-added

  • 8007c86ad53123See the full diff
    • ▲

      removed the enum value autopilot from the property anyOf[subschema #1]/ of the query request parameter origin

      request-parameter-property-enum-value-removed

    • ▲

      removed the enum value builder from the property anyOf[subschema #1]/ of the query request parameter origin

      request-parameter-property-enum-value-removed

    • ○

      added the enum value generated to the property anyOf[subschema #1]/ of the query request parameter origin

      request-parameter-property-enum-value-added

    • ○

      added the enum value uploaded to the property anyOf[subschema #1]/ of the query request parameter origin

      request-parameter-property-enum-value-added

    • ○

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

      response-required-property-added

  • 2163723f16ca2See the full diff
    • ○

      added the new optional query request parameter origin

      new-optional-request-parameter

    • ○

      added the new optional query request parameter q

      new-optional-request-parameter

  • 8c84efcb3afb15See the full diff
    • ▲

      removed the required property // from the response with the status

      response-required-property-removed

    • ●

      deleted the query request parameter folder_id

      request-parameter-removed

    • ●

      deleted the query request parameter origin

      request-parameter-removed

    • ●

      deleted the query request parameter q

      request-parameter-removed

    • ●

      deleted the query request parameter root_only

      request-parameter-removed

    • ●

      removed the optional property // from the response with the status

      response-optional-property-removed

    This revision also has 96 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog