API — Circle

Tóm tắt endpoint

Method	Path	Mô tả	Auth	Rate limit
GET	`/api/v1/circle`	Danh sách circle.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle`	Tạo circle mới.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/circle/me-join`	Circle người dùng đã tham gia.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/circle/me/owner-circle`	Circle người dùng là owner.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/circle/request-invitation`	Lời mời circle của user.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle/send-invitation`	Mời user có sẵn vào circle.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle/response-invitation`	Chấp nhận hoặc từ chối lời mời.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/circle/:publicId/energy`	Xem HP/EXP. [CẦN XÁC NHẬN] response đang mock.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle/:publicId/posts`	Tạo bài circle và enqueue AI evaluation.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/circle/:publicId/posts`	Đọc bài trong circle.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle/:publicId/posts/:postPublicId/reply`	Reply bài trong circle.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle/:publicId/join-request`	Gửi hoặc hủy join request.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle/:publicId/manage/join-request/respond`	Admin/owner accept hoặc reject join request.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle/:publicId/send-invitation/manage`	Admin mời qua email/token.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/circle/:publicId/sacrifice`	Đốt karma để cộng HP cho circle.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/circle/:publicId/stats`	Stats cho owner/admin.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/circle/:publicId`	Chi tiết circle.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.

GET /api/v1/circle

GET Auth required apiLimiter

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

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/circle \
  -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": "circle",
    "endpoint": "/api/v1/circle"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

POST /api/v1/circle

POST Auth required apiLimiter

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

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/circle \
  -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": "circle",
    "endpoint": "/api/v1/circle"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

GET /api/v1/circle/me-join

GET Auth required apiLimiter

Endpoint này dùng để circle người dùng đã tham gia. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/me-join \
  -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": "circle",
    "endpoint": "/api/v1/circle/me-join"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

GET /api/v1/circle/me/owner-circle

GET Auth required apiLimiter

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

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/circle/me/owner-circle \
  -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": "circle",
    "endpoint": "/api/v1/circle/me/owner-circle"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

GET /api/v1/circle/request-invitation

GET Auth required apiLimiter

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

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/circle/request-invitation \
  -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": "circle",
    "endpoint": "/api/v1/circle/request-invitation"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

POST /api/v1/circle/send-invitation

POST Auth required apiLimiter

Endpoint này dùng để mời user có sẵn vào circle. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/send-invitation \
  -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": "circle",
    "endpoint": "/api/v1/circle/send-invitation"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

POST /api/v1/circle/response-invitation

POST Auth required apiLimiter

Endpoint này dùng để chấp nhận hoặc từ chối lời mời. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/response-invitation \
  -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": "circle",
    "endpoint": "/api/v1/circle/response-invitation"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

GET /api/v1/circle/:publicId/energy

GET Auth required apiLimiter

Endpoint này dùng để xem HP/EXP. [CẦN XÁC NHẬN] response đang mock. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/cm_public_123/energy \
  -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": "circle",
    "endpoint": "/api/v1/circle/:publicId/energy"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

POST /api/v1/circle/:publicId/posts

POST Auth required apiLimiter

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

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/circle/cm_public_123/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": "circle",
    "endpoint": "/api/v1/circle/:publicId/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.
Tên file đang là circle-enery.service.ts, không phải energy.

GET /api/v1/circle/:publicId/posts

GET Auth required apiLimiter

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

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/circle/cm_public_123/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": "circle",
    "endpoint": "/api/v1/circle/:publicId/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.
Tên file đang là circle-enery.service.ts, không phải energy.

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

POST Auth required apiLimiter

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

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/circle/cm_public_123/posts/post_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": "circle",
    "endpoint": "/api/v1/circle/:publicId/posts/:postPublicId/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.
Tên file đang là circle-enery.service.ts, không phải energy.

POST /api/v1/circle/:publicId/join-request

POST Auth required apiLimiter

Endpoint này dùng để gửi hoặc hủy join request. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/cm_public_123/join-request \
  -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": "circle",
    "endpoint": "/api/v1/circle/:publicId/join-request"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

POST /api/v1/circle/:publicId/manage/join-request/respond

POST Auth required apiLimiter

Endpoint này dùng để admin/owner accept hoặc reject join request. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/cm_public_123/manage/join-request/respond \
  -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": "circle",
    "endpoint": "/api/v1/circle/:publicId/manage/join-request/respond"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

POST /api/v1/circle/:publicId/send-invitation/manage

POST Auth required apiLimiter

Endpoint này dùng để admin mời qua email/token. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/cm_public_123/send-invitation/manage \
  -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": "circle",
    "endpoint": "/api/v1/circle/:publicId/send-invitation/manage"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

POST /api/v1/circle/:publicId/sacrifice

POST Auth required apiLimiter

Endpoint này dùng để đốt karma để cộng HP cho circle. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/cm_public_123/sacrifice \
  -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": "circle",
    "endpoint": "/api/v1/circle/:publicId/sacrifice"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

GET /api/v1/circle/:publicId/stats

GET Auth required apiLimiter

Endpoint này dùng để stats cho owner/admin. Gọi endpoint này khi client cần thao tác đúng phạm vi module circle.

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/circle/cm_public_123/stats \
  -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": "circle",
    "endpoint": "/api/v1/circle/:publicId/stats"
  }
}

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.
Tên file đang là circle-enery.service.ts, không phải energy.

GET /api/v1/circle/:publicId

GET Auth required apiLimiter

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

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/circle/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": "circle",
    "endpoint": "/api/v1/circle/: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.
Tên file đang là circle-enery.service.ts, không phải energy.