Streamline your WordPress media workflow with this lightweight plugin that exports selected media files to a publicly accessible JSON endpoint, perfect for headless CMS implementations, mobile apps, and third-party integrations.
Introduction
In today’s interconnected digital ecosystem, WordPress often serves as more than just a website platform—it’s a content management system that feeds data to mobile applications, external services, and headless frontend frameworks. The Media JSON Exporter plugin bridges this gap by providing a simple, elegant solution for exposing selected media files through a JSON API endpoint.
Whether you’re building a React Native mobile app, integrating with a Next.js frontend, or simply need a programmatic way to access your media library, this plugin offers a straightforward approach without the complexity of custom REST API development.
The Problem: Media Access Beyond WordPress
WordPress developers frequently encounter scenarios where external applications need access to specific media files. Traditional solutions involve:
- Building custom REST API endpoints (time-consuming and requires ongoing maintenance)
- Using the full WordPress REST API (often provides too much data and requires authentication)
- Manual CSV exports (static, non-scalable, and error-prone)
- Database queries from external applications (security risks and coupling issues)
Each approach has significant drawbacks. Custom endpoints require development time and WordPress API knowledge. The native REST API exposes more data than needed. Manual exports become outdated immediately. Direct database access creates security vulnerabilities.
The Solution: Selective JSON Export
Media JSON Exporter takes a different approach: it allows content managers to selectively mark media files for export through a simple checkbox interface, then automatically generates and maintains a publicly accessible JSON file containing only the chosen media URLs and metadata.
Key Features
1. Simple User Interface
The plugin adds a single checkbox labeled “Include in JSON Export” to the media editor screen. No complex configuration, no technical knowledge required—just check a box and save.
2. Automatic Synchronization
The JSON file regenerates automatically whenever media is added, edited, or deleted. Your external applications always have access to the latest data without manual intervention.
3. Public JSON Endpoint
The exported JSON file lives at a predictable URL: /wp-content/uploads/media-export.json. No authentication required, no API keys to manage—simple HTTP GET requests return your media data.
4. Rich Metadata
Each exported media item includes comprehensive information:
- ID: WordPress attachment ID for reference
- Title: The media file’s title
- URL: Direct public URL to the file
- Type: MIME type (image/jpeg, image/png, video/mp4, etc.)
- Alt Text: Accessibility alternative text
- Description: Full media description
- Caption: Media caption text
- Date: Upload/modification timestamp
5. Admin Management Interface
A dedicated admin page under Media → JSON Export provides:
- The public JSON URL for easy copying
- Count of currently exported media files
- Manual regeneration button for troubleshooting
- Clear usage instructions
Real-World Use Cases
Headless CMS Architecture
Modern web applications often separate the frontend from the backend. A React or Vue.js application might pull content from WordPress while maintaining its own interface. Media JSON Exporter allows you to mark specific images for use in your frontend application, creating a curated media feed.
// React component example
useEffect(() => {
fetch('https://yoursite.com/wp-content/uploads/media-export.json')
.then(response => response.json())
.then(data => {
setGalleryImages(data.filter(item => item.type.startsWith('image/')));
});
}, []);
Mobile Application Integration
Mobile apps built with React Native, Flutter, or native iOS/Android often need to display images and media from a WordPress site. Rather than implementing OAuth authentication and parsing the full REST API, developers can simply fetch the JSON export:
// React Native example
const loadMedia = async () => {
const response = await fetch('https://yoursite.com/wp-content/uploads/media-export.json');
const mediaData = await response.json();
// Filter for specific image types
const banners = mediaData.filter(item =>
item.title.includes('banner') && item.type === 'image/png'
);
setBannerImages(banners);
};Dynamic Image Galleries
Create client-side photo galleries that update automatically as you add new images to WordPress. Mark gallery images with the export checkbox, and your JavaScript gallery fetches the latest set on each page load.
CDN Distribution Lists
Generate manifests for CDN synchronization by exporting specific media files. Your deployment scripts can parse the JSON to identify which assets need to be pushed to your CDN.
Third-Party Service Integration
Services like email marketing platforms, social media schedulers, or content aggregators can pull your curated media without WordPress authentication. Simply provide the JSON URL.
Technical Implementation
JSON Structure
The exported file contains a clean, flat array of media objects:
[
{
"id": 245,
"title": "Product Hero Image",
"url": "https://yoursite.com/wp-content/uploads/2024/01/hero-product.jpg",
"type": "image/jpeg",
"alt": "Premium wireless headphones on marble surface",
"description": "Main product photography for homepage hero section",
"caption": "New ANC Pro Series",
"date": "2024-01-15 10:30:00"
},
{
"id": 246,
"title": "About Us Team Photo",
"url": "https://yoursite.com/wp-content/uploads/2024/01/team-2024.jpg",
"type": "image/jpeg",
"alt": "Company team members in office",
"description": "",
"caption": "Our amazing 2024 team",
"date": "2024-01-16 14:20:00"
}
]
Performance Considerations
The plugin uses WordPress meta queries to efficiently retrieve only marked media files. The JSON file is static and served directly by your web server, resulting in minimal server overhead. Large media libraries with hundreds of exported files still generate lightweight JSON (typically under 100KB).
Security
The plugin follows WordPress security best practices:
- Prevents direct file access with
ABSPATHchecks - Uses WordPress nonces for AJAX requests
- Checks user capabilities before allowing regeneration
- Only exposes media you explicitly mark for export
- Sets appropriate file permissions (0644) for the JSON file
Installation and Setup
Installation Steps
- Download the plugin ZIP file
- Upload to
/wp-content/plugins/media-json-exporter/ - Extract the files
- Activate through the WordPress Plugins menu
- The JSON file is created automatically at
/wp-content/uploads/media-export.json
Basic Usage
- Navigate to Media → Library
- Click any media file to edit
- Scroll to find the “Include in JSON Export” checkbox
- Check the box and click Update
- Access your JSON at the public URL
Admin Configuration
Visit Media → JSON Export to:
- Copy the public JSON URL
- View the current count of exported files
- Manually trigger regeneration if needed
- Access detailed usage instructions
Customization and Extension
Changing the JSON Filename
Edit line 15 of the plugin file to use a custom filename:
private $json_filename = 'my-custom-media-export.json';Adding Custom Fields
Extend the exported data by modifying the get_export_media() method. For example, to include custom field data:
$media_data[] = array(
'id' => $attachment->ID,
'title' => $attachment->post_title,
'url' => wp_get_attachment_url($attachment->ID),
'type' => get_post_mime_type($attachment->ID),
'alt' => get_post_meta($attachment->ID, '_wp_attachment_image_alt', true),
'description' => $attachment->post_content,
'caption' => $attachment->post_excerpt,
'date' => $attachment->post_date,
// Custom additions
'photographer' => get_post_meta($attachment->ID, 'photographer_name', true),
'license' => get_post_meta($attachment->ID, 'image_license', true),
'tags' => wp_get_post_tags($attachment->ID, array('fields' => 'names')),
);
Filtering by Media Type
You can create separate JSON exports for different media types by adding filters to the query arguments in get_export_media():
// Only export images
$args = array(
'post_type' => 'attachment',
'post_status' => 'inherit',
'posts_per_page' => -1,
'post_mime_type' => 'image',
'meta_query' => array(
array(
'key' => '_include_in_json_export',
'value' => '1',
'compare' => '='
)
)
);Troubleshooting
JSON File Not Accessible
Problem: Receiving 404 errors when accessing the JSON URL.
Solutions:
- Verify that
/wp-content/uploads/directory is writable - Check file permissions (should be 0644)
- Some servers block
.jsonfiles—add a MIME type rule in.htaccess - Clear any caching plugins or CDN caches
JSON Not Updating
Problem: Changes to media not reflected in the JSON file.
Solutions:
- Visit Media → JSON Export and click “Regenerate JSON Now”
- Verify the checkbox is properly saved on media files
- Check for JavaScript errors in the browser console
- Disable caching plugins temporarily to test
Permission Errors
Problem: Cannot regenerate JSON file manually.
Solutions:
- Ensure your WordPress user has administrator privileges
- Check file ownership in the uploads directory
- Verify server write permissions
Best Practices
Naming Conventions
Establish consistent naming for exported media to make filtering easier in consuming applications. Use descriptive titles that indicate the media’s purpose.
Regular Audits
Periodically review your exported media list to remove outdated files and ensure only current assets are exposed.
Documentation
Document which media files are exported and why, especially in team environments where multiple people manage the media library.
Version Control
Consider versioning your JSON exports if you need to maintain backwards compatibility with older applications.
Caching Strategy
Implement appropriate cache headers for the JSON file based on how frequently your media changes. For frequently updated media, use shorter cache times.
Comparison with Alternatives
vs. WordPress REST API
REST API Advantages: Full-featured, supports filtering, pagination, and authentication.
Media JSON Exporter Advantages: No authentication required, simpler implementation, smaller payload, faster response times for simple use cases, no need to understand WordPress API structure.
vs. Custom Endpoints
Custom Endpoints Advantages: Complete control over data structure and logic.
Media JSON Exporter Advantages: Zero development time, automatic maintenance, no coding required, non-technical users can manage exports.
vs. GraphQL
GraphQL Advantages: Flexible queries, fetch exactly what you need, strong typing.
Media JSON Exporter Advantages: No additional server setup, works everywhere, simpler for basic needs, no query language to learn.
Future Enhancements
While the current version provides solid functionality, potential future improvements could include:
- Multiple Export Groups: Create separate JSON files for different categories of media
- Scheduled Regeneration: Option to regenerate on a schedule rather than on every change
- Image Size Variants: Include URLs for different image sizes (thumbnail, medium, large)
- Webhook Notifications: Notify external services when the JSON file updates
- CSV Export Option: Alternative export format for spreadsheet users
- Bulk Selection: Add bulk actions to the media library for faster marking
- Custom Taxonomies: Filter exports by media categories or tags
Conclusion
The Media JSON Exporter plugin solves a common WordPress challenge with elegant simplicity. By providing a straightforward interface for selectively exposing media through a JSON endpoint, it enables headless CMS architectures, mobile app integrations, and third-party service connections without the complexity of custom API development.
Whether you’re a developer building a React frontend, a mobile app creator needing image assets, or a content manager preparing media for external distribution, this plugin offers a practical, maintenance-free solution. Its automatic synchronization ensures your external applications always have access to current data, while its selective export model maintains security by only exposing intentionally marked files.
For WordPress sites that need to bridge the gap between their media library and the broader digital ecosystem, Media JSON Exporter provides an essential tool that’s both powerful in capability and simple in execution.
Download: The Media JSON Exporter plugin is available as a free download with full source code and documentation.
Support: For questions, feature requests, or bug reports, visit the plugin’s GitHub repository or contact the author.
License: GPL v2 or later
Author: Konstantinos Kourentzes
