---
title: "Posts & Blog API"
canonical_url: "https://ainode.run/docs/posts"
type: "doc"
locale: "en"
description: "Endpoints for managing and retrieving blog posts and articles."
---

# Posts & Blog API
> Endpoints for managing and retrieving blog posts and articles.

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 to `blog`.
- `locale` (optional): Active locale code (e.g., `en`, `zh`). When multi-language is enabled and `type=blog`, only blog posts bound to the requested locale (or legacy unbound posts with `locale = 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. `all` is ignored.

**Response:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "id": 1,
  "slug": "getting-started",
  "title": "Getting Started with APayShop",
  "content": "This is the full HTML content of the post...

",
  "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 by `published` or `draft`.
- `category` (optional): Filter by category id, or `uncategorized` / `none` for 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:**

```json
{
  "slug": "new-blog-post",
  "title": "New Feature Release",
  "description": "We just released a great new feature.",
  "content": "Details here...

",
  "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:**

```json
{
  "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`; each language falls back to the top-level `name`/`description` when omitted.

### Get / Update / Delete Post Category

- `GET /api/admin/posts/categories/:id`
- `PUT /api/admin/posts/categories/:id` — same body as create; omit `slug` to keep the current one.
- `DELETE /api/admin/posts/categories/:id` — posts using the category become uncategorized.
