Note: There is an updated version of this article for EVO v7 (ShareBrowser 6.1.5) systems available here: ShareBrowser API Documentation (6.1.5+)

API Permissions

By default, the public API is read-only as of ShareBrowser 6.0. To manipulate any database entry, read-write privileges must first be granted using the following requests. These requests use the ShareBrowser Admin credentials (default: administrator:adminpw111).

HTTP Request

PUT http://evo-address:8577/api/v1.0/preferencesservice/publicAPIMode

Disable the public API

This request sets the permissions to none, disabling the public API.

cURL Example:

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" "http://127.0.0.1:8577/api/v1.0/preferencesservice/publicAPIMode" -X PUT -d 'none'

Set API to Read-Only

This request sets the permissions to Read-Only, the default permission scheme.

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" "http://127.0.0.1:8577/api/v1.0/preferencesservice/publicAPIMode" -X PUT -d 'ro'

Set API to Read-Write

This is required to make any changes using the public API.

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" "http://127.0.0.1:8577/api/v1.0/preferencesservice/publicAPIMode" -X PUT -d 'rw'

Sessions

Create a Session

All API methods require a valid session. This method creates a session.

HTTP Request:

POST http://evo-address:8577/api/public/v1.0/auth/session

cURL Example:

#To Create a session, use the POST method and include the login credentials.
curl -H "Content-Type: application/json" -X POST -d '{"name":"q","password":"q"}' "http://127.0.0.1:8577/api/public/v1.0/auth/session"
#Make sure to replace 127.0.0.1 with your EVO IP.

This request body is in JSON format.

{ 
 "name":"q",
 "password":"q"
}

The above command returns JSON structured like this:

{ 
 "status":"success",
 "data":{ 
 "cookie":1447413700,
 "user_id":2
 }
}

Using a Session_ID

Every call to the API after the session is created expects a session cookie in the header. If there are no requests within an open session for 3 minutes, the session is closed.

cURL Example:

curl -H "session_id: 1447413700"

Delete a Session

When finished making calls to the ShareBrowser API, it's best to delete your session to do this use the DELETE method.

HTTP Request:

DELETE http://evo-address:8577/api/public/v1.0/auth/session

cURL Example:

# Make sure to specify your session and send a DELETE request.
curl -H "session_id: 1447413700" -X DELETE "http://127.0.0.1:8577/api/public/v1.0/auth/session"
#Make sure to replace 127.0.0.1 with your EVO IP and 1447413700 with your session_id.

Volumes

GET Volume ID

Retrieves a Volume ID from ShareBrowser's database.

HTTP Request:

GET http://evo-address:8577/api/public/v1.0/volume/id?volume_uuid={volume_uuid}

cURL Example:

#Make sure to specify your session and send a GET request with the volume_uuid.
curl -H "session_id: 1447413700" -X GET "http://127.0.0.1:8577/api/public/v1.0/volume/id?volume_uuid=09ABC165-86B1-46BB-A678-3E8A7D0882E4"

The above command returns JSON structured like this:

{
   "status":"success",
   "data":{
      "volume_id":2
   }
}

Query Parameters:

volume_uuid

Can be found in the _ShareBrowserVolumeUID_ file on any NAS volume.

Files

GET File ID

Retrieves a File ID from ShareBrowser's database.

HTTP Request

GET http://evo-address:8577/api/public/v1.0/file/id?volume_id={volume_id}&path={path}

cURL Example:

# Make sure to specify your session and send a GET request with the volume_id and path.
curl -H "session_id: 1447413700" -X GET "http://127.0.0.1:8577/api/public/v1.0/file/id?volume_id=2&path=%2Ffolderonroot%2Fmovie.mov"

The above command returns JSON structured like this:

{
   "status":"success",
   "data":{
      "file_id":23
   }
}

Query Parameters:

volume_id	The volume_id returned from GET volume_id.
path	The path to the file from the root of the volume to the filename separated by slashes (%2F)

GET Metadata for a file

Retrieves a file's metadata from ShareBrowser's database.

HTTP Request:

GET http://evo-address:8577/api/public/v1.0/file/metadata?file_id={file_id}

cURL Example:

# Make sure to specify your session and send a GET request with the file_id.
curl -H "session_id: 1447413700" -X GET "http://127.0.0.1:8577/api/public/v1.0/file/metadata?file_id=23"

