OVERVIEW

PJT AI REST API

Một REST API chuẩn để tích hợp dữ liệu PJT AI với các hệ thống bên ngoài. Mọi yêu cầu và phản hồi đều ở định dạng JSON, và URL cơ sở là https://api.pjt.ai/api/external/v1.

Cơ bản

Xác thực — header X-API-Key (API key tài khoản, tiền tố pjt_)
Phạm vi khóa — read (chỉ đọc, mặc định) / write. POST·PUT·DELETE cần khóa có phạm vi write — nếu không sẽ trả về 403 SCOPE_FORBIDDEN
Giới hạn — 60 req/phút + 10.000 req/tháng mỗi khóa (Enterprise thỏa thuận)
Mã phản hồi — 2xx thành công, 4xx lỗi máy khách, 5xx lỗi máy chủ
Ngày tháng — mọi dấu thời gian đều ở định dạng ISO 8601 (UTC)

AUTH

Xác thực

Mọi yêu cầu đều cần header X-API-Key: <API_KEY> . Cấp khóa tại Cài đặt tài khoản > API key (chỉ hiển thị một lần khi tạo).

⚠

Lưu trữ khóa

Chỉ dùng khóa API ở phía máy chủ. Nếu một khóa bị lộ ra máy khách (trình duyệt hoặc ứng dụng di động), hãy thu hồi và phát hành lại ngay lập tức.

Workspaces

GET/workspaces

Danh sách workspace

Trả về các workspace mà tài khoản API key có thể truy cập.

Mã phản hồi

200OK401Unauthorized429Rate Limited

GET/workspaces/{workspaceId}

Xem workspace

Trả về một workspace.

Tham số đường dẫn

Tên	Kiểu	Mô tả
workspaceIdBẮT BUỘC	integer	ID workspace

Mã phản hồi

200OK401Unauthorized404Not Found

Projects

GET/workspaces/{workspaceId}/projects

Danh sách dự án

Trả về các dự án đang hoạt động của workspace (loại trừ đã hủy/lưu trữ).

Tham số đường dẫn

Tên	Kiểu	Mô tả
workspaceIdBẮT BUỘC	integer	ID workspace

Mã phản hồi

200OK401Unauthorized403Forbidden

POST/projects

Tạo dự án (idempotent)

Tạo dự án. Khi gửi kèm externalRef, lời gọi là idempotent — lặp lại cùng (workspaceId, externalRef) sẽ trả về dự án hiện có với 200 thay vì tạo mới (201 khi tạo lần đầu).

Tham số body

Tên	Kiểu	Mô tả
workspaceIdBẮT BUỘC	integer	ID workspace
nameBẮT BUỘC	string	Tên dự án
externalRef	string	Khóa idempotency — gửi lại cùng giá trị sẽ trả về dự án hiện có với 200 thay vì tạo mới
code	string	Mã dự án (tiền tố khóa công việc). Tự động tạo từ tên nếu bỏ trống
description	string	Mô tả
clientIds	array	Mảng ID khách hàng
managerId	integer	ID tài khoản quản lý
startDate	date	Ngày bắt đầu — ISO 8601 (YYYY-MM-DD)
endDate	date	Ngày kết thúc — ISO 8601 (YYYY-MM-DD)
budget	integer	Ngân sách

Mã phản hồi

201Created200OK400Bad Request401Unauthorized

GET/projects/{projectId}

Chi tiết / tiến độ dự án

Trả về chi tiết dự án gồm trạng thái, tiến độ (%), lịch kế hoạch/thực tế và thời điểm sửa cuối.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Mã phản hồi

200OK404Not Found

PUT/projects/{projectId}

Cập nhật dự án

Chỉ cập nhật các trường được gửi (cập nhật một phần).

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Tham số body

Tên	Kiểu	Mô tả
name	string	Tên dự án
status	enum	Trạng thái — PLANNING·ESTIMATING·WAITING·IN_PROGRESS·ON_HOLD·COMPLETED·CANCELLED
progressRate	integer	Tiến độ (%) 0–100
startDate	date	Ngày bắt đầu — ISO 8601 (YYYY-MM-DD)
endDate	date	Ngày kết thúc — ISO 8601 (YYYY-MM-DD)

Mã phản hồi

200OK400Bad Request404Not Found

