Current Version

The current version of the API is v1. This is also the default version if no version is specified. A specific version should be specified using the x-img-api-version HTTP header.

As new versions of the API are released, the default version will change. So it is recommended to specify the desired version using the x-img-api-version HTTP header.


All API access is over HTTPS. The base URL for all request is http://img.local:2001.

Unsecure requests made to http:// (note the missing s) will be dropped. These unsecure requests will not be redirected to https://.


All dates are represented in ISO 8601 format e.g. 2011-07-10T18:35:16-0800.


Requests are authorized using your API key. API keys can be specified in the following ways:


Every image has an ID assigned by Img. These IDs are 16 character strings made up of lowercase ASCII letters and digits e.g. 7hci0z8txgvzkgkl.

In the future, assigned IDs may be as long as 48 characters.

You can optionally assign an image a custom ID. Custom IDs must be unique across all images in your account and must contain only

Custom IDs can be up to 64 characters in length.

Supported image formats


There are three considerations when creating images:


POST /image
You may specify a custom ID. See below for instructions.

File Upload



Receive ID, then Upload

Uploading images can take a long time. Because of this, we offer an option where one can begin serving images even before an image is completely uploaded (of course, the request will block until the image is completely uploaded). To do this, one must

  1. Get an pre-allocated ID (custom or assigned)
  2. Use this ID to build an image URL (see Serving Images below)
  3. Upload the image using the ID from step 1

Get an pre-allocated ID

GET /image/new-id
GET /image/new-id/{custom-id}
Returns an ID that can be used to create an image.
The first endpoint /image/new-id will return an assigned ID. the second endpoint /image/new-id/{custom-id} will allow one to use a custom ID.

Upload an image with a pre-allocated ID

POST /image/{id}
POST /image/{domain}/{custom-id}
{id} or {custom-id} must be an pre-allocated ID received from one of the GET /image/new-id or GET /image/new-id endpoints.

Serving Images

Images are served using a URL generated from the image's ID (assigned or custom). To generate an image URL, use the following patterns

Transformed Images


DELETE /image/{id}
DELETE /image/{domain}/{customId}
Name Required? Type Description
url Yes String Publicly accessible URL of image.
my-id No String User specified ID

Get ID

GET /id
Returns an ID that can be used to create an image. (An ID is a 16 character string made up of lowercase ASCII letters and digits.)