Users API

Everything scoped to the signed-in account: the profile behind the API Key, its storage quota, its password, and the per-user collections - recent, starred, trash, and notifications - plus the tenant configuration a client needs to render correctly. For administering other people's accounts, see Admin.

Base URL and scope

/api/external/v1/users
/api/external/v1/recent
/api/external/v1/starred
/api/external/v1/trash
/api/external/v1/notifications
/api/external/v1/config

Read scope is enough for most writes here

Only the trash, starred, and recent write operations require api:write. Everything under users, notifications, and config is reachable with a key that holds only api:read - including changing a password, updating the profile, and marking notifications read. Do not treat an api:read key as read-only.

Registering a recent document, adding and removing a star, and the five trash write operations require api:write.

Read your account

GET /api/external/v1/users

Returns the account the API Key represents.

Field	Type	Meaning
`userSeq`	integer	Account identifier
`userId`	string	Account id, an email address
`userName`	string	Display name
`status`	enum	Account status, such as `ACTIVE`
`isActive`	boolean	Whether the account is usable
`roleType`	enum	Role, such as `USER`
`totalQuotaByte`	long	Storage allowance in bytes
`useQuotaByte`	long	Storage used in bytes
`userLanguage`	string	Language preference - `ko`, `en`, or `auto`
`countryCode`	string	Country dialing code
`phoneNumber`	string	Phone number
`defaultLandingPage`	string	Start screen - `home` or `my-drive`
`profileImageKey`	string	Storage key of the profile image, or `null`
`tenantSeq`	integer	Tenant the account belongs to

Update your profile

PATCH /api/external/v1/users

Send as multipart/form-data.

Parameter	Type	Required	Description
`ul`	string	Yes	Language preference - `ko`, `en`, or `auto`
`dlp`	string	Yes	Start screen - `home` or `my-drive`
`pn`	string	No	Phone number
`ct`	string	No	Country dialing code
`pif`	file	No	Profile image
`dpi`	boolean	No	Delete the existing profile image
`sk`	string	No	Storage key

Update profile
curl -X PATCH "https://drive.example.com/api/external/v1/users" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -F "pn=010-1111-2222" \
  -F "ul=ko" \
  -F "dlp=my-drive" \
  -F "ct=82" \
  -F "dpi=false" \
  -F "pif=@profile.png"

A failed image upload returns USER_007; a failed image deletion returns USER_015.

Profile images

GET /api/external/v1/users/profile-image
GET /api/external/v1/users/{userSeq}/profile-image
GET /api/external/v1/users/anonymous-profile-image

The first returns your own image, the second returns another user's, and the third generates a placeholder avatar. All three stream the image rather than returning JSON. A missing image returns USER_008.

The placeholder takes two required integers, animal and color, both in the range 1 to 30.

Out-of-range values return a server error

The server does not validate animal and color. A value outside 1 to 30 fails with RESPONSE_001 and HTTP 500 rather than a validation error. Clamp the values before calling.

Check whether an account id is taken

GET /api/external/v1/users/exists

Parameter	Type	Required	Description
`userId`	string	Yes	Account id to check

An available id returns success. An id already in use returns USER_004 with HTTP 409 - the check reports "taken" as a failure response, not as a boolean in a successful one.

Find users

GET /api/external/v1/users/search

Parameter	Type	Required	Description
`sk`	string	Yes	Search keyword matched against account id and display name

Returns matching accounts with their id, name, status, and tenant. To find users for a specific share instead, use the share user search in Shares.

Storage quota

GET /api/external/v1/users/quota

Returns totalQuotaByte, useQuotaByte, and hasUnread, which reports whether the account has unread notifications.

Change your password

PATCH /api/external/v1/users/password

Parameter	Type	Required	Description
`currentPwd`	string	Yes	Current password
`newPwd`	string	Yes	New password

A wrong current password returns USER_009; reusing the previous password returns USER_010.

Password reset by email

Three endpoints send and consume a reset link.

POST /api/external/v1/users/password/reset-link/me
POST /api/external/v1/users/password/reset-link
GET  /api/external/v1/users/password/reset-link/verify
POST /api/external/v1/users/password/reset-link/confirm