DELETE/projects/{projectId}

Xóa dự án

Xóa dự án. Thành công trả về 204 No Content (không có nội dung).

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Mã phản hồi

204No Content403Forbidden404Not Found

GET/projects/{projectId}/timeline

Timeline (milestone)

Danh sách milestone của dự án — tên, trạng thái (PLANNED/IN_PROGRESS/COMPLETED), hạn chót, ngày hoàn thành và tiến độ. Sắp xếp theo sortOrder.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Mã phản hồi

200OK403Forbidden404Not Found

GET/projects/{projectId}/activities

Hoạt động

Các sự kiện thay đổi công việc của dự án, mới nhất trước — loại, thông điệp, người thực hiện và thời gian.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Tham số truy vấn

Tên	Kiểu	Mô tả
page	integer	Số trang (bắt đầu từ 0, mặc định 0)
size	integer	Kích thước trang (mặc định 50, tối đa 200)

Mã phản hồi

200OK403Forbidden404Not Found

GET/projects/{projectId}/files

Danh sách tệp

Gộp tệp đính kèm của công việc và bình luận trong dự án, mới nhất trước. fileUrl là URL tĩnh không hết hạn.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Tham số truy vấn

Tên	Kiểu	Mô tả
limit	integer	Số lượng tối đa (mặc định 100, tối đa 500)

Mã phản hồi

200OK403Forbidden404Not Found

Tasks

GET/projects/{projectId}/tasks

Danh sách công việc

Trả về các công việc của dự án. Dùng /tasks/paged nếu cần phân trang.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Tham số truy vấn

Tên	Kiểu	Mô tả
sortBy	string	Trường sắp xếp (mặc định createdAt)

Mã phản hồi

200OK403Forbidden404Not Found

POST/tasks

Tạo công việc

Tạo công việc.

Tham số body

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	integer	ID dự án (số)
titleBẮT BUỘC	string	Tiêu đề
description	string	Mô tả
assigneeId	integer	ID tài khoản người phụ trách
status	enum	Trạng thái — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED
priority	enum	Độ ưu tiên — URGENT·HIGH·MEDIUM·LOW
dueDate	date	Hạn chót — ISO 8601
milestoneId	integer	ID milestone cần liên kết

Mã phản hồi

201Created400Bad Request401Unauthorized

GET/tasks/{taskId}

Xem công việc

Trả về một công việc.

Tham số đường dẫn

Tên	Kiểu	Mô tả
taskIdBẮT BUỘC	integer	ID công việc

Mã phản hồi

200OK404Not Found

PUT/tasks/{taskId}

Cập nhật công việc

Chỉ cập nhật các trường được gửi.

Tham số đường dẫn

Tên	Kiểu	Mô tả
taskIdBẮT BUỘC	integer	ID công việc

Tham số body

Tên	Kiểu	Mô tả
title	string	Tiêu đề
status	enum	Trạng thái — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED
priority	enum	Độ ưu tiên — URGENT·HIGH·MEDIUM·LOW
dueDate	date	Hạn chót — ISO 8601

Mã phản hồi

200OK400Bad Request404Not Found

DELETE/tasks/{taskId}

Xóa công việc

Xóa công việc. Thành công trả về 204 No Content.

Tham số đường dẫn

Tên	Kiểu	Mô tả
taskIdBẮT BUỘC	integer	ID công việc

Mã phản hồi

204No Content403Forbidden404Not Found

GET/tasks/assigned

Công việc được giao cho tôi

Trả về các công việc được giao cho tài khoản API key.

Mã phản hồi

200OK401Unauthorized

Documents

GET/projects/{projectId}/documents

Danh sách tài liệu

Trả về các tài liệu của dự án. Dùng /documents/paged nếu cần phân trang.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Mã phản hồi

200OK403Forbidden404Not Found

GET/documents/{documentId}

Xem tài liệu

Trả về một tài liệu (gồm nội dung).

Tham số đường dẫn

Tên	Kiểu	Mô tả
documentIdBẮT BUỘC	integer	ID tài liệu

Mã phản hồi

200OK404Not Found

POST/documents

Tạo tài liệu

Tạo tài liệu.

Tham số body

