PolyCMS Core REST API: Reference & Developer Guide

This guide provides the complete route reference, request parameters, response JSON payloads, and integration guidelines for the PolyCMS Core REST API.

API Architecture & Authentication

PolyCMS Core exposes RESTful API endpoints under the /api/v1 prefix. All protected requests require a secure Bearer Token managed via Laravel Sanctum.

To authenticate your requests:

1. Log in to the Admin Panel.
2. Navigate to your User Profile and click API Tokens (or Settings > API Tokens).
3. Generate a token, copy the plain-text token, and keep it safe.
4. Pass the token in the Authorization header of every HTTP request:

Authorization: Bearer YOUR_SANCTUM_TOKEN_HERE
Accept: application/json
Content-Type: application/json

Core Endpoint List & API Reference

1. Posts & Pages Management

• List Posts: GET /api/v1/posts
  • Query Parameters:
    • page (integer): Page number for pagination (defaults to 1).
    • per_page (integer): Number of posts per page (defaults to 15, max 100).
    • status (string): Filter by post status (published or draft).
    • category_id (integer): Filter by Category ID.
    • search (string): Search phrase inside titles or content.
    • sort_by (string): Column to sort (created_at, views, order).
  • Response Payload:

    {
      "data": [
        {
          "id": 12,
          "title": "Getting Started with PolyCMS",
          "slug": "getting-started-with-polycms",
          "type": "post",
          "status": "published",
          "locale": "en",
          "content_html": "<p>Welcome to PolyCMS...</p>"
        }
      ],
      "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 15,
        "total": 75
      }
    }
    

• Retrieve Post Detail: GET /api/v1/posts/{id_or_slug}
• Create Post: POST /api/v1/posts (Auth Required)
  • Request Body Parameters:
    • title (string, required): Title of the post.
    • slug (string, required): Unique URL-friendly slug.
    • content_raw (array, optional): TipTap JSON editor structure.
    • content_html (string, optional): Raw HTML content if content_raw is not provided.
    • status (string, optional): draft or published (defaults to draft).
    • locale (string, optional): ISO code (defaults to en).
    • translation_group_id (string, optional): UUID to link translations.
• Update Post: PUT /api/v1/posts/{id} (Auth Required)
• Delete Post: DELETE /api/v1/posts/{id} (Auth Required)

2. E-Commerce Products

• List Products: GET /api/v1/products
  • Query Parameters: page, per_page, search, category_id, brand_id.
• Retrieve Product Detail: GET /api/v1/products/{id}
• Create / Update / Delete Products: POST / PUT / DELETE endpoints under /api/v1/products (Auth Required).

3. Category & Tag Taxonomy

• List Categories Tree: GET /api/v1/categories
• Create Category: POST /api/v1/categories (Auth Required)
  • Request Body:

    {
      "name": "Developer Guide",
      "slug": "developer-guide",
      "parent_id": null
    }
    

• Update / Delete Category: PUT / DELETE under /api/v1/categories/{id} (Auth Required).

4. Media Library Management

• List Media Files: GET /api/v1/media (Auth Required)
  • Returns paginated files inside the uploads directory with MIME type filters.
• Upload Media File: POST /api/v1/media/upload (Auth Required)
  • Content-Type: multipart/form-data
  • Payload: File input key file.
  • Security Processing: All files go through a 6-layer security verification (MIME validation, double extension blocking, GD library image rebuilding to purge embedded scripts, and virus scanning).
• Delete Media File: DELETE /api/v1/media/{id} (Auth Required)
  • Automatically deletes physical file from storage disk, cleans database records, and removes foreign key attachments on posts.

5. System Cache & Operations

• Get Cache Status: GET /api/v1/system/cache/status (Auth Required)
• Clear System Cache: POST /api/v1/system/cache/clear (Auth Required)
  • Purges application cache, Blade views compile cache, configuration cache, and database query cache.

Code Integration Examples

JavaScript (Fetch API)

const token = 'YOUR_SANCTUM_TOKEN';
const baseUrl = 'https://polycms.org/api/v1';

async function fetchPosts() {
  const response = await fetch(`${baseUrl}/posts?status=published`, {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'Authorization': `Bearer ${token}`
    }
  });
  
  if (response.ok) {
    const payload = await response.json();
    console.log(payload.data);
  }
}

Python (Requests)

import requests

token = "YOUR_SANCTUM_TOKEN"
headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {token}"
}

response = requests.get("https://polycms.org/api/v1/posts", headers=headers)
if response.status_code == 200:
    posts = response.json().get("data", [])
    print(f"Retrieved {len(posts)} posts.")