API
Documentation

Introduction

This is the API documentation for imagefactory.io.

The API is currently in beta and is subject to change.

Setup

To use the API, you will first need to register for an account. You can register for an account by visiting the Register page.

Once you have registered, you will need to create an API token. You can view a guide on how to create an API token by visiting the Creating API Tokens page.

Webhooks

Webhooks are a way to receive notifications when an image is generated. Depending on how busy servers are, how complex the theme is to render and other factors, images can take up to 30 seconds to be generated. We cannot keep connections open for a long period of time for every request as this would be very taxing on our servers. So webhooks allow us to tell you when an image has completed rendering.

Signing Webhooks

We sign our webhook calls for added security, so you know that requests are coming from us and not another party. A secret signing key is given when setting up an API key.

We will add a header called `Signature` that will contain a signature the receiving app can use to make sure the payload hasn't been tampered with.

The signature is calculated by using the `sha256` algorithm where the response body is the hash payload data and the webhook secret key is the key.

Lifecycle

The request lifecycle is as follows:

1. The user makes a request to the API
2. The API receives the request and validates it
3. The API adds the request to the queue
4. The API sends a response saying the request has been successful and a uuid is given to track the request
5. The API generates the image from the queue
6. The API upload the image to a CDN
7. The API calls the URL with a post request to the webhook URL with a link to the image and the reference UUID