API Documentation

API Credentials

You need an Account to get an API Key. Just register on MirrorAce to get one.

Register

API Documentation

Overview

The file upload API is an interface which can be used in your own applications to securely upload, manage and download files externally from this website.

API compatibility

This API will evolve over time when access to other data within the system is made available. However, none of the current endpoints or response values will change. You can write your integration code knowing that it will not be affected by future updates unless there is a bug or security fix.

More functionalities will be added soon.

SSL/HTTPS recommended

All requests to the API requires SSL.

UTF-8 encoding

Every string passed to and from the API needs to be UTF-8 encoded.

HTTP Method

All methods are done using POST unless otherwise stated.

Date format

All date/times are based on UTC timezone.

All date/times in the API are strings in the following format:

Y-m-d H:i:s

For example:

2024-10-16 05:16:56
File size

All file sizes are provided in bytes.

1024 Bytes is equal to 1 Megabytes in our system.

API Path

All requests are sent to the follow path:

https://mirrorace.com/api/v1/

Response

All information is included in the body of the return call, JSON-formatted.

Response Content

All JSON response contains two keys. 'status' and 'result'.

Sample JSON Response:

{
	"status": "<status>",
	"result": "<informational message. varies depending on the request>"
}

Details:

status:
"error" or "success"
result:
Gives response in case of success or detailed information in case of an error. Might hold an array of data or just a boolean true/false, depending on the request.

Authentication

Each and every request requires an API key and API token which is unique for each and every user.

API key and API token can be regenerated in case of exposure.

Credentials

Get your API Credentials from here.

Upload

Get variables required for uploading file directly or via remote url.

URL Structure
https://mirrorace.com/api/v1/file/upload
Parameters
Name Description Example Required
api_key Your personal API key. 0123456789abcdefabcdefabcdefabcd Yes
api_token Your personal API token. 0123456789abcdefabcdefabcdefabcd Yes
Response

Returns an array of variables required for uploading file directly or via remote url.

Name Description Example
server The server domain to upload file. https://m1.mirrorace.com
server_file The url where you can post file for direct file uploads. https://m1.mirrorace.com/api/v1/upload
server_remote The url where you can request remote url uploads. https://m1.mirrorace.com/api/v1/upload/remote
cTracker The chunk tracker that will track your file chunks. 0123456789abcdefabcdefabcdefabcd
mirrors The mirrors that you are allowed to upload to. Note: The list contains all the mirrors with true/false boolean. { "1": true, "2": true, "3": false }
default_mirrors Default mirrors that you have set in your account mirror settings. [ "1", "2", "3" ]
max_chunk_size Maximum chuck size to upload. Chunk should not exceed this limit. 99999995
max_file_size Maximum file size allowed to upload. File size should not exceed this limit. 10737418240
max_mirrors Maximum number of mirrors you are allowed to select. Number of mirrors should not exceed this limit. 100
upload_key The upload key required to upload file. Each and every upload key is uniquely assigned to your API key. Upload key expires in one hour if upload has not started. 0123456789abcdefabcdefabcdefabcd
upload_key_expiry The expiry of the upload key. 2024-10-16 06:16:56

Sample Successful JSON Response:

{
	"status": "success",
	"result": {
		"server": "https://m1.mirrorace.com",
		"server_file": "https://m1.mirrorace.com/api/v1/upload",
		"server_remote": "https://m1.mirrorace.com/api/v1/upload/remote",
		"cTracker": "0123456789abcdefabcdefabcdefabcd",
		"mirrors": {
			"1": true,
			"2": true,
			"3": true
		},
		"default_mirrors": [
			"1",
			"2",
			"3"
		],
		"max_chunk_size": "99999988",
		"max_file_size": "10737418240",
		"max_mirrors": "100",
		"upload_key": "0123456789abcdefabcdefabcdefabcd",
		"upload_key_expiry": "2024-10-16 06:16:56"
	}
}

File Info

Check the status of a file, e.g. if the file exists.

URL Structure
https://mirrorace.com/api/v1/file/info
Parameters
Name Description Example Required
api_key Your personal API key. 0123456789abcdefabcdefabcdefabcd Yes
api_token Your personal API token. 0123456789abcdefabcdefabcdefabcd Yes
files File slug(s), single file slug or comma-separated (max. 50). 7hzy,7hzz Yes
Response

Returns an array of status of each file.

