NAV

NOTE: This is a work in progress.

Introduction

Welcome to FileAgo v1.0 API.

This document assumes that a FileAgo installation is running on https://fileago.mydomain.com/, and the examples are also based on this host. You must modify the CURL commands so that you are referring to your FileAgo server.

Authentication

To authorize, use this code:

curl -X POST \
  'https://fileago.mydomain.com/auth' \
  -d '{"username":"<EMAIL ADDRESS>", "password": "<PASSWORD>"}'

A successfull response will be like:

Status Code: 200 OK

{
    "uuid": "a805ae1b-5bde-454d-9c2e-4b171aa04c17",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1Mzg3MDYwMjIsInVzZXJuYW1lIjoiam9obmRvZUBnbWFpbC5jb20iLCJ1dWlkIjoiYTgwNWFlMWItNWJkZS00NTRkLTljMmUtNGIxNzFhYTA0YzE3In0.fSYkeR4LBEp_Z2n7vIWvUIl_Y_EJd01MT9UFiziij-w",
    "status": "success",
    "msg": "Login successful.",
    "is_admin": true,
    "fullname": "Vimal Kumar",
    "fileaccesskey": "6dba6924-ad66-42de-8ed2-8008f2c7c06e-3a18c571-2638-475f-ae4b-62211395cab3",
    "avatar": "/images/default_avatar.png"
}

The first step is to authenticate with the server, and grab the token and fileaccesskey. The token is valid for next 24 hours.

HTTP Request

POST /auth

POST Parameters

Parameter Description
username Email address of the user, or admin (if admin is trying to login)
password Password of the user

HTTP Response

Parameter Description
uuid UUID of the user
token JWT token for this session. All subsequent API calls must contain this token in the Authorization header. Keep this handy
status success when the authentication is successful
msg Message
is_admin true if the user has administrator privileges
fullname Name of the user
fileaccesskey This key is necessary for downloading files
avatar URL of the avatar image of this user

File Actions

Files & Folders Concepts

All files and folders has a unique identity (UUID) associated with it. In order to access details of a file or folder, the corresponding API call will almost always include this UUID.

Like files and folders, users and groups also has UUID associated to it. In order to access top level directories, the UUID of the owner (user or group) has to be included as well.

For example, if a user wants to access the top level directories of a group (UUID = 3d768c52-a685-4f15-a487-3b5fdaa333a4), then the values will be like:

Folder Value in API call
home home:3d768c52-a685-4f15-a487-3b5fdaa333a4
incoming incoming:3d768c52-a685-4f15-a487-3b5fdaa333a4
trash trash:3d768c52-a685-4f15-a487-3b5fdaa333a4
public_shares public_shares:3d768c52-a685-4f15-a487-3b5fdaa333a4
private_shares private_shares:3d768c52-a685-4f15-a487-3b5fdaa333a4
favorites favorites:3d768c52-a685-4f15-a487-3b5fdaa333a4
shared_with_you shared_with_you:3d768c52-a685-4f15-a487-3b5fdaa333a4

Example API calls:

GET /api/nodes/home:3d768c52-a685-4f15-a487-3b5fdaa333a4

GET /api/nodes/trash:3d768c52-a685-4f15-a487-3b5fdaa333a4/dirlist

.. and so on. However, to access his own home or trash folder, a user does not need to include own user UUID in URL. For example,

GET /api/nodes/home

GET /api/nodes/trash/dirlist

.. is enough.

Create folder

To create a new folder, the API call will be like:

curl -X POST \
  'https://fileago.mydomain.com/api/nodes/NODEUUID' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  		"new_dir": DIRNAME
  	}'

On success, the server returns:

Status Code: 204 No Content

POST Parameters

Parameter Type Description
NODEUUID String UUID of the folder in which new folder should be created
DIRNAME String Name of the new folder

Rename a node

To rename a node, the API call will be like:

curl -X POST \
  'https://fileago.mydomain.com/api/nodes/NODEUUID' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  		"new_name": NEWNAME
  	}'

On success, the server returns:

Status Code: 204 No Content

POST Parameters

Parameter Type Description
NODEUUID String UUID of the folder or file
NEWNAME String New name to be set

Delete a node

curl -X DELETE \
  'https://fileago.mydomain.com/api/nodes/NODEUUID' \
  -H 'Authorization: Bearer TOKEN'

On success, the server returns:

Status Code: 204 No Content

Request Parameters

Parameter Type Description
NODEUUID String UUID of the folder or file which is to be deleted

Mark as favorite

To mark a node as favorite, the API call will be like:

curl -X POST \
  'https://fileago.mydomain.com/api/nodes/NODEUUID' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  		"starred": BOOL
  	}'

On success, the server returns:

Status Code: 204 No Content

POST Parameters

Parameter Type Description
NODEUUID String UUID of the folder or file
BOOL Boolean true will add the node to favorites list, while false will remove it from favorites

Copy node to another folder

To copy a node to another folder, the API call will be like:

curl -X POST \
  'https://fileago.mydomain.com/api/nodes/NODEUUID' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  		"copy_to": TARGETNODEUUID
  	}'

On success, the server returns:

Status Code: 204 No Content

POST Parameters

Parameter Type Description
NODEUUID String UUID of the folder or file
TARGETNODEUUID String UUID of the target folder

Move node to another folder

To move a node to another folder, the API call will be like:

curl -X POST \
  'https://fileago.mydomain.com/api/nodes/NODEUUID' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  		"move_to": TARGETNODEUUID
  	}'

