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

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:

GET an upload token for the target folder (which is valid for next 5 seconds)

Request Parameters

Parameter	Type	Description
NODEUUID	String	UUID of the folder

Response Parameters

Parameter	Type	Description
token	String	Upload token

POST file content to the upload endpoint /upload/UPLOADTOKEN

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:

GET an upload token for the target file (which is valid for next 5 seconds)

Request Parameters

Parameter	Type	Description
NODEUUID	String	UUID of the file

Response Parameters

Parameter	Type	Description
token	String	Upload token

POST file content to the upload endpoint /upload/UPLOADTOKEN

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

Introduction

Authentication

HTTP Request

POST Parameters

HTTP Response

File Actions

Files & Folders Concepts

Example API calls:

Create folder

POST Parameters

Rename a node

POST Parameters

Delete a node

Request Parameters

Mark as favorite

POST Parameters

Copy node to another folder

POST Parameters

Move node to another folder

POST Parameters

Share a copy of node with other users/groups

POST Parameters

Create new file

Request Parameters

Response Parameters

POST Parameters

Create new file revision

Request Parameters

Response Parameters

POST Parameters

Get details of a node

Request Parameters

Response Parameters

Get path of a node

Request Parameters

Response Parameters

List contents of a folder

Request Parameters

Response Parameters