API Documentation
API Credentials
You need an Account to get an API Key. Just register on MirrorAce to get one.
RegisterAPI Documentation
- General
- Overview
- Response
- Authentication
- File
- Upload
- Info
- Upload
- File Upload
- Remote Upload
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"
}
}