PolyCMS REST API: Complete Developer Guide with Media Database

Last updated on Jul 30, 2026 2:40 AM 2:40 AM 325.30 ms

Blog Post: PolyCMS REST API Developer Guide

SEO Meta

Meta Title: PolyCMS REST API: Complete Developer Guide with Media Database Tracking Meta Description: Comprehensive guide to the PolyCMS REST API with CRUD endpoints for Posts, Pages, Categories, Tags, and database-backed Media tracking with enterprise-grade upload security. Focus Keyphrase: PolyCMS REST API

Title

PolyCMS REST API: Complete Developer Guide with Media Database

Description

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

Resource	GET	POST	PUT	DELETE
Posts	Yes	Yes	Yes	Yes
Pages	Yes	Yes	Yes	Yes
Categories	Yes	Yes	Yes	Yes
Tags	Yes	Yes	Yes	Yes
Media	Yes	Yes	--	Yes

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:

Parameter	Description	Default
`page`	Page number	1
`per_page`	Items per page (max 100)	20
`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:

Physical file removal - deletes the original file and its thumbnail from disk.
Database record deletion - removes the entry from blog_media.
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

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