PolyCMS REST API: Complete Developer Guide

Introduction

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, path, URL, alt_text, title, caption, MIME type, file size, dimensions (width/height), and author. The API returns a media_id on successful upload.

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 now queries the database for fast, paginated results instead of scanning the filesystem. Supported query parameters:

• page — Page number (default: 1)
• per_page — Items per page (default: 20, max: 100)
• search — Search by filename, alt_text, or title
• mime — Filter by MIME type prefix (e.g., image)

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

* This is demo data for PolyCMS module for Perfex CRM to help customers explore features. If your business uses Perfex CRM and needs customizations or enhancements for integrated plugins/themes, you can leave feedback on Envato (CodeCanyon) while having active support time. Useful and suitable features will be received, integrated and updated.