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, used both for the share as a whole and for each recipient.

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

cv is the prerequisite for the others: any of ce, cd, cu, or cs set to true requires cv to be true. Turning cv off while another permission is on fails with PERMISSION_003. For ORG_LINK and PUBLIC_LINK, cv must be true and the remaining four must be sent explicitly.

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
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-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. This endpoint uses cursor pagination; 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": "Specific users",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "SHARE", "VIEW"]
      },
      {
        "code": "ORG_LINK",
        "name": "Anyone in the organization",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "VIEW"]
      },
      {
        "code": "PUBLIC_LINK",
        "name": "Anyone with the link",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "VIEW"]
      }
    ]
  }
}

allowedPermissions is what an administrator permits for that type; a share cannot grant more than this. Note that ORG_LINK and PUBLIC_LINK do not offer re-share.

Create a share

Requires api:write

Only the owner of the resource can create a share. 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; used when st is SPECIFIC_USERS

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-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 owner of the resource can change a share. Recipients can be set only while the type is SPECIFIC_USERS.

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

Change share

curl -X PATCH "https://drive.example.com/api/external/v1/shares/36" \
  -H "Authorization: Bearer replace-with-your-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}]}'

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.

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

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.

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 internal path for this operation allows anonymous access, but this external endpoint does not. 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

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