OVERVIEW
PJT AI REST API
REST API มาตรฐานสำหรับการเชื่อมต่อข้อมูล PJT AI กับระบบภายนอก คำขอและการตอบกลับทั้งหมดเป็น JSON และ base URL คือ https://api.pjt.ai/api/external/v1.
พื้นฐาน
- การยืนยันตัวตน — เฮดเดอร์ X-API-Key (API key ของบัญชี, prefix pjt_)
- ขอบเขตคีย์ — read (อ่านอย่างเดียว ค่าเริ่มต้น) / write. POST·PUT·DELETE ต้องใช้คีย์ที่มีขอบเขต write — ไม่เช่นนั้นจะได้ 403 SCOPE_FORBIDDEN
- ขีดจำกัด — 60 ครั้ง/นาที + 10,000 ครั้ง/เดือน ต่อคีย์ (Enterprise ตกลงเพิ่มเติม)
- รหัสการตอบกลับ — 2xx สำเร็จ, 4xx ข้อผิดพลาดฝั่งไคลเอนต์, 5xx ข้อผิดพลาดเซิร์ฟเวอร์
- วันที่ — timestamp ทั้งหมดเป็น ISO 8601 (UTC)
AUTH
การยืนยันตัวตน
ทุกคำขอต้องมี header X-API-Key: <API_KEY> สร้างคีย์ได้ที่ การตั้งค่าบัญชี > API key (แสดงเพียงครั้งเดียวตอนสร้าง)
การจัดเก็บคีย์
ใช้ API key เฉพาะฝั่งเซิร์ฟเวอร์เท่านั้น หากคีย์ถูกเปิดเผยต่อไคลเอนต์ (เบราว์เซอร์หรือแอปมือถือ) ให้เพิกถอนและออกใหม่ทันที
Workspaces
GET
/workspacesรายการเวิร์กสเปซ
คืนรายการเวิร์กสเปซที่บัญชี API key เข้าถึงได้
รหัสการตอบกลับ
200OK401Unauthorized429Rate Limited
GET
/workspaces/{workspaceId}ดูเวิร์กสเปซ
คืนเวิร์กสเปซหนึ่งรายการ
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| workspaceIdREQUIRED | integer | ID เวิร์กสเปซ |
รหัสการตอบกลับ
200OK401Unauthorized404Not Found
Projects
GET
/workspaces/{workspaceId}/projectsรายการโปรเจกต์
คืนรายการโปรเจกต์ที่ใช้งานอยู่ของเวิร์กสเปซ (ไม่รวมที่ยกเลิก/เก็บถาวร)
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| workspaceIdREQUIRED | integer | ID เวิร์กสเปซ |
รหัสการตอบกลับ
200OK401Unauthorized403Forbidden
POST
/projectsสร้างโปรเจกต์ (idempotent)
สร้างโปรเจกต์ หากส่ง externalRef การเรียกจะเป็น idempotent — การส่งซ้ำด้วย (workspaceId, externalRef) เดิมจะคืนโปรเจกต์เดิมพร้อม 200 แทนการสร้างใหม่ (สร้างครั้งแรกคือ 201)
พารามิเตอร์ body
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| workspaceIdREQUIRED | integer | ID เวิร์กสเปซ |
| nameREQUIRED | string | ชื่อโปรเจกต์ |
| externalRef | string | คีย์ idempotency — ส่งซ้ำด้วยค่าเดิมจะคืนโปรเจกต์เดิมพร้อม 200 แทนการสร้างใหม่ |
| code | string | รหัสโปรเจกต์ (prefix ของคีย์งาน) หากเว้นว่างจะสร้างอัตโนมัติจากชื่อ |
| description | string | คำอธิบาย |
| clientIds | array | อาร์เรย์ของ ID ลูกค้า |
| managerId | integer | ID บัญชีผู้จัดการ |
| startDate | date | วันเริ่ม — ISO 8601 (YYYY-MM-DD) |
| endDate | date | วันสิ้นสุด — ISO 8601 (YYYY-MM-DD) |
| budget | integer | งบประมาณ |
รหัสการตอบกลับ
201Created200OK400Bad Request401Unauthorized
GET
/projects/{projectId}รายละเอียด / ความคืบหน้าโปรเจกต์
คืนรายละเอียดโปรเจกต์ รวมสถานะ ความคืบหน้า (%) กำหนดการตามแผน/จริง และเวลาแก้ไขล่าสุด
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | string | ID โปรเจกต์ — ID ตัวเลขหรือ publicId ที่ขึ้นต้นด้วย p_ |
รหัสการตอบกลับ
200OK404Not Found
PUT
/projects/{projectId}แก้ไขโปรเจกต์
อัปเดตเฉพาะฟิลด์ที่ส่งมา (partial update)
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | string | ID โปรเจกต์ — ID ตัวเลขหรือ publicId ที่ขึ้นต้นด้วย p_ |
พารามิเตอร์ body
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| name | string | ชื่อโปรเจกต์ |
| status | enum | สถานะ — PLANNING·ESTIMATING·WAITING·IN_PROGRESS·ON_HOLD·COMPLETED·CANCELLED |
| progressRate | integer | ความคืบหน้า (%) 0–100 |
| startDate | date | วันเริ่ม — ISO 8601 (YYYY-MM-DD) |
| endDate | date | วันสิ้นสุด — ISO 8601 (YYYY-MM-DD) |
รหัสการตอบกลับ
200OK400Bad Request404Not Found
DELETE
/projects/{projectId}ลบโปรเจกต์
ลบโปรเจกต์ สำเร็จจะคืน 204 No Content (ไม่มีเนื้อหา)
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | string | ID โปรเจกต์ — ID ตัวเลขหรือ publicId ที่ขึ้นต้นด้วย p_ |
รหัสการตอบกลับ
204No Content403Forbidden404Not Found
GET
/projects/{projectId}/timelineไทม์ไลน์ (ไมล์สโตน)
รายการไมล์สโตนของโปรเจกต์ — ชื่อ สถานะ (PLANNED/IN_PROGRESS/COMPLETED) กำหนดส่ง วันเสร็จ และความคืบหน้า เรียงตาม sortOrder
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | string | ID โปรเจกต์ — ID ตัวเลขหรือ publicId ที่ขึ้นต้นด้วย p_ |
รหัสการตอบกลับ
200OK403Forbidden404Not Found
GET
/projects/{projectId}/activitiesกิจกรรม
เหตุการณ์การเปลี่ยนแปลงงานของโปรเจกต์ เรียงจากใหม่สุด — ประเภท ข้อความ ผู้กระทำ และเวลา
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | string | ID โปรเจกต์ — ID ตัวเลขหรือ publicId ที่ขึ้นต้นด้วย p_ |
พารามิเตอร์ query
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| page | integer | หมายเลขหน้า (เริ่มที่ 0 ค่าเริ่มต้น 0) |
| size | integer | ขนาดหน้า (ค่าเริ่มต้น 50 สูงสุด 200) |
รหัสการตอบกลับ
200OK403Forbidden404Not Found
GET
/projects/{projectId}/filesรายการไฟล์
รวมไฟล์แนบจากงานและคอมเมนต์ในโปรเจกต์ เรียงจากใหม่สุด fileUrl เป็น URL แบบคงที่ไม่หมดอายุ
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | string | ID โปรเจกต์ — ID ตัวเลขหรือ publicId ที่ขึ้นต้นด้วย p_ |
พารามิเตอร์ query
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| limit | integer | จำนวนสูงสุด (ค่าเริ่มต้น 100 สูงสุด 500) |
รหัสการตอบกลับ
200OK403Forbidden404Not Found
Tasks
GET
/projects/{projectId}/tasksรายการงาน
คืนรายการงานของโปรเจกต์ หากต้องการแบ่งหน้าให้ใช้ /tasks/paged
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | string | ID โปรเจกต์ — ID ตัวเลขหรือ publicId ที่ขึ้นต้นด้วย p_ |
พารามิเตอร์ query
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| sortBy | string | เกณฑ์เรียงลำดับ (ค่าเริ่มต้น createdAt) |
รหัสการตอบกลับ
200OK403Forbidden404Not Found
POST
/tasksสร้างงาน
สร้างงาน
พารามิเตอร์ body
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | integer | ID โปรเจกต์ (ตัวเลข) |
| titleREQUIRED | string | หัวข้อ |
| description | string | คำอธิบาย |
| assigneeId | integer | ID บัญชีผู้รับผิดชอบ |
| status | enum | สถานะ — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED |
| priority | enum | ความสำคัญ — URGENT·HIGH·MEDIUM·LOW |
| dueDate | date | กำหนดส่ง — ISO 8601 |
| milestoneId | integer | ID ไมล์สโตนที่จะเชื่อมโยง |
รหัสการตอบกลับ
201Created400Bad Request401Unauthorized
GET
/tasks/{taskId}ดูงาน
คืนงานหนึ่งรายการ
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| taskIdREQUIRED | integer | ID งาน |
รหัสการตอบกลับ
200OK404Not Found
PUT
/tasks/{taskId}แก้ไขงาน
อัปเดตเฉพาะฟิลด์ที่ส่งมา
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| taskIdREQUIRED | integer | ID งาน |
พารามิเตอร์ body
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| title | string | หัวข้อ |
| status | enum | สถานะ — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED |
| priority | enum | ความสำคัญ — URGENT·HIGH·MEDIUM·LOW |
| dueDate | date | กำหนดส่ง — ISO 8601 |
รหัสการตอบกลับ
200OK400Bad Request404Not Found
DELETE
/tasks/{taskId}ลบงาน
ลบงาน สำเร็จจะคืน 204 No Content
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| taskIdREQUIRED | integer | ID งาน |
รหัสการตอบกลับ
204No Content403Forbidden404Not Found
GET
/tasks/assignedงานที่มอบหมายให้ฉัน
คืนรายการงานที่มอบหมายให้บัญชี API key
รหัสการตอบกลับ
200OK401Unauthorized
Documents
GET
/projects/{projectId}/documentsรายการเอกสาร
คืนรายการเอกสารของโปรเจกต์ หากต้องการแบ่งหน้าให้ใช้ /documents/paged
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| projectIdREQUIRED | string | ID โปรเจกต์ — ID ตัวเลขหรือ publicId ที่ขึ้นต้นด้วย p_ |
รหัสการตอบกลับ
200OK403Forbidden404Not Found
GET
/documents/{documentId}ดูเอกสาร
คืนเอกสารหนึ่งรายการ (รวมเนื้อหา)
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| documentIdREQUIRED | integer | ID เอกสาร |
รหัสการตอบกลับ
200OK404Not Found
POST
/documentsสร้างเอกสาร
สร้างเอกสาร
พารามิเตอร์ body
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| workspaceIdREQUIRED | integer | ID เวิร์กสเปซ |
| titleREQUIRED | string | หัวข้อ |
| documentTypeREQUIRED | enum | ประเภทเอกสาร (เช่น REQUIREMENT, MEETING_NOTE) |
| projectId | integer | ID โปรเจกต์ (ตัวเลข) |
| content | string | เนื้อหาเอกสาร |
| visibility | enum | ขอบเขตการมองเห็น — PUBLIC·TEAM·PRIVATE |
รหัสการตอบกลับ
201Created400Bad Request401Unauthorized
PUT
/documents/{documentId}แก้ไขเอกสาร
อัปเดตเฉพาะฟิลด์ที่ส่งมา
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| documentIdREQUIRED | integer | ID เอกสาร |
พารามิเตอร์ body
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| title | string | หัวข้อ |
| content | string | เนื้อหาเอกสาร |
| visibility | enum | ขอบเขตการมองเห็น — PUBLIC·TEAM·PRIVATE |
รหัสการตอบกลับ
200OK400Bad Request404Not Found
DELETE
/documents/{documentId}ลบเอกสาร
ลบเอกสาร สำเร็จจะคืน 204 No Content
พารามิเตอร์ path
| ชื่อ | ประเภท | คำอธิบาย |
|---|---|---|
| documentIdREQUIRED | integer | ID เอกสาร |
รหัสการตอบกลับ
204No Content403Forbidden404Not Found
ERRORS
รหัสข้อผิดพลาด
การตอบกลับข้อผิดพลาดทุกครั้งมี error.code และ error.message
| รหัส | ชื่อ | คำอธิบาย | การดำเนินการ |
|---|---|---|---|
| 400 | Bad Request | request body ไม่ถูกต้อง | ตรวจสอบ request body |
| 401 | Unauthorized | API key ไม่ถูกต้องหรือขาดหายไป | ตรวจสอบ API key อีกครั้ง |
| 403 | Forbidden | คุณไม่มีสิทธิ์เข้าถึงทรัพยากรนี้ คำขอเขียนด้วยคีย์แบบอ่านอย่างเดียวจะได้รับ SCOPE_FORBIDDEN | ตรวจสอบบทบาท/ขอบเขต |
| 404 | Not Found | ไม่พบทรัพยากรที่ร้องขอ | ตรวจสอบ ID อีกครั้ง |
| 429 | Rate Limited | คุณเกินขีดจำกัดอัตรา | ดู header Retry-After และชะลอการเรียก |
| 500 | Server Error | เกิดข้อผิดพลาดขณะเซิร์ฟเวอร์ประมวลผลคำขอ | ลองใหม่หลัง 5 นาที ตรวจสอบ status.pjt.ai |