Tên	Kiểu	Mô tả
workspaceIdBẮT BUỘC	integer	ID workspace
titleBẮT BUỘC	string	Tiêu đề
documentTypeBẮT BUỘC	enum	Loại tài liệu (vd: REQUIREMENT, MEETING_NOTE)
projectId	integer	ID dự án (số)
content	string	Nội dung tài liệu
visibility	enum	Phạm vi hiển thị — PUBLIC·TEAM·PRIVATE

Mã phản hồi

201Created400Bad Request401Unauthorized

PUT/documents/{documentId}

Cập nhật tài liệu

Chỉ cập nhật các trường được gửi.

Tham số đường dẫn

Tên	Kiểu	Mô tả
documentIdBẮT BUỘC	integer	ID tài liệu

Tham số body

Tên	Kiểu	Mô tả
title	string	Tiêu đề
content	string	Nội dung tài liệu
visibility	enum	Phạm vi hiển thị — PUBLIC·TEAM·PRIVATE

Mã phản hồi

200OK400Bad Request404Not Found

DELETE/documents/{documentId}

Xóa tài liệu

Xóa tài liệu. Thành công trả về 204 No Content.

Tham số đường dẫn

Tên	Kiểu	Mô tả
documentIdBẮT BUỘC	integer	ID tài liệu

Mã phản hồi

204No Content403Forbidden404Not Found

ERRORS

Mã lỗi

Mọi phản hồi lỗi đều bao gồm error.code và error.message.

Mã	Tên	Mô tả	Hành động
400	Bad Request	Body của yêu cầu không hợp lệ.	Xác thực body của yêu cầu
401	Unauthorized	Khóa API không hợp lệ hoặc thiếu.	Kiểm tra lại khóa API
403	Forbidden	Bạn không có quyền truy cập tài nguyên này. Yêu cầu ghi bằng khóa chỉ đọc sẽ trả về SCOPE_FORBIDDEN.	Kiểm tra vai trò/phạm vi
404	Not Found	Không tìm thấy tài nguyên được yêu cầu.	Kiểm tra lại ID
429	Rate Limited	Bạn đã vượt quá giới hạn tốc độ.	Xem header Retry-After và giảm tốc
500	Server Error	Đã xảy ra lỗi khi máy chủ xử lý yêu cầu.	Thử lại sau 5 phút, kiểm tra status.pjt.ai

OVERVIEW

PJT AI REST API

Cơ bản

Xác thực — header X-API-Key (API key tài khoản, tiền tố pjt_)
Phạm vi khóa — read (chỉ đọc, mặc định) / write. POST·PUT·DELETE cần khóa có phạm vi write — nếu không sẽ trả về 403 SCOPE_FORBIDDEN
Giới hạn — 60 req/phút + 10.000 req/tháng mỗi khóa (Enterprise thỏa thuận)
Mã phản hồi — 2xx thành công, 4xx lỗi máy khách, 5xx lỗi máy chủ
Ngày tháng — mọi dấu thời gian đều ở định dạng ISO 8601 (UTC)

AUTH

Xác thực

Mọi yêu cầu đều cần header X-API-Key: <API_KEY> . Cấp khóa tại Cài đặt tài khoản > API key (chỉ hiển thị một lần khi tạo).

⚠

Lưu trữ khóa

Chỉ dùng khóa API ở phía máy chủ. Nếu một khóa bị lộ ra máy khách (trình duyệt hoặc ứng dụng di động), hãy thu hồi và phát hành lại ngay lập tức.

Workspaces

GET/workspaces

Danh sách workspace

Trả về các workspace mà tài khoản API key có thể truy cập.

Mã phản hồi

200OK401Unauthorized429Rate Limited

GET/workspaces/{workspaceId}

Xem workspace

Trả về một workspace.

Tham số đường dẫn

Tên	Kiểu	Mô tả
workspaceIdBẮT BUỘC	integer	ID workspace

Mã phản hồi

200OK401Unauthorized404Not Found

Projects

GET/workspaces/{workspaceId}/projects

Danh sách dự án

Trả về các dự án đang hoạt động của workspace (loại trừ đã hủy/lưu trữ).

Tham số đường dẫn

Tên	Kiểu	Mô tả
workspaceIdBẮT BUỘC	integer	ID workspace

Mã phản hồi

200OK401Unauthorized403Forbidden