The first sends a reset link to the API Key's own account and takes no parameters.

The second endpoint targets any account

POST /password/reset-link sends the reset email to whatever userId the request body names, not to the key's own account. A key holder can trigger a password reset email for another user. Use /reset-link/me unless you deliberately need to reset someone else's password, and restrict which of your callers can reach this endpoint. An unknown userId returns USER_005.

Parameter	Type	Required	Description
`userId`	string	Yes	Account to send the reset link to; body of `POST /password/reset-link`
`token`	string	Yes	Reset token; query parameter of `verify`, body field of `confirm`
`newPwd`	string	Yes	New password; body of `confirm`

verify reports whether a token is still usable: an unrecognized token returns USER_022 and an expired one returns USER_023.

Close your account

PATCH /api/external/v1/users/{userSeq}

This endpoint does nothing today

The account-closure logic is disabled. The call returns success for any userSeq without changing the account's state. Do not rely on it to close accounts, and do not treat its success response as confirmation.

Security log

GET /api/external/v1/users/log

Lists sign-in, sign-out, and password-change events for your own account.

Parameter	Type	Required	Description
`ps`	integer	Yes	Number of entries to return
`ci`	long	No	Cursor - the last `userLogSeq` of the previous page

Each entry reports activityType, ipAddress, region, and registerDate.

Recent documents

GET  /api/external/v1/recent
POST /api/external/v1/recent

Register a recent document

Registering requires api:write. The body takes rs for the resource, and ss for the sharing user when the resource is shared (null or omitted otherwise). A shared resource can be registered only with view (VIEW) permission.

Registering a resource that is already in the list does not fail: it moves its recentUpdateDate to the current time and always returns 201 Created. Call it each time a document is opened to move that document to the top of the list.

Request
curl -X POST "https://drive.example.com/api/external/v1/recent" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"rs": 224, "ss": 1}'

Register response
{
  "result": true,
  "code": 201,
  "message": "Created"
}

List recent documents

The list is always ordered by last-used time (recentUpdateDate) descending, then resourceSeq descending; there is no sort parameter. Unlike the other lists, folders are not placed ahead of files - files and folders are mixed in last-used order.

Parameter	Type	Required	Description
`ps`	integer	Yes	Page size, minimum `1`
`rt`	enum	No	`FILE` or `FOLDER`
`ft`	enum	No	File type - `document`, `spreadsheet`, `presentation`, `pdf`, `image`, `note`
`oi`	string	No	Owner id, up to 254 characters; exact match only, not a partial match
`sd`	date	No	Start of the last-used range (`recentUpdateDate`, `YYYY-MM-DD`); ignored unless `ed` is also sent
`ed`	date	No	End of the last-used range (`recentUpdateDate`, `YYYY-MM-DD`); ignored unless `sd` is also sent
`ci`	long	No	Cursor - `nextCursor` from the previous response; `null` for the first page
`cv`	object	No	Cursor value - `nextCursorValue` from the previous response, the last entry's `recentUpdateDate`
`ct`	enum	No	Accepted but not used

sd and ed filter on when you last opened or registered the resource, not on when the resource was modified.

Request
curl -X GET "https://drive.example.com/api/external/v1/recent?ps=10" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY"

Each entry carries the resource fields - owner (owner*), path (fullPathSeq, fullPath), sizeByte, isLocked, and the register and update users and dates (resourceRegister*, resourceUpdate*) - plus recentSeq, recentRegisterDate, recentUpdateDate, isStarred, starredSeq, the share fields isShared, shareSeq, shareResourceSeq, and shareTargetSeq, the permission flags canView, canEdit, canDownload, canUpload, canDelete, and canShare, and resourceLocation, which is MY for your own drive and SHARE for something shared with you - 41 fields in all.

When hasNext is true, the response also carries nextCursor and nextCursorValue; send them as ci and cv for the next page. The next page is decided by those two values alone, and no nextCursorType is returned.

Next page fields
{
  "pageSize": 2,
  "nextCursor": 40004,
  "nextCursorValue": "2026-05-12T13:15:29",
  "hasNext": true
}

