Introduction

cloudlayer.io is a service for helping you automate your document generation processes using our PDF Generation and Image Generation services.

In simple steps:

1. Create an account, or login.
2. Get your API Key from the Dashboard.
3. Find the API Endpoint you want to use.
4. Call the API using your API Key.

API Base URL - v2

https://api.cloudlayer.io/v2

info

There are some important but slight differences between v1 and v2. In addition, some default behaviors have changed. If you are currently using v1, please read about the changes in the changelog before switching to v2.

Authentication

cloudlayer.io authenticates your API requests using your account's API keys. If you don't include your key when making an API request or use an incorrect one, a 401 Unauthorized response gets returned.

To obtain your API Key, you will need to log into your account. Go to the API Management tab, and by default, a single API Key gets generated for you. Up to 5 API Keys are allowed at any given time.

Each API request will record the API Key used for that request, which can help you secure your keys and track their usage if you're using them from multiple locations.

Using Your API Key

The API Key needs to get added to the header of each request. The name of the header is X-API-Key and the value will be the key which begins with cl-.

API Key Example

X-API-Key: <YOUR-API-KEY>

Make a Test Request

curl --request GET \
  --url https://api.cloudlayer.io/v2/getStatus \
  --header 'x-api-key: <YOUR-API-KEY>'

If everything worked correctly, you should get the following JSON response back.

{ "status": "ok" }

note

Requests against informational endpoints such as this one do not count against your API Credits, but they follow the API Key rules with credit remaining and rate limits, so they act as a good test.

HTTP Status Codes

Code	Description
200	OK
201	Received when using the synchronous API call and successfully getting back a result.
202	Received when using the asynchronous API call and successfully getting back a result.
400	Bad request. Such as malformed JSON in the request, missing parameters, etc.
401	Unauthorized. Incorrect or revoked API Key or your account is delinquent and requires payment.
404	Not found. The endpoint path you are using is incorrect.
429	Too many requests. You have exceeded your request rate and need to slow your requests down.
500	Internal Server Error. An exception occurred while processing the request. Try it again or adjust the parameters.
503	Service Unavailable. Our service is down or experiencing trouble. Contact support if you continue to receive this status code.

Webhooks

A webhook is an external URL endpoint that can be sent data when a jobs status has changed to success or error.

Webhooks are especially useful when using async calls, you can send many async calls and then have your external service receive the webhook calls. To keep it simple all webhook calls follow the exact same format of the job response.

{
  "webhook": "https://<your_webhook_url>"
}

Testing Webhooks

An easy way to test a webhook is to use a service like Webook.Site (not affiliated).

1. Create an endpoint on Webhook.Site by visiting, you will get a unique workspace generated.
2. Copy the Your unique URL using the Copy to clipboard button.
3. In your request add the webhook parameter with this url as the value.
4. Submit the job.
5. When the job status changes to either success or error the webhook will receive a response.

info

Webhooks must be https endpoints.

Async & Sync

All calls made to the v1 API are synchronous by default. In v2 endpoints, all calls are asynchronous by default.

v1 Endpoints

If you're using the v1 endpoint and want to use asynchronous calls, you can pass the parameter async: true, which will force asynchronous calls.

Use Asynchronous Calls in v1 Endpoint

{
  "async": true
}

v2 Endpoints

If your using the v2 endpoint and want to use synchronous calls you can pass in async: false

Use Synchrounous Calls in v2 Endpoints

{
  "async": false
}