> ## Documentation Index
> Fetch the complete documentation index at: https://docs.imperial.gay/llms.txt
> Use this file to discover all available pages before exploring further.

# List Media

> Retrieve a paginated list of your uploaded media

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key in the format: `Bearer imperial_live_xxxxxxxxxxxxx`
</ParamField>

### Query Parameters

<ParamField query="page" type="number" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of items per page (max: 100)
</ParamField>

<ParamField query="status" type="string" default="active">
  Filter by status: `active`, `trash`, or `all`
</ParamField>

<ParamField query="folderId" type="string">
  Filter by folder. For `active` status, leaving this empty shows **Root** by default.
</ParamField>

<ParamField query="q" type="string">
  Search across your whole library (filename/original filename, plus tag exact match)
</ParamField>

<ParamField query="from" type="string">
  Date filter start (YYYY-MM-DD, UTC)
</ParamField>

<ParamField query="to" type="string">
  Date filter end (YYYY-MM-DD, UTC)
</ParamField>

<ParamField query="mimePrefix" type="string">
  MIME prefix filter (e.g. `image/`, `video/`, `application/`) or `other`
</ParamField>

<ParamField query="minSize" type="number">
  Minimum file size in bytes
</ParamField>

<ParamField query="maxSize" type="number">
  Maximum file size in bytes
</ParamField>

<ParamField query="favorite" type="boolean">
  Filter favorites (`true` or `false`)
</ParamField>

<ParamField query="tags" type="string">
  Include tags (comma-separated). Must include **all** tags.
</ParamField>

<ParamField query="excludeTags" type="string">
  Exclude tags (comma-separated)
</ParamField>

<Info>Back-compat: `tag=foo` is still supported and behaves like `tags=foo`.</Info>

## Response

<ResponseField name="images" type="array">
  Array of media objects (images and videos)
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information

  <Expandable title="pagination properties">
    <ResponseField name="page" type="number">
      Current page number
    </ResponseField>

    <ResponseField name="limit" type="number">
      Items per page
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of items
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.imperial.gay/images?page=1&limit=20" \
    -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx"
  ```

  ```javascript Node.js theme={null}
  const axios = require("axios");

  const response = await axios.get("https://api.imperial.gay/images", {
    headers: {
      Authorization: "Bearer imperial_live_xxxxxxxxxxxxx",
    },
    params: {
      page: 1,
      limit: 20,
    },
  });

  console.log(response.data);
  ```

  ```python Python theme={null}
  import requests

  url = 'https://api.imperial.gay/images'
  headers = {'Authorization': 'Bearer imperial_live_xxxxxxxxxxxxx'}
  params = {'page': 1, 'limit': 20}

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "images": [
    {
      "_id": "67d8f9a1b2c3d4e5f6789012",
      "url": "https://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789012-cat.jpg",
      "thumbnailUrl": null,
      "mimeType": "image/jpeg",
      "prompt": "cat.jpg",
      "modelName": "240.1KB",
      "size": {
        "width": 0,
        "height": 0
      },
      "createdAt": "2026-01-07T12:34:56.789Z",
      "type": "upload"
    },
    {
      "_id": "67d8f9a1b2c3d4e5f6789013",
      "url": "https://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789013-video.mp4",
      "thumbnailUrl": "https://origin.imperial.gay/uploads/user-id/thumbs/67d8f9a1b2c3d4e5f6789013-thumb.jpg",
      "mimeType": "video/mp4",
      "prompt": "video.mp4",
      "modelName": "5.0MB",
      "size": {
        "width": 0,
        "height": 0
      },
      "createdAt": "2026-01-07T12:35:00.123Z",
      "type": "upload"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 245,
    "totalPages": 13
  }
}
```

## Media Object Fields

<ResponseField name="_id" type="string">
  Unique identifier for the media
</ResponseField>

<ResponseField name="url" type="string">
  Direct CDN URL to the media file
</ResponseField>

<ResponseField name="thumbnailUrl" type="string | null">
  Thumbnail URL (for videos only, `null` for images)
</ResponseField>

<ResponseField name="mimeType" type="string">
  MIME type (e.g., `image/jpeg`, `video/mp4`)
</ResponseField>

<ResponseField name="prompt" type="string">
  Original filename
</ResponseField>

<ResponseField name="modelName" type="string">
  File size displayed in human-readable format
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of upload
</ResponseField>

<ResponseField name="type" type="string">
  Always `"upload"` for user uploads
</ResponseField>

## Pagination

The API returns up to 50 items per page by default. Use the `page` and `limit` parameters to navigate through your media:

```bash theme={null}
# Get page 2 with 100 items per page
curl -X GET "https://api.imperial.gay/images?page=2&limit=100" \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx"
```

## Filtering

Currently, the API returns all media sorted by upload date (newest first). Additional filtering options will be added in future updates.

## Error Responses

### Unauthorized

```json theme={null}
{
  "error": "Unauthorized",
  "statusCode": 401
}
```

### Invalid Parameters

```json theme={null}
{
  "error": "Invalid page or limit parameter",
  "statusCode": 400
}
```

<Tip>Use this endpoint to build custom galleries or dashboards for your media library.</Tip>