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 키는 서버 측에서만 사용하세요. 클라이언트(브라우저·모바일 앱)에 노출되면 즉시 키를 폐기·재발급해야 합니다.

🔑

키 권한

API 키는 발급한 계정의 권한으로 동작합니다. 기존 테넌트(tenantId) 아래 생성은 그 계정이 해당 테넌트의 OWNER/ADMIN 이어야 하며(아니면 403), 신규 테넌트 생성 시에는 그 계정이 OWNER 가 됩니다. provisioning 스코프 키 발급은 SUPER_ADMIN 만 가능합니다.

Account

GET/me

내 API 키 정보 (연결 테스트)

API 키의 유효성과 능력(스코프)을 조회합니다. GET 이라 write 스코프가 필요 없어 read-only 키도 자기 능력을 확인할 수 있습니다. 키가 없거나 무효·만료면 401 을 반환하며 이 자체가 연결 테스트 결과입니다. 응답의 canProvision/canWrite/canRead 로 프로비저닝·쓰기 가능 여부를 사전 판정하세요(예: canProvision=false 이면 프로비저닝 호출 전에 「이 키로는 불가」 경고 → 초록불 오탐 방지). 인프라 liveness(서버 생존 확인)와는 별개입니다.

Response codes

200OK401Unauthorized

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

401UNAUTHORIZEDX-API-Key 누락·무효·만료 — 이 401 자체가 「연결 실패」 신호입니다 (200 이면 연결 정상).

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Provisioning

POST/provisioning/workspacesEnterprise 전용

워크스페이스 프로비저닝 (멱등)

provisioning 스코프 API 키로 테넌트와 워크스페이스를 한 번에 준비합니다. tenantId 를 보내면 그 테넌트(호출 키 계정이 OWNER/ADMIN)를 사용하고, 없으면 tenantExternalRef 로 계정 네임스페이스에서 멱등 조회/생성합니다(둘 다 없으면 400). workspaceExternalRef 는 필수 멱등 키 — 재요청 시 신규 생성(201) 대신 기존 리소스를 200 으로 반환하며 createdTenant/createdWorkspace 로 구분합니다. 스코프 계층 provisioning ⊃ write(별도 write 불필요). ⚠️ businessType 은 현재 생성물에 영향 없음(audit 기록만), defaultLocale/accentHue/template 은 약검증(정확한 허용값 전송·미인식 template 은 무시), 응답 tenant.myRole 은 null 일 수 있어 권한판단에 쓰지 말 것.

이 엔드포인트는 Enterprise 플랜에서만 사용할 수 있습니다. 프로비저닝 스코프 키 발급 및 사용은 Enterprise 계약에 포함됩니다.

Body parameters

이름	타입	설명
tenantId	integer	기존 테넌트 ID (Long, optional). 제공 시 tenant·tenantExternalRef 는 무시. 호출 키 계정이 해당 테넌트의 OWNER/ADMIN 이어야 함
tenantExternalRef	string	신규 테넌트 멱등 키 (≤100, tenantId 없을 때 사용). 같은 (계정, 값) 재요청 시 기존 테넌트 재사용
tenant.name	string	신규 테넌트 이름 (≤100, 생략 시 workspace.name 사용)
tenant.slug	string	신규 테넌트 slug (≤50, 전역 유니크·미지정 시 자동 생성)
tenant.description	string	신규 테넌트 설명 (≤500)
workspaceExternalRefREQUIRED	string	워크스페이스 멱등 키 (≤100, 필수). 같은 (tenantId, 값) 재요청 시 기존 워크스페이스 재사용
workspace.nameREQUIRED	string	워크스페이스 이름 (≤100, 필수)
workspace.slug	string	워크스페이스 slug (≤50, 테넌트 내 유니크·미지정 시 name 파생)
workspace.description	string	워크스페이스 설명 (≤500)
workspace.defaultLocale	string	기본 로케일 — ko\|en\|ja\|zh\|zh-TW\|es\|vi\|th (미검증 통과, 정확한 값 전송)
workspace.accentHue	integer	액센트 색상 (0~360, 미검증 통과)
workspace.template	string	프리셋 — BLANK\|DEV\|AGENCY\|OPS (미인식 값은 조용히 무시)
workspace.businessType	string	업종 (forward-looking) — 현재 audit 기록만·생성 워크스페이스에 미반영

