PolyCMS REST API Guide for RISE CRM
The PolyCMS REST API (/cms/api/v1/) turns PolyCMS for RISE CRM into a production-grade headless CMS with full CRUD endpoints for Posts, Pages, Categories, Tags, and database-backed Media. Protected by 192-bit pcms_* API keys, constant-time hash_equals() verification, automatic RISE CRM CSRF exclusion, per-IP rate limiting, strict CMS data isolation, and a 6-layer image upload security pipeline, the API safely connects mobile apps, React/Vue/Next.js frontends, and external automation workflows to your content without exposing sensitive RISE CRM records.
Getting Started
- Open PolyCMS > Settings > REST API (
#tab-api) inside RISE CRM. - Toggle Enable REST API to On.
- Click Generate New API Key to create a 192-bit cryptographic key prefixed with
pcms_and save your settings. - Adjust the per-minute Read and Write rate limits to match your traffic profile.
- Open PolyCMS > API Explorer to test live endpoints interactively with auto-generated cURL, PHP, JavaScript, and Python snippets. See the API Explorer Interactive Sandbox Guide for details.
Authentication and RISE CRM CSRF Exclusion
Every request to /cms/api/v1/* requires your active API key passed through one of two channels:
- HTTP Header (Recommended):
X-PolyCMS-API-Key: pcms_your_key_here - Query Parameter:
?api_key=pcms_your_key_here
curl -X GET \
-H "X-PolyCMS-API-Key: pcms_your_key_here" \
-H "Accept: application/json" \
"https://your-rise-site.com/cms/api/v1/posts"
Cryptographic Verification and Automatic CSRF Whitelist
- 192-Bit Key Entropy: Generated via
random_bytes(24)(48 hex characters) prefixed withpcms_. - Constant-Time Verification: Verified using PHP
hash_equals()to prevent timing side-channel attacks. - Automatic RISE CSRF Exclusion:
plugins/polycms/index.phpregisterscms/api/v1.*+via RISE CRM'sapp_filter_app_csrf_exclude_urisfilter. StatelessPOST,PUT,PATCH, andDELETEclients authenticate cleanly usingX-PolyCMS-API-Keywithout requiring browser session cookies, while all RISE CRM web forms remain fully CSRF-protected. - Fail-Closed Design: If no API key has been generated or the REST API toggle is disabled, all endpoints immediately reject requests (
401 Unauthorizedor403 Forbidden).
Rate Limiting
The REST API enforces configurable per-IP sliding window rate limits stored privately in writable/polycms/rate_limit/.
- Read Operations (
GET): Default60requests per minute. - Write Operations (
POST,PUT,PATCH,DELETE): Default30requests per minute.
Every response includes standard rate-limit headers:
X-RateLimit-Limit- Maximum requests allowed in the current 60-second window.X-RateLimit-Remaining- Remaining requests before throttling triggers.Retry-After- Seconds until the window resets (included when returning429 Too Many Requests).
Available Endpoints Overview
All endpoints are served under /cms/api/v1/:
| Resource | Base Route | GET | POST | PUT / PATCH | DELETE |
|---|---|---|---|---|---|
| Posts | /cms/api/v1/posts |
List & Single (/{id}) |
Create | Update (/{id}) |
Delete (/{id}) |
| Pages | /cms/api/v1/pages |
List & Single (/{id}) |
Create | Update (/{id}) |
Delete (/{id}) |
| Categories | /cms/api/v1/categories |
Tree & Single (/{id}) |
Create | Update (/{id}) |
Delete (/{id}) |
| Tags | /cms/api/v1/tags |
List & Single (/{id}) |
Create | Update (/{id}) |
Delete (/{id}) |
| Media | /cms/api/v1/media |
Paginated DB List | Multipart Upload | Not applicable | Delete (/{path} or ?id={id}) |
Endpoint Reference
Posts
- List Posts:
GET /cms/api/v1/posts- Query parameters:
page(default1),per_page(default10, max100),status(published,draft),category_id,author_id,search,sort_by(defaultcreated_at),sort_order(defaultDESC).
- Query parameters:
- Get Single Post:
GET /cms/api/v1/posts/{id}(includes fullcontentHTML andtagsarray). - Create Post:
POST /cms/api/v1/posts(returns201 Created). - Update Post:
PUT /cms/api/v1/posts/{id}orPATCH /cms/api/v1/posts/{id}. - Delete Post:
DELETE /cms/api/v1/posts/{id}.
{
"title": "Launching Our RISE CRM Customer Portal",
"slug": "launching-rise-crm-customer-portal",
"description": "How we unified project updates and knowledge base guides inside RISE CRM.",
"content": "<p>Full sanitized HTML body content.</p>",
"status": "published",
"visibility": "public",
"feature_image": "polycms/2026/05/17/portal-cover.jpg",
"category_ids": [1, 2],
"tags": ["rise-crm", "release"]
}
Pages
- List Pages:
GET /cms/api/v1/pages(supportspage,per_page,status,search). - Get Single Page:
GET /cms/api/v1/pages/{id}(includes fullcontentanddescription). - Create Page:
POST /cms/api/v1/pages(titlerequired; optionalslug,content,description,status,template,menu_order). - Update Page:
PUT /cms/api/v1/pages/{id}orPATCH /cms/api/v1/pages/{id}. - Delete Page:
DELETE /cms/api/v1/pages/{id}.
Categories
- List Category Tree:
GET /cms/api/v1/categories(returns nestedchildrenhierarchy). - Get Single Category:
GET /cms/api/v1/categories/{id}. - Create / Update / Delete:
POST /cms/api/v1/categories,PUT /cms/api/v1/categories/{id},DELETE /cms/api/v1/categories/{id}(namerequired on create; optionalslug,description,parent_id,status).
Tags
- List Tags:
GET /cms/api/v1/tags(supportspage,per_page,search; includesusage_count). - Get Single Tag:
GET /cms/api/v1/tags/{id}. - Create / Update / Delete:
POST /cms/api/v1/tags,PUT /cms/api/v1/tags/{id},DELETE /cms/api/v1/tags/{id}.
Media (Database-Backed)
List Media (GET /cms/api/v1/media)
Queries the {prefix}blog_media database table directly for fast paginated results instead of slow recursive directory scans.
| Parameter | Description | Default |
|---|---|---|
page |
Page number | 1 |
per_page |
Items per page (max 100) |
10 |
search |
Matches filename, alt_text, or title |
None |
mime |
Filters by MIME prefix (for example, image) |
None |
Upload Media (POST /cms/api/v1/media)
Submit images as multipart/form-data using field name file (max size 10 MB). Uploaded files are stored under files/polycms/ (hardened with .htaccess, web.config, and index.html) and tracked in {prefix}blog_media. On success (201 Created), the response returns id (use as feature_image_id), url, path, filename, original_name, size, type, and thumbnail_url.
curl -X POST \
-H "X-PolyCMS-API-Key: pcms_your_key_here" \
-F "file=@cover-photo.jpg" \
"https://your-rise-site.com/cms/api/v1/media"
6-Layer Media Upload Security Pipeline
Every API media upload must pass six sequential security gates before touching disk:
- Size Limit and Strict Extension Whitelist: Enforces a 10 MB ceiling and accepts only genuine image extensions (
jpg,jpeg,png,gif,webp). - Null-Byte and Double-Extension Blocking: Rejects filenames containing null bytes or embedded executable extensions such as
payload.php.jpgorshell.phtml.png. - Server-Side MIME Validation (
finfo): Inspects actual file bytes rather than trusting client-suppliedContent-Typeheaders. - Magic Bytes Signature Verification: Confirms the binary header matches JPEG (
FF D8 FF), PNG, GIF87a/GIF89a, or WebP (RIFF....WEBP). - GD Image Reprocessing: Decodes and re-encodes pixels through PHP GD, stripping hidden EXIF metadata and appended payloads before scanning.
- Post-GD Malicious Code Scanning: Scans the reprocessed image for surviving executable markers such as
<?php,<script, and__HALT_COMPILER.
Delete Media (DELETE /cms/api/v1/media/{path} or ?id={id})
You can delete media by relative path (/cms/api/v1/media/2026/05/17/photo.jpg), query string (?id=42 or ?path=...), or JSON body ({"path": "..."}). Every deletion runs a 3-layer cleanup cascade after realpath() traversal verification inside files/polycms/:
- Physical file removal: Deletes both the original file and its generated thumbnail from
files/polycms/. - Database record deletion: Removes the tracking row from
{prefix}blog_media. - Reference cascade: Clears
feature_imageandfeature_image_idon any posts or pages referencing the deleted file, preventing broken image links on the frontend.
Media Database Architecture (blog_media)
All uploaded media assets are indexed in {prefix}blog_media (rise_blog_media) with the following metadata columns:
filename- Sanitized stored filenamepath- Relative path insidefiles/polycms/(for example,2026/05/17/cover-photo.jpg)url- Full public URL for direct displayalt_text- SEO alternative texttitle- Media titlecaption- Optional caption or descriptionmime_type- Verified MIME type (for example,image/jpeg)file_size- File size in byteswidth/height- Pixel dimensions extracted viagetimagesize()author_id- RISE staff user ID who uploaded the file
Feature Image Relationship and Auto-Sync Migration
Posts and Pages store a feature_image_id foreign reference to blog_media.id alongside the denormalized feature_image path string for fast frontend rendering without extra JOIN queries. Whenever PolyCMS is installed or reactivated in RISE CRM, Blog_media_model::sync_from_filesystem() and sync_feature_image_ids() run idempotently to register any existing files in files/polycms/ and link matching posts automatically.
Standard JSON Response Format
Successful responses always share a consistent envelope and return security headers (X-PolyCMS-API: v1.0, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Cache-Control: no-store, no-cache, must-revalidate):
{
"success": true,
"message": "Posts retrieved",
"data": [
{
"id": 1,
"title": "Welcome to PolyCMS for RISE CRM",
"slug": "welcome-to-polycms-for-rise-crm",
"status": "published",
"author": {
"id": 1,
"name": "Alex Morgan"
}
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 10,
"pages": 1
}
}
Errors return {"success": false, "message": "..."} with standard HTTP status codes (400, 401, 403, 404, 405, 413, 429, 500), including a registered PHP shutdown handler that formats fatal errors as clean JSON instead of raw HTML.
Security and Data Isolation
Strict CMS Data Scope
The REST API operates exclusively on dedicated PolyCMS tables (blog_posts, blog_post_meta, blog_post_categories, blog_post_tags, blog_pages, blog_page_meta, blog_categories, blog_tags, blog_media). It has zero read or write access to RISE CRM core tables such as clients, invoices, projects, leads, estimates, tickets, or password hashes. The only core RISE table referenced is users (read-only, first and last name only) to display author attribution.
SQL Injection and XSS Protection
- Query Builder Parameter Binding: Every query runs through CodeIgniter's Query Builder with automatic value escaping, strict
(int)casting on numeric parameters, and whitelisted sort fields. - Plugin-Local HTMLPurifier: All submitted HTML fields (
content,description) are sanitized throughpolycms_purify_content(), backed by PolyCMS's bundledvendor/ezyang/htmlpurifierlibrary (polycms_html_purify(), cached inwritable/polycms/htmlpurifier/), followed by regex stripping of<script>blocks and inline JavaScript event handlers (onclick,onerror, etc.). - Plain-Text Sanitization: Text-only fields (
title,slug,status,visibility,template) pass throughstrip_tags(). - Global Kill Switch and No Admin Mutation: Disabling the REST API toggle immediately returns
403 Forbiddenacross all routes. No API endpoint can modify RISE settings, staff roles, themes, or plugins.
Related Documentation
- API Explorer Interactive Sandbox - Test every REST endpoint live from your RISE CRM admin sidebar.
- Media Library Guide - Manage uploads, thumbnails, and
blog_mediametadata visually. - Building a Custom Plugin for PolyCMS - Extend PolyCMS workflows alongside external API consumers.
- Hooks and Filters Complete Reference - React to post, page, and media lifecycle events.
- Architecture Overview - Inspect the 19-table schema and CodeIgniter 4 routing bridge.