PolyCMS REST API: Complete Developer Guide with Media Database

The PolyCMS REST API enables external applications to interact with your CMS data programmatically. Whether you are building a mobile app, a headless frontend with React/Vue, or integrating with third-party services, the REST API provides secure, standardized access to all your content.

Authentication

All API requests require an API key. You can pass it via the X-PolyCMS-API-Key header (recommended) or as a ?api_key= query parameter.

curl -X GET \
  -H "X-PolyCMS-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  "https://your-site.com/cms/api/v1/posts"

Available Endpoints

Media Upload & Database Tracking

Upload images via POST /cms/api/v1/media using multipart/form-data with the field name file. The API enforces 6 layers of security: extension whitelist, MIME validation, magic bytes verification, malicious code scanning, double-extension blocking, and GD image reprocessing to strip embedded payloads.

New in v1.1.0: All uploaded media are now tracked in the blog_media database table. Each record stores:

• filename - Original file name
• path - Relative path (e.g., 2026/05/17/my-image.jpg)
• url - Full URL for direct display
• alt_text - SEO alt text
• title - Image title
• caption - Image caption/description
• mime_type - Detected MIME type (e.g., image/jpeg)
• file_size - File size in bytes
• width / height - Image dimensions in pixels
• author_id - Staff member who uploaded the file

The API returns a media_id on successful upload for immediate use as feature_image_id in posts and pages.

curl -X POST \
  -H "X-PolyCMS-API-Key: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  "https://your-site.com/cms/api/v1/media"

Media Listing with Pagination

The GET /cms/api/v1/media endpoint queries the database for fast, paginated results instead of scanning the filesystem. Supported parameters:

Media Delete Cascade

When a media file is deleted via DELETE /cms/api/v1/media/{path}, the system performs a 3-layer cleanup:

1. Physical file removal - deletes the original file and its thumbnail from disk.
2. Database record deletion - removes the entry from blog_media.
3. Reference cascade - automatically clears feature_image and feature_image_id from any posts or pages that referenced this media, preventing broken images on the frontend.

Feature Image Relationship

Posts and Pages now have a feature_image_id column that links to blog_media.id. The original feature_image path string is retained for fast rendering without JOIN queries. When the module is activated (or reactivated), existing files are automatically synced into the database and feature_image_id is populated for matching posts.

Rate Limiting

The API enforces configurable rate limits (default: 60 reads / 30 writes per minute). Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are included in every response.

Getting Started

1. Go to Blog > Settings > REST API tab
2. Enable the REST API toggle
3. Generate your API key
4. Configure rate limits as needed
5. Use the API Explorer plugin to test endpoints interactively