Response codes

200OK201Created400Bad Request401Unauthorized403Forbidden429Rate Limited

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

403SCOPE_FORBIDDENread-only 키(write 스코프 없음)로 쓰기 시도 — 게이트웨이 필터가 차단

{
  "error": "SCOPE_FORBIDDEN",
  "message": "This API key is read-only. A 'write' scope is required for this operation."
}

403FORBIDDENprovisioning 스코프가 없는 키 — 이 엔드포인트는 provisioning 필수(write 만으로는 불가)

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "The 'provisioning' scope is required."
}

403FORBIDDEN기존 tenantId 지정 시 호출 계정이 해당 테넌트의 OWNER/ADMIN 이 아님(또는 멤버 아님)

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "OWNER or ADMIN role on the tenant is required."
}

400BAD_REQUESTtenantId·tenantExternalRef 를 둘 다 보내지 않음

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "One of tenantId or tenantExternalRef is required."
}

400VALIDATION_ERROR필수/길이 등 검증 실패 — errors[] 에 필드별 상세

{
  "timestamp": "2026-07-14T09:00:00Z",
  "code": "VALIDATION_ERROR",
  "message": "workspaceExternalRef: must not be blank",
  "errors": [
    { "field": "workspaceExternalRef", "code": "NotBlank", "message": "must not be blank" }
  ]
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Tenants

GET/tenants

내 테넌트 목록

API 키 계정이 소속된 모든 테넌트를 반환합니다(테넌트 직접 멤버 + 워크스페이스로만 닿는 조직=MEMBER). GET 이라 read 스코프면 충분합니다. 각 항목의 myRole(OWNER|ADMIN|MEMBER)로 권한을 판정하세요 — 워크스페이스 생성(POST /workspaces)은 myRole ∈ [OWNER, ADMIN] 인 테넌트에서만 가능하므로, SI 클라이언트는 이 목록에서 OWNER/ADMIN 인 항목의 id 를 골라 tenantId 로 사용합니다.

Response fields

이름	타입	설명
id	Long	POST /workspaces 의 tenantId 로 사용하는 테넌트 ID
myRole	String (enum)	OWNER \| ADMIN \| MEMBER (소속 없으면 null). 워크스페이스 생성(POST /workspaces)은 OWNER/ADMIN 인 테넌트에서만 가능
status	String (enum)	테넌트 상태 — ACTIVE \| ARCHIVED \| DELETE (Tenant.Status)
slug	String	조직 slug (라우팅용)
mfaSetupRequired	boolean	조직이 2FA 를 강제하고 아직 미등록이면 true
slugSet	boolean	사용자가 slug 를 직접 설정했는지 여부 (자동 생성 org-xxxx 는 false)

Response codes

200OK401Unauthorized

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/tenants/{tenantId}

테넌트 단건

테넌트 1개를 목록과 동일한 shape 로 반환합니다. 소속이 아니면 접근 검증 실패(403), 없는 테넌트면 400 tenant.not_found. read 스코프면 충분합니다.

Path parameters

이름	타입	설명
tenantIdREQUIRED	integer	조회할 테넌트 ID (Long, 필수)

Response codes

200OK400Bad Request401Unauthorized403Forbidden

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

403FORBIDDEN호출 계정이 그 테넌트의 멤버가 아님 (tenant 접근 검증 실패)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트 멤버가 아닙니다"
}

400BAD_REQUEST존재하지 않는 테넌트 (tenant.not_found)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트를 찾을 수 없습니다"
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Workspaces

POST/workspaces

워크스페이스 생성 (기존 테넌트)

프로비저닝과 분리된 경량 경로 — 테넌트를 만들지 않고, 기존 테넌트(tenantId) 아래에 워크스페이스만 생성합니다. write 스코프면 충분(provisioning 불필요·read-only 키는 403 SCOPE_FORBIDDEN). 호출 키 계정이 해당 테넌트의 OWNER/ADMIN 이어야 합니다. externalRef 를 주면 멱등 — 같은 (tenantId, externalRef) 재요청 시 신규 생성(201) 대신 기존 워크스페이스를 200 으로 반환하며, 생략 시 매 호출 새로 생성됩니다(재시도 안전을 위해 부여 권장). 생성물은 팀 워크스페이스(개인 아님)입니다. ⚠️ defaultLocale/accentHue/template 은 약검증(값 통과·미인식 template 은 무시). 테넌트 자동 생성이 필요하면 프로비저닝(POST /provisioning/workspaces)을 사용하세요.

