OCS Share API

Introduction

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: /ocs/v1.php/apps/files_sharing/api/v1/shares.

Local Shares

Get All Shares

Get all shares shared with a user.

Endpoint

/ocs/v1.php/apps/files_sharing/api/v1/shares

Method

GET

Request Attributes

Attribute Type Description

format

string

sets the output format of the response. Default value is xml. Available options are xml and json.

path

string

limit the shares to those in a specific path.

reshares

boolean

returns not only the shares shared with the current user but all shares.

shared_with_me

string

limits the returned shares to only those shared with the authenticating user.

state

string

limits the returned shares to only those with the specified state. Available options are accepted, all, declined, pending, and rejected.

This attribute is only valid when shared_with_me is set.
declined and rejected are interchangeable.

subfiles

boolean

returns all shares within a folder, given that path defines a folder. This option requires the path option to be specified.

Status Codes

Code Description

100

Successful.

400

Not a directory (if the `subfile' argument was used).

404

Couldn’t fetch shares or file doesn’t exist.

997

Unauthorised.

Example Request Response Payloads

If the user that you’re connecting with is not authorized, then you will see output similar to the following:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>failure</status>
    <statuscode>997</statuscode>
    <message>Unauthorised</message>
  </meta>
  <data/>
</ocs>

If the user that you’re connecting with is authorized, then you will see output similar to the following:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message/>
  </meta>
  <data/>
</ocs>
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>failure</status>
    <statuscode>404</statuscode>
    <message>wrong path, file/folder doesn't exist</message>
  </meta>
  <data/>
</ocs>
Files shared with the current user in XML format.
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message/>
  </meta>
  <data>
    <element>
      <id>115468</id>
      <share_type>3</share_type>
      <uid_owner>auser</uid_owner>
      <displayname_owner>A User</displayname_owner>
      <permissions>1</permissions>
      <stime>1481537775</stime>
      <parent/>
      <expiration/>
      <token>MMqyHrR0GTepo4B</token>
      <uid_file_owner>auser</uid_file_owner>
      <displayname_file_owner>A User</displayname_file_owner>
      <path>/Photos/Paris.jpg</path>
      <item_type>file</item_type>
      <mimetype>image/jpeg</mimetype>
      <storage_id>home::auser</storage_id>
      <storage>993</storage>
      <item_source>3994486</item_source>
      <file_source>3994486</file_source>
      <file_parent>3994485</file_parent>
      <file_target>/Shared/Paris.jpg</file_target>
      <share_with/>
      <share_with_displayname/>
      <url>https://your.owncloud.install.com/owncloud/index.php/s/MMqyHrR0GTepo4B</url>
      <mail_send>0</mail_send>
    </element>
  </data>
</ocs>
Files shared with the current user in JSON format.
{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 100,
      "message": null,
      "totalitems": "",
      "itemsperpage": ""
    },
    "data": [
      {
        "id": "1",
        "share_type": 0,
        "uid_owner": "testuser",
        "displayname_owner": "test user",
        "permissions": 19,
        "stime": 1564484858,
        "parent": null,
        "expiration": null,
        "token": null,
        "uid_file_owner": "testuser",
        "displayname_file_owner": "test user",
        "state": 1,
        "path": "/ownCloud Manual.pdf",
        "item_type": "file",
        "mimetype": "application/pdf",
        "storage_id": "home::testuser",
        "storage": 3,
        "item_source": 97,
        "file_source": 97,
        "file_parent": 57,
        "file_target": "/ownCloud Manual.pdf",
        "share_with": "admin",
        "share_with_displayname": "admin",
        "share_with_additional_info": null,
        "mail_send": 0,
        "attributes": null
      }
    ]
  }
}

Code Example

Get Information About A Known Share

Endpoint

/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>

Method

GET

Supported Attributes

Attribute Type Description

share_id

int

The share’s unique id

Response Status Codes

Code Description

100

Successful

404

Share doesn’t exist

Code Example

The Java and Kotlin examples use the square/okhttp library.

Example Response Payloads

Response Attributes

For details about the elements in the XML response payload please refer to the Response Attributes section of the Create a New Share section below.

Accept a Pending Share

Endpoint

/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>

Method

POST

Request Attributes

Attribute Type Description

share id

integer

the id of the pending share to accept. Pending share ids are available in the get all shares response.

Status Codes

Code Description

200

  • Pending share successfully accepted.

  • Share doesn’t exist.

Example Request Response Payloads

Code Example

Decline a Pending Share

Endpoint

/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>

Method

DELETE

Request Attributes

Attribute Type Description

share id

integer

the id of the pending share to decline. Pending share ids are available in the get all shares response.

Status Codes

Code Description

200

  • Pending share successfully declined (one or more times).

  • Share doesn’t exist.

Example Request Response Payloads

A pending share is successfully declined.
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message/>
  <totalitems></totalitems>
  <itemsperpage></itemsperpage>
 </meta>
 <data/>
</ocs>
The share id does not exist or the pending share has already been declined.
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>failure</status>
  <statuscode>404</statuscode>
  <message>Wrong share ID, share doesn't exist</message>
  <totalitems></totalitems>
  <itemsperpage></itemsperpage>
 </meta>
 <data/>
</ocs>

Code Example

Create A New Share

Share an existing file or folder with a user, a group, or as a public link.

Endpoint

/ocs/v1.php/apps/files_sharing/api/v1/shares

Method

POST

Function Arguments

Argument Type Description

name

string

A (human-readable) name for the share, which can be up to 64 characters in length.

path

string

The path to the file or folder which should be shared.

shareType

int

The type of the share. This can be one of:

  • 0 = user

  • 1 = group

  • 3 = public link

  • 6 = federated cloud share

shareWith

string

The user or group id with which the file should be shared.

publicUpload

boolean

Whether to allow public upload to a public link shared folder.

password

string

The password to protect the public link share with.

permissions

int

The permissions to set on the share.

  • 1 = read (default for public link shares);

  • 2 = update;

  • 4 = create;

  • 8 = delete;

  • 16 = share;

Common example combinations are:

  • 15 = read/write(update and create)/delete;

  • 31 = All permissions.

expireDate

string

An expire date for the user, group or public link share. This argument expects a date string in the following format 'YYYY-MM-DD'. The share expires at the end of the specified day.

attributes

array

Contain a set of one or more permissions to set for a share. The list of available permissions can be obtained from a request to the Roles API.

Things to remember about public link shares

  • Files can only ever have the read and update permission set

  • Folders can have read, update, create, and delete set

  • Public link shares cannot be shared with users and groups

  • Public link shares are not available if public link sharing is disabled by the administrator

  • When creating a public link share of a folder, specify permissions 15 to give download/view/edit access

  • When creating a public link share of a single file, also specify permissions 15 in the API request to give download/view/edit access. The public link share will actually be given permissions 3 (read and update) because create and delete permissions are not relevant for single file shares

Mandatory Fields

shareType is mandatory; path and shareWith are mandatory if shareType is set to 0 or 1

Returns

XML containing the share ID (int) of the newly created share

Status Codes

Code Description

100

Successful

400

Unknown share type

403

Public upload was disabled by the admin

404

File or folder couldn’t be shared

Code Example

Example Request Response Payloads

Failure

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>failure</status>
    <statuscode>400</statuscode>
    <message>unknown share type</message>
  </meta>
  <data/>
</ocs>

Success

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message/>
  </meta>
  <data>
    <id>115468</id>
    <share_type>3</share_type>
    <uid_owner>auser</uid_owner>
    <displayname_owner>A User</displayname_owner>
    <permissions>1</permissions>
    <stime>1481537775</stime>
    <parent/>
    <expiration/>
    <token>MMqyHrR0GTepo4B</token>
    <uid_file_owner>auser</uid_file_owner>
    <displayname_file_owner>A User</displayname_file_owner>
    <path>/Photos/Paris.jpg</path>
    <item_type>file</item_type>
    <mimetype>image/jpeg</mimetype>
    <storage_id>home::auser</storage_id>
    <storage>993</storage>
    <item_source>3994486</item_source>
    <file_source>3994486</file_source>
    <file_parent>3994485</file_parent>
    <file_target>/Shared/Paris.jpg</file_target>
    <share_with/>
    <share_with_displayname/>
    <url>https://your.owncloud.install.com/owncloud/index.php/s/MMqyHrR0GTepo4B</url>
    <mail_send>0</mail_send>
    <name>paris photo</name>
  </data>
</ocs>

Response Attributes

Argument Type Description

id

int

The share’s unique id.

share_type

int

The share’s type. This can be one of:

  • 0 = user

  • 1 = group

  • 3 = public link

  • 6 = federated cloud share

uid_owner

string

The username of the owner of the share.

displayname_owner

string

The display name of the owner of the share.

permissions

octal a

The permission attribute set on the file. Options are:

* 1 = Read * 2 = Update * 4 = Create * 8 = Delete * 16 = Share * 31 = All permissions

The default is 31, and for public link shares is 1.

stime

int

The UNIX timestamp when the share was created.

parent

int

The UNIX timestamp when the share was created.

expiration

string

The date when the share expires, in format YYYY-MM-DD 00:00:00.

token

string

The public link to the item being shared.

uid_file_owner

string

The unique id of the user that owns the file or folder being shared.

displayname_file_owner

string

The display name of the user that owns the file or folder being shared.

path

string

The path to the shared file or folder.

item_type

string

The type of the object being shared. This can be one of file or folder.

mimetype

string

The RFC-compliant mimetype of the file.

storage_id

string

storage

int

item_source

int

The unique node id of the item being shared.

file_source

int

The unique node id of the item being shared. For legacy reasons item_source and file_source attributes have the same value.

file_parent

int

The unique node id of the parent node of the item being shared.

file_target

int

The name of the shared file.

share_with

string

The uid of the receiver of the file. This is either a GID (group id) if it is being shared with a group or a UID (user id) if the share is shared with a user.

share_with_displayname

string

The display name of the receiver of the file.

url

string

mail_send

int

Whether the recipient was notified, by mail, about the share being shared with them.

name

string

A (human-readable) name for the share, which can be up to 64 characters in length

Delete A Share

Remove the given share.

Endpoint

/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>

Method

DELETE
Attribute Type Description

share_id

int

The share’s unique id

Status Codes

Code Description

100

Successful

404

Share couldn’t be deleted

Code Example

Example Request Response Payloads

Failure

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message/>
  </meta>
  <data/>
</ocs>

Success

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>failure</status>
    <statuscode>404</statuscode>
    <message>wrong share ID, share doesn't exist.</message>
  </meta>
  <data/>
</ocs>

Update Share

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

Endpoint

/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>

Method

PUT

Request Arguments

Argument Type Description

name

string

A (human-readable) name for the share, which can

be up to 64 characters in length

share_id

int

The share’s unique id

permissions

int

Update permissions

(see the create share section above)

password

string

Updated password for a public link share

publicUpload

boolean

Enable (true) / disable (false)

public upload for public link shares.

expireDate

string

Set an expire date for the user, group or public link share.
This argument expects a well-formatted date string such as: YYYY-MM-DD
Only one of the update parameters can be specified at once.

Status Codes

Code Description

100

Successful

400

Wrong or no update parameter given

403

Public upload disabled by the admin

404

Couldn’t update share

Code Example

Example Request Response Payloads

Failure

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>failure</status>
    <statuscode>400</statuscode>
    <message>can't change permission for public link share</message>
  </meta>
  <data/>
</ocs>

Success

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message/>
  </meta>
  <data>
    <id>115470</id>
    <share_type>3</share_type>
    <uid_owner>auser</uid_owner>
    <displayname_owner>A User</displayname_owner>
    <permissions>1</permissions>
    <stime>1481552410</stime>
    <parent/>
    <expiration>2017-01-01 00:00:00</expiration>
    <token>11CUiVe0l7iaIwM</token>
    <uid_file_owner>auser</uid_file_owner>
    <displayname_file_owner>A User</displayname_file_owner>
    <path>/Photos/Paris.jpg</path>
    <item_type>file</item_type>
    <mimetype>image/jpeg</mimetype>
    <storage_id>home::auser</storage_id>
    <storage>993</storage>
    <item_source>3994486</item_source>
    <file_source>3994486</file_source>
    <file_parent>3994485</file_parent>
    <file_target>/Shared/Paris.jpg</file_target>
    <share_with/>
    <share_with_displayname/>
    <url>https://your.owncloud.install.com/owncloud/index.php/s/11CUiVe0l7iaIwM</url>
    <mail_send>0</mail_send>
    <name>paris photo</name>
  </data>
</ocs>

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

Returns

XML with all accepted federated cloud shares

Status Codes

Code Description

100

Successful

Get Information About A Known Federated Cloud Share

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

  • Syntax: /remote_shares/<share_id>

  • Method: GET

Attribute Type Description

share_id

int

The share id as listed in the id field

in the remote_shares list

Returns

XML with the share information

Status Codes

Code Description

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

Attribute Type Description

share_id

int

The share id as listed in the id field

in the remote_shares list

Status Codes

Code Description

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

Returns

XML with all pending federated cloud shares

Status Codes

Code Description

100

Successful

404

Share doesn’t exist

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

Attribute Type Description

share_id

int

The share id as listed in the id field

in the remote_shares/pending list

Status Codes

Code Description

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

Attribute Type Description

share_id

int

The share id as listed in the id field

in the remote_shares/pending list

Status Codes

Code Description

100

Successful

404

Share doesn’t exist