공통 규약

모든 Document Management API 요청은 같은 base 경로, 인증 헤더, scope 검사, 응답 구조를 공유합니다. 이 페이지를 먼저 읽은 뒤 필요한 동작은 각 endpoint 페이지에서 확인합니다.

Base URL

이 reference의 모든 endpoint는 하나의 prefix 아래에 있습니다.

https://drive.example.com/api/external/v1

drive.example.com은 플레이스홀더입니다. 자신의 tenant host로 바꿔서 사용합니다. 운영 중인 Thinkfree Drive 배포에서 해당 tenant에 할당된 서브도메인입니다. 각 endpoint 페이지는 이 prefix를 기준으로 한 상대 경로를 표기합니다.

인증

모든 요청은 API Key를 bearer token으로 보내 인증합니다.

Authorization: Bearer replace-with-your-api-key

관리자가 Thinkfree Drive 관리 화면의 API Key 화면에서 키를 생성합니다. API로 키를 생성·조회·폐기하는 방법은 Authentication을 참고합니다.

서버 측 secret

API Key는 서버 측 secret 저장소에 보관합니다. 브라우저 JavaScript, 모바일 바이너리, URL, 형상관리, 로그에 절대 넣지 않습니다. 노출되었을 가능성이 있으면 즉시 폐기합니다.

키는 tenant에 묶입니다. 키를 소유한 tenant와 요청 host의 tenant가 다르면 요청은 REQUEST_006으로 실패합니다.

Scope

각 API Key는 두 scope 중 하나 또는 둘 다를 가집니다. scope는 endpoint 실행 전에 검사됩니다.

Scope	허용 범위
api:read	읽기 동작 - 목록, 조회, 검색, 다운로드
api:write	쓰기 동작 - 업로드, 이름 변경, 이동, 복제, 삭제, 복원, 설정 변경

쓰기 endpoint는 api:read에 더해 api:write가 필요합니다. api:write가 필요한 동작은 각 endpoint 페이지에 표시되어 있습니다.

키는 MCP 접근을 위한 mcp:read와 mcp:write도 가지며, 발급 가능한 scope 조합은 두 가지뿐입니다. 전체 모델은 Authentication을 참고합니다.

모든 endpoint 그룹이 scope를 검사하지는 않음

admins와 super-admin 트리, 그리고 users, notifications, config, web-office, pinned-folders, API Key 관리 endpoint는 공통 게이트 외에 scope를 검사하지 않습니다. api:read만 가진 키로도 이들에서 쓰기가 가능합니다. 접근 통제는 scope가 아니라 누가 어떤 키를 갖는지로 결정합니다.

응답 구조

성공

대부분의 endpoint는 payload를 공통 구조로 감쌉니다. endpoint별 payload는 data 아래에 들어가며, 반환할 값이 없으면 생략됩니다.

Field	Type	Required	의미
result	boolean	Yes	성공이면 true
code	integer	Yes	결과의 HTTP 상태 코드, 예: 200, 201
message	string	Yes	짧은 상태 문자열, 예: OK, Created
data	object or array	No	endpoint payload. 반환할 값이 없으면 생략

Success with payload

{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "resourceSeq": 283,
    "resourceName": "report.docx"
  }
}

Success without payload

{
  "result": true,
  "code": 200,
  "message": "OK"
}

실패

Field	Type	의미
result	boolean	false
code	integer	HTTP 상태 코드
errorCode	string	RESOURCE_005 같은 고정 심볼 에러 코드
message	string	사람이 읽는 실패 문구

Failure

{
  "result": false,
  "code": 404,
  "errorCode": "RESOURCE_005",
  "message": "데이터를 찾을 수 없습니다."
}

message가 아니라 errorCode로 분기합니다. message 문구는 언어별로 다르고 변경될 수 있습니다. 전체 코드 목록은 Errors를 참고합니다.

공통 구조를 쓰지 않는 endpoint

이 페이지 끝에 설명하는 build endpoint는 result나 data 래퍼 없이 본문 객체를 그대로 내려줍니다. 실패 응답은 공통 실패 구조를 그대로 따릅니다. 이렇게 동작하는 endpoint 그룹은 이것뿐입니다.

날짜

sd, ed처럼 날짜를 받는 요청 파라미터는 YYYY-MM-DD를 씁니다. resourceRegisterDate, resourceUpdateDate처럼 응답에 담기는 시각은 YYYY-MM-DD HH:mm:ss.SSS를 씁니다.

축약 파라미터 이름

이 API의 query·body 파라미터는 축약 이름을 씁니다. 같은 이름은 항상 같은 의미입니다.

