Common conventions

Every Document Management API request shares the same base path, authentication header, scope check, and response envelope. Read this page once, then use the endpoint pages for the operations you need.

Base URL

All endpoints described in this reference live under one prefix:

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

drive.example.com is a placeholder. Replace it with your own tenant's host - your Thinkfree Drive deployment, at the subdomain assigned to your tenant. Endpoint pages show paths relative to this prefix.

Authentication

Authenticate every request with an API Key sent as a bearer token:

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

An administrator creates keys from the API Key screen in the Thinkfree Drive admin area. See Authentication for how keys are created, listed, and revoked through the API.

Server-side secret

Keep the API Key in a server-side secret store. Never put it in browser JavaScript, a mobile binary, a URL, source control, or logs. Revoke a key immediately if it may have been exposed.

The key is bound to a tenant. When the tenant that owns the key does not match the tenant of the request host, the request fails with REQUEST_006.

Scopes

Each API Key carries one or both of two scopes. The scope is checked before the endpoint runs.

Scope	Grants
api:read	Read operations - listing, retrieving, searching, downloading
api:write	Write operations - upload, rename, move, copy, delete, restore, and settings changes

A write endpoint requires api:write in addition to api:read. Endpoint pages mark every operation that needs api:write.

Keys also carry mcp:read and mcp:write for MCP access, and only two scope combinations can be issued. See Authentication for the full model.

Not every endpoint group checks scope

The admins and super-admin trees, and the users, notifications, config, web-office, pinned-folders, and API Key management endpoints, perform no scope check beyond the shared gate. A key holding only api:read can write through those. Decide access by who holds which key rather than by scope alone.

Response envelope

Success

Most endpoints wrap the payload in a common envelope. The endpoint-specific payload is nested under data, which is omitted when the operation returns nothing.

Field	Type	Required	Meaning
result	boolean	Yes	true on success
code	integer	Yes	HTTP status code of the result, such as 200 or 201
message	string	Yes	Short status text, such as OK or Created
data	object or array	No	Endpoint payload; omitted when there is nothing to return

Success with payload

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

Success without payload

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

Failure

Field	Type	Meaning
result	boolean	false
code	integer	HTTP status code
errorCode	string	Stable symbolic error code such as RESOURCE_005
message	string	Human-readable failure text

Failure

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

Match on errorCode, not on message. Message text is localized and can change. See Errors for the full code list.

Endpoints without the envelope

The build endpoints described at the end of this page return the body object directly, with no result or data wrapper. Their failure responses still use the common failure envelope. No other endpoint group behaves this way.

Dates

Request parameters that take a date, such as sd and ed, use YYYY-MM-DD. Timestamps in responses, such as resourceRegisterDate and resourceUpdateDate, use YYYY-MM-DD HH:mm:ss.SSS.

Short parameter names

Query and body parameters use short names throughout this API. The same name always means the same thing:

Name	Type	Meaning
ss	integer	Sharing user seq. Required when the caller is not the owner of the shared resource; null when the caller owns it
ts	integer	Target user seq for a move or copy
rs	long	Resource seq, used when a resource is referenced in a request body
pfs	long	Parent folder seq
rn	string	Resource name
rt	enum	Resource type - FILE or FOLDER
sk	string	Search keyword matched against file and folder names
sb	enum	Sort field - name, size, update, open
so	enum	Sort order - asc, desc
pi	integer	Page index, minimum 1
ps	integer	Page size, minimum 1
ci	long	Cursor id - the last resourceSeq of the previous page
cv	object	Cursor value - the sort-field value of the last item of the previous page
ct	enum	Cursor type - the resourceType of the last item of the previous page
dt	string	Download token issued by a download-token endpoint

Pagination

Two pagination styles appear in this API.

Cursor pagination is used for resource listings. Send ps for the page size, omit the cursor parameters on the first request, then send ci, cv, and ct from the previous response to fetch the next page. sb and so must be sent together, and default to name ascending when omitted.

Cursor page response

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

Index pagination is used for version history and most administrative listings. Send pi and ps; the response reports totalCount, pageIndex, and pageSize.

Resource model

Files and folders are both resources, identified by a resourceSeq and distinguished by resourceType. A resource listing returns the same shape for both.

