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

Local Shares

Get All Shares

Get all shares from the user.

  • Syntax: /shares

  • Method: GET

Attribute Type Description

shared_with_me

boolean

Returns all shares shared with the sharee.

Returns

XML with all shares

Status Codes

Code Description

100

Successful

404

Couldn’t fetch shares

997

Unauthorised

Code Example

Curl

#!/bin/bash

##
## Variable Declaration
##
SERVER_URI=https://your.owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1

curl --user your.username:your.password "$SERVER_URI/$API_PATH/shares"

PHP

<?php

use GuzzleHttp\Client;

require_once ('vendor/autoload.php');

// Configure the basic client
$client = new Client([
    'base_uri' => 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);

try {
    $response = $client->get('sha_res', [
        'auth' => ['your.username', 'your.password'],
        'debug' => true,
    ]);
    print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
    print $e->getMessage();
}

Ruby

require 'net/http'
require 'uri'

base_uri = 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI("#{base_uri}/shares")

Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
  req = Net::HTTP::Get.new uri
  req.basic_auth 'your.username', 'your.password'
  res = http.request req

  puts res.body
end

Go

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
)

func main() {
	serverUri := "https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
	username := "your.username"
	passwd := "your.password"

	client := &http.Client{}

	req, err := http.NewRequest("GET", fmt.Sprintf("%s/%s", serverUri, "shares"), nil)
	if err != nil {
		log.Print(err)
		os.Exit(1)
	}

	req.SetBasicAuth(username, passwd)

	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}

	bodyText, err := ioutil.ReadAll(resp.Body)
	fmt.Println(string(bodyText))
}

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: MISSING

Get Shares From A Specific File Or Folder

Get all shares from a given file or folder.

  • Syntax: /shares

  • Method: GET

Request Attributes

Attribute Type Description

path

string

path to file/folder

reshares

boolean

returns not only the shares from the current user but all

shares from the given file.

subfiles

boolean

returns all shares within a folder, given that path defines

a folder

Mandatory fields: path

Returns

XML with the shares

Code Example

Curl

#!/bin/bash

##
## Variable Declaration
##
SERVER_URI=https://your.owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1

curl --user your.username:your.password "$SERVER_URI/$API_PATH/shares?path=/Photos/Paris.jpg&reshares=true"

PHP

<?php

use GuzzleHttp\Client;

require_once ('vendor/autoload.php');

// Configure the basic client
$client = new Client([
    'base_uri' => 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);

try {
    $response = $client->get('shares?path=/Photos/Paris.jpg&reshares=true', [
        'auth' => ['your.username', 'your.password'],
        'debug' => true,
    ]);
    print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
    print $e->getMessage();
}

Ruby

require 'net/http'
require 'uri'

base_uri = 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI("#{base_uri}/shares?path=/Photos/Paris.jpg&reshares=true")

Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
  req = Net::HTTP::Get.new uri
  req.basic_auth 'your.username', 'your.password'
  res = http.request req

  puts res.body
end

Go

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"os"
)

func main() {
	serverUri := "https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
	username := "your.username"
	passwd := "your.password"

	client := &http.Client{}

	req, err := http.NewRequest("GET", fmt.Sprintf("%s/%s", serverUri, "shares"), nil)
	if err != nil {
		log.Print(err)
		os.Exit(1)
	}

	// Add on some, relevant, query parameters
	q := req.URL.Query()
	q.Add("path", "/Photos/Paris.jpg")
	q.Add("reshares", "true")
	req.URL.RawQuery = q.Encode()

	req.SetBasicAuth(username, passwd)

	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}

	bodyText, err := ioutil.ReadAll(resp.Body)
	fmt.Println(string(bodyText))
}

Example Request Response Payloads

Status Codes

Code Description

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

Attribute Type Description

share_id

int

The share’s unique id

Returns

XML with the share information

Status Codes

Code Description

100

Successful

404

Share doesn’t exist

Code Example

Curl

#!/bin/bash

##
## Variable Declaration
##
SERVER_URI=https://your.owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1

curl --user your.username:your.password "$SERVER_URI/$API_PATH/shares/115464"

PHP

<?php

use GuzzleHttp\Client;

require_once ('vendor/autoload.php');

