List Files

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

HTTP Request

GET/api/media/files

Authorization

Authorization

• Required: Yes
• Permission: Staff or Admin
• 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 filter results by id, name
ordering	string	—	Field to 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)
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)
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

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

Status Codes

Code	Description
200	Files retrieved successfully
401	Unauthorized — authentication required
403	Forbidden — insufficient permissions
500	Internal server error

Response Fields

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

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