Back to Main Site

PolyCMS REST API Guide for RISE CRM

Last updated on Nov 22, 2026 7:37 AM 7:37 AM 1,854.54 ms

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

  1. Open PolyCMS > Settings > REST API (#tab-api) inside RISE CRM.
  2. Toggle Enable REST API to On.
  3. Click Generate New API Key to create a 192-bit cryptographic key prefixed with pcms_ and save your settings.
  4. Adjust the per-minute Read and Write rate limits to match your traffic profile.
  5. 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 with pcms_.
  • Constant-Time Verification: Verified using PHP hash_equals() to prevent timing side-channel attacks.
  • Automatic RISE CSRF Exclusion: plugins/polycms/index.php registers cms/api/v1.*+ via RISE CRM's app_filter_app_csrf_exclude_uris filter. Stateless POST, PUT, PATCH, and DELETE clients authenticate cleanly using X-PolyCMS-API-Key without 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 Unauthorized or 403 Forbidden).

Rate Limiting

The REST API enforces configurable per-IP sliding window rate limits stored privately in writable/polycms/rate_limit/.

  • Read Operations (GET): Default 60 requests per minute.
  • Write Operations (POST, PUT, PATCH, DELETE): Default 30 requests 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 returning 429 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 (default 1), per_page (default 10, max 100), status (published, draft), category_id, author_id, search, sort_by (default created_at), sort_order (default DESC).
  • Get Single Post: GET /cms/api/v1/posts/{id} (includes full content HTML and tags array).
  • Create Post: POST /cms/api/v1/posts (returns 201 Created).
  • Update Post: PUT /cms/api/v1/posts/{id} or PATCH /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 (supports page, per_page, status, search).
  • Get Single Page: GET /cms/api/v1/pages/{id} (includes full content and description).
  • Create Page: POST /cms/api/v1/pages (title required; optional slug, content, description, status, template, menu_order).
  • Update Page: PUT /cms/api/v1/pages/{id} or PATCH /cms/api/v1/pages/{id}.
  • Delete Page: DELETE /cms/api/v1/pages/{id}.

Categories

  • List Category Tree: GET /cms/api/v1/categories (returns nested children hierarchy).
  • 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} (name required on create; optional slug, description, parent_id, status).

Tags

  • List Tags: GET /cms/api/v1/tags (supports page, per_page, search; includes usage_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:

  1. Size Limit and Strict Extension Whitelist: Enforces a 10 MB ceiling and accepts only genuine image extensions (jpg, jpeg, png, gif, webp).
  2. Null-Byte and Double-Extension Blocking: Rejects filenames containing null bytes or embedded executable extensions such as payload.php.jpg or shell.phtml.png.
  3. Server-Side MIME Validation (finfo): Inspects actual file bytes rather than trusting client-supplied Content-Type headers.
  4. Magic Bytes Signature Verification: Confirms the binary header matches JPEG (FF D8 FF), PNG, GIF87a/GIF89a, or WebP (RIFF....WEBP).
  5. GD Image Reprocessing: Decodes and re-encodes pixels through PHP GD, stripping hidden EXIF metadata and appended payloads before scanning.
  6. Post-GD Malicious Code Scanning: Scans the reprocessed image for surviving executable markers such as &lt;?php, &lt;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/:

  1. Physical file removal: Deletes both the original file and its generated thumbnail from files/polycms/.
  2. Database record deletion: Removes the tracking row from {prefix}blog_media.
  3. Reference cascade: Clears feature_image and feature_image_id on 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 filename
  • path - Relative path inside files/polycms/ (for example, 2026/05/17/cover-photo.jpg)
  • url - Full public URL for direct display
  • alt_text - SEO alternative text
  • title - Media title
  • caption - Optional caption or description
  • mime_type - Verified MIME type (for example, image/jpeg)
  • file_size - File size in bytes
  • width / height - Pixel dimensions extracted via getimagesize()
  • 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 through polycms_purify_content(), backed by PolyCMS's bundled vendor/ezyang/htmlpurifier library (polycms_html_purify(), cached in writable/polycms/htmlpurifier/), followed by regex stripping of &lt;script&gt; blocks and inline JavaScript event handlers (onclick, onerror, etc.).
  • Plain-Text Sanitization: Text-only fields (title, slug, status, visibility, template) pass through strip_tags().
  • Global Kill Switch and No Admin Mutation: Disabling the REST API toggle immediately returns 403 Forbidden across all routes. No API endpoint can modify RISE settings, staff roles, themes, or plugins.

Related Documentation