이름	Type	의미
ss	integer	공유 사용자 seq. 호출자가 공유 리소스의 소유자가 아닐 때 필수. 본인 소유면 null
ts	integer	이동·복제 대상 사용자 seq
rs	long	리소스 seq. 요청 body에서 리소스를 가리킬 때 사용
pfs	long	부모 폴더 seq
rn	string	리소스 이름
rt	enum	리소스 유형 - FILE 또는 FOLDER
sk	string	파일·폴더 이름에 대한 검색 키워드
sb	enum	정렬 기준 - name, size, update, open
so	enum	정렬 순서 - asc, desc
pi	integer	페이지 번호, 최소 1
ps	integer	페이지 크기, 최소 1
ci	long	cursor id - 이전 페이지 마지막 항목의 resourceSeq
cv	object	cursor value - 이전 페이지 마지막 항목의 정렬 기준 값
ct	enum	cursor type - 이전 페이지 마지막 항목의 resourceType
dt	string	download-token endpoint가 발급한 다운로드 토큰

페이지네이션

이 API에는 두 가지 페이지네이션 방식이 있습니다.

cursor 페이지네이션은 리소스 목록에 쓰입니다. 페이지 크기로 ps를 보내고 첫 요청에서는 cursor 파라미터를 생략한 뒤, 다음 페이지부터는 이전 응답의 ci, cv, ct를 보냅니다. sb와 so는 반드시 함께 보내야 하며, 생략하면 name 오름차순이 기본입니다.

Cursor page response

{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": [],
  "pageSize": 10,
  "nextCursor": 40094,
  "nextCursorValue": "Sample folder",
  "nextCursorType": "FOLDER",
  "hasNext": true
}

번호 페이지네이션은 버전 이력과 대부분의 관리자 목록에 쓰입니다. pi와 ps를 보내면 응답이 totalCount, pageIndex, pageSize를 알려줍니다.

리소스 모델

파일과 폴더는 모두 리소스이며, resourceSeq로 식별하고 resourceType으로 구분합니다. 리소스 목록은 둘 다 같은 형태로 반환합니다.

Field	Type	의미
resourceSeq	long	파일 또는 폴더의 고정 식별자
resourceType	enum	FILE 또는 FOLDER
parentFolderSeq	long	상위 폴더. 드라이브 최상위면 null
resourceName	string	파일 또는 폴더 이름
ownerId	string	소유자 계정 id
sizeByte	long	바이트 크기. 폴더면 null
isShared	boolean	공유 여부
isLocked	boolean	편집 잠금 여부
canView	boolean	호출 계정이 이 리소스를 열 수 있는지
canEdit	boolean	호출 계정이 이 리소스를 수정할 수 있는지
canDownload	boolean	호출 계정이 이 리소스를 다운로드할 수 있는지
canDelete	boolean	호출 계정이 이 리소스를 삭제할 수 있는지
canShare	boolean	호출 계정이 이 리소스를 공유할 수 있는지
resourceRegisterDate	string	생성 시각
resourceUpdateDate	string	마지막 수정 시각

리소스 동작

아래 동작은 파일과 폴더에 공통으로 적용됩니다.

리소스 목록

GET /api/external/v1/resources

파라미터	Type	필수	설명
st	enum	Yes	검색 범위 - 내 드라이브는 MY, 볼 수 있는 전체는 ALL
ps	integer	Yes	페이지 크기, 최소 1
ss	integer	No	공유 사용자 seq. st가 ALL이면 적용되지 않음
sk	string	No	이름 검색 키워드
pfs	long	No	부모 폴더 seq. 공유 사용자가 호출할 때 필수
rt	enum	No	FILE 또는 FOLDER
oi	string	No	소유자 id, 최대 254자
sd	date	No	수정일 범위 시작, YYYY-MM-DD. ed를 함께 보내지 않으면 무시
ed	date	No	수정일 범위 종료, YYYY-MM-DD. sd를 함께 보내지 않으면 무시
ft	enum	No	파일 유형 - document, spreadsheet, presentation, pdf, image, note
sb	enum	No	정렬 기준. so를 함께 보내지 않으면 무시
so	enum	No	정렬 순서. sb를 함께 보내지 않으면 무시
ci	long	No	이전 페이지의 cursor id
cv	object	No	이전 페이지의 cursor value
ct	enum	No	이전 페이지의 cursor type

Request

curl -X GET "https://drive.example.com/api/external/v1/resources?st=MY&ps=10" \
  -H "Authorization: Bearer replace-with-your-api-key"

리소스 단건 조회

GET /api/external/v1/resources/{resourceSeq}

파라미터	Type	필수	설명
resourceSeq	long	Yes	path 파라미터 - 조회할 리소스
ss	integer	No	공유 사용자 seq
d	boolean	No	true면 삭제된 리소스를 조회. 기본값은 false

이름 중복 확인

GET /api/external/v1/resources/exists

파라미터	Type	필수	설명
rn	string	Yes	확인할 리소스 이름
rt	enum	Yes	FILE 또는 FOLDER
pfs	long	No	부모 폴더 seq
ss	integer	No	공유 사용자 seq

이름이 이미 쓰이고 있으면 기존 리소스의 resourceSeq를 반환합니다.

폴더 트리 조회

GET /api/external/v1/resources/tree

호출자가 볼 수 있는 모든 폴더를 resourceSeq, resourceName, parentFolderSeq, resourceType의 평면 배열로 반환합니다. 트리는 parentFolderSeq로 구성하며, 상위가 null이면 최상위 폴더입니다.