Body parameters

이름	타입	설명
tenantIdREQUIRED	integer	이 테넌트 아래 생성 (Long, 필수). 호출 키 계정이 해당 테넌트의 OWNER/ADMIN 이어야 함
externalRef	string	멱등 키 (≤100, optional). 같은 (tenantId, 값) 재요청 시 기존 워크스페이스 반환. 생략 시 매번 신규 생성
nameREQUIRED	string	워크스페이스 이름 (≤100, 필수)
slug	string	워크스페이스 slug (≤50, 테넌트 내 유니크·미지정 시 name 파생)
description	string	워크스페이스 설명 (≤500)
defaultLocale	string	기본 로케일 — ko\|en\|ja\|zh\|zh-TW\|es\|vi\|th (미검증 통과, 정확한 값 전송 권장)
accentHue	integer	액센트 색상 (0~360, 미검증 통과)
template	string	프리셋 — BLANK\|DEV\|AGENCY\|OPS (미인식 값은 조용히 무시)

Response codes

201Created200OK400Bad Request401Unauthorized403Forbidden

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

403SCOPE_FORBIDDENread-only 키(write 스코프 없음)로 쓰기 시도 — 게이트웨이 필터가 차단

{
  "error": "SCOPE_FORBIDDEN",
  "message": "This API key is read-only. A 'write' scope is required for this operation."
}

403FORBIDDEN호출 계정이 tenantId 테넌트의 OWNER/ADMIN 이 아님 (tenant.admin_required)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "관리자 권한이 필요합니다"
}

403FORBIDDEN호출 계정이 그 테넌트의 멤버가 아님(없는 테넌트 포함, tenant.not_member)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트 멤버가 아닙니다"
}

400VALIDATION_ERROR필수/길이 등 검증 실패(tenantId·name 누락 등) — errors[] 에 필드별 상세

{
  "timestamp": "2026-07-14T20:00:00Z",
  "code": "VALIDATION_ERROR",
  "message": "tenantId: must not be null",
  "errors": [
    { "field": "tenantId", "code": "NotNull", "message": "must not be null" }
  ]
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces/slug/available

워크스페이스 slug 중복 확인

테넌트 안에서 워크스페이스 slug 를 쓸 수 있는지(중복 아님) 검사합니다. slug 는 (tenantId, slug) 로 유니크하므로 워크스페이스 생성과 동일하게 tenantId 가 필요합니다. slug 는 저장 규칙과 동일하게 정규화(앞뒤 공백 제거·소문자)해 비교하며, 빈 값·중복이면 available:false 입니다. 인가는 워크스페이스 생성과 동일한 게이트 — 호출 계정이 해당 테넌트의 OWNER/ADMIN 이어야 하고(requireTenantAdmin), 비멤버·비관리자는 403 이며 테넌트 존재 여부는 노출하지 않습니다. GET 이라 read 스코프면 충분합니다. 워크스페이스 생성(POST /workspaces) 전에 이 API 로 slug 가용성을 미리 확인하세요.

Query parameters

이름	타입	설명
tenantIdREQUIRED	integer	이 테넌트 범위에서 중복 검사 (Long, 필수 query). slug 유니크 스코프. 호출 계정이 이 테넌트의 OWNER/ADMIN 이어야 함
slugREQUIRED	string	확인할 워크스페이스 slug (query, 필수). 정규화(trim·소문자) 후 비교

Response fields

이름	타입	설명
available	boolean	true=사용 가능(중복 아님), false=이미 사용 중이거나 빈 slug

Response codes

200OK401Unauthorized403Forbidden

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

403FORBIDDEN호출 계정이 tenantId 테넌트의 OWNER/ADMIN 이 아님(비멤버 포함) — requireTenantAdmin 차단(테넌트 존재 미노출)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "관리자 권한이 필요합니다"
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces

워크스페이스 목록

API 키 계정이 접근 가능한 워크스페이스 목록을 반환합니다.

Response codes

200OK401Unauthorized429Rate Limited

GET/workspaces/{workspaceId}

워크스페이스 조회

워크스페이스 단건을 조회합니다.

Path parameters

이름	타입	설명
workspaceIdREQUIRED	integer	워크스페이스 ID

Response codes

200OK401Unauthorized404Not Found

Projects

GET/projects

프로젝트 목록 조회

지정한 테넌트·워크스페이스의 프로젝트 목록을 페이지 단위로 반환합니다. tenantId 와 workspaceId 는 필수이며, status 로 추가 필터링할 수 있습니다.

Query parameters

이름	타입	설명
tenantIdREQUIRED	integer	테넌트 ID (필수)
workspaceIdREQUIRED	integer	워크스페이스 ID (필수)
status	enum	프로젝트 상태 정확 매칭 (PLANNING·ESTIMATING·WAITING·IN_PROGRESS·ON_HOLD·COMPLETED·CANCELLED). 지정 시 취소/아카이브도 조회.
page	integer	페이지 번호 (0부터)
size	integer	페이지 크기 (기본 20, 상한 100)

Response codes

200OK400Bad Request401Unauthorized403Forbidden429Rate Limited

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

400BAD_REQUEST워크스페이스가 없거나 해당 테넌트 소속이 아님 (교차 테넌트는 존재를 노출하지 않고 not_found 처리).

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "워크스페이스를 찾을 수 없습니다"
}

