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 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.

Starred and recent registration do 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-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

The list is always ordered by most recently touched; there is no sort parameter. Registering an entry requires api:write and takes rs for the resource and ss for the sharing user when the resource is shared.

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
sd	date	No	Start of the modified-date range; ignored unless ed is also sent
ed	date	No	End of the modified-date range; ignored unless sd 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

Entries carry the resource fields plus recentSeq, isStarred, shareSeq, and resourceLocation, which is MY for your own drive and SHARE for something shared with you.

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

Starring takes rs for the resource and ss for the sharing user when the resource is shared. Removing takes the starredSeq from the list, not the resourceSeq. A failed removal returns STARRED_001.

The list accepts the same filters as recent documents, and additionally sb and so for sorting by name, size, or update. Default order is by name ascending.

Trash

Deleting a file or folder moves it here rather than removing it.

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 and permanent deletion require api:write

The listing defaults to most recently deleted first and accepts ps, rt, ft, ci, cv, ct, sd and ed for the deletion-date range, di for the account that deleted the item, and sb with so to sort by name, size, or register. Each entry carries a trashSeq, the original parentFolderSeq and parentFolderName, and who deleted it.

Restoring takes one body parameter:

Parameter	Type	Required	Description
pe	boolean	Yes	Whether the original parent folder still exists

pe is trusted, not verified

The server does not check pe against the actual state of the parent folder. Sending a value that does not match reality restores the resource to the wrong place - the original parent or the drive root - and still reports success. Read the current state of parentFolderSeq before restoring, and set pe from that.

A failed restore returns RESOURCE_009. Permanently deleting a folder that cannot be removed returns TRASH_001, and a failed empty returns TRASH_CLEAN_UP_001. Permanent deletion and emptying cannot be undone.

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 internal equivalents let an anonymous share-link visitor read office and global settings. The external endpoints documented here do not; a valid API Key is always required.

Errors

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