On success, the server returns:

Status Code: 204 No Content

POST Parameters

Parameter Type Description
NODEUUID String UUID of the folder or file
TARGETNODEUUID String UUID of the target folder

Share a copy of node with other users/groups

To share a copy of a node with other users or groups, the API call will be like:

curl -X POST \
  'https://fileago.mydomain.com/api/nodes/NODEUUID' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  		"share_copy_with": [TARGET]
  	}'

On success, the server returns:

Status Code: 204 No Content

POST Parameters

Parameter Type Description
NODEUUID String UUID of the folder or file
TARGET String UUID of the target user or group. Mention more UUIDs within the list if the node is being shared with multiple users or groups, e.g.: [UUID_OF_USER1, UUID_OF_USER2, UUID_OF_GROUP1]

Create new file

  • Request an upload token
curl 'https://fileago.mydomain.com/api/nodes/NODEUUID/upload' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json'

On success, the server returns:

Status Code: 200 OK

{
	"token":UPLOADTOKEN,
	"status":"success",
	"msg":"This token is valid for next 5 seconds only"
}
  • Upload file using the upload endpoint
curl 'https://fileago.mydomain.com/upload/UPLOADTOKEN' \
  -F 'file=@filename.txt'

On success, the server returns:

Status Code: 200 OK

{
	"status":"success",
	"msg":"File(s) uploaded successfully"
}

Creating a new file consists of 2 steps:

Request Parameters

Parameter Type Description
NODEUUID String UUID of the folder

Response Parameters

Parameter Type Description
token String Upload token

POST Parameters

Parameter Type Description
UPLOADTOKEN String Upload token
file String Path of the filename to upload

Create new file revision

  • Request an upload token
curl 'https://fileago.mydomain.com/api/nodes/NODEUUID/upload' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json'

On success, the server returns:

Status Code: 200 OK

{
	"token":UPLOADTOKEN,
	"status":"success",
	"msg":"This token is valid for next 5 seconds only"
}
  • Upload file using the upload endpoint
curl 'https://fileago.mydomain.com/upload/UPLOADTOKEN' \
  -F 'file=@filename.txt'

On success, the server returns:

Status Code: 200 OK

{
	"status":"success",
	"msg":"File(s) uploaded successfully"
}

Creating a new file revision consists of 2 steps:

Request Parameters

Parameter Type Description
NODEUUID String UUID of the file

Response Parameters

Parameter Type Description
token String Upload token

POST Parameters

Parameter Type Description
UPLOADTOKEN String Upload token
file String Path of the filename to upload

Get details of a node

To fetch the detail of a node, the API call will be like:

curl 'https://fileago.mydomain.com/api/nodes/NODEUUID' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json'

On success, the server returns (example result given below):

Status Code: 200 OK

{
	"status": "success",
	"msg": "Node info fetched successfully",
	"data": {
		"name": "Misc",
		"type": "Dir",
		"uuid": "d27fd3e2-2a5e-40c2-abc3-74f6734b190f",
		"owner_type": "User",
		"owner_uuid": "db1990e6-519c-4596-8778-37fd2d959691",
		"owner_fullname": "John Doe",
		"created": 1503597685574,
		"updated": 1533281990916
	}
}

Request Parameters

Parameter Type Description
NODEUUID String UUID of the folder or file

Response Parameters

Parameter Type Description
status String success if no errors
msg String Message
name String Name of the node
type String Dir if the node is a folder, else File
uuid String UUID of the node
owner_type String User if the owner is a user, else Group
owner_uuid String UUID of the owner of the node
owner_fullname String Name of the owner
created Integer Created time in epoch (milliseconds)
updated Integer Updated time in epoch (milliseconds)

Get path of a node

To find the path of a node, the API call will be like:

curl 'https://fileago.mydomain.com/api/nodes/NODEUUID/path' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json'

On success, the server returns (example result given below):

Status Code: 200 OK

{
	"status":"success",
	"msg":"Node path fetched successfully",
	"data":[
		{"name": "Home", "uuid": "home"},
		{"name": "Misc", "uuid": "d27fd3e2-2a5e-40c2-abc3-74f6734b190f"}
	]
}

Request Parameters

Parameter Type Description
NODEUUID String UUID of the folder or file

Response Parameters

Parameter Type Description
status String success if no errors
msg String Message
data List List of node names and its UUID starting from the top level directory

List contents of a folder

To list the items inside a folder, the API call will be like:

curl 'https://fileago.mydomain.com/api/nodes/NODEUUID/dirlist' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json'

On success, the server returns (example result given below):

Status Code: 200 OK

{
	"status": "success", 
	"msg": "Directory contents fetched successfully",
	"data": [
		{
			"is_starred": false,
			"public_shares": 0,
			"name": "My Documents", 
			"size": 4,
			"comment_count": 13,
			"uuid": "50a3495d-9da5-469a-a971-57f2fe97a6fa",
			"private_shares": 0,
			"updated": 1522740152809,
			"type": "Dir"
		}, {
			"is_starred": true,
			"public_shares": 0,
			"name": "Invoice.docx",
			"size": 493135,
			"comment_count": 0,
			"uuid": "1339025b-d6e4-4c1e-9c62-85fc65ee0118",
			"private_shares": 0,
			"revision": 1,
			"updated": 1538224353000,
			"type": "File"
		}
	]
}

Request Parameters

Parameter Type Description
NODEUUID String UUID of the folder

Response Parameters

Parameter Type Description
status String success if no errors
msg String Message
data List List of nodes that are present in this folder