Upload a media file

Uploads a new file to the system. The file will be associated with the authenticated user.

HTTP Request

POST/api/media/files

Authorization

Authorization

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

Request Body

Field	Type	Required	Description
f	File	Yes	File to upload (multipart/form-data)
name	String	No	Custom filename (defaults to original filename)
description	String	No	File description

Example Requests

🐍 Python

1import requests
2
3# Upload a file
4with open('image.jpg', 'rb') as file:
5  response = requests.post('http://www.example.com/api/media/files', 
6      files={
7          'f': ('image.jpg', file, 'image/jpeg')
8      },
9      data={
10          'name': 'Profile Picture',
11          'description': 'User profile avatar'
12      },
13      headers={'Authorization': 'Token <your_api_key>'}
14  )
15print(response.json())
16
17# Upload with minimal data
18with open('document.pdf', 'rb') as file:
19  response = requests.post('http://www.example.com/api/media/files', 
20      files={
21          'f': ('document.pdf', file, 'application/pdf')
22      },
23      headers={'Authorization': 'Token <your_api_key>'}
24  )
25print(response.json())

🌐 Curl

1# Upload a file
2curl -X POST "http://www.example.com/api/media/files" \
3-H "Authorization: Token <your_api_key>" \
4-F "f=@image.jpg" \
5-F "name=Profile Picture" \
6-F "description=User profile avatar"
7
8# Upload with minimal data
9curl -X POST "http://www.example.com/api/media/files" \
10-H "Authorization: Token <your_api_key>" \
11-F "f=@document.pdf"

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
thumbnails	List of thumbnail objects	thumbnails of the image

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

{
    "id": 10,
    "type": "image",
    "user": {
        "id": 1,
        "username": "BehroozGhorbani",
        "full_name": "بهروز قربانی"
    },
    "f": "http://127.0.0.1:8000/media/core_media/2025/12/22/Fantasticheskie_kartinki_dlja_monitora_68_68.jpg",
    "name": "slipknot member chris fehn",
    "description": "some description for image if required",
    "size": 1728593,
    "human_readable_size": "1.65 MB",
    "width": 2560,
    "height": 1600,
    "mode": "RGB",
    "created_at": "2025-12-22T17:43:06.351315Z",
    "updated_at": "2025-12-22T17:43:06.351324Z",
    "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
        }
    ]
}

Notes

• File upload requires multipart/form-data content type
• File type is automatically detected based on content and MIME type
• For image files, dimensions and color mode are automatically extracted
• Files are associated with the authenticated user who uploads them
• File size is automatically calculated and stored in both bytes and human-readable format
• Only the 'f' field is required; name and description are optional
• If name is not provided, the original filename will be used
• The user is automatically set to the current authenticated user
• Thumbnails are auto-generated in four sizes for image-type files