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

MethodDescription
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)

ParameterPossible Values
compressionintelligent, ultra or lossless (default: intelligent)
typeurl, urls, file, files. file/s are local paths
webp1 or 0 (default: 0)
cmyktorgb1 or 0 (default: 1)
keep_exif1 or 0 (default: 0)
max_height0 or N (default: 0 – disabled)
max_width0 or N (default: 0 – disabled)
urlRequired if type is url
urlNRequired if type is urls. Can be url1,url2 up to 5.
fileRequired if type is file
fileNRequired if type is files. Can be file1,file2 up to 5.
callback_urlIf 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)

ParameterPossible Values
timeoutNumeric 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":"john@doe.com",
      "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": "john@doe.com",
        "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.

CodeEndpointsNotes
200/users/info, /register, /optimize/uuid/result/
202/optimizeThe /optimize endpoint returns 202 when job is successfully queued.
400/register, /optimize, /optimize/uuid/resultWhen there is validation error. Such as wrong parameter value, etc.
401/users/info, /optimize/uuid/resultWhen data is accessed that does not belong to the provided api key.
404AUTH, /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/optimizeWhen the account doesn’t have enough api tokens to proceed with optimization.
500/register, /optimize/uuid/result, /optimizeInternal server error, should be reported to info@megaoptim.com.
504/optimize/uuid/resultOnce 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.

EndpointLimits
https://api.megaoptim.com/v1/optimize120 requests per 1 minute
https://api.megaoptim.com/v1/optimize/process_id/result120 requests per 1 minute
https://api.megaoptim.com/v1/users/info120 requests per 1 minute