400BAD_REQUESTstatus 에 허용되지 않은 값 전달.

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "유효하지 않은 프로젝트 상태 값입니다"
}

403FORBIDDEN해당 워크스페이스에 접근 권한 없음 (ACTIVE 멤버 또는 수락된 클라이언트/파트너 아님 — 테넌트 멤버십 fallback 없음).

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "워크스페이스 접근 권한이 없습니다"
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료.

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

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 확인

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 키는 서버 측에서만 사용하세요. 클라이언트(브라우저·모바일 앱)에 노출되면 즉시 키를 폐기·재발급해야 합니다.

🔑

키 권한

Account

GET/me

내 API 키 정보 (연결 테스트)

Response codes

200OK401Unauthorized

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

401UNAUTHORIZEDX-API-Key 누락·무효·만료 — 이 401 자체가 「연결 실패」 신호입니다 (200 이면 연결 정상).

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Provisioning

POST/provisioning/workspacesEnterprise 전용

워크스페이스 프로비저닝 (멱등)

이 엔드포인트는 Enterprise 플랜에서만 사용할 수 있습니다. 프로비저닝 스코프 키 발급 및 사용은 Enterprise 계약에 포함됩니다.

Body parameters

이름	타입	설명
tenantId	integer	기존 테넌트 ID (Long, optional). 제공 시 tenant·tenantExternalRef 는 무시. 호출 키 계정이 해당 테넌트의 OWNER/ADMIN 이어야 함
tenantExternalRef	string	신규 테넌트 멱등 키 (≤100, tenantId 없을 때 사용). 같은 (계정, 값) 재요청 시 기존 테넌트 재사용
tenant.name	string	신규 테넌트 이름 (≤100, 생략 시 workspace.name 사용)
tenant.slug	string	신규 테넌트 slug (≤50, 전역 유니크·미지정 시 자동 생성)
tenant.description	string	신규 테넌트 설명 (≤500)
workspaceExternalRefREQUIRED	string	워크스페이스 멱등 키 (≤100, 필수). 같은 (tenantId, 값) 재요청 시 기존 워크스페이스 재사용
workspace.nameREQUIRED	string	워크스페이스 이름 (≤100, 필수)
workspace.slug	string	워크스페이스 slug (≤50, 테넌트 내 유니크·미지정 시 name 파생)
workspace.description	string	워크스페이스 설명 (≤500)
workspace.defaultLocale	string	기본 로케일 — ko\|en\|ja\|zh\|zh-TW\|es\|vi\|th (미검증 통과, 정확한 값 전송)
workspace.accentHue	integer	액센트 색상 (0~360, 미검증 통과)
workspace.template	string	프리셋 — BLANK\|DEV\|AGENCY\|OPS (미인식 값은 조용히 무시)
workspace.businessType	string	업종 (forward-looking) — 현재 audit 기록만·생성 워크스페이스에 미반영

