---
title: "List your uploaded files"
method: GET
path: "/v1/ai/uploads"
tags: ["uploads"]
---

# List your uploaded files

`GET /v1/ai/uploads`

## Request

- Base URL: `https://api.magnific.com`
- URL: `https://api.magnific.com/v1/ai/uploads`
- Auth: API key in header `x-magnific-api-key`

Lists the files you have uploaded, each identified by its opaque `file_id`, with size and expiration metadata plus a freshly-signed readable `asset_url`.

## Response `200`

OK - The list of uploaded files.

- UploadListResponse
  - `files` UploadListItem[], required
    - `file_id` string: Opaque identifier of the uploaded file. Use this value in reference_images, image_url, video_url, or similar fields.
    - `content_type` string: MIME type of the file
    - `size_bytes` integer: File size in bytes
    - `created_at` string, date-time: Upload timestamp
    - `expires_at` string, date-time: Expiration timestamp (based on bucket lifecycle)
    - `ttl_seconds` integer: Seconds until the file becomes eligible for auto-deletion (bucket lifecycle). Deletion is eventual, so the file may persist a little past this.
    - `asset_url` string, uri: Readable URL for the file (image, video or audio), serving the original file. A fresh URL is signed on each listing and stays valid for about a day (asset_url_expires_in); an expired URL returns 403, so just list again to get a new one. Once the file itself is deleted (see ttl_seconds) no URL works. Use it as image_url/video_url/audio_url/reference in any endpoint that accepts a URL. Prefer file_id on AI endpoints when available.
    - `asset_url_expires_in` integer: Seconds until asset_url expires (counted from this listing response).

## Other responses

- `401`: Unauthorized - The client must authenticate itself to get the requested response.
- `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
- `503`: Service Unavailable

---

[API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)