POST/projects

Tạo dự án (idempotent)

Tham số body

Tên	Kiểu	Mô tả
workspaceIdBẮT BUỘC	integer	ID workspace
nameBẮT BUỘC	string	Tên dự án
externalRef	string	Khóa idempotency — gửi lại cùng giá trị sẽ trả về dự án hiện có với 200 thay vì tạo mới
code	string	Mã dự án (tiền tố khóa công việc). Tự động tạo từ tên nếu bỏ trống
description	string	Mô tả
clientIds	array	Mảng ID khách hàng
managerId	integer	ID tài khoản quản lý
startDate	date	Ngày bắt đầu — ISO 8601 (YYYY-MM-DD)
endDate	date	Ngày kết thúc — ISO 8601 (YYYY-MM-DD)
budget	integer	Ngân sách

Mã phản hồi

201Created200OK400Bad Request401Unauthorized

GET/projects/{projectId}

Chi tiết / tiến độ dự án

Trả về chi tiết dự án gồm trạng thái, tiến độ (%), lịch kế hoạch/thực tế và thời điểm sửa cuối.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Mã phản hồi

200OK404Not Found

PUT/projects/{projectId}

Cập nhật dự án

Chỉ cập nhật các trường được gửi (cập nhật một phần).

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Tham số body

Tên	Kiểu	Mô tả
name	string	Tên dự án
status	enum	Trạng thái — PLANNING·ESTIMATING·WAITING·IN_PROGRESS·ON_HOLD·COMPLETED·CANCELLED
progressRate	integer	Tiến độ (%) 0–100
startDate	date	Ngày bắt đầu — ISO 8601 (YYYY-MM-DD)
endDate	date	Ngày kết thúc — ISO 8601 (YYYY-MM-DD)

Mã phản hồi

200OK400Bad Request404Not Found

DELETE/projects/{projectId}

Xóa dự án

Xóa dự án. Thành công trả về 204 No Content (không có nội dung).

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Mã phản hồi

204No Content403Forbidden404Not Found

GET/projects/{projectId}/timeline

Timeline (milestone)

Danh sách milestone của dự án — tên, trạng thái (PLANNED/IN_PROGRESS/COMPLETED), hạn chót, ngày hoàn thành và tiến độ. Sắp xếp theo sortOrder.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Mã phản hồi

200OK403Forbidden404Not Found

GET/projects/{projectId}/activities

Hoạt động

Các sự kiện thay đổi công việc của dự án, mới nhất trước — loại, thông điệp, người thực hiện và thời gian.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Tham số truy vấn

Tên	Kiểu	Mô tả
page	integer	Số trang (bắt đầu từ 0, mặc định 0)
size	integer	Kích thước trang (mặc định 50, tối đa 200)

Mã phản hồi

200OK403Forbidden404Not Found

GET/projects/{projectId}/files

Danh sách tệp

Gộp tệp đính kèm của công việc và bình luận trong dự án, mới nhất trước. fileUrl là URL tĩnh không hết hạn.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Tham số truy vấn

Tên	Kiểu	Mô tả
limit	integer	Số lượng tối đa (mặc định 100, tối đa 500)

Mã phản hồi

200OK403Forbidden404Not Found

Tasks

GET/projects/{projectId}/tasks

Danh sách công việc

Trả về các công việc của dự án. Dùng /tasks/paged nếu cần phân trang.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Tham số truy vấn

Tên	Kiểu	Mô tả
sortBy	string	Trường sắp xếp (mặc định createdAt)

Mã phản hồi

200OK403Forbidden404Not Found

POST/tasks

Tạo công việc

Tạo công việc.

Tham số body

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	integer	ID dự án (số)
titleBẮT BUỘC	string	Tiêu đề
description	string	Mô tả
assigneeId	integer	ID tài khoản người phụ trách
status	enum	Trạng thái — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED
priority	enum	Độ ưu tiên — URGENT·HIGH·MEDIUM·LOW
dueDate	date	Hạn chót — ISO 8601
milestoneId	integer	ID milestone cần liên kết

Mã phản hồi

201Created400Bad Request401Unauthorized

GET/tasks/{taskId}

Xem công việc

Trả về một công việc.

Tham số đường dẫn