The above command returns JSON structured like this:

{
   "status":"success",
   "data":{
      "tags":"a,b,c",
      "comment":"comment",
      "harvestedMetadata":{

      }
   }
}

Query Parameters:

file_id

The file_id returned from GET file_id.

Search for a file by filename

Retrieves a list of files whose filenames match a particular string.

HTTP Request:

GET http://evo-address:8577/api/public/v1.0/file/search?filename={filename}

cURL Example:

# Make sure to specify your session and send a GET request with the filename.
curl -H "session_id: 1447413700" -X GET "http://127.0.0.1:8577/api/public/v1.0/file/search?filename=img.bmp"

The above command returns JSON structured like this:

{
   "status":"success",
   "data":{
      "search_results":[
         {
            "file_id":31,
            "file_path":"/b/folder/img.bmp",
            "volume_id":2,
            "volume_name":"unlocked",
            "volume_uuid":"09ABC165-86B1-46BB-A678-3E8A7D0882E4"
         },
         {
            "file_id":28,
            "file_path":"/a/b/newimg.bmp",
            "volume_id":2,
            "volume_name":"unlocked",
            "volume_uuid":"09ABC165-86B1-46BB-A678-3E8A7D0882E4"
         },
         {
            "file_id":26,
            "file_path":"/a/img.bmp",
            "volume_id":2,
            "volume_name":"unlocked",
            "volume_uuid":"09ABC165-86B1-46BB-A678-3E8A7D0882E4"
         }
      ]
   }
}

Query Parameters:

filename

The pattern to match in the filename.

Archive Requests

Archive requests are available as of ShareBrowser 6.0

Get Archive Status

Gets the archive status of a file.

HTTP Request

GET http://evo-address:8577/api/public/v1.0/file/{file_id}/archived

cURL Example

curl --silent -H "session_id: 1447413700" GET "http://127.0.0.1:8577/api/public/v1.0/file/2506/archived"

Query Parameters:

file_id

The file_id returned from GET file_id.

Change Archive Status

Sets the archive status of a file (true/false).

HTTP Request

POST http://evo-address:8577/api/public/v1.0/file/{file_id}/archived?value={true|false}&recursive={true|false}

cURL Example

curl --silent -H "session_id: 1447413700" -X POST "http://127.0.0.1:8577/api/public/v1.0/file/2506/archived?value=true&recursive=false"

Query Parameters:

file_id

The file_id returned from GET file_id.

Custom Metadata

Custom metadata requests are available as of ShareBrowser 6.0.

Get Custom Metadata

Get the value of Custom Metadata for a file.

HTTP Request

GET http://evo-address:8577/api/public/v1.0/file/{file_id}/custom_metadata?field_name={field_name}

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X GET "http://127.0.0.1:8577/api/public/v1.0/file/26456/custom_metadata?field_name=Status"

Query Parameters:

file_id	The file_id returned from GET file_id.
field_name	(Optional) The field name to query.

Post Custom Metadata

Set the value of a specific Custom Metadata field to text.

HTTP Request

POST http://evo-address:8577/api/public/v1.0/file/{file_id}/custom_metadata?field_name={field_name}

cURL Example

curl -H "session_id: 1447413700" -H "Content-Type: application/json" -X POST "http://127.0.0.1:8577/api/public/v1.0/file/26456/custom_metadata?field_name=Director" -d '"Spielberg"'

Query Parameters:

file_id	The file_id returned from GET file_id.
field_name	The field name to post.

Post a Custom List

Post a new field with the value of an option in a list.

HTTP Request

POST http://evo-address:8577/api/public/v1.0/file/{file_id}/custom_metadata?field_name={field_name}

cURL Example

curl -H "session_id: 1447413700" -H "Content-Type: application/json" -X POST "http://127.0.0.1:8577/api/public/v1.0/file/26456/custom_metadata?field_name=Director" -d '["Spielberg"]'

Query Parameters:

file_id	The file_id returned from GET file_id.
field_name	The field name to post.

Post Tags

Post ShareBrowser Tags to a file.

HTTP Request

POST http://evo-address:8577/api/public/v1.0/file/{file_id}/tags

cURL Example