Failure
{
  "result": false,
  "code": 400,
  "errorCode": "REQUEST_001",
  "message": "[{field=ps, msg=필수 입력값 입니다.}]"
}

Code	Status	When
`REQUEST_001`	400	A request value fails validation, such as a missing `ps`
`PERMISSION_001`	403	Registering a resource that is not shared with you
`PERMISSION_002`	403	Registering a shared resource without view permission
`RESOURCE_005`	404	The resource does not exist
`RESPONSE_001`	500	Server error

Starred documents

GET    /api/external/v1/starred
POST   /api/external/v1/starred
DELETE /api/external/v1/starred/{starredSeq}

Adding and removing a star requires api:write

Star a resource

The body takes rs for the resource, and ss for the sharing user when the resource is shared (null or omitted otherwise). A shared resource can be starred only with view (VIEW) permission. Starring a resource that is already starred fails with STARRED_002. On success the response is 201 Created with data.starredSeq, the value you pass to remove the star.

Request
curl -X POST "https://drive.example.com/api/external/v1/starred" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"rs": 48, "ss": 1}'

Star response
{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "starredSeq": 2501
  }
}

Failure
{
  "result": false,
  "code": 409,
  "errorCode": "STARRED_002",
  "message": "이미 중요문서함에 등록된 리소스입니다."
}

Remove a star

Removing takes the starredSeq from the star response or the list, not the resourceSeq. Only entries you starred yourself can be removed; a starredSeq that does not exist or belongs to someone else fails with STARRED_001.

Request
curl -X DELETE "https://drive.example.com/api/external/v1/starred/{starredSeq}" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY"

Failure
{
  "result": false,
  "code": 400,
  "errorCode": "STARRED_001",
  "message": "삭제에 실패 했습니다."
}

List starred documents

Default order is by name ascending. Whatever the sort, folders always come before files, and the sort applies within each group.

Parameter	Type	Required	Description
`ps`	integer	Yes	Page size, minimum `1`
`rt`	enum	No	`FILE` or `FOLDER`
`ft`	enum	No	File type - `document`, `spreadsheet`, `presentation`, `pdf`, `image`, `note`
`oi`	string	No	Owner id, up to 254 characters; exact match only, not a partial match
`sd`	date	No	Start of the resource modified-date range (`YYYY-MM-DD`); ignored unless `ed` is also sent
`ed`	date	No	End of the resource modified-date range (`YYYY-MM-DD`); ignored unless `sd` is also sent
`sb`	enum	No	Sort key - `name`, `size`, or `update`; ignored unless `so` is also sent
`so`	enum	No	`asc` or `desc`; ignored unless `sb` is also sent
`ci`	long	No	Cursor - `nextCursor` from the previous response; `null` for the first page
`cv`	object	No	Cursor value - `nextCursorValue` from the previous response
`ct`	enum	No	Cursor type - `nextCursorType` from the previous response, `FILE` or `FOLDER`

The parameter names match recent documents, but sd and ed here filter on the resource's modified date, and ct is used.

Request
curl -X GET "https://drive.example.com/api/external/v1/starred?ps=10" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY"

Each entry carries the resource fields plus starredSeq, starredRegisterDate, the share fields isShared, shareSeq, shareResourceSeq, and shareTargetSeq, the permission flags canView, canEdit, canDownload, canUpload, canDelete, and canShare, and resourceLocation (MY or SHARE) - 39 fields in all.

