List media files

Retrieves a list of all media files with filtering, searching, and ordering capabilities.

HTTP Request

GET/api/media/files

Authorization

Authorization

• Required: Yes
• Permission: Staff with FilePermission or Admin
• Permission Code: 3802
• Authentication: Token-based (Authorization: Token <your_api_key>)

Query Parameters

Parameter	Type	Default	Description
limit	integer	10	Number of results to return per page
offset	integer	0	Number of results to skip before returning results
search	string	—	Search term to lookup results by id, name
ordering	string	-created_at	Order results by (id, type, name, size, width, height, mode, created_at, updated_at, user__id, user__username, user__first_name, user__last_name, user__last_login)
id_min	integer	—	Minimum ID filter
id_max	integer	—	Maximum ID filter
created_date	string	—	Filter by creation date (e.g., 2023-01-01)
updated_date	string	—	Filter by last updated date (e.g., 2023-01-01)
created_from	string	—	Filter by creation date range start
created_to	string	—	Filter by creation date range end
updated_from	string	—	Filter by last updated date range start
updated_to	string	—	Filter by last updated date range end
type	string	—	Filter by file type (pdf, text, image, document, compressed, spreadsheet, presentation, video, audio)
user_id	integer	—	Filter by specific user ID who uploaded the file
size_min	integer	—	Minimum file size in bytes
size_max	integer	—	Maximum file size in bytes
width_min	integer	—	Minimum image width in pixels (applies to images only)
width_max	integer	—	Maximum image width in pixels (applies to images only)
height_min	integer	—	Minimum image height in pixels (applies to images only)
height_max	integer	—	Maximum image height in pixels (applies to images only)

Example Requests

🐍 Python

1import requests
2
3# List all files
4response = requests.get('http://www.example.com/api/media/files', 
5  headers={'Authorization': 'Token <your_api_key>'}
6)
7print(response.json())
8
9# Search for files with filters
10response = requests.get('http://www.example.com/api/media/files', params={
11  'search': 'profile',
12  'type': 'image',
13  'size_min': 1024,
14  'ordering': '-created_at',
15  'limit': 20
16}, headers={'Authorization': 'Token <your_api_key>'})
17print(response.json())
18
19# Filter by user and image dimensions
20response = requests.get('http://www.example.com/api/media/files', params={
21  'user_id': 123,
22  'width_min': 800,
23  'height_min': 600,
24  'created_from': '2023-01-01'
25}, headers={'Authorization': 'Token <your_api_key>'})
26print(response.json())

🌐 Curl

1# List all files
2curl "http://www.example.com/api/media/files" -H "Authorization: Token <your_api_key>"
3
4# Search with filters
5curl "http://www.example.com/api/media/files?search=profile&type=image&size_min=1024&ordering=-created_at&limit=20" \
6-H "Authorization: Token <your_api_key>"
7
8# Filter by user and image dimensions
9curl "http://www.example.com/api/media/files?user_id=123&width_min=800&height_min=600&created_from=2023-01-01" \
10-H "Authorization: Token <your_api_key>"

Response Fields

Field	Type	Description
count	Integer	Total number of categories
next	String	URL for the next page of results
previous	String	URL for the previous page of results
results	Array[Object]	Array of MediaFile objects

MediaFile Object Structure

Field	Type	Description
id	Integer	Unique ID of the file
type	String	File type(Choices)
user	Object	User who uploaded the file with id, username, full_name (nullable)
f	String	File URL/path
name	String	Original filename (nullable)
description	String	File description (nullable)
size	Integer	File size in bytes (nullable)
human_readable_size	String	Human-readable file size (e.g., "2.5 MB", nullable)
width	Integer	Image width in pixels (images only, nullable)
height	Integer	Image height in pixels (images only, nullable)
mode	String	Image color mode (images only, nullable)
created_at	String (ISO 8601)	Timestamp when file was uploaded
updated_at	String (ISO 8601)	Timestamp when file was last updated
thumbnails	List of thumbnail objects	thumbnails of the image files

Thumbnail Data Structure

Field	Type	Description
id	Integer	Unique ID of the thumbnail (unique)
f	String	URL to access the thumbnail file
size	Integer	File size in bytes (nullable)

*** User Object Structure

Field	Type	Description
id	Integer	Unique id of the uploader user
username	String	Username of the user
full_name	String	Full name of the user (computed value from first and last name)

Example Response

{
    "count": 9,
    "next": "http://127.0.0.1:8000/api/media/files?limit=3&offset=3",
    "previous": null,
    "results": [
        {
            "id": 9,
            "type": "text",
            "user": {
                "id": 14,
                "username": "Shakira_Anderson47",
                "full_name": "بهرام نوروزی"
            },
            "f": "http://127.0.0.1:8000/media/core_media/2025/12/22/askari.txt",
            "name": "textfile",
            "description": "",
            "size": 1408,
            "human_readable_size": "1.38 KB",
            "created_at": "2025-12-22T17:29:34.807896Z",
            "updated_at": "2025-12-22T17:29:34.807905Z"
        },
        {
            "id": 8,
            "type": "image",
            "user": {
                "id": 1,
                "username": "BehroozGhorbani",
                "full_name": "بهروز قربانی"
            },
            "f": "http://127.0.0.1:8000/media/core_media/2025/12/20/Fantasticheskie_kartinki_dlja_monitora_68_63.jpg",
            "name": "پیک موتوری",
            "description": "",
            "size": 808754,
            "human_readable_size": "789.80 KB",
            "width": 1920,
            "height": 1080,
            "mode": "RGB",
            "created_at": "2025-12-20T16:27:27.975156Z",
            "updated_at": "2025-12-20T16:27:27.975163Z",
            "thumbnails": [
                {
                    "id": 313,
                    "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_64x64.jpg",
                    "size": 64
                },
                {
                    "id": 314,
                    "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_128x128.jpg",
                    "size": 128
                },
                {
                    "id": 315,
                    "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_512x512.jpg",
                    "size": 512
                },
                {
                    "id": 316,
                    "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_1080x1080.jpg",
                    "size": 1080
                }
            ]
        },
        {
            "id": 7,
            "type": "image",
            "user": {
                "id": 1,
                "username": "BehroozGhorbani",
                "full_name": "بهروز قربانی"
            },
            "f": "http://127.0.0.1:8000/media/core_media/2025/12/02/computer.png",
            "name": "computers",
            "description": "the computers and all",
            "size": 3284,
            "human_readable_size": "3.21 KB",
            "width": 235,
            "height": 215,
            "mode": "P",
            "created_at": "2025-12-02T14:31:15.787793Z",
            "updated_at": "2025-12-02T14:31:15.787799Z",
            "thumbnails": [
              {
                  "id": 213,
                  "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_64x64.jpg",
                  "size": 64
              },
              {
                  "id": 214,
                  "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_128x128.jpg",
                  "size": 128
              },
              {
                  "id": 215,
                  "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_512x512.jpg",
                  "size": 512
              },
              {
                  "id": 216,
                  "f": "http://127.0.0.1:8000/media/core_media/2026/02/02/thumbnails/test2_ecH0zVV_thumbnail_1080x1080.jpg",
                  "size": 1080
              }
          ]
        }
    ]
}

Notes

• width, height, and mode fields are only included in the response for image files
• File type is automatically detected and set upon upload based on content and MIME type
• Search works on file ID and name fields
• Size filters work in bytes - use appropriate values for filtering by file size
• Image dimension filters (width_min, width_max, height_min, height_max) only apply to image files
• User object includes basic information about who uploaded the file
• Thubnails are only generated for image-type files