OCS Share API

The OCS Share API allows you to access the sharing API from outside over pre-defined OCS calls.

The base URL for all calls to the share API is: <nextcloud_base_url>/ocs/v2.php/apps/files_sharing/api/v1

All calls to OCS endpoints require the OCS-APIRequest header to be set to true.

Local Shares

Get all Shares

Get all shares from the user.

• Syntax: /shares

• Method: GET

• Result: XML with all shares

Statuscodes:

• 100 - successful

• 404 - couldn’t fetch shares

Get Shares from a specific file or folder

Get all shares from a given file/folder.

• Syntax: /shares

• Method: GET

• URL Arguments: path - (string) path to file/folder

• URL Arguments: reshares - (boolean) returns not only the shares from the current user but all shares from the given file.

• URL Arguments: subfiles - (boolean) returns all shares within a folder, given that path defines a folder

• Mandatory fields: path

• Result: XML with the shares

Statuscodes:

• 100 - successful

• 400 - not a directory (if the ‘subfile’ argument was used)

• 404 - file doesn’t exist

Get information about a known Share

Get information about a given share.

• Syntax: /shares/<share_id>

• Method: GET

• Arguments: share_id - (int) share ID

• Result: XML with the share information

Statuscodes:

• 100 - successful

• 404 - share doesn’t exist

Create a new Share

Share a file/folder with a user/group or as public link.

• Syntax: /shares

• Method: POST

• POST Arguments: path - (string) path to the file/folder which should be shared

• POST Arguments: shareType - (int) 0 = user; 1 = group; 3 = public link; 4 = email; 6 = federated cloud share; 7 = circle; 10 = Talk conversation

• POST Arguments: shareWith - (string) user / group id / email address / circleID / conversation name with which the file should be shared

• POST Arguments: publicUpload - (string) allow public upload to a public shared folder (true/false)

• POST Arguments: password - (string) password to protect public link Share with

• POST Arguments: permissions - (int) 1 = read; 2 = update; 4 = create; 8 = delete; 16 = share; 31 = all (default: 31, for public shares: 1)

• POST Arguments: expireDate - (string) set a expire date for public link shares. This argument expects a well formatted date string, e.g. ‘YYYY-MM-DD’

• Mandatory fields: shareType, path and shareWith for shareType 0 or 1.

• Result: XML containing the share ID (int) of the newly created share

Statuscodes:

• 100 - successful

• 400 - unknown share type

• 403 - public upload was disabled by the admin

• 404 - file couldn’t be shared

Delete Share

Remove the given share.

• Syntax: /shares/<share_id>

• Method: DELETE

• Arguments: share_id - (int) share ID

Statuscodes:

• 100 - successful

• 404 - file couldn’t be deleted

Update Share

Update a given share. Only one value can be updated per request.

• Syntax: /shares/<share_id>

• Method: PUT

• Arguments: share_id - (int) share ID

• PUT Arguments: permissions - (int) update permissions (see “Create share” above)

• PUT Arguments: password - (string) updated password for public link Share

• PUT Arguments: publicUpload - (string) enable (true) /disable (false) public upload for public shares.

• PUT Arguments: expireDate - (string) set a expire date for public link shares. This argument expects a well formatted date string, e.g. ‘YYYY-MM-DD’

• PUT Arguments: note - (string) Adds a note for the share recipient.

Note

Only one of the update parameters can be specified at once.

Statuscodes:

• 100 - successful

• 400 - wrong or no update parameter given

• 403 - public upload disabled by the admin

• 404 - couldn’t update share

Federated Cloud Shares

Both the sending and the receiving instance need to have federated cloud sharing enabled and configured. See Configuring Federated Cloud Sharing.

Create a new Federated Cloud Share

Creating a federated cloud share can be done via the local share endpoint, using (int) 6 as a shareType and the Federated Cloud ID of the share recipient as shareWith. See Create a new Share for more information.

List accepted Federated Cloud Shares

Get all federated cloud shares the user has accepted.

• Syntax: /remote_shares

• Method: GET

• Result: XML with all accepted federated cloud shares

Statuscodes:

• 100 - successful

Get information about a known Federated Cloud Share

Get information about a given received federated cloud that was sent from a remote instance.

• Syntax: /remote_shares/<share_id>

• Method: GET

• Arguments: share_id - (int) share ID as listed in the id field in the remote_shares list

• Result: XML with the share information

Statuscodes:

• 100 - successful

• 404 - share doesn’t exist

Delete an accepted Federated Cloud Share

Locally delete a received federated cloud share that was sent from a remote instance.

• Syntax: /remote_shares/<share_id>

• Method: DELETE

• Arguments: share_id - (int) share ID as listed in the id field in the remote_shares list

• Result: XML with the share information

Statuscodes:

• 100 - successful

• 404 - share doesn’t exist

List pending Federated Cloud Shares

Get all pending federated cloud shares the user has received.

• Syntax: /remote_shares/pending

• Method: GET

• Result: XML with all pending federated cloud shares

Statuscodes:

• 100 - successful

Accept a pending Federated Cloud Share

Locally accept a received federated cloud share that was sent from a remote instance.

• Syntax: /remote_shares/pending/<share_id>

• Method: POST

• Arguments: share_id - (int) share ID as listed in the id field in the remote_shares/pending list

• Result: XML with the share information

Statuscodes:

• 100 - successful

• 404 - share doesn’t exist

Decline a pending Federated Cloud Share

Locally decline a received federated cloud share that was sent from a remote instance.

• Syntax: /remote_shares/pending/<share_id>

• Method: DELETE

• Arguments: share_id - (int) share ID as listed in the id field in the remote_shares/pending list

• Result: XML with the share information

Statuscodes:

• 100 - successful

• 404 - share doesn’t exist