When hasNext is true, the response also carries nextCursor (the last resourceSeq), nextCursorValue (the last entry's sort value), and nextCursorType (the last resourceType); send them as ci, cv, and ct for the next page.

Next page fields
{
  "pageSize": 2,
  "nextCursor": 40002,
  "nextCursorValue": "sample.pptx",
  "nextCursorType": "FILE",
  "hasNext": true
}

Code	Status	When
`REQUEST_001`	400	A request value fails validation, such as a missing `ps`
`STARRED_001`	400	Removing a star fails, including a `starredSeq` that is missing or not yours
`PERMISSION_001`	403	Starring a resource that is not shared with you
`PERMISSION_002`	403	Starring a shared resource without view permission
`RESOURCE_005`	404	The resource does not exist
`STARRED_002`	409	The resource is already starred
`RESPONSE_001`	500	Server error

Trash

Deleting a file or folder moves it here rather than removing it. Every trash endpoint acts only on the API Key owner's own trash entries; a resource that is not in the trash, or is not your entry, fails with RESOURCE_005.

GET    /api/external/v1/trash
PATCH  /api/external/v1/trash/files/{resourceSeq}/restore
PATCH  /api/external/v1/trash/folders/{resourceSeq}/restore
DELETE /api/external/v1/trash/files/{resourceSeq}
DELETE /api/external/v1/trash/folders/{resourceSeq}
DELETE /api/external/v1/trash/empty

Restoring, permanent deletion, and emptying require api:write

All five write endpoints - both restores, both permanent deletions, and emptying the trash - require api:write.

List the trash

Default order is by deletion date, most recent first.

Parameter	Type	Required	Description
`ps`	integer	Yes	Page size, minimum `1`
`rt`	enum	No	`FILE` or `FOLDER`
`ft`	enum	No	File type - `document`, `spreadsheet`, `presentation`, `pdf`, `image`, `note`
`di`	string	No	Id of the account that deleted the item, up to 254 characters; exact match only, not a partial match
`sd`	date	No	Start of the deletion-date range (`YYYY-MM-DD`); ignored unless `ed` is also sent
`ed`	date	No	End of the deletion-date range (`YYYY-MM-DD`); ignored unless `sd` is also sent
`sb`	enum	No	Sort key - `name`, `size`, or `register` (deletion date); ignored unless `so` is also sent
`so`	enum	No	`asc` or `desc`; ignored unless `sb` is also sent
`ci`	long	No	Cursor - `nextCursor` from the previous response; `null` for the first page
`cv`	object	No	Cursor value - `nextCursorValue` from the previous response
`ct`	enum	No	Cursor type - `nextCursorType` from the previous response, `FILE` or `FOLDER`

Request
curl -X GET "https://drive.example.com/api/external/v1/trash?ps=10" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY"

Each entry carries trashSeq, resourceSeq, userSeq, the owner (ownerSeq, ownerId, ownerName, ownerStatus, ownerTenantSeq, ownerTenantName), resourceType, resourceName, the original location (parentFolderSeq, parentFolderName, fullPathSeq, fullPath), sizeByte, isLocked, the register and update users and dates (resourceRegister*, resourceUpdate*), the user who deleted it (deleteUserSeq, deleteUserId, deleteUserName, deleteUserTenantSeq, deleteUserTenantName, deleteUserStatus), and deleteDate - 32 fields in all.

Next page fields
{
  "pageSize": 1,
  "nextCursor": 40048,
  "nextCursorValue": "2026-06-01T16:54:59",
  "nextCursorType": "FILE",
  "hasNext": true
}

Failure
{
  "result": false,
  "code": 400,
  "errorCode": "REQUEST_001",
  "message": "[{field=ps, msg=필수 입력값 입니다.}]"
}

Restore a file or folder

PATCH /trash/files/{resourceSeq}/restore and PATCH /trash/folders/{resourceSeq}/restore take one body parameter:

Parameter	Type	Required	Description
`pe`	boolean	Yes	`true` restores to the original parent folder; `false` restores to the drive root

If an item with the same name already exists where the resource is restored, the restored resource gets a numbered name. On success the response is 200 OK with no data.

pe decides the location

pe=true restores to the original parent folder, and fails with RESOURCE_005 if that folder has been deleted or no longer exists. pe=false restores to the drive root without error, even when the original parent folder still exists. Read the current state of parentFolderSeq before restoring, and set pe from that.

Request
curl -X PATCH "https://drive.example.com/api/external/v1/trash/files/{resourceSeq}/restore" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"pe": true}'

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

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

Delete permanently and empty the trash

DELETE /trash/files/{resourceSeq} and DELETE /trash/folders/{resourceSeq} delete one entry permanently; DELETE /trash/empty deletes every entry in your trash. On success each returns 200 OK. Permanent deletion and emptying cannot be undone.