curl -H "session_id: 1447413700" -H "Content-Type: application/json" -X POST "http://127.0.0.1:8577/api/public/v1.0/file/26456/tags" -d '["newtag"]'

Query Parameters:

file_id

The file_id returned from GET file_id.

Post Comment

Post a ShareBrowser Comment to a file.

HTTP Request

POST http://evo-address:8577/api/public/v1.0/file/{file_id}/comment

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X POST "http://127.0.0.1:8577/api/public/v1.0/file/26456/comment" -d 'This is a comment'

Query Parameters:

file_id

The file_id returned from GET file_id.

Search Custom Metadata

Get a list of files wherein the value contains a string for a specific custom metadata field (not tags/comments).

HTTP Request

GET http://evo-address:8577/api/public/v1.0/file/search_custom_metadata?key={key}&value={value}

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X GET "http://127.0.0.1:8577/api/public/v1.0/file/search_custom_metadata?key=camera&value=GoPro"

Query Parameters:

key	The case-sensitive custom metadata field
value	The search string

Custom Metadata Template

Manipulation of custom metadata template fields is possible as of ShareBrowser 6.0 and requires ShareBrowser Admin permissions.

Create Custom Text Field

Create a metadata field to hold text (ShareBrowser 6.0). This requires ShareBrowser Admin Credentials.

HTTP Request

PUT http://evo-address:8577/api/v1.0/customtemplate/field

cURL Example

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" -X PUT "http://127.0.0.1:8577/api/v1.0/customtemplate/field" -d '{"name":"fieldname", "type":"text"}'

Query Parameters:

name	The name for the field.
type	The type of field text,list,protected, or invisible.

Create Custom List Field

Create a metadata field to hold a value from a list (ShareBrowser 6.0). This requires ShareBrowser Admin Credentials.

HTTP Request

PUT http://evo-address:8577/api/v1.0/customtemplate/field

cURL Example

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" -X PUT "http://127.0.0.1:8577/api/v1.0/customtemplate/field" -d '{"name":"newfieldname", "type":"list", "options":["value1", "value2"], "multipleValues":true}'

Query Parameters:

name	The name for the field.
type	The type of field text,list,protected, or invisible.
options	The options that may be selected from the list.
multipleValues	Allow multiple values to be selected(true,false).

Create Invisible Text Field

Create an invisible field to hold a value that the user cannot see (ShareBrowser 6.0). This requires ShareBrowser Admin Credentials.

HTTP Request

PUT http://evo-address:8577/api/v1.0/customtemplate/field

cURL Example

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" -X PUT "http://127.0.0.1:8577/api/v1.0/customtemplate/field" -d '{"name":"newfieldname", "type":"invisible"}'

Query Parameters:

name	The name for the field.
type	The type of field text,list,protected, or invisible.

Create Protected Text Field

Create an protected field to hold a value that the user can see but not edit (ShareBrowser 6.0). This requires ShareBrowser Admin Credentials.

HTTP Request

PUT http://evo-address:8577/api/v1.0/customtemplate/field

cURL Example

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" -X PUT "http://127.0.0.1:8577/api/v1.0/customtemplate/field" -d '{"name":"newfieldname", "type":"protected"}'

Query Parameters:

name	The name for the field.
type	The type of field text,list,protected, or invisible.

Modify Custom List Field

Modify a custom list field (ShareBrowser 6.0). This requires ShareBrowser Admin Credentials.

HTTP Request

POST http://evo-address:8577/api/v1.0/customtemplate/field/{field_name}

cURL Example

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" -X POST "http://127.0.0.1:8577/api/v1.0/customtemplate/field/nameoffield" -d '{"type":"list", "options":["value1", "value2"], "multipleValues":true}'

Query Parameters:

field_name	The name for the field.
type	The type of field text,list,protected, or invisible.
options	The options that may be selected from the list.
multipleValues	Allow multiple values to be selected(true,false).

Delete Custom Metadata Field

Delete a custom field from the Custom Metadata Template (ShareBrowser 6.0). This requires ShareBrowser Admin Credentials.

HTTP Request

DELETE http://evo-address:8577/api/v1.0/customtemplate/field/{field_name}

cURL Example

curl -u 'administrator:adminpw111' -H "Content-Type: application/json" -X DELETE "http://127.0.0.1:8577/api/v1.0/customtemplate/field/nameoffield"

Query Parameters:

