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.
You can only set images to be private programmatically. Images added by an admin on the dashboard will automatically be set to public
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
Parameters
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.
Request
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"
    }
}
Response
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
Parameters
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.
Request
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"
}
Response
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. {IMG_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
Parameters
Body Parameters
Type
Description
url
string
The image's URL.
Request
GET /images/<url> HTTP/1.1
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
HTTP/1.1 200 OK
Content-Type: image/jpeg
Cache-Control: public, max-age=31536000
Content-Length: 52204

Nuts & Bolts - Previous

Addresses

Next - Nuts & Bolts

Templates and Attributes

Last updated 1 month ago

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.

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.

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.