Field	Type	Meaning
resourceSeq	long	Stable identifier of the file or folder
resourceType	enum	FILE or FOLDER
parentFolderSeq	long	Containing folder; null at the drive root
resourceName	string	File or folder name
ownerId	string	Account id of the owner
sizeByte	long	Size in bytes; null for a folder
isShared	boolean	Whether the resource is shared
isLocked	boolean	Whether the resource is locked for editing
canView	boolean	Whether the calling account may open the resource
canEdit	boolean	Whether the calling account may modify the resource
canDownload	boolean	Whether the calling account may download the resource
canDelete	boolean	Whether the calling account may delete the resource
canShare	boolean	Whether the calling account may share the resource
resourceRegisterDate	string	Creation timestamp
resourceUpdateDate	string	Last modification timestamp

Resource operations

These operations apply to files and folders alike.

List resources

GET /api/external/v1/resources

Parameter	Type	Required	Description
st	enum	Yes	Search scope - MY for the caller's drive, ALL for everything visible
ps	integer	Yes	Page size, minimum 1
ss	integer	No	Sharing user seq; not applied when st is ALL
sk	string	No	Name search keyword
pfs	long	No	Parent folder seq; required when a shared user calls
rt	enum	No	FILE or FOLDER
oi	string	No	Owner id, up to 254 characters
sd	date	No	Start of the modified-date range, YYYY-MM-DD; ignored unless ed is also sent
ed	date	No	End of the modified-date range, YYYY-MM-DD; ignored unless sd is also sent
ft	enum	No	File type - document, spreadsheet, presentation, pdf, image, note
sb	enum	No	Sort field; ignored unless so is also sent
so	enum	No	Sort order; ignored unless sb is also sent
ci	long	No	Cursor id from the previous page
cv	object	No	Cursor value from the previous page
ct	enum	No	Cursor type from the previous page

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 one resource

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

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the resource to read
ss	integer	No	Sharing user seq
d	boolean	No	Read a deleted resource when true; defaults to false

Check whether a name is taken

GET /api/external/v1/resources/exists

Parameter	Type	Required	Description
rn	string	Yes	Resource name to check
rt	enum	Yes	FILE or FOLDER
pfs	long	No	Parent folder seq
ss	integer	No	Sharing user seq

Returns the resourceSeq of the existing resource when the name is taken.

Get the folder tree

GET /api/external/v1/resources/tree

Returns every folder the caller can see as a flat array of resourceSeq, resourceName, parentFolderSeq, and resourceType. Build the tree from parentFolderSeq; a null parent is a root folder.

Get a share link

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

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the resource to link
ss	integer	No	Sharing user seq; required when the caller did not create the share

Returns data.linkUrl containing a tokenized share URL.

Download several resources as one archive

Downloading more than one resource takes two calls. First issue a token:

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

Parameter	Type	Required	Description
rl	array	Yes	Resources to include, each an object of ss and 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}]}'

Then send the browser to the returned path, which streams a ZIP archive:

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

Lock and unlock a resource

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

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the resource to lock or unlock
ss	integer	No	Sharing user seq; null when the caller owns the share

Both accept an optional Accept-Language header. A failed lock or unlock returns RESOURCE_015.

Version history

A file keeps a version history. The current revision is reported with a versionType of CURRENT and a null resourceVersionSeq; earlier revisions are HISTORY.

List versions

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

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the file to read history for
pi	integer	Yes	Page index, minimum 1
ps	integer	Yes	Page size, minimum 1
ss	integer	No	Sharing user seq; required for a shared file

Each entry reports versionNumber, sizeByte, versionType, versionRegisterDate, and the owner and tenant that produced it.

Download a version

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

Issue a token for the version, then send the browser to the returned path to stream the file.

Restore a version

Requires api:write

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

Makes the named version current and returns 201 Created. An unexpected failure during restore returns RESOURCE_VERSION_005.

Delete versions

Requires api:write

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

The first deletes one revision, the second deletes the whole history. Neither removes the current revision.

Activity log

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

Not backed by real data yet

This endpoint currently returns a fixed sample payload rather than the resource's real activity. Do not build on its response shape until it is connected to the activity store. For an evidenced activity record today, see Governance integration.

Build information

These two endpoints report the running Thinkfree Drive build. They return the body object directly, with no envelope. Either scope is enough to call them.

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	Meaning
applicationName	string	Always Thinkfree-Drive
buildFileName	string	Build artifact name, composed of the application name, version, and build timestamp
version	string	Application version
profile	string	Runtime profile - local, dev, stage, or prod
buildTime	string	Build time, yyyy-MM-dd HH:mm

GET /api/external/v1/build/summary returns the same information as a single display string in buildInfo, formatted as the version followed by the build timestamp.