Response codes

200OK201Created400Bad Request401Unauthorized403Forbidden429Rate Limited

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

403SCOPE_FORBIDDENread-only 키(write 스코프 없음)로 쓰기 시도 — 게이트웨이 필터가 차단

{
  "error": "SCOPE_FORBIDDEN",
  "message": "This API key is read-only. A 'write' scope is required for this operation."
}

403FORBIDDENprovisioning 스코프가 없는 키 — 이 엔드포인트는 provisioning 필수(write 만으로는 불가)

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "The 'provisioning' scope is required."
}

403FORBIDDEN기존 tenantId 지정 시 호출 계정이 해당 테넌트의 OWNER/ADMIN 이 아님(또는 멤버 아님)

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "OWNER or ADMIN role on the tenant is required."
}

400BAD_REQUESTtenantId·tenantExternalRef 를 둘 다 보내지 않음

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "One of tenantId or tenantExternalRef is required."
}

400VALIDATION_ERROR필수/길이 등 검증 실패 — errors[] 에 필드별 상세

{
  "timestamp": "2026-07-14T09:00:00Z",
  "code": "VALIDATION_ERROR",
  "message": "workspaceExternalRef: must not be blank",
  "errors": [
    { "field": "workspaceExternalRef", "code": "NotBlank", "message": "must not be blank" }
  ]
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Tenants

GET/tenants

내 테넌트 목록

Response fields

이름	타입	설명
id	Long	POST /workspaces 의 tenantId 로 사용하는 테넌트 ID
myRole	String (enum)	OWNER \| ADMIN \| MEMBER (소속 없으면 null). 워크스페이스 생성(POST /workspaces)은 OWNER/ADMIN 인 테넌트에서만 가능
status	String (enum)	테넌트 상태 — ACTIVE \| ARCHIVED \| DELETE (Tenant.Status)
slug	String	조직 slug (라우팅용)
mfaSetupRequired	boolean	조직이 2FA 를 강제하고 아직 미등록이면 true
slugSet	boolean	사용자가 slug 를 직접 설정했는지 여부 (자동 생성 org-xxxx 는 false)

Response codes

200OK401Unauthorized

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/tenants/{tenantId}

테넌트 단건

테넌트 1개를 목록과 동일한 shape 로 반환합니다. 소속이 아니면 접근 검증 실패(403), 없는 테넌트면 400 tenant.not_found. read 스코프면 충분합니다.

Path parameters

이름	타입	설명
tenantIdREQUIRED	integer	조회할 테넌트 ID (Long, 필수)

Response codes

200OK400Bad Request401Unauthorized403Forbidden

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

403FORBIDDEN호출 계정이 그 테넌트의 멤버가 아님 (tenant 접근 검증 실패)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트 멤버가 아닙니다"
}

400BAD_REQUEST존재하지 않는 테넌트 (tenant.not_found)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트를 찾을 수 없습니다"
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Workspaces

POST/workspaces

워크스페이스 생성 (기존 테넌트)

Body parameters

이름	타입	설명
tenantIdREQUIRED	integer	이 테넌트 아래 생성 (Long, 필수). 호출 키 계정이 해당 테넌트의 OWNER/ADMIN 이어야 함
externalRef	string	멱등 키 (≤100, optional). 같은 (tenantId, 값) 재요청 시 기존 워크스페이스 반환. 생략 시 매번 신규 생성
nameREQUIRED	string	워크스페이스 이름 (≤100, 필수)
slug	string	워크스페이스 slug (≤50, 테넌트 내 유니크·미지정 시 name 파생)
description	string	워크스페이스 설명 (≤500)
defaultLocale	string	기본 로케일 — ko\|en\|ja\|zh\|zh-TW\|es\|vi\|th (미검증 통과, 정확한 값 전송 권장)
accentHue	integer	액센트 색상 (0~360, 미검증 통과)
template	string	프리셋 — BLANK\|DEV\|AGENCY\|OPS (미인식 값은 조용히 무시)

Response codes

201Created200OK400Bad Request401Unauthorized403Forbidden

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

403SCOPE_FORBIDDENread-only 키(write 스코프 없음)로 쓰기 시도 — 게이트웨이 필터가 차단

