Shares API

Share a file or folder, choose who can reach it, and set what each recipient may do. Two base paths are involved: shared lists what has been shared with you, and shares manages the shares you provide.

Base URL and scope

/api/external/v1/shared
/api/external/v1/shares

Listing, reading a share, searching users, and reading share types need api:read. Creating, changing, removing a share, and setting recipients additionally need api:write.

Share types

A share has one type, which decides who can reach the resource.

Type	Who can reach the resource
SPECIFIC_USERS	Only the users you name as recipients
ORG_LINK	Anyone inside the organization
PUBLIC_LINK	Anyone with the link

Every resource in the same hierarchy must use the same share type. Call the share-types endpoint before creating a share to find out which types the resource allows.

Permission flags

Permissions are five booleans. They appear at two levels: on the share row itself (cv to cs in the request body) and on each recipient in ts.

Flag	Permission
cv	View
ce	Edit
cd	Download
cu	Upload
cs	Re-share

• cv is the prerequisite for the others. If cv is false, the request fails with PERMISSION_003 regardless of the other values.
• For ORG_LINK and PUBLIC_LINK, the share-row permissions apply and all five must be sent. A missing flag fails with SHARE_009 on create and SHARE_005 (500) on change. A flag the share type does not allow, sent as true, fails with PERMISSION_005 (403).
• For SPECIFIC_USERS, the share-row permissions are neither used nor validated; only the per-recipient permissions apply.
• Per-recipient permissions are not limited by the share type, except that upload cannot be granted on a file.

In responses the same permissions appear under their long names: canView, canEdit, canDownload, canUpload, canDelete, and canShare.

List what is shared with you

GET /api/external/v1/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; matches the exact id, not a partial match
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
sb	enum	No	Sort field - name, size, update, open, share; 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

List shared

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

cv means two different things

As a query parameter on this endpoint, cv is the pagination cursor value. In a share request body, cv is the view permission. The two never appear in the same request.

Each entry reports the resource, its owner and tenant, when it was shared, your effective permissions, and who registered or last changed the share. It also carries isStarred and starredSeq, so a shared item can be starred like any other resource.

Without sb and so, entries are sorted by share time (share) descending. Folders always come before files, whatever the sort. When hasNext is true, the response carries nextCursor (the last resourceSeq), nextCursorValue (the value of the sort field), and nextCursorType (the resource type); send them as ci, cv, and ct on the next request. See Common conventions.

Read the share types a resource allows

GET /api/external/v1/shares/{resourceSeq}/share-types

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the resource to check
ss	integer	No	Owner seq; null when you own the resource

Share types response

{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": {
    "editable": true,
    "allowSpecificUsers": true,
    "allowOrgLink": true,
    "allowPublic": true,
    "shareTypes": [
      {
        "code": "SPECIFIC_USERS",
        "name": "특정 사용자만",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "SHARE", "VIEW"]
      },
      {
        "code": "ORG_LINK",
        "name": "조직 내부 공개",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "VIEW"]
      },
      {
        "code": "PUBLIC_LINK",
        "name": "전체 공개",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "VIEW"]
      }
    ]
  }
}

name is a fixed string and is not localized.

allowedPermissions is a fixed rule per share type and resource kind, not an administrator setting: upload is offered only on folders and never for PUBLIC_LINK, and re-share only for SPECIFIC_USERS. The example is for a file, so no type lists UPLOAD. This limit applies only to the share-row permissions of a link share, not to per-recipient permissions. What the tenant settings decide is allowSpecificUsers, allowOrgLink, and allowPublic.

Create a share

Requires api:write

Only the owner of the resource can create a share; for anyone else the request fails with RESOURCE_005. Read the allowed share types first.

POST /api/external/v1/shares

Parameter	Type	Required	Description
rs	long	Yes	The file or folder to share
st	enum	Yes	Share type - SPECIFIC_USERS, ORG_LINK, or PUBLIC_LINK
cv	boolean	No	View permission; must be true for ORG_LINK and PUBLIC_LINK
ce	boolean	No	Edit permission; required for ORG_LINK and PUBLIC_LINK
cd	boolean	No	Download permission; required for ORG_LINK and PUBLIC_LINK
cu	boolean	No	Upload permission; required for ORG_LINK and PUBLIC_LINK
cs	boolean	No	Re-share permission; required for ORG_LINK and PUBLIC_LINK
ts	array	No	Recipients; allowed with any share type if the tenant settings allow SPECIFIC_USERS (otherwise SHARE_011)

Each entry in ts names one recipient and their permissions:

Field	Type	Required	Description
us	integer	Yes	Recipient user seq
cv	boolean	Yes	View permission; must be true
ce	boolean	Yes	Edit permission
cd	boolean	Yes	Download permission
cu	boolean	Yes	Upload permission
cs	boolean	Yes	Re-share permission
se	boolean	No	Send a notification email to this recipient

Create share

curl -X POST "https://drive.example.com/api/external/v1/shares" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"rs": 5125, "st": "SPECIFIC_USERS", "cv": true, "ce": true, "cd": false, "cu": true, "cs": false, "ts": [{"us": 21, "cv": true, "ce": true, "cd": false, "cu": false, "cs": false, "se": true}]}'

The response returns the new shareSeq and the resulting permissions. Keep the shareSeq; every later operation on this share uses it.

Read a share

GET /api/external/v1/shares/{shareSeq}

Parameter	Type	Required	Description
shareSeq	long	Yes	Path parameter - the share to read
ss	integer	No	Owner seq; required when you are not the owner

