---
title: "List Files"
method: GET
path: "/v2/files"
tags: ["Files"]
---

# List Files

`GET /v2/files`

List all files for the authenticated organization, with optional filtering.

Args:
    workspace_uuid (str, optional): Filter by workspace UUID.
    file_type (str, optional): Filter by file type (image, video, text, document).

Returns:
    list[FileDetail]: List of files matching the filters.

Raises:
    AymaraAPIError: If the organization is missing.

Example:
    GET /api/v2/files?workspace_uuid=...&file_type=image

## Query parameters

- `workspace_uuid` string, nullable
- `file_type` string, nullable
- `limit` integer
- `offset` integer

## Response `200`

OK

- PagedFileDetail
  - `items` FileDetail[], required
    - `file_uuid` string, required — Unique identifier for the file.
    - `organization_uuid` string, required — UUID of the organization that owns this file.
    - `workspace_uuid` string, nullable — UUID of the workspace this file belongs to, if any.
    - `remote_file_path` string, required — S3 path to the file (or directory for videos).
    - `content_type` string, required — MIME type of the file.
    - `file_type` string, required — Type of file content (text, image, video, document).
    - `file_size_bytes` integer, nullable — Size of file in bytes, if known.
    - `original_file_url` string, nullable — Original file URL or path from upload.
    - `uploaded_by_uuid` string, nullable — UUID of user who uploaded the file.
    - `video_metadata` object, nullable — Video metadata (fps, duration, etc.) for video files.
    - `file_url` string, nullable — Presigned URL to access the file. For videos, points to raw video file. Use GET /api/v2/files/{file_uuid}/frames to get frame URLs. May be null in list responses for performance.
    - `created_at` string, date-time, required — Timestamp when the file was created.
    - `updated_at` string, date-time, required — Timestamp when the file was last updated.
  - `count` integer, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/aymara-ai/apis/aymara-api.md) · [All operations](https://skmtc.net/aymara-ai/apis/aymara-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aymara-ai/aymara-api/versions/0cb64ef11adf/schema)