Files API

Operations on a single file. Files and folders share the resource model, the listing endpoint, version history, and locking described in Common conventions; this page covers what applies to files only.

Base URL and scope

/api/external/v1/files

Read operations need api:read. Upload, delete, rename, move, and copy additionally need api:write.

Download a file

GET /api/external/v1/files/{resourceSeq}/download

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the file to download
ss	integer	No	Sharing user seq

Request

curl -X GET "https://drive.example.com/api/external/v1/files/{resourceSeq}/download?ss=21" \
  -H "Authorization: Bearer replace-with-your-api-key"

On success the response is the file itself, not the JSON envelope:

HTTP 200 OK
Content-Type: {contentType}
Content-Disposition: attachment; filename={fileName}

Download through the browser

When the download should be performed by the user's browser rather than your server, issue a short-lived token first and hand the returned path to the browser. The token carries the authorization, so the second request needs no Authorization header.

GET /api/external/v1/files/{resourceSeq}/download-token

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the file to download
ss	integer	No	Sharing user seq

Token response

{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": {
    "linkUrl": "/files/download?dt={token}"
  }
}

Then:

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

To download several resources in one archive, use the multi-resource download described in Common conventions.

Preview a file

GET /api/external/v1/files/{resourceSeq}/view

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the file to preview
ss	integer	No	Sharing user seq

Returns the rendered preview as a binary stream.

Upload a file

Requires api:write

POST /api/external/v1/files

Send the file as multipart/form-data.

Parameter	Type	Required	Description
file	file	Yes	The file to upload
pfs	long	No	Parent folder seq; required when a shared user uploads
ss	integer	No	Sharing user seq; null when uploading to your own drive
st	enum	No	Name-collision policy - duplicate adds a copy number and is the default, version adds a new version, overwrite replaces the file
rs	long	No	Target resource seq; required when st is version or overwrite

Request

curl -X POST "https://drive.example.com/api/external/v1/files" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@report.docx" \
  -F "pfs=1"

Upload response

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

Uploading beyond the account quota fails with RESOURCE_015.

Rename a file

Requires api:write

PATCH /api/external/v1/files/{resourceSeq}/rename

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the file to rename
rn	string	Yes	New name
ncp	enum	No	Name-collision policy - NONE rejects a duplicate name, AUTO appends a number
pfs	long	No	Parent folder seq; not used when ncp is AUTO
ss	integer	No	Sharing user seq

Request

curl -X PATCH "https://drive.example.com/api/external/v1/files/{resourceSeq}/rename" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ss": 21, "rn": "quarterly-report", "ncp": "AUTO"}'

The response returns the name that was actually applied in data.name, which differs from rn when AUTO resolved a collision.

Move a file

Requires api:write

POST /api/external/v1/files/{resourceSeq}/move

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the file to move
ts	integer	No	Target user seq; required when the caller did not create the share
pfs	long	No	Destination folder seq; required when the caller did not create the share
ss	integer	No	Sharing user seq

Request

curl -X POST "https://drive.example.com/api/external/v1/files/{resourceSeq}/move" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ts": 1, "pfs": 367}'

Copy a file

Requires api:write

POST /api/external/v1/files/{resourceSeq}/copy

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the file to copy
ts	integer	No	User seq to copy to; null when the caller provides the share
pfs	long	No	Destination folder seq; required when it differs from the sharing user
ss	integer	No	Sharing user seq; null when the caller provides the share

Accepts an optional Accept-Language header. Returns 201 Created with the new resourceSeq. Copying beyond the account quota fails with RESOURCE_015.

Delete a file

Requires api:write

PATCH /api/external/v1/files/{resourceSeq}/delete

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the file to delete

The file moves to the trash rather than being removed. See Users for listing, restoring, and permanently deleting trashed items.

Create a new Office document

Requires api:write

Creates an empty Word, Spreadsheet, Presentation, or note document from a built-in template, without uploading a file.

POST /api/external/v1/documents