Returns the share type, the share-level permissions, password and isPasswordEnabled, expireDate, and a targets array of recipients with their own permissions and tenant.

modifiable reports whether the share type can still be changed. When it is false, the type is fixed - usually because another resource in the same hierarchy already set it.

Change a share

Requires api:write

Only the user who created the share can change it; for anyone else the request fails with SHARE_004. Recipients can be sent with any share type, as long as the tenant settings allow SPECIFIC_USERS (otherwise SHARE_011).

PATCH /api/external/v1/shares/{shareSeq}

Parameter	Type	Required	Description
shareSeq	long	Yes	Path parameter - the share to change
st	enum	Yes	Share type
cv	boolean	No	View permission; must be true for ORG_LINK and PUBLIC_LINK
ce	boolean	No	Edit permission; required for ORG_LINK and PUBLIC_LINK
cd	boolean	No	Download permission; required for ORG_LINK and PUBLIC_LINK
cu	boolean	No	Upload permission; required for ORG_LINK and PUBLIC_LINK
cs	boolean	No	Re-share permission; required for ORG_LINK and PUBLIC_LINK
ts	array	No	Recipients, in the same shape as on create; replaces the whole list

Change share

curl -X PATCH "https://drive.example.com/api/external/v1/shares/36" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"st": "SPECIFIC_USERS", "cv": true, "ce": true, "cd": true, "cu": true, "cs": false, "ts": [{"us": 25, "cv": true, "ce": true, "cd": true, "cu": false, "cs": false, "se": true}]}'

ts replaces every recipient

If you omit ts or send an empty list, every existing recipient is removed and receives an unshare notification. To change only the type or permissions, send the current recipients again in ts.

Set recipients

Requires api:write

Replaces the recipient list without changing the share type or its share-level permissions. Unlike the change endpoint, a user who was granted re-share permission may call this, not only the owner.

PUT /api/external/v1/shares/{shareSeq}/targets

Parameter	Type	Required	Description
shareSeq	long	Yes	Path parameter - the share to set recipients on
ts	array	No	Recipients, in the same shape as on create
ss	integer	No	Sharing user seq; null for your own resource

The list is replacing, not additive: a recipient you leave out loses access. If you omit ts or send an empty list, every existing recipient is removed and receives an unshare notification.

The request fails with SHARE_012 when sharing is disabled for the tenant, and with SHARE_013 when the share's existing type is no longer allowed by the tenant settings.

Remove a share

Requires api:write

DELETE /api/external/v1/shares/{shareSeq}

Parameter	Type	Required	Description
shareSeq	long	Yes	Path parameter - the share to remove

Only the user who created the share can remove it; for anyone else the request fails with SHARE_004.

Everyone loses access, and any link for this share stops resolving. The resource itself is untouched.

Find recipients

GET /api/external/v1/shares/{shareSeq}/users

Lists the current recipients of a share with their id, name, status, and tenant. Pass ss when you are not the owner.

To find users who could be added, search instead. Use the first form when the share already exists and the second when you are still composing one:

GET /api/external/v1/shares/{shareSeq}/users/search
GET /api/external/v1/shares/users/search

Parameter	Type	Required	Description
sk	string	Yes	Search keyword - an email address or account name
ss	integer	No	Owner seq; required when you are not the owner

Matches are returned under data.items. The caller needs share permission on the resource. The search fails with SHARE_012 when sharing is disabled and with SHARE_011 when SPECIFIC_USERS is not allowed. Results exclude the owner and include only active (ACTIVE) regular users (USER); when external sharing is not allowed, only users in the same tenant are returned.

Resolve a share link

GET /api/external/v1/shares/link/{token}

Parameter	Type	Required	Description
token	string	Yes	Path parameter - the token from the share URL

Returns the resource the link points to, its owner, isPublicLink, and a redirectUrl to send the browser to. Get the link itself from the share-link endpoint in Common conventions.

A public link still requires a key here

The Drive web app lets anonymous visitors use this operation, but this endpoint does not allow anonymous access. It always requires an API Key, and it checks view permission against the account the key represents - even for a PUBLIC_LINK share. A link that works anonymously in a browser will return PERMISSION_002 here if the key's account cannot view the resource. An unknown or revoked token returns SHARE_007.

Errors

A failure uses the common envelope:

Share failure

{
  "result": false,
  "code": 403,
  "errorCode": "SHARE_011",
  "message": "..."
}

Code	Status	Meaning
REQUEST_001	400	A request value failed validation
RESOURCE_005	404	The resource was not found, or you do not own it (create)
PERMISSION_002	403	You do not have access to the resource
PERMISSION_003	400	cv is false
PERMISSION_004	-	The permission check failed
PERMISSION_005	403	A permission the share type does not allow was set to true
SHARE_004	404	The share was not found, or you did not create it
SHARE_005	500	The share could not be changed
SHARE_007	404	No share link matches that token
SHARE_008	400	A parent or child resource already has a share of a different type
SHARE_009	500	The share could not be created
SHARE_011	403	SPECIFIC_USERS is not allowed by the tenant settings
SHARE_012	403	Sharing is disabled for the tenant
SHARE_013	403	The share type is not allowed by the tenant settings
SHARE_014	403	External sharing is not allowed
SHARE_TARGET_001	500	The recipients could not be set
RESPONSE_001	500	Unexpected server error

A recipient who is the owner or who does not exist fails with SHARE_009 on create, SHARE_005 on change, and SHARE_TARGET_001 on set recipients. A recipient in another tenant requires external sharing to be allowed (SHARE_014). See Errors for every code.