field_name

The name for the field.

Bins

Working with ShareBrowser Bins via the API is available in ShareBrowser 6.0.

GET Bins

Gets a list of public and private ShareBrowser Bins.

HTTP Request

GET http://evo-address:8577/api/public/v1.0/bin

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X GET "http://127.0.0.1:8577/api/public/v1.0/bin"

Create a bin

Creates a public or private ShareBrowser Bin.

HTTP Request

PUT http://evo-address:8577/api/public/v1.0/bin

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X PUT "http://127.0.0.1:8577/api/public/v1.0/bin" -d '{"name":"new bin name", "isPrivate": false}'

Add Files to a Bin

Adds a list of file_ids to a specific bin.

HTTP Request

POST "http://evo-address:8577/api/public/v1.0/bin/{bin_id}/files"

cURL Example

curl -H "session_id: 1447413700" -H "Content-Type: application/json" -X POST "http://127.0.0.1:8577/api/public/v1.0/bin/13/files" -d '[26, 3214]'

file_id	The file_id returned from GET file_id.
bin_id	The bin_id returned from GET Bins.

Update Bin

Change a bin name or its private status.

HTTP Request

POST "http://evo-address:8577/api/public/v1.0/bin/{bin_id}"

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X POST "http://127.0.0.1:8577/api/public/v1.0/bin/13" -d '{"name":"new bin name", "isPrivate": false}'

bin_id

The bin_id returned from GET Bins.

List Bin Contents

Get a list of files within a bin.

HTTP Request

GET "http://evo-address:8577/api/public/v1.0/bin/{bin_id}/files"

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X GET "http://127.0.0.1:8577/api/public/v1.0/bin/13/files"

bin_id

The bin_id returned from GET Bins.

Remove Files from a Bin

Removes a list of file_ids from a specific bin.

HTTP Request

DELETE "http://evo-address:8577/api/public/v1.0/bin/{bin_id}/files"

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X DELETE "http://127.0.0.1:8577/api/public/v1.0/bin/13/files" -d '[97]'

file_id	The file_id returned from GET file_id.
bin_id	The bin_id returned from GET Bins.

Delete Bin

Removes a bin.

HTTP Request

DELETE "http://evo-address:8577/api/public/v1.0/bin/{bin_id}"

cURL Example

curl --silent -H "session_id: 1447413700" -H "Content-Type: application/json" -X DELETE "http://127.0.0.1:8577/api/public/v1.0/bin/13"

bin_id

The bin_id returned from GET Bins.

Proxies

GET Proxy URL

Retrieves the location of a Proxy from ShareBrowser's database.

HTTP Request:

GET http://evo-address:8577/api/public/v1.0/preview/proxy_url?file_id={file_id}

cURL Example:

# Make sure to specify your session and send a GET request with the volume_id and path.
curl -H "session_id: 1447413700" -X GET "http://127.0.0.1:8577/api/public/v1.0/preview/proxy_url?file_id=23"

The above command returns JSON structured like this:

{
   "status":"success",
   "data":{
      "video_proxy_url":"http://127.0.0.1:8577/api/v1.1/proxyservice/videoproxy/107021146/v23-1.mp4"
   }
}

Query Parameters:

file_id

The file_id returned from GET file_id.

GET Thumbnail URL

Retrieves the location of a thumbnail from ShareBrowser's database.

HTTP Request:

GET http://evo-address:8577/api/public/v1.0/preview/thumbnail_url?file_id={file_id}

cURL Example:

# Make sure to specify your session and send a GET request with the volume_id and path.
curl -H "session_id: 1447413700" -X GET "http://127.0.0.1:8577/api/public/v1.0/preview/thumbnail_url?file_id=23"

The above command returns JSON structured like this:

{
   "status":"success",
   "data":{
      "thumbnail_url":"http://127.0.0.1:8577/api/v1.1/proxyservice/thumbnail/1607986310/t23-1.jpg"
   }
}

Query Parameters:

file_id

The file_id returned from GET file_id.

Errors

The ShareBrowser API uses the following error codes:

Error Code	Description
1	Internal Server Error
3	Invalid or empty parameters
108	Volume Not Found
112	Invalid Username or Password
118	Invalid Session ID
121	Access Not Permitted
131	File not found
132	Thumbnail not found
133	Proxy not found