OVERVIEW
PJT AI REST API
PJT AI 데이터를 외부 시스템과 연동하기 위한 표준 REST API입니다. 모든 요청·응답은 JSON이며, Base URL은 https://api.pjt.ai/api/external/v1 입니다.
기본 사항
- 인증 — X-API-Key 헤더 (계정 API 키, pjt_ prefix)
- 키 스코프 — read(조회 전용, 기본) / write. POST·PUT·DELETE 는 write 스코프 키 필요 — 없으면 403 SCOPE_FORBIDDEN
- 요청 제한 — 60 req/min + 월 10,000회 / 키 (Enterprise는 협의)
- 응답 코드 — 2xx 성공, 4xx 클라이언트 오류, 5xx 서버 오류
- 날짜 — 모든 타임스탬프는 ISO 8601 (UTC)
AUTH
인증
모든 요청은 X-API-Key: <API_KEY> 헤더가 필요합니다. 키 발급은 계정 설정 > API 키에서 (발급 시 1회만 표시).
키 보관
API 키는 서버 측에서만 사용하세요. 클라이언트(브라우저·모바일 앱)에 노출되면 즉시 키를 폐기·재발급해야 합니다.
Workspaces
GET
/workspaces워크스페이스 목록
API 키 계정이 접근 가능한 워크스페이스 목록을 반환합니다.
Response codes
200OK401Unauthorized429Rate Limited
GET
/workspaces/{workspaceId}워크스페이스 조회
워크스페이스 단건을 조회합니다.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| workspaceIdREQUIRED | integer | 워크스페이스 ID |
Response codes
200OK401Unauthorized404Not Found
Projects
GET
/workspaces/{workspaceId}/projects프로젝트 목록
워크스페이스의 활성 프로젝트 목록을 반환합니다 (취소·아카이브 제외).
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| workspaceIdREQUIRED | integer | 워크스페이스 ID |
Response codes
200OK401Unauthorized403Forbidden
POST
/projects프로젝트 생성 (멱등)
프로젝트를 생성합니다. externalRef 를 보내면 멱등 동작 — 같은 (workspaceId, externalRef) 재요청 시 새로 만들지 않고 기존 프로젝트를 200 으로 반환합니다 (신규 생성은 201).
Body parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| workspaceIdREQUIRED | integer | 워크스페이스 ID |
| nameREQUIRED | string | 프로젝트 이름 |
| externalRef | string | 멱등 키 — 같은 값으로 재요청하면 새로 만들지 않고 기존 프로젝트를 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 | 예산 |
Response codes
201Created200OK400Bad Request401Unauthorized
GET
/projects/{projectId}프로젝트 상세 / 진행률
상태·진행률(%)·계획/실제 일정·최종 수정 시각을 포함한 프로젝트 상세를 반환합니다.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| projectIdREQUIRED | string | 프로젝트 ID — 숫자 ID 또는 p_ 로 시작하는 publicId |
Response codes
200OK404Not Found
PUT
/projects/{projectId}프로젝트 수정
보낸 필드만 수정합니다 (부분 업데이트).
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| projectIdREQUIRED | string | 프로젝트 ID — 숫자 ID 또는 p_ 로 시작하는 publicId |
Body parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| 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) |
Response codes
200OK400Bad Request404Not Found
DELETE
/projects/{projectId}프로젝트 삭제
프로젝트를 삭제합니다. 성공 시 204 No Content (응답 본문 없음).
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| projectIdREQUIRED | string | 프로젝트 ID — 숫자 ID 또는 p_ 로 시작하는 publicId |
Response codes
204No Content403Forbidden404Not Found
GET
/projects/{projectId}/timeline타임라인 (마일스톤)
프로젝트 마일스톤 목록 — 제목·상태(PLANNED/IN_PROGRESS/COMPLETED)·기한·완료일·진행률. 표시 순서(sortOrder)대로 반환합니다.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| projectIdREQUIRED | string | 프로젝트 ID — 숫자 ID 또는 p_ 로 시작하는 publicId |
Response codes
200OK403Forbidden404Not Found
GET
/projects/{projectId}/activities활동 내역
프로젝트의 태스크 변경 이벤트를 최신순으로 반환합니다 — 유형·메시지·행위자·시각.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| projectIdREQUIRED | string | 프로젝트 ID — 숫자 ID 또는 p_ 로 시작하는 publicId |
Query parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| page | integer | 페이지 번호 (0부터, 기본 0) |
| size | integer | 페이지 크기 (기본 50, 최대 200) |
Response codes
200OK403Forbidden404Not Found
GET
/projects/{projectId}/files파일 목록
프로젝트 내 태스크·코멘트 첨부 파일을 최신순으로 통합 반환합니다. fileUrl 은 만료 없는 정적 URL 입니다.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| projectIdREQUIRED | string | 프로젝트 ID — 숫자 ID 또는 p_ 로 시작하는 publicId |
Query parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| limit | integer | 최대 개수 (기본 100, 최대 500) |
Response codes
200OK403Forbidden404Not Found
Tasks
GET
/projects/{projectId}/tasks태스크 목록
프로젝트의 태스크 목록을 반환합니다. 페이지네이션이 필요하면 /tasks/paged 를 사용하세요.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| projectIdREQUIRED | string | 프로젝트 ID — 숫자 ID 또는 p_ 로 시작하는 publicId |
Query parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| sortBy | string | 정렬 기준 (기본 createdAt) |
Response codes
200OK403Forbidden404Not Found
POST
/tasks태스크 생성
태스크를 생성합니다.
Body parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| 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 |
Response codes
201Created400Bad Request401Unauthorized
GET
/tasks/{taskId}태스크 조회
태스크 단건을 조회합니다.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| taskIdREQUIRED | integer | 태스크 ID |
Response codes
200OK404Not Found
PUT
/tasks/{taskId}태스크 수정
보낸 필드만 수정합니다.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| taskIdREQUIRED | integer | 태스크 ID |
Body parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| title | string | 제목 |
| status | enum | 상태 — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED |
| priority | enum | 우선순위 — URGENT·HIGH·MEDIUM·LOW |
| dueDate | date | 마감일 — ISO 8601 |
Response codes
200OK400Bad Request404Not Found
DELETE
/tasks/{taskId}태스크 삭제
태스크를 삭제합니다. 성공 시 204 No Content.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| taskIdREQUIRED | integer | 태스크 ID |
Response codes
204No Content403Forbidden404Not Found
GET
/tasks/assigned내 배정 태스크
API 키 계정에 배정된 태스크 목록을 반환합니다.
Response codes
200OK401Unauthorized
Documents
GET
/projects/{projectId}/documents문서 목록
프로젝트의 문서 목록을 반환합니다. 페이지네이션이 필요하면 /documents/paged 를 사용하세요.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| projectIdREQUIRED | string | 프로젝트 ID — 숫자 ID 또는 p_ 로 시작하는 publicId |
Response codes
200OK403Forbidden404Not Found
GET
/documents/{documentId}문서 조회
문서 단건(본문 포함)을 조회합니다.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| documentIdREQUIRED | integer | 문서 ID |
Response codes
200OK404Not Found
POST
/documents문서 생성
문서를 생성합니다.
Body parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| workspaceIdREQUIRED | integer | 워크스페이스 ID |
| titleREQUIRED | string | 제목 |
| documentTypeREQUIRED | enum | 문서 타입 (예: REQUIREMENT, MEETING_NOTE) |
| projectId | integer | 프로젝트 ID (숫자) |
| content | string | 문서 본문 |
| visibility | enum | 공개 범위 — PUBLIC·TEAM·PRIVATE |
Response codes
201Created400Bad Request401Unauthorized
PUT
/documents/{documentId}문서 수정
보낸 필드만 수정합니다.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| documentIdREQUIRED | integer | 문서 ID |
Body parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| title | string | 제목 |
| content | string | 문서 본문 |
| visibility | enum | 공개 범위 — PUBLIC·TEAM·PRIVATE |
Response codes
200OK400Bad Request404Not Found
DELETE
/documents/{documentId}문서 삭제
문서를 삭제합니다. 성공 시 204 No Content.
Path parameters
| 이름 | 타입 | 설명 |
|---|---|---|
| documentIdREQUIRED | integer | 문서 ID |
Response codes
204No Content403Forbidden404Not Found
ERRORS
에러 코드
모든 에러 응답에는 error.code와 error.message 가 포함됩니다.
| 코드 | 이름 | 설명 | 대응 |
|---|---|---|---|
| 400 | Bad Request | 요청 본문이 유효하지 않습니다. | 요청 body 검증 |
| 401 | Unauthorized | API 키가 잘못되었거나 누락되었습니다. | API 키 재확인 |
| 403 | Forbidden | 해당 리소스에 접근 권한이 없습니다. read 전용 키로 쓰기 요청 시 SCOPE_FORBIDDEN 이 반환됩니다. | 역할/스코프 확인 |
| 404 | Not Found | 요청한 리소스를 찾을 수 없습니다. | ID 재확인 |
| 429 | Rate Limited | 요청 제한을 초과했습니다. | Retry-After 헤더 참고, 백오프 적용 |
| 500 | Server Error | 서버 처리 중 오류가 발생했습니다. | 5분 후 재시도, status.pjt.ai 확인 |