Media API Reference

The Media API provides endpoints for managing media files programmatically. This document outlines all available media operations through the API.

Authentication

All media endpoints require API token authentication and specific media scopes. See the Authentication section for details about obtaining and using API tokens.

List Media

Retrieve a paginated list of media files.

Query Parameters

• page: Page number (default: 1)
• page_size: Items per page (default: 10, max: 100)
• type: Filter by media type (image, video, audio, file)
• search: Search by file name

Response Format

{
  "data": [
    {
      "id": "uuid",
      "name": "example.jpg",
      "type": "image",
      "mime_type": "image/jpeg",
      "size": 1024,
      "path": "media/example.jpg",
      "url": "https://example.com/media/example.jpg",
      "width": 800,
      "height": 600,
      "duration": null,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "created_by": "user-uuid"
    }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "page_size": 10
  }
}

Get Media

Retrieve a specific media file by its ID.

Upload Media

Upload a new media file.

Supported File Types

Images

• JPEG (.jpg, .jpeg) - image/jpeg
• PNG (.png) - image/png
• GIF (.gif) - image/gif

Documents

• PDF (.pdf) - application/pdf
• Microsoft Word (.doc, .docx) - application/msword
• Microsoft Excel (.xls, .xlsx) - application/vnd.ms-excel

Media

• Video (.mp4) - video/mp4
• Audio (.mp3) - audio/mpeg

File Size Limits

• Images: Max 10MB
• Documents: Max 20MB
• Videos: Max 100MB
• Audio: Max 50MB

Delete Media

Delete a media file.

Error Responses

400 Bad Request

{
  "error": "No file uploaded"
}

{
  "error": "Invalid file type"
}

401 Unauthorized

{
  "error": "Missing or invalid API token"
}

403 Forbidden

{
  "error": "Insufficient scope"
}

404 Not Found

{
  "error": "Media not found"
}

500 Internal Server Error

{
  "error": "Failed to upload file"
}

{
  "error": "Failed to create media record"
}

Best Practices

1. File Preparation

   • Optimize images before upload
   • Use appropriate file formats
   • Keep file sizes within limits
   • Use descriptive file names

2. Error Handling

   • Implement proper error handling
   • Validate file types before upload
   • Handle network issues gracefully
   • Check file size limits

3. Security

   • Validate file content types
   • Scan for malware
   • Use secure connections (HTTPS)
   • Implement proper authentication

4. Performance

   • Batch uploads when possible
   • Consider implementing resumable uploads
   • Cache frequently accessed media
   • Use appropriate compression