Request
curl -X DELETE "https://drive.example.com/api/external/v1/trash/files/{resourceSeq}" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY"

Failure
{
  "result": false,
  "code": 400,
  "errorCode": "TRASH_001",
  "message": "삭제에 실패 했습니다."
}

Request
curl -X DELETE "https://drive.example.com/api/external/v1/trash/empty" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY"

Failure
{
  "result": false,
  "code": 400,
  "errorCode": "TRASH_CLEAN_UP_001",
  "message": "삭제에 실패 했습니다."
}

Code	Status	When
`REQUEST_001`	400	A request value fails validation, such as a missing `ps` or `pe`
`RESOURCE_009`	400	Restoring fails
`TRASH_001`	400	Permanently deleting a file or folder fails
`TRASH_CLEAN_UP_001`	400	Emptying the trash fails
`RESOURCE_005`	404	The resource is not in your trash, or `pe=true` and the original parent folder no longer exists
`RESPONSE_001`	500	Server error

Notifications

GET   /api/external/v1/notifications
GET   /api/external/v1/notifications/unread-count
PATCH /api/external/v1/notifications/read-all
PATCH /api/external/v1/notifications/{notificationSeq}/read
PATCH /api/external/v1/notifications/{notificationSeq}/unread

All five are limited to the API Key owner's own notifications. Naming another user's notificationSeq updates nothing and fails with NOTIFICATION_002 or NOTIFICATION_003, which is the same response you get for a notificationSeq that does not exist.

Parameter	Type	Required	Description
`ps`	integer	Yes	Page size, minimum `1`; a missing or smaller value returns `REQUEST_001`
`ci`	long	No	Cursor - `nextCursor` from the previous response
`ir`	boolean	No	`true` for read only, `false` for unread only; omit for both

The list is always ordered by notificationSeq descending, so the page cursor is a single value and no nextCursorValue or nextCursorType is returned. Notifications raised by deleted or inactive users are left out, and resourceType, resourceSeq, and resourceName can be null when the resource has been deleted.

The shape of description depends on actionType:

`actionType`	`description` fields	Meaning
`SHARED`	`userName`, `fileName`, `tenantSeq`, `tenantName`	A resource was shared with you
`UNSHARED`	`userName`, `fileName`, `tenantSeq`, `tenantName`	A share was removed
`FILE_UPLOAD`	`userName`, `folderName`, `fileName`	Someone uploaded into a shared folder
`STORAGE_WARNING`	`usagePercentage`	Storage is filling up
`STORAGE_EXCEEDED`	`exceeded`	Storage allowance is exhausted

Marking one notification read or unread returns the resulting unreadCount. read-all succeeds even when there was nothing to mark, and does not return a count.

Tenant configuration

Read-only settings a client needs in order to render correctly. The tenant comes from the API Key and must match the tenant of the request host, otherwise the call fails with REQUEST_006.

GET /api/external/v1/config
GET /api/external/v1/config/file-size-limit
GET /api/external/v1/config/office

GET /config returns intellectStatus, shareStatus, and tenantCount. shareStatus reflects the global setting when a super administrator is enforcing one, and the tenant setting otherwise.

GET /config/file-size-limit returns maxFileUploadSize in bytes. When uploads are unlimited or no limit is configured, the field is omitted entirely and data is an empty object - check for the field's presence rather than comparing to a value.

GET /config/office returns officeDomain and officeAdapterName. When either is unset, the call fails with SYSTEM_CONFIG_003 rather than returning partial data.

These endpoints always require a key

The Drive web app lets an anonymous share-link visitor read Office and global settings, but the endpoints on this page do not allow anonymous access. A valid API Key is always required.

Errors

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

Base URL and scope​

Read your account​

Update your profile​

Profile images​

Check whether an account id is taken​

Find users​

Storage quota​

Change your password​

Password reset by email​

Close your account​

Security log​

Recent documents​

Register a recent document​

List recent documents​

Starred documents​

Star a resource​

Remove a star​

List starred documents​

Trash​

List the trash​

Restore a file or folder​

Delete permanently and empty the trash​

Notifications​

Tenant configuration​

Errors​