Parameter	Type	Required	Description
tt	enum	Yes	Template type - word, excel, ppt, or note
pfs	long	No	Parent folder seq; required for a shared resource
ss	integer	No	Sharing user seq; null when creating in your own drive

The Accept-Language header selects the template language. Korean and US English templates are available today.

Request

curl -X POST "https://drive.example.com/api/external/v1/documents" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ss": 21, "pfs": 5, "tt": "word"}'

Create response

{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "resourceSeq": 4699,
    "userSeq": 1
  }
}

Creating beyond the account quota fails with QUOTA_003; calling without access to the target folder fails with PERMISSION_002.

Editor session endpoints

The web-office endpoints back a browser editing session: the editor reads document metadata, fetches the file, locks it while editing, writes it back, and unlocks it. Use them when you host the Thinkfree editor yourself. For embedding an editor through a supported SDK instead, see Editor SDK.

GET  /api/external/v1/web-office/{loginUserSeq}/info
GET  /api/external/v1/web-office/{loginUserSeq}/get
POST /api/external/v1/web-office/{loginUserSeq}/lock
PUT  /api/external/v1/web-office/{loginUserSeq}/put
POST /api/external/v1/web-office/{loginUserSeq}/unlock

The caller chooses the acting user

loginUserSeq is supplied by the caller, not derived from the API Key. The server checks only that the named user belongs to the same tenant as the key - it does not check that the user matches the key's own account. Any key holder can therefore act as any user in that tenant through these endpoints. Treat a key that can reach them as a tenant-wide credential, and do not pass a browser-supplied loginUserSeq through without deciding server-side who the caller is allowed to act as.

These endpoints skip the scope check

All five are exempt from the scope check because they serve the editor session flow. A key holding only api:read can call lock, put, and unlock, which change stored content.

Common parameters

Parameter	Type	Required	Description
loginUserSeq	long	Yes	Path parameter - the user the session acts as
docId	string	Yes	Document identifier, formed as the sharing user seq and resource seq joined by a hyphen
app	enum	Yes	Editor surface, such as WORD_EDITOR, CELL_VIEWER, or SHOW_WATCHER; required by info, get, and put
user_id	string	Yes	Signed-in account name; required by info, get, and put
lang	string	No	Session language, such as ko_KR

The app value names both the application and the mode. Applications are WORD, CELL, SHOW, HWP, and PDF; modes are EDITOR, VIEWER, and WATCHER.

Read document metadata

GET /api/external/v1/web-office/{loginUserSeq}/info

Returns an XML document, not JSON, describing the file name, size, revision, permissions, lock state, and the collaborator cursor name and color.

Request

curl -X GET "https://drive.example.com/api/external/v1/web-office/{loginUserSeq}/info?app=WORD_EDITOR&user_id={user_id}&docId=21-512&lang=ko_KR" \
  -H "Authorization: Bearer replace-with-your-api-key"

A resource that is not shared with the named user fails with SHARE_001.

Fetch and store the document

GET /api/external/v1/web-office/{loginUserSeq}/get
PUT /api/external/v1/web-office/{loginUserSeq}/put

get streams the file as application/octet-stream. put uploads the replacement body as application/octet-stream and returns the docId as plain text.

Parameter	Type	Required	Description
size	long	Yes	Size of the uploaded document in bytes; put only
type	enum	No	Save reason - save, saveAs, autoSave, autoPut after an abnormal session end, or close; may be absent
openTimestamp	string	No	Accepted but currently unused

Lock and unlock the document

POST /api/external/v1/web-office/{loginUserSeq}/lock
POST /api/external/v1/web-office/{loginUserSeq}/unlock

Both take docId and return 200 OK with no body.

Plain-text failures

Unlike every other endpoint in this reference, a failed lock or unlock returns a plain-text message with no JSON envelope and no errorCode. A permission failure on any web-office endpoint is also returned as plain text with HTTP 403. Parse these by status code, not by response body.

Errors

See Errors for the full list of codes these endpoints return.