Skip to main content

Admin API Requests

This document outlines the API endpoints available for admin applications to manage posts in the CMS module.

List Posts​

Retrieves a list of all posts with administrative details.

Request​

GET /api/admin/v3/cms/post?includes=category,tags,author&field_sets=%7B%22cms_posts%22%3A%22id%2Ctitle%2Cslug%2Cexcerpt%2Ccontent%2Cfeatured_image%2Cstatus%2Ccreated_at%2Cupdated_at%2Cpublished_at%2Ccategory%2Ctags%2Cauthor%2Cview_count%2Ccomment_count%2Cis_featured%2Cseo%22%7D&search=status%3Apublished&searchFields=status&per_page=20&page=1 HTTP/1.1
Api-Key: {{api-key}}

Query Parameters​

ParameterTypeDescription
includesstringRelated entities to include in the response (e.g., category,tags,author)
field_setsobjectJSON object specifying which fields to include for each entity type
searchstringSearch terms with format field:value
searchFieldsstringFields to search in
searchJoinstringHow to join multiple search terms (and or or)
per_pageintegerNumber of items per page
pageintegerPage number for pagination
sortstringField to sort by (options: id, created_at, updated_at, title, status)
orderstringSort order (options: asc, desc)

Response​

{
  "status": true,
  "result": [
    {
      "id": 1,
      "title": "نمونه عنوان مقاله",
      "slug": "sample-post-title",
      "excerpt": "این یک نمونه خلاصه مقاله است...",
      "content": "این محتوای کامل مقاله نمونه است...",
      "featured_image": "https://example.com/images/sample-post.jpg",
      "status": "published",
      "created_at": "2025-03-15T10:30:00.000000Z",
      "updated_at": "2025-03-15T14:45:00.000000Z",
      "published_at": "2025-03-15T15:00:00.000000Z",
      "category": {
        "id": 3,
        "name": "تکنولوژی",
        "slug": "technology"
      },
      "tags": [
        {
          "id": 7,
          "name": "API",
          "slug": "api"
        },
        {
          "id": 12,
          "name": "مستندات",
          "slug": "documentation"
        }
      ],
      "author": {
        "id": 5,
        "name": "جان دو",
        "email": "john.doe@example.com",
        "avatar_url": "https://www.gravatar.com/avatar/abc123.jpg?s=80&d=mp&r=g"
      },
      "view_count": 1250,
      "comment_count": 18,
      "is_featured": true,
      "seo": {
        "meta_title": "عنوان سئو سفارشی",
        "meta_description": "توضیحات سئو سفارشی برای موتورهای جستجو",
        "og_image": "https://example.com/images/og-sample-post.jpg"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 98,
      "count": 20,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 5,
      "links": {
        "next": "http://localhost:8080/api/admin/v3/cms/post?includes=category,tags,author&field_sets=%7B%22cms_posts%22%3A%22id%2Ctitle%2Cslug%2Cexcerpt%2Ccontent%2Cfeatured_image%2Cstatus%2Ccreated_at%2Cupdated_at%2Cpublished_at%2Ccategory%2Ctags%2Cauthor%2Cview_count%2Ccomment_count%2Cis_featured%2Cseo%22%7D&search=status%3Apublished&searchFields=status&per_page=20&page=2"
      }
    }
  }
}

Create Post​

Creates a new post in the CMS.

Request​

POST /api/admin/v3/cms/post HTTP/1.1
Api-Key: {{api-key}}
Content-Type: application/json

Request Body​

{
  "title": "عنوان مقاله جدید",
  "slug": "new-post-title",
  "excerpt": "این خلاصه برای مقاله جدید است...",
  "content": "این محتوای کامل مقاله جدید است...",
  "featured_image": "https://example.com/images/new-post.jpg",
  "status": "draft",
  "category_id": 3,
  "tag_ids": [7, 12],
  "author_id": 5,
  "is_featured": false,
  "published_at": "2025-04-10T12:00:00Z",
  "seo": {
    "meta_title": "عنوان سئو سفارشی",
    "meta_description": "توضیحات سئو سفارشی برای موتورهای جستجو",
    "og_image": "https://example.com/images/og-new-post.jpg"
  }
}

Response​

{
  "status": true,
  "result": {
    "id": 99,
    "title": "عنوان مقاله جدید",
    "slug": "new-post-title",
    "excerpt": "این خلاصه برای مقاله جدید است...",
    "content": "این محتوای کامل مقاله جدید است...",
    "featured_image": "https://example.com/images/new-post.jpg",
    "status": "draft",
    "created_at": "2025-04-05T19:30:00.000000Z",
    "updated_at": "2025-04-05T19:30:00.000000Z",
    "published_at": "2025-04-10T12:00:00.000000Z",
    "category": {
      "id": 3,
      "name": "تکنولوژی",
      "slug": "technology"
    },
    "tags": [
      {
        "id": 7,
        "name": "API",
        "slug": "api"
      },
      {
        "id": 12,
        "name": "مستندات",
        "slug": "documentation"
      }
    ],
    "author": {
      "id": 5,
      "name": "جان دو",
      "email": "john.doe@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/abc123.jpg?s=80&d=mp&r=g"
    },
    "view_count": 0,
    "comment_count": 0,
    "is_featured": false,
    "seo": {
      "meta_title": "عنوان سئو سفارشی",
      "meta_description": "توضیحات سئو سفارشی برای موتورهای جستجو",
      "og_image": "https://example.com/images/og-new-post.jpg"
    }
  }
}

Update Post​

Updates an existing post.

Request​

PUT /api/admin/v3/cms/post/{post_id} HTTP/1.1
Api-Key: {{api-key}}
Content-Type: application/json

Path Parameters​

ParameterTypeDescription
post_idintegerPost ID

Request Body​

Same as Create Post, but all fields are optional. Only include the fields you want to update.

Response​

{
  "status": true,
  "result": {
    "id": 1,
    "title": "عنوان مقاله به‌روزرسانی شده",
    "slug": "updated-post-title",
    "excerpt": "این خلاصه به‌روزرسانی شده مقاله است...",
    "content": "این محتوای کامل به‌روزرسانی شده مقاله است...",
    "featured_image": "https://example.com/images/updated-post.jpg",
    "status": "published",
    "created_at": "2025-03-15T10:30:00.000000Z",
    "updated_at": "2025-04-05T20:15:00.000000Z",
    "published_at": "2025-04-05T20:15:00.000000Z",
    "category": {
      "id": 5,
      "name": "آموزش",
      "slug": "education"
    },
    "tags": [
      {
        "id": 7,
        "name": "API",
        "slug": "api"
      },
      {
        "id": 15,
        "name": "برنامه‌نویسی",
        "slug": "programming"
      }
    ],
    "author": {
      "id": 5,
      "name": "جان دو",
      "email": "john.doe@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/abc123.jpg?s=80&d=mp&r=g"
    },
    "view_count": 1250,
    "comment_count": 18,
    "is_featured": true,
    "seo": {
      "meta_title": "عنوان سئو به‌روزرسانی شده",
      "meta_description": "توضیحات سئو به‌روزرسانی شده برای موتورهای جستجو",
      "og_image": "https://example.com/images/og-updated-post.jpg"
    }
  }
}

Get Post​

Retrieves a specific post by ID.

Request​

GET /api/admin/v3/cms/post/{post_id}?includes=category,tags,author HTTP/1.1
Api-Key: {{api-key}}

Path Parameters​

ParameterTypeDescription
post_idintegerPost ID

Query Parameters​

ParameterTypeDescription
includesstringRelated entities to include in the response (e.g., category,tags,author)

Response​

Same as the response for Update Post.

Delete Post (Move to Trash)​

Moves a post to the trash (soft delete).

Request​

DELETE /api/admin/v3/cms/post/{post_id}/trash HTTP/1.1
Api-Key: {{api-key}}

Path Parameters​

ParameterTypeDescription
post_idintegerPost ID

Response​

{
  "status": true,
  "result": {
    "message": "Post moved to trash successfully"
  }
}

Permanently Delete Post​

Permanently deletes a post from the database.

Request​

DELETE /api/admin/v3/cms/post/{post_id} HTTP/1.1
Api-Key: {{api-key}}

Path Parameters​

ParameterTypeDescription
post_idintegerPost ID

Response​

{
  "status": true,
  "result": {
    "message": "Post deleted permanently"
  }
}

Restore Post from Trash​

Restores a post from the trash.

Request​

POST /api/admin/v3/cms/post/{post_id}/restore HTTP/1.1
Api-Key: {{api-key}}

Path Parameters​

ParameterTypeDescription
post_idintegerPost ID

Response​

{
  "status": true,
  "result": {
    "message": "Post restored successfully"
  }
}

Bulk Actions​

Performs actions on multiple posts at once.

Request​

POST /api/admin/v3/cms/post/bulk HTTP/1.1
Api-Key: {{api-key}}
Content-Type: application/json

Request Body​

{
  "ids": [1, 2, 3, 4, 5],
  "action": "trash"  // Options: trash, restore, delete, publish, draft, archive
}

Response​

{
  "status": true,
  "result": {
    "message": "Bulk action completed successfully",
    "affected": 5
  }
}

Manage Post Comments​

List Comments for a Post​

GET /api/admin/v3/cms/post/{post_id}/comments?page=1&per_page=20 HTTP/1.1
Api-Key: {{api-key}}

Response​

{
  "status": true,
  "result": {
    "comments": [
      {
        "id": 101,
        "content": "این مقاله بسیار مفید بود!",
        "created_at": "2025-03-16T09:45:00.000000Z",
        "updated_at": "2025-03-16T09:45:00.000000Z",
        "status": "approved",
        "user": {
          "id": 42,
          "name": "سارا احمدی",
          "email": "sara@example.com",
          "avatar_url": "https://www.gravatar.com/avatar/abc123.jpg?s=80&d=mp&r=g"
        },
        "parent_id": null,
        "replies_count": 1
      }
    ],
    "meta": {
      "pagination": {
        "total": 18,
        "count": 1,
        "per_page": 20,
        "current_page": 1,
        "total_pages": 1
      }
    }
  }
}

Approve Comment​

PUT /api/admin/v3/cms/comment/{comment_id}/approve HTTP/1.1
Api-Key: {{api-key}}

Response​

{
  "status": true,
  "result": {
    "message": "Comment approved successfully"
  }
}

Reject Comment​

PUT /api/admin/v3/cms/comment/{comment_id}/reject HTTP/1.1
Api-Key: {{api-key}}

Response​

{
  "status": true,
  "result": {
    "message": "Comment rejected successfully"
  }
}

Delete Comment​

DELETE /api/admin/v3/cms/comment/{comment_id} HTTP/1.1
Api-Key: {{api-key}}

Response​

{
  "status": true,
  "result": {
    "message": "Comment deleted successfully"
  }
}

Error Responses​

Not Found (404)​

{
  "status": false,
  "error": {
    "message": "Post not found",
    "code": "resource_not_found"
  }
}

Validation Error (422)​

{
  "status": false,
  "error": {
    "message": "Validation failed",
    "errors": {
      "title": [
        "عنوان مقاله الزامی است."
      ],
      "content": [
        "محتوای مقاله الزامی است."
      ]
    },
    "code": "validation_failed"
  }
}

Authentication Error (401)​

{
  "status": false,
  "error": {
    "message": "Unauthenticated",
    "code": "authentication_required"
  }
}

Authorization Error (403)​

{
  "status": false,
  "error": {
    "message": "You do not have permission to perform this action",
    "code": "permission_denied"
  }
}
Last updated on by Behnam Moradi