---
title: "List workspace files"
method: GET
path: "/api/workspace/files"
tags: ["workspace"]
---

# List workspace files

`GET /api/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 files from that hired expert's own
conversations. It excludes the other axes for the same reason. An expert
the caller does not own (or no longer has) yields an empty list.

## Query parameters

- `session_id` string, nullable
- `limit` integer
- `offset` integer
- `q` string, 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_id` string, nullable — Only return files in this folder.
- `root_only` boolean — Only return root-level files (not in any folder).
- `expert_id` string, nullable — Only return files from this hired expert's conversations. Cannot be combined with session_id, folder_id or root_only.

## Response `200`

Successful Response

- ListFilesResponse
  - `files` WorkspaceFileItem[], required
    - `id` string, required
    - `name` string, required
    - `path` string, required
    - `mime_type` string, required
    - `size_bytes` integer, required
    - `folder_id` string, nullable
    - `metadata` object
    - `origin` 'uploaded' | 'generated', required
    - `created_at` string, required
    - `expert_id` string, nullable
  - `offset` integer
  - `has_more` boolean

## Other responses

- `400` — Conflicting filters
- `401` — Authentication required
- `422` — Validation Error

## Changes

- **2026-09-08** `aed958578b4c` — 3 info
  - added the new optional `query` request parameter `expert_id`
  - added the non-success response with the status `400`
  - added the optional property `files/items/expert_id` to the response with the `200` status
- **2026-07-01** `8b9989912718` — 3 info
  - added the new optional `query` request parameter `folder_id`
  - added the new optional `query` request parameter `root_only`
  - added the optional property `files/items/folder_id` to the response with the `200` status
- **2026-06-15** `8007c86ad531` — 2 breaking, 3 info
  - removed the enum value `autopilot` from the property `anyOf[subschema #1]/` of the `query` request parameter `origin`
  - removed the enum value `builder` from the property `anyOf[subschema #1]/` of the `query` request parameter `origin`
  - added the enum value `generated` to the property `anyOf[subschema #1]/` of the `query` request parameter `origin`
  - added the enum value `uploaded` to the property `anyOf[subschema #1]/` of the `query` request parameter `origin`
  - …1 more
- **2026-05-30** `2163723f16ca` — 2 info
  - added the new optional `query` request parameter `origin`
  - added the new optional `query` request parameter `q`
- …earlier changes not shown

[Full history](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/changes/api/workspace/files/get.md)

---

[API](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server.md) · [All operations](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/llms.txt) · [OpenAPI document](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/revisions/9a062c6d49b5?raw)