공유 링크 조회

GET /api/external/v1/resources/{resourceSeq}/link

파라미터	Type	필수	설명
resourceSeq	long	Yes	path 파라미터 - 링크를 만들 리소스
ss	integer	No	공유 사용자 seq. 호출자가 공유를 만든 당사자가 아니면 필수

토큰이 포함된 공유 URL이 data.linkUrl로 반환됩니다.

여러 리소스를 한 번에 내려받기

리소스를 두 개 이상 내려받으려면 두 번 호출합니다. 먼저 토큰을 발급합니다.

POST /api/external/v1/resources/download-token

파라미터	Type	필수	설명
rl	array	Yes	내려받을 리소스 목록. 각 항목은 ss와 rs를 가진 객체

Request

curl -X POST "https://drive.example.com/api/external/v1/resources/download-token" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"rl": [{"ss": 41, "rs": 25068}, {"ss": 41, "rs": 25013}]}'

그다음 반환된 경로로 브라우저를 보내면 ZIP 아카이브가 스트리밍됩니다.

GET /api/external/v1/resources/download?dt={dt}

리소스 잠금과 잠금 해제

PATCH /api/external/v1/resources/{resourceSeq}/lock
PATCH /api/external/v1/resources/{resourceSeq}/unlock

파라미터	Type	필수	설명
resourceSeq	long	Yes	path 파라미터 - 잠그거나 풀 리소스
ss	integer	No	공유 사용자 seq. 호출자가 공유 소유자면 null

둘 다 Accept-Language 헤더를 선택적으로 받습니다. 잠금 또는 잠금 해제에 실패하면 RESOURCE_015를 반환합니다.

버전 이력

파일은 버전 이력을 유지합니다. 현재 리비전은 versionType이 CURRENT이고 resourceVersionSeq가 null이며, 이전 리비전은 HISTORY입니다.

버전 목록

GET /api/external/v1/resources/{resourceSeq}/versions

파라미터	Type	필수	설명
resourceSeq	long	Yes	path 파라미터 - 이력을 조회할 파일
pi	integer	Yes	페이지 번호, 최소 1
ps	integer	Yes	페이지 크기, 최소 1
ss	integer	No	공유 사용자 seq. 공유 파일이면 필수

각 항목은 versionNumber, sizeByte, versionType, versionRegisterDate와 그 버전을 만든 소유자·tenant를 알려줍니다.

버전 다운로드

GET /api/external/v1/resources/{resourceSeq}/versions/{resourceVersionSeq}/download-token
GET /api/external/v1/resources/{resourceSeq}/versions/download?dt={dt}

해당 버전의 토큰을 발급받은 뒤, 반환된 경로로 브라우저를 보내면 파일이 스트리밍됩니다.

버전 복원

api:write 필요

POST /api/external/v1/resources/{resourceSeq}/versions/{resourceVersionSeq}/restore

지정한 버전을 현재 버전으로 만들고 201 Created를 반환합니다. 복원 중 예기치 못한 오류가 나면 RESOURCE_VERSION_005를 반환합니다.

버전 삭제

api:write 필요

DELETE /api/external/v1/resources/{resourceSeq}/versions/{resourceVersionSeq}
DELETE /api/external/v1/resources/{resourceSeq}/versions

앞은 리비전 하나를, 뒤는 이력 전체를 삭제합니다. 둘 다 현재 리비전은 지우지 않습니다.

활동 내역

GET /api/external/v1/resources/{resourceSeq}/activities

아직 실제 데이터와 연결되지 않음

이 endpoint는 현재 리소스의 실제 활동이 아니라 고정된 샘플 payload를 반환합니다. 활동 저장소와 연결되기 전까지는 응답 형태에 의존해 개발하지 않습니다. 지금 증적이 필요한 활동 기록은 Governance integration을 참고합니다.

빌드 정보

아래 두 endpoint는 구동 중인 Thinkfree Drive 빌드를 알려줍니다. 공통 구조 없이 본문 객체를 그대로 반환하며, 두 scope 중 하나만 있어도 호출할 수 있습니다.

GET /api/external/v1/build
GET /api/external/v1/build/summary

Build response

{
  "applicationName": "Thinkfree-Drive",
  "buildFileName": "Thinkfree-Drive-1.5.0_202609140944",
  "version": "1.5.0",
  "profile": "prod",
  "buildTime": "2026-09-14 09:44"
}

Field	Type	의미
applicationName	string	항상 Thinkfree-Drive
buildFileName	string	애플리케이션 이름·버전·빌드 시각으로 구성된 빌드 산출물 이름
version	string	애플리케이션 버전
profile	string	구동 프로파일 - local, dev, stage, prod
buildTime	string	빌드 시각, yyyy-MM-dd HH:mm

GET /api/external/v1/build/summary는 같은 정보를 버전과 빌드 시각을 이어 붙인 표기용 문자열 하나로 buildInfo에 담아 반환합니다.