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’
POST Arguments: note - (string) Adds a note for the share recipient.
POST Arguments: attributes - (string) URI-encoded serialized JSON string for share attributes
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.
PUT Arguments: attributes - (string) serialized JSON string for share attributes
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
Share attributes
Share attributes are used for more advanced flags like permissions.
To remove the download permission from a share, use the following serialized string in the “attributes” parameter:
[
{"scope":"permissions","key":"download","enabled":false}
]
This will prevent users from downloading the files from the share. For specific file types like office files, it will still be possible to view the files using the appropriate viewer app, which itself will present the file in a way that downloading will not be allowed.
By default when unset, the “download” attribute will be true and so the download permission will be granted.
Note
There is currently only one share attribute “download” from the scope “permissions”. This attribute is only valid for user and group shares, not for public link shares.
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
listResult: 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
listResult: 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
listResult: 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
listResult: XML with the share information
Statuscodes:
100 - successful
404 - share doesn’t exist