{
  "error": "SCOPE_FORBIDDEN",
  "message": "This API key is read-only. A 'write' scope is required for this operation."
}

403FORBIDDEN호출 계정이 tenantId 테넌트의 OWNER/ADMIN 이 아님 (tenant.admin_required)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "관리자 권한이 필요합니다"
}

403FORBIDDEN호출 계정이 그 테넌트의 멤버가 아님(없는 테넌트 포함, tenant.not_member)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트 멤버가 아닙니다"
}

400VALIDATION_ERROR필수/길이 등 검증 실패(tenantId·name 누락 등) — errors[] 에 필드별 상세

{
  "timestamp": "2026-07-14T20:00:00Z",
  "code": "VALIDATION_ERROR",
  "message": "tenantId: must not be null",
  "errors": [
    { "field": "tenantId", "code": "NotNull", "message": "must not be null" }
  ]
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces/slug/available

워크스페이스 slug 중복 확인

Query parameters

이름	타입	설명
tenantIdREQUIRED	integer	이 테넌트 범위에서 중복 검사 (Long, 필수 query). slug 유니크 스코프. 호출 계정이 이 테넌트의 OWNER/ADMIN 이어야 함
slugREQUIRED	string	확인할 워크스페이스 slug (query, 필수). 정규화(trim·소문자) 후 비교

Response fields

이름	타입	설명
available	boolean	true=사용 가능(중복 아님), false=이미 사용 중이거나 빈 slug

Response codes

200OK401Unauthorized403Forbidden

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

403FORBIDDEN호출 계정이 tenantId 테넌트의 OWNER/ADMIN 이 아님(비멤버 포함) — requireTenantAdmin 차단(테넌트 존재 미노출)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "관리자 권한이 필요합니다"
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료 (External 공통)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces

워크스페이스 목록

API 키 계정이 접근 가능한 워크스페이스 목록을 반환합니다.

Response codes

200OK401Unauthorized429Rate Limited

GET/workspaces/{workspaceId}

워크스페이스 조회

워크스페이스 단건을 조회합니다.

Path parameters

이름	타입	설명
workspaceIdREQUIRED	integer	워크스페이스 ID

Response codes

200OK401Unauthorized404Not Found

Projects

GET/projects

프로젝트 목록 조회

지정한 테넌트·워크스페이스의 프로젝트 목록을 페이지 단위로 반환합니다. tenantId 와 workspaceId 는 필수이며, status 로 추가 필터링할 수 있습니다.

Query parameters

이름	타입	설명
tenantIdREQUIRED	integer	테넌트 ID (필수)
workspaceIdREQUIRED	integer	워크스페이스 ID (필수)
status	enum	프로젝트 상태 정확 매칭 (PLANNING·ESTIMATING·WAITING·IN_PROGRESS·ON_HOLD·COMPLETED·CANCELLED). 지정 시 취소/아카이브도 조회.
page	integer	페이지 번호 (0부터)
size	integer	페이지 크기 (기본 20, 상한 100)

Response codes

200OK400Bad Request401Unauthorized403Forbidden429Rate Limited

에러 응답

message 필드는 요청 로케일(?lang 또는 Accept-Language)에 따라 8개 로케일로 반환됩니다.

400BAD_REQUEST워크스페이스가 없거나 해당 테넌트 소속이 아님 (교차 테넌트는 존재를 노출하지 않고 not_found 처리).

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "워크스페이스를 찾을 수 없습니다"
}

400BAD_REQUESTstatus 에 허용되지 않은 값 전달.

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "유효하지 않은 프로젝트 상태 값입니다"
}

403FORBIDDEN해당 워크스페이스에 접근 권한 없음 (ACTIVE 멤버 또는 수락된 클라이언트/파트너 아님 — 테넌트 멤버십 fallback 없음).

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "워크스페이스 접근 권한이 없습니다"
}

401UNAUTHORIZEDX-API-Key 누락·무효·만료.

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces/{workspaceId}/projects

프로젝트 목록

워크스페이스의 활성 프로젝트 목록을 반환합니다 (취소·아카이브 제외).

Path parameters

이름	타입	설명
workspaceIdREQUIRED	integer	워크스페이스 ID

Response codes

200OK401Unauthorized403Forbidden

POST/projects

프로젝트 생성 (멱등)

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 확인