Name Description Example
id ID of the file. 735848
name The name of the file. Space Man Jelly.jpg
slug Slug of the file. 7hzy
size Size of the file. 35892
url Url to access file on MirrorAce. https://mirrorace.com/m/7hzy
status Status of the file. One of these: [ "active", "user removed", "admin removed", "copyright removed", "not found" ]. active

Sample Successful JSON Response:

{
	"status": "success",
	"result": {
		"7hzy": {
			"id": "735848",
			"name": "Space Man Jelly.jpg",
			"slug": "7hzy",
			"size": "35892",
			"url": "https://mirrorace.com/m/7hzy",
			"status": "active"
		},
		"7hzz": {
			"id": "null",
			"name": "null",
			"slug": "null",
			"size": "null",
			"url": "null",
			"status": "not found"
		}
	}
}

Upload File Direct

Provides an interface to upload files.

All Upload requests shall be multipart/form-data encoded.

MirrorAce only supports chunk upload for files larger than Maximum chuck size. A single request should not upload more than Maximum chuck size. Note: Maximum chuck size will be returned from file/upload method.

Maximum chuck size as of now is 99999995 Bytes.

For files larger then the Maximum chuck size, files should be sent in chunks with proper "Content-Length" and "Content-Range" headers.

Every parameter should be sent with every chunk.

Example code

Login to see Example code.

URL Structure
https://mirrorace.com/api/v1/upload
Parameters
Name Description Example Required
api_key Your personal API key. 0123456789abcdefabcdefabcdefabcd Yes
api_token Your personal API token. 0123456789abcdefabcdefabcdefabcd Yes
cTracker Chunk tracker requested from file/upload method. 0123456789abcdefabcdefabcdefabcd Yes
upload_key Upload key found from file/upload method. 0123456789abcdefabcdefabcdefabcd Yes
files Your file. Only a single file per request. Check the above example for details. Yes
mirrors[] An array of ID(s) of Mirrors that you want to upload files to. For PHP, you should set keys as well as values for array. e.g.: mirrors[1] => 1, mirrors[2] => 2 Check the above example for details. Yes
file_password Provide a password if you want to password protect your file. No
Response

Returns an array of file upload status.

Name Description Example
name The name of the file. Space Man Jelly.jpg
size Size of the file. 35892
slug Slug of the file. 7hzy
url Url to access file on MirrorAce. https://mirrorace.com/m/7hzy
info Status of the Upload. Returns "complete" if it is the last or only chunk of the file. Returns "continue" if more chunks are required. complete

Sample Successful Upload Complete JSON Response (If last or only chunk):

{
	"status": "success",
	"result": {
		"name": "Space Man Jelly.jpg",
		"size": "35892",
		"slug": "7hzy",
		"url": "https://mirrorace.com/m/7hzy",
		"info": "complete"
	}
}

Sample Successful Upload Pending JSON Response (If requires more chunks):

{
	"status": "success",
	"result": {
		"name": "Space Man Jelly.jpg",
		"size": "35892",
		"info": "continue"
	}
}

Upload File Remote

Provides an interface to upload via remote URL.

URL Structure
https://mirrorace.com/api/v1/upload/remote
Parameters
Name Description Example Required
api_key Your personal API key. 0123456789abcdefabcdefabcdefabcd Yes
api_token Your personal API token. 0123456789abcdefabcdefabcdefabcd Yes
cTracker Chunk tracker requested from file/upload method. 0123456789abcdefabcdefabcdefabcd Yes
upload_key Upload key found from file/upload method. 0123456789abcdefabcdefabcdefabcd Yes
url Url of the file you want to upload. http://google.com/favicon.ico Yes
mirrors[] An array of ID(s) of Mirrors that you want to upload files to. For PHP, you should set keys as well as values for array. e.g.: mirrors[1] => 1, mirrors[2] => 2 Check the above example for details. Yes
file_password Provide a password if you want to password protect your file. No
Response

Returns an array of file upload status.

Name Description Example
name The name of the file. Space Man Jelly.jpg
size Size of the file. 35892
slug Slug of the file. 7hzy
url Url to access file on MirrorAce. https://mirrorace.com/m/7hzy
info Status of the Upload. Returns "complete" if it is the last or only chunk of the file. Returns "continue" if more chunks are required. complete

Sample Successful JSON Response:

{
	"status": "success",
	"result": {
		"name": "Space Man Jelly.jpg",
		"size": "35892",
		"slug": "7hzy",
		"url": "https://mirrorace.com/m/7hzy",
		"info": "complete"
	}
}

MirrorAce
Copyright © 2024 - MirrorAce
Created with and Caffeine