Images

This section will explain how to create and retrieve an Image.

They say an image is worth a thousand words, right? With our API, you can upload images and use them to showcase your products. We use Amazon Web Services to store and serve them through a CDN, so you'll get a good response time and your images stay secure.

Should I set my image to public or private? Public images can be used for products, resources, user avatars, etc. Private ones could be used for bills or invoices, for example.

Image Object

Attribute

Type

Description

original_name

string

The image's name.

original_file_type

string

The file type of the image uploaded.

public

boolean

A boolean indicating if the image is public. The default value is True.

public_url

string

The full URL of the public image.

description

string

The image's description.

title

string

The image's title.

url

string

A relative path that you can use to retrieve images. See example below. Whenever possible, use the public_url instead.

Create an Image

To create an Image object , which can be associated with products, you can either upload the image to us or supply us with a public URL. We recommend you only link to images and URLs you own and have control over.

Create an Image from a File

Parameters
Request
Response

Body Parameters

Type

Description

image

bytes

The image you want to upload.

metadata

object

Allows you to add some metadata for the image.

public

boolean

A boolean indicating if the image is public. The default value is True.

title

string

Gives a title to the image.

description

string

Gives a description to the image.

POST /images HTTP/1.1
Content-Type: image/jpeg
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"image": <image_bytes>,
"metadata": {
"key": "value"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "5964a0ead57ke2034200f4e2"},
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"created": {"$date": 1499767018360},
"deleted": false,
"modified": {"$date": 1499767018360},
"original_name": "file_name",
"original_file_type": "jpg",
"url": "image_url",
"public_url": "image_url/path",
"public": true,
"metadata": {
"key": "value"
}
}

Create an Image from a URL

Parameters
Request
Response

Body Parameters

Type

Description

public_url

string

The public URL you want to use for your image.

public

boolean

A boolean indicating if the image is public. The default value is True.

title

string

Gives a title to the image.

description

string

Gives a description to the image.

POST /images HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"public_url": "https://images.pexels.com/photos/22221/pexels-photo.jpg",
"metadata": {
"key": "value"
},
"title": "happy",
"description": "makes your day better"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "5964a0ead57ke2034200f4e2"},
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"created": {"$date": 1499767018360},
"deleted": false,
"modified": {"$date": 1499767018360},
"public_url": "https://images.pexels.com/photos/22221/pexels-photo.jpg",
"public": true,
"metadata": {
"key": "value"
},
"title": "happy",
"description": "makes your day better"
}

Get an Image by URL

The recommended way to get images is by the image's relative URL, e.g. {IIMG_ID}/name, provided in the Image object. However, if you prefer, you can see an example of how to retrieve images using the relative URL below.

Parameters
Request
Response

Body Parameters

Type

Description

url

string

The image's URL.

GET /images/<url> HTTP/1.1
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{}
HTTP/1.1 200 OK
Content-Type: image/jpeg
Cache-Control: public, max-age=31536000
Content-Length: 52204