Tên	Kiểu	Mô tả
taskIdBẮT BUỘC	integer	ID công việc

Mã phản hồi

200OK404Not Found

PUT/tasks/{taskId}

Cập nhật công việc

Chỉ cập nhật các trường được gửi.

Tham số đường dẫn

Tên	Kiểu	Mô tả
taskIdBẮT BUỘC	integer	ID công việc

Tham số body

Tên	Kiểu	Mô tả
title	string	Tiêu đề
status	enum	Trạng thái — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED
priority	enum	Độ ưu tiên — URGENT·HIGH·MEDIUM·LOW
dueDate	date	Hạn chót — ISO 8601

Mã phản hồi

200OK400Bad Request404Not Found

DELETE/tasks/{taskId}

Xóa công việc

Xóa công việc. Thành công trả về 204 No Content.

Tham số đường dẫn

Tên	Kiểu	Mô tả
taskIdBẮT BUỘC	integer	ID công việc

Mã phản hồi

204No Content403Forbidden404Not Found

GET/tasks/assigned

Công việc được giao cho tôi

Trả về các công việc được giao cho tài khoản API key.

Mã phản hồi

200OK401Unauthorized

Documents

GET/projects/{projectId}/documents

Danh sách tài liệu

Trả về các tài liệu của dự án. Dùng /documents/paged nếu cần phân trang.

Tham số đường dẫn

Tên	Kiểu	Mô tả
projectIdBẮT BUỘC	string	ID dự án — ID số hoặc publicId bắt đầu bằng p_

Mã phản hồi

200OK403Forbidden404Not Found

GET/documents/{documentId}

Xem tài liệu

Trả về một tài liệu (gồm nội dung).

Tham số đường dẫn

Tên	Kiểu	Mô tả
documentIdBẮT BUỘC	integer	ID tài liệu

Mã phản hồi

200OK404Not Found

POST/documents

Tạo tài liệu

Tạo tài liệu.

Tham số body

Tên	Kiểu	Mô tả
workspaceIdBẮT BUỘC	integer	ID workspace
titleBẮT BUỘC	string	Tiêu đề
documentTypeBẮT BUỘC	enum	Loại tài liệu (vd: REQUIREMENT, MEETING_NOTE)
projectId	integer	ID dự án (số)
content	string	Nội dung tài liệu
visibility	enum	Phạm vi hiển thị — PUBLIC·TEAM·PRIVATE

Mã phản hồi

201Created400Bad Request401Unauthorized

PUT/documents/{documentId}

Cập nhật tài liệu

Chỉ cập nhật các trường được gửi.

Tham số đường dẫn

Tên	Kiểu	Mô tả
documentIdBẮT BUỘC	integer	ID tài liệu

Tham số body

Tên	Kiểu	Mô tả
title	string	Tiêu đề
content	string	Nội dung tài liệu
visibility	enum	Phạm vi hiển thị — PUBLIC·TEAM·PRIVATE

Mã phản hồi

200OK400Bad Request404Not Found

DELETE/documents/{documentId}

Xóa tài liệu

Xóa tài liệu. Thành công trả về 204 No Content.

Tham số đường dẫn

Tên	Kiểu	Mô tả
documentIdBẮT BUỘC	integer	ID tài liệu

Mã phản hồi

204No Content403Forbidden404Not Found

ERRORS

Mã lỗi

Mọi phản hồi lỗi đều bao gồm error.code và error.message.

Mã	Tên	Mô tả	Hành động
400	Bad Request	Body của yêu cầu không hợp lệ.	Xác thực body của yêu cầu
401	Unauthorized	Khóa API không hợp lệ hoặc thiếu.	Kiểm tra lại khóa API
403	Forbidden	Bạn không có quyền truy cập tài nguyên này. Yêu cầu ghi bằng khóa chỉ đọc sẽ trả về SCOPE_FORBIDDEN.	Kiểm tra vai trò/phạm vi
404	Not Found	Không tìm thấy tài nguyên được yêu cầu.	Kiểm tra lại ID
429	Rate Limited	Bạn đã vượt quá giới hạn tốc độ.	Xem header Retry-After và giảm tốc
500	Server Error	Đã xảy ra lỗi khi máy chủ xử lý yêu cầu.	Thử lại sau 5 phút, kiểm tra status.pjt.ai