// Configure the basic client
$client = new Client([
    'base_uri' => 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);

try {
    $response = $client->get('shares/115464', [
        'auth' => ['your.username', 'your.password'],
        'debug' => true,
    ]);
    print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
    print $e->getMessage();
}

Ruby

require 'net/http'
require 'uri'

base_uri = 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/'
uri = URI("#{base_uri}/shares/115464")

Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
  req = Net::HTTP::Get.new uri
  req.basic_auth 'your.username', 'your.password'
  res = http.request req

  puts res.body
end

Go

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"os"
)

func main() {
	serverUri := "https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
	username := "your.username"
	passwd := "your.password"

	client := &http.Client{}

	req, err := http.NewRequest("GET", fmt.Sprintf("%s/%s", serverUri, "shares/115464"), nil)
	if err != nil {
		log.Print(err)
		os.Exit(1)
	}

	req.SetBasicAuth(username, passwd)

	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}

	bodyText, err := ioutil.ReadAll(resp.Body)
	fmt.Println(string(bodyText))
}

Kotlin

package main

import okhttp3.Credentials
import okhttp3.OkHttpClient
import okhttp3.Request
import java.io.IOException

fun main(args: Array<String>) {
    val ownCloudDomain = "your.owncloud.domain.com/owncloud"
    var client = OkHttpClient()
    val credentials = Credentials.basic("your.username", "your.password");

    var builder = Request.Builder()
            .url("https://$ownCloudDomain/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>'")
            .header("Authorization", credentials)
            .build()

    try {
        var response = client.newCall(builder).execute()

        when {
            response.isSuccessful -> println(
                    "Request was successful. Response was: ${response.body()?.string()}"
            )
            else -> println("Request was not successful.")
        }
    } catch (e: IOException) {
        println("Request failed. Reason: ${e.toString()}")
    }
}

Java

import okhttp3.Credentials;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

import java.io.IOException;

public class GetShareInfo {
    OkHttpClient client = new OkHttpClient();

    String run(String url, String credentials) throws IOException {
        Request request = new Request.Builder()
                .url(url)
                .header("Authorization", credentials)
                .build();

        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful()) {
                String responseBody = (response.body().string() != null) ? response.body().string() : "empty";
                return "Request was successful. Response was: " + responseBody;
            }

        } catch (IOException e) {
            return "Request was not successful. Reason: " + e.toString();
        }

        return "Request was not successful.";
    }

    public static void main(String[] args) throws IOException {
        GetShareInfo info = new GetShareInfo();

        String credentials = Credentials.basic("your.username", "your.password");
        String ownCloudDomain = "your.owncloud.domain.com/owncloud";
        String url = "https://" + ownCloudDomain + "/ocs/v1.php/apps/files_sharing/api/v1/shares/<share_id>'";

        String response = info.run(url, credentials);
        System.out.println(response);
    }
}

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

Example Request 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.

Create A New Share

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

  • Syntax: /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 shared folder.

password

string

The password to protect public link share with.

permissions

int a

The permissions to set on the share.

* 1 = read (default for public shares); * 2 = update; * 4 = create; * 8 = delete; * 15 = read/write.

expireDate

string

An expire date for public link shares. This argument expects a date string in the following format 'YYYY-MM-DD'.

Things to remember about public link shares

  • Files will only ever have the read permission set

  • Folders will 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

Mandatory Fields

shareType, 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

Curl

#!/bin/bash

##
## Variable Declaration
##
SERVER_URI=https://your.owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1

curl --user your.username:your.password "$SERVER_URI/$API_PATH/shares" \
     --data 'path=/Photos/Paris.jpg&shareType=3&permissions=1&name=paris%20photo'

PHP

<?php

use GuzzleHttp\Client;

require_once ('vendor/autoload.php');

// Configure the basic client
$client = new Client([
    'base_uri' => 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);

try {
    $response = $client->post('shares', [
        'auth' => ['your.username', 'your.password'],
        'debug' => true,
        'form_params' => [
            'path' => 'Photos/Paris.jpg',
            'shareType' => 3,
            'permissions' => 1
        ]
    ]);
    print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
    print $e->getMessage();
}

Ruby

require 'net/http'
require 'uri'

base_uri = 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1'
uri = URI("#{base_uri}/shares")

Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
  req = Net::HTTP::Get.new uri
  req.basic_auth 'your.username', 'your.password'
  res = http.request req

  puts res.body
end

Go

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"net/url"
	"strconv"
	"strings"
)

func main() {
	serverUri := "https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
	username := "your.username"
	passwd := "your.password"

	client := &http.Client{}

	// Set the form POST body
	form := url.Values{}
	form.Add("path", "/Photos/Paris.jpg")
	form.Add("shareType", "3")
	form.Add("permissions", "1")

	// Build the core request object
	req, _ := http.NewRequest(
		"POST",
		fmt.Sprintf("%s/%s", serverUri, "shares"),
		strings.NewReader(form.Encode()),
	)
	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
	req.Header.Add("Content-Length", strconv.Itoa(len(form.Encode())))
	req.SetBasicAuth(username, passwd)

	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}

	bodyText, err := ioutil.ReadAll(resp.Body)
	fmt.Println(string(bodyText))
}

Example Request Response Payloads

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 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 UNIX timestamp when the share expires.

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.

  • Syntax: /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

Curl

#!/bin/bash

##
## Variable Declaration
##
SERVER_URI=https://your.owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1

curl --user your.username:your.password "$SERVER_URI/$API_PATH/shares/115470" \
     --request DELETE

PHP

<?php

use GuzzleHttp\Client;

require_once ('vendor/autoload.php');

// Configure the basic client
$client = new Client([
    'base_uri' => 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);

try {
    $response = $client->delete('shares/115468', [
        'auth' => ['your.username', 'your.password'],
        'debug' => true,
    ]);
    print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
    print $e->getMessage();
}

Ruby

require 'net/http'
require 'uri'

base_uri = 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1'
uri = URI("#{base_uri}/shares/115468")

Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
  req = Net::HTTP::Delete.new uri
  req.basic_auth 'your.username', 'your.password'
  res = http.request req

  puts res.body
end

Go

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
)

func main() {
	serverUri := "https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
	username := "your.username"
	passwd := "your.password"

	client := &http.Client{}

	// Build the core request object
	req, _ := http.NewRequest(
		"DELETE",
		fmt.Sprintf("%s/%s", serverUri, "shares/115470"),
		nil,
	)
	req.SetBasicAuth(username, passwd)

	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}

	bodyText, err := ioutil.ReadAll(resp.Body)
	fmt.Println(string(bodyText))
}

Example Request Response Payloads

Update Share

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

  • Syntax: /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 public link Share

publicUpload

boolean

Enable (true) / disable (false)

public upload for public shares.

expireDate

string

Set an expire date for public link shares.

This argument expects a well-formatted date string,

such as: `YYYY-MM-DD'

Only one of the update parameters can be specified at once. Also, a permission cannot be changed for a public link share.

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

Curl

#!/bin/bash

##
## Variable Declaration
##
SERVER_URI=https://your.owncloud.install.com/owncloud
API_PATH=ocs/v1.php/apps/files_sharing/api/v1

curl --user your.username:your.password "$SERVER_URI/$API_PATH/shares/115470" \
     --request PUT \
     --data 'expireDate=2017-01-02&name=paris%20photo'

PHP

<?php

use GuzzleHttp\Client;

require_once ('vendor/autoload.php');

// Configure the basic client
$client = new Client([
    'base_uri' => 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1/',
]);

try {
    $response = $client->put('shares/115470', [
        'auth' => ['your.username', 'your.password'],
        'debug' => true,
        'form_params' => [
            'expireDate' => '2017-01-01'
        ]
    ]);
    print $response->getBody()->getContents();
} catch (\GuzzleHttp\Exception\ClientException $e) {
    print $e->getMessage();
}

Ruby

require 'net/http'
require 'uri'

base_uri = 'https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1'
uri = URI("#{base_uri}/shares/115470")

Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
  req = Net::HTTP::Put.new uri
  req.basic_auth 'your.username', 'your.password'
  req.set_form_data('expireDate' => '2017-01-03')
  res = http.request req

  puts res.body
end

Go

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"net/url"
	"strconv"
	"strings"
)

func main() {
	serverUri := "https://your.owncloud.install.com/owncloud/ocs/v1.php/apps/files_sharing/api/v1"
	username := "your.username"
	passwd := "your.password"

	client := &http.Client{}

	// Set the form POST body
	form := url.Values{}
	form.Add("expireDate", "2017-01-03")

	// Build the core request object
	req, _ := http.NewRequest(
		"PUT",
		fmt.Sprintf("%s/%s", serverUri, "shares/115470"),
		strings.NewReader(form.Encode()),
	)
	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
	req.Header.Add("Content-Length", strconv.Itoa(len(form.Encode())))
	req.SetBasicAuth(username, passwd)

	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}

	bodyText, err := ioutil.ReadAll(resp.Body)
	fmt.Println(string(bodyText))
}

Example Request Response Payloads

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