API Documentation

REST API documentation

Authentication

The authentication is required on all endpoints. To authenticate using your API key you need to specify a header named X-API-KEY and the api key as value.

Endpoints

Method Description
POST

https://api.megaoptim.com/v1/optimize

This method is used to send image for optimization and accepts the parameters as descirbed bellow.

Accepted HTTP parameters: (Note: json encoded parameters aren’t supported at this time)

Parameter Possible Values
compression intelligent, ultra or lossless (default: intelligent)
type url, urls, file, files. file/s are local paths
webp 1 or 0 (default: 0)
cmyktorgb 1 or 0 (default: 1)
keep_exif 1 or 0 (default: 0)
max_height 0 or N (default: 0 – disabled)
max_width 0 or N (default: 0 – disabled)
url Required if type is url
urlN Required if type is urls. Can be url1,url2 up to 5.
file Required if type is file
fileN Required if type is files. Can be file1,file2 up to 5.
callback_url If specified the request results will be send to this url using HTTP POST

Example Response:

{
    "status": "processing",
    "code": 202,
    "process_id": "a4f1d060-c292-11e8-b3e3-edd916bf7758"
}

The process_id identifies the job that is currently processing on the server and can be used to retrieve the final results.
POST

https://api.megaoptim.com/v1/optimize/process_id/result

This method is used to retrieve the results for specific process_id that you receive in /v1/optimize call.

To retrieve the results, send a POST to the results url specifying the process_id as follows:

https://api.megaoptim.com/v1/optimize/a4f1d060-c292-11e8-b3e3-edd916bf7758/result

Accepted HTTP parameters: (Note: json encoded parameters aren’t supported at this time)

Parameter Possible Values
timeout Numeric value in seconds. Defaults to 120.

Example Response (webp property is null when webp parameter is 0)

{
   "status":"ok",
   "code":200,
   "result":[
      {
         "success":1,
         "file_name":"flowers.jpg",
         "original_size":1426896,
         "optimized_size":307279,
         "saved_bytes":1119617,
         "saved_percent":78,
         "url":"https://api.megaoptim.com/image/b12020cdf3a1/NFwK5Qcnmlb34cl.jpg",
         "webp":{
            "url":"https://api.megaoptim.com/image/b12020cdf3a1/NFwK5Qcnmlb34cl.jpg.webp",
            "optimized_size":179738,
            "saved_bytes":1247158,
            "saved_percent":87
         }
      }
   ],
   "id":"a4f1d060-c292-11e8-b3e3-edd916bf7758",
   "user":{
      "name":"John Doe",
      "email":"[email protected]",
      "tokens":42
   }
}
POST

This endpoint is used to query the api user details, such as name, email and remaining tokens.

https://api.megaoptim.com/v1/users/info

Example Response:

{
    "status": "ok",
    "code": 200,
    "result": {
        "name": "John Doe",
        "email": "[email protected]",
        "tokens": 42
    }
}

Return codes

The API will always return status 200 for any call, but the result contains “code” property which gives you the exact code.

Code Endpoints Notes
200 /users/info, /register, /optimize/uuid/result /
202 /optimize The /optimize endpoint returns 202 when job is successfully queued.
400 /register, /optimize, /optimize/uuid/result When there is validation error. Such as wrong parameter value, etc.
401 /users/info, /optimize/uuid/result When data is accessed that does not belong to the provided api key.
404 AUTH, /optimize/uuid/result /optimize/uuid/result returns 404 when job is not found. AUTH guard returns 404 when the api key not found in the system.
455 /optimize When the account doesn’t have enough api tokens to proceed with optimization.
500 /register, /optimize/uuid/result, /optimize Internal server error, should be reported to [email protected].
504 /optimize/uuid/result Once the result endpoint timesout – when provided timeout parameter seconds are reached.

Rate Limiting

The following table outlines the rate limit set on each endpoint. We rate limit endpoints in order to prevent attacks. The rate limit rules are within normal boundaries, so nothing to worry. If you are not abuser you will not be rate limited.

Endpoint Limits
https://api.megaoptim.com/v1/optimize 120 requests per 1 minute
https://api.megaoptim.com/v1/optimize/process_id/result 120 requests per 1 minute
https://api.megaoptim.com/v1/users/info 120 requests per 1 minute