Xverum

API Documentation

Introduction

 

Operia’s API is very simple to use. So easy that you can even run it from your browser!

 

All requests are sent to the following base URL:
https://run.operia.io/KEY/

 

where KEY is your personal API KEY.

 

Please read how to protect your API key below.

Fetcher API

 

This is the main API: give us a URL and we’ll fetch it for you!

 
Example:

https://run.operia.io/KEY/?url=https://example.com

 
CURL example:

Your client must support HTTP redirections. CURL supports this by using the -L or --location switch.

curl -L 'https://run.operia.io/KEY/?url=https://example.com'

 

In PHP use the CURLOPT_FOLLOWLOCATION parameter.

 
Supported parameters:
urlthe URL of the page to fetch (make sure to URL-encode it)

ua

(optional)
the User-Agent header field value to use. Using this parameter you can simulate mobile devices.

ck

(optional)
the Cookie header field value to use. List of key=value separated by ;.
 
Response:

On success, the response body is the body of the requested URL.

 
Response headers:

The response headers are not preserved. Instead, the following response headers may be added:

Operia-CostThe actual cost the request took.
Operia-Original-Status-CodeThe original status code reported by the fetched page.
Operia-Original-Content-TypeIf the original Content-Type header was changed by Operia, it will be specified here.
Operia-Original-Set-CookieIf the fetched page attempted to set cookies, they will be specified here. This header may appear multiple times for multiple cookies.
 
Errors:

On failure, the response status code will be in the range of 4xx-5xx and the error string will be returned as the response body.

REQUEST_FAILEDFailed sending request to the backend provider or parsing provider’s response. Feel free to resend the request, it may be served by a different provider next time. You will not be charged for the failed request.
REQUEST_TIMED_OUTProvider did not respond in a timely manner. Feel free to resend the request, it may be served by a different provider next time. You will not be charged for the timed-out request.
CAPTCHAA CAPTCHA challenge was detected in the fetched page. Feel free to resend the request, it may be served by a different provider next time. You will not be charged for this request.
NO_RESOURCESCurrently no provider is able to accept your request. Feel free to resend the request. You will not be charged for the unhandled request.
NO_CREDITSYour account does not have enough credits to process the request. Please contact us for options.
INVALID_URLThe supplied URL is invalid. Make sure it includes the scheme (http:// or https://) and that it is properly encoded.

Credits API

 

Want to check your account’s remaining credits?

https://run.operia.io/KEY/credits/

 
Response:

Your remaining credits in USD.

Cost API

 

Each request to the Fetcher API costs credits. The exact cost varies on the cheapest price which we are able to obtain for your request at run time. Since the price varies often, it is recommended to sample the Cost API periodically.

https://run.operia.io/KEY/cost/google

 
Response:

The request price in USD for requested destination.

Statistics API

 

Show usage statistics. Notice that statistics may take a few minutes to update.

https://run.operia.io/KEY/statistics/

 
Parameters:
daysFilter statistics for the last X days (default=30)
pp=1Human readable output (“pretty print”)
 
Response:

A JSON formatted usage report, grouped by status code.

How to protect your API key

 

Since (most) requests to the API are performed using the HTTP GET method to a URL which includes your KEY, it’s relatively easy to expose it to unwanted parties. You should be aware of this when sharing constructed API links with peers.

 

Another point to consider is that most messaging platforms today attempt to generate preview of shared links, which would trigger a valid API call and charge credits from your account. For this reason it is recommended to avoid sending constructed API links which includes your KEY via these platforms.

 

If you believe your key has been compromised, please contact us right away and we will send you a new key.

 

A more secure authentication method also exists. If you’re interested in using it, please contact us.