---
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.

## 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).

## 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
  - `offset` integer
  - `has_more` boolean

## Other responses

- `401` — Authentication required
- `422` — Validation Error

---

[API](https://skmtc.net/significant-gravitas/apis/autogpt-agent-server.md) · [All operations](https://skmtc.net/significant-gravitas/apis/autogpt-agent-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/significant-gravitas/autogpt-agent-server/versions/382041c7ecb2/schema)