How to access the API

Calaméo provide a quick and easy to use RESTful API.
Making a request against the Calaméo API requires only a few easy steps:
  1. Select an API key
  2. Select an API method
  3. Make the request
  4. Parse the response
  5. Handle errors

Step 1: Select an API key

If you have not done it already, create an API key for your account (see Get an API key for more detail). An API key provides two information that should remain confidential at all time: a public key and a secret key (click on See more to display an API secret key):

Note: Do not post either the public or secret key on the support community or anywhere else in order to preserve your account's data integrity.

Step 2: Select an API method

The Calaméo API provides many methods to manage subscribers, fetch publications listings, etc. According to the method you select you will have to send your request to the correct endpoint. Almost all requests must be made to the following endpoint:

http://api.calameo.com/1.0

You can send the request parameters as part of the URL (GET) or inside the HTTP body (POST).

When dealing with document uploads, the appropriate endpoint is:

http://upload.calameo.com/1.0
Note: When uploading files you must use HTTP POST with encoding multipart/form-data.

Step3: Make the request

To perform an action against the Calaméo API, some parameters are always required:

Name Type Description
apikey[required] string API public key. The request will be carried out on behalf of the associated account.
signature[required] string Signature of the request. See how to sign your requests.
action[required] string Method to execute against the API platform.

Sending the parameters using HTTP GET or HTTP POST request does not impact the response.

http://api.calameo.com/1.0?apikey=<apiKey>&signature=<signature>&action=<method>&...

Some optional parameters may also be included:

Name Type Description
expires timestamp An UNIX timestamp specifying an expiration date and time for the request.
output string Format of the response. Either XML (default), JSON or PHP. 
http://api.calameo.com/1.0?apikey=<apiKey>&signature=<signature>&action=<method>&expires=<expires>&output=<output>&...
Note: All data sent to the Calaméo API must be UTF-8 encoded. And all data returned by the API will be UTF-8 encoded. Submitting data in a different encoding may result in incorrect stored values.

Step 4: Parse the response

The response from the API platform has the same structure for XML, JSON and PHP formats:

Name Type Description
requestid string Unique ID of the request.
requests integer Total number of requests made during the last hour (for rate limiting).
status string Status of the response. Either ok (success), error (failure).
content mixed Response payload
Note: The HTTP status code from the API platform is always 200 OK even if the request fails.
Here are some examples of response in each output formats:
<response> <requestid>...</requestid> <requests>...</requests> <status>ok</status> <content> <!-- payload --> </content> </response>
{ "response": { "requestid": ..., "requests": ..., "status": "ok", "content": ... } }
[ "response" => [ "requestid" => ..., "requests" => ..., "status" => "ok", "content" => ... ] ]

Step 5: Handle errors

If the API platform encounters a problem, the response status is then error and the content object is replaced with a simple error object containing the error code and a message explaining what went wrong.

See the complete error codes table.

Here are some examples of error in each output formats:
<response> <requestid>...</requestid> <requests>...</requests> <status>error</status> <error> <code>...</code> <message>...</message> </error> </response>
{ "response": { "requestid": ..., "requests": ..., "status": "error", "error": { "code": ..., "message": ... } } }
[ "response" => [ "requestid" => ..., "requests" => ..., "status" => "error", "error": [ "code" => ..., "message" => ... ] ] ]