Posts & Blog API
This section describes the API endpoints for managing and retrieving blog posts, announcements, and pages.
Public Endpoints
List Posts
Retrieve a list of active posts, optionally filtered by type.
Endpoint: GET /api/posts
Query Parameters:
type(optional): Filter by post type (e.g.,blog,announcement,page). Defaults toblog.locale(optional): Active locale code (e.g.,en,zh). When multi-language is enabled andtype=blog, only blog posts bound to the requested locale (or legacy unbound posts withlocale = null) are returned.category(optional): Filter by category slug. An unknown or inactive slug returns an empty list rather than falling back to all posts.allis ignored.
Response:
{
"data": [
{
"id": 1,
"slug": "getting-started",
"title": "Getting Started with APayShop",
"description": "Learn how to set up your store in minutes.",
"imageUrl": "https://example.com/image.jpg",
"type": "blog",
"locale": "en",
"categoryId": 3,
"category": { "id": 3, "slug": "tutorials", "name": "Tutorials", "description": null },
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-02T00:00:00.000Z"
}
],
"total": 1
}
category is null when the post is uncategorized; the name is localized to the request language.
List Post Categories
Retrieve the active blog categories, ordered by sort then id, with names localized to the request language.
Endpoint: GET /api/post-categories
Response:
{
"data": [
{ "id": 3, "slug": "tutorials", "name": "Tutorials", "description": null, "sort": 0 }
]
}
Get Post by Slug
Retrieve a single active post by its unique slug. When multi-language is enabled and a blog post is bound to a specific locale (e.g., zh), visiting a non-matching storefront URL (such as /blog/:slug) automatically 301-redirects to the post's bound locale URL (/zh/blog/:slug).
Endpoint: GET /api/posts/:slug
Query Parameters:
locale(optional): Active locale code (e.g.,en,zh).
Response:
{
"id": 1,
"slug": "getting-started",
"title": "Getting Started with APayShop",
"content": "<p>This is the full HTML content of the post...</p>",
"description": "Learn how to set up your store in minutes.",
"imageUrl": "https://example.com/image.jpg",
"type": "blog",
"locale": "en",
"isActive": true,
"metaData": null,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-02T00:00:00.000Z"
}
Admin Endpoints (Requires Authentication)
List All Posts
Retrieve a paginated list of all posts, including drafts.
Endpoint: GET /api/admin/posts
Query Parameters:
type(optional): Filter by post type (blog,changelog,announcement,page).locale(optional): Filter by bound post locale (e.g.,en,zh).status(optional): Filter bypublishedordraft.category(optional): Filter by category id, oruncategorized/nonefor posts without a category.search(optional): Keyword search across title, slug, key, and description.
Create Post
Create a new post. When type is blog, locale binds the blog post to a single language (en, zh, etc.). Other post types (changelog, announcement, page) store locale = null and use metaData.translations.
Endpoint: POST /api/admin/posts
Body:
{
"slug": "new-blog-post",
"title": "New Feature Release",
"description": "We just released a great new feature.",
"content": "<p>Details here...</p>",
"type": "blog",
"locale": "en",
"categoryId": 3,
"imageUrl": "https://example.com/image2.jpg",
"isActive": true
}
categoryId is optional; pass null (or 0/"") for uncategorized.
Update Post
Update an existing post.
Endpoint: PUT /api/admin/posts/:id
Delete Post
Delete a post permanently.
Endpoint: DELETE /api/admin/posts/:id
List Post Categories
Retrieve all categories (including inactive) with a postCount of posts assigned to each.
Endpoint: GET /api/admin/posts/categories
Create Post Category
Endpoint: POST /api/admin/posts/categories
Body:
{
"slug": "tutorials",
"name": "Tutorials",
"description": "Step-by-step guides.",
"sort": 0,
"isActive": true,
"locales": { "zh": { "name": "教程", "description": "分步指南" } }
}
slug must be lowercase letters, digits and hyphens, and unique. locales is an optional Record<lang, { name?, description? }>; each language falls back to the top-level name/description when omitted.
Get / Update / Delete Post Category
GET /api/admin/posts/categories/:idPUT /api/admin/posts/categories/:id— same body as create; omitslugto keep the current one.DELETE /api/admin/posts/categories/:id— posts using the category become uncategorized.