---
title: "List posts"
method: GET
path: "/api/v1/posts"
tags: ["Posts"]
---

# List posts

`GET /api/v1/posts`

Retrieves a list of posts with optional filtering and pagination. Returns lightweight post objects optimized for list views (excludes full content, only returns content_length for read time calculation).

## Query parameters

- `limit` integer
- `offset` integer
- `status` 'draft' | 'published' | 'archived' | 'deleted'
- `category_id` integer
- `sub_category_id` integer
- `search` string
- `sort_by` 'created_at' | 'updated_at' | 'view_count' | 'title'
- `sort_order` 'ASC' | 'DESC'

## Response `200`

Posts retrieved successfully

- PostListResponse
  - `status` boolean
  - `message` string
  - `data` PostListItem[]
    - `id` integer
    - `slug` string
    - `title` string
    - `summary` string
    - `meta_description` string
    - `keywords` string
    - `category_id` integer
    - `sub_category_id` integer, nullable
    - `is_featured` boolean
    - `is_pinned` boolean
    - `created_by` integer
    - `view_count` integer
    - `content_length` integer — Character count of the content (for read time calculation)
    - `created_at` string, date-time
  - `meta` object
    - `total` integer
    - `limit` integer
    - `offset` integer

## Changes

- **2026-02-26** `f04a452a2baf` — 2 breaking, 16 warning, 5 info
  - for the `query` request parameter `limit`, default value was changed from `10` to `20`
  - the response property `data/items/sub_category_id` became nullable for the status `200`
  - for the `query` request parameter `limit`, the max was set to `100.00`
  - for the `query` request parameter `limit`, the min was set to `1.00`
  - …19 more
- **2026-02-06** `3d17f189af69` — 2 breaking, 4 warning, 13 info
  - for the `query` request parameter `limit`, default value was changed from `20` to `10`
  - removed the enum value `deleted` from the `query` request parameter `status`
  - deleted the `query` request parameter `search`
  - deleted the `query` request parameter `sort_by`
  - …15 more

[Change history](https://skmtc.dev/nesohq/apis/postal-post-management-service-apis/changes/api/v1/posts/get.md)

---

[API](https://skmtc.dev/nesohq/apis/postal-post-management-service-apis.md) · [All operations](https://skmtc.dev/nesohq/apis/postal-post-management-service-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nesohq/postal-post-management-service-apis/revisions/64a3f9ff2411/schema)