API — Post

Tóm tắt endpoint

Method	Path	Mô tả	Auth	Rate limit
GET	`/api/v1/posts/news-feed`	Feed theo type.	Public/optional	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/posts/search`	Semantic search bằng Mixedbread + Pinecone.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/posts/:publicId`	Chi tiết post.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/posts/:publicId/replies`	Replies của post.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/posts/user/:username`	Posts của user.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/posts/:postId/judge-status`	Judge status placeholder.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/posts`	Tạo post.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/posts/:publicId/reply`	Reply post.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/posts/:publicId/like`	Like/unlike qua Redis.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/posts/:publicId/repost`	Repost origin/root.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/posts/:publicId/quote`	Quote post.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/posts/:publicId/save`	Save post. [CẦN XÁC NHẬN] service hiện no-op.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/posts/:publicId/hide`	Ẩn bài của người khác.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/posts/:publicId/report`	Tạo report và enqueue evaluation.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
PATCH	`/api/v1/posts/:publicId`	Update post nếu là owner.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
DELETE	`/api/v1/posts/:publicId`	Soft delete nếu là owner.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.

GET /api/v1/posts/news-feed

GET Auth varies apiLimiter

Endpoint này dùng để feed theo type. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/posts/news-feed \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/news-feed"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

GET /api/v1/posts/search

GET Auth varies apiLimiter

Endpoint này dùng để semantic search bằng Mixedbread + Pinecone. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/posts/search \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/search"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

GET /api/v1/posts/:publicId

GET Auth varies apiLimiter

Endpoint này dùng để chi tiết post. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/posts/cm_public_123 \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

GET /api/v1/posts/:publicId/replies

GET Auth varies apiLimiter

Endpoint này dùng để replies của post. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/posts/cm_public_123/replies \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId/replies"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

GET /api/v1/posts/user/:username

GET Auth varies apiLimiter

Endpoint này dùng để posts của user. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/posts/user/alice \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/user/:username"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

GET /api/v1/posts/:postId/judge-status

GET Auth required apiLimiter

Endpoint này dùng để judge status placeholder. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/posts/1/judge-status \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:postId/judge-status"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

POST /api/v1/posts

POST Auth required apiLimiter

Endpoint này dùng để tạo post. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/posts \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

POST /api/v1/posts/:publicId/reply

POST Auth required apiLimiter

Endpoint này dùng để reply post. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/posts/cm_public_123/reply \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId/reply"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

POST /api/v1/posts/:publicId/like

POST Auth required apiLimiter

Endpoint này dùng để like/unlike qua Redis. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/posts/cm_public_123/like \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId/like"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

POST /api/v1/posts/:publicId/repost

POST Auth required apiLimiter

Endpoint này dùng để repost origin/root. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/posts/cm_public_123/repost \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId/repost"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

POST /api/v1/posts/:publicId/quote

POST Auth required apiLimiter

Endpoint này dùng để quote post. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/posts/cm_public_123/quote \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId/quote"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

POST /api/v1/posts/:publicId/save

POST Auth required apiLimiter

Endpoint này dùng để save post. [CẦN XÁC NHẬN] service hiện no-op. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/posts/cm_public_123/save \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId/save"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

POST /api/v1/posts/:publicId/hide

POST Auth required apiLimiter

Endpoint này dùng để ẩn bài của người khác. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/posts/cm_public_123/hide \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId/hide"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

POST /api/v1/posts/:publicId/report

POST Auth required apiLimiter

Endpoint này dùng để tạo report và enqueue evaluation. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/posts/cm_public_123/report \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId/report"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

PATCH /api/v1/posts/:publicId

PATCH Auth required apiLimiter

Endpoint này dùng để update post nếu là owner. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X PATCH http://localhost:3302/api/v1/posts/cm_public_123 \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.

DELETE /api/v1/posts/:publicId

DELETE Auth required apiLimiter

Endpoint này dùng để soft delete nếu là owner. Gọi endpoint này khi client cần thao tác đúng phạm vi module post.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X DELETE http://localhost:3302/api/v1/posts/cm_public_123 \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "post",
    "endpoint": "/api/v1/posts/:publicId"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
Like count trả theo Redis sCard, DB đồng bộ sau.