Restful API
API
Introduction
Our RESTful API lets you programatically create projects and products (360° views), as well as list existing projectss and products.
The following guide will go through the endpoints that are required to create a 360° view.
It consists of:
- Create a project
- Create a product (360° view)
- Upload images
- Finish upload
- Embed
- List all products (360° views)
- List all projects
- List all products for a given project
- Update a product
- Delete a product
- Download a product's source files
Furthermore, to list projects and products:
Additional API endpoints:
1. Create a project
All products (360° views) are grouped into projects. In order to create a product, you must first create a project and obtain a project UUID.
POST https://app.imajize.com/api/v2/projects
Params
-
title
Project title
Example
curl -u "USER:PASSWORD" -X POST -H "Content-Type: application/json" -H "Accept: application/json" "https://app.imajize.com/api/v2/projects" -d ' { "title": "Model cars" }'
In return, you'll receive a JSON with the project credentials. Take special note of the project UUID, you'll need it in the next step.
Example
{ "uuid": "sAQizc_u9gM", "title": "Model cars", "created_at": 2014-06-24T07:23:51.071Z }
2. Create a product (360° view)
Create a product and customize the viewer settings.
POST https://app.imajize.com/api/v2/products
Params
-
title
Title -
sku
SKU -
manufacturer
Manufacturer name -
year
Year -
project
Project UUID -
images
Number of images ("1" for video uploads)
Example
curl -u "USER:PASSWORD" -X POST -H "Content-Type: application/json" -H "Accept: application/json" "https://app.imajize.com/api/v2/products" -d ' { "title": "VW van", "sku": "10023", "manufacturer": "Lego", "year": "2013", "project": "sAQizc_u9gM", "images": 24 }'
In return, you'll receive a JSON with the credentials needed to upload the images.
Example
{ "uuid": "123456789", "title": "VW van", "path": "123456789/00000/1-rotation/row-1", "policy": "jAwMFonLAogICAg...", "signature": "GP35g00a3NsILoIf3...", "hostname": "upload.imajize.com", "access_key_id": "KTFSMTRXEMSGR...", "acl": "private" }
3. Upload images
Upload the images to S3.
Make sure that the image's file names are sortable, as this will later provide the order for the 360 view.
https://HOSTNAME where HOSTNAME is returned by the previous call's JSON object.
Params
-
key
PATH/FILENAME -
acl
ACL -
AWSAccessKeyId
ACCESS_KEY_ID -
Policy
POLICY -
Signature
SIGNATURE -
Content-Type
image/jpeg, video/mp4, etc. -
file
PATH_TO_FILE
Example
curl -s \ -F "key=123456789/00000/1-rotation/row-1/vw-van-01.jpg" \ -F "acl=private" \ -F "AWSAccessKeyId=KTFSMTRXEMSGR..." \ -F "Policy=jAwMFonLAogICAg..." \ -F "Signature=GP35g00a3NsILoIf3..." \ -F "Content-Type=image/jpeg" \ -F "file=@360-views/model-cars/vw-van/vw-van-01.jpg" \ https://$hostname
Repeat this step for each single image.
4. Finish upload
Notify Imajize that the upload to S3 has completed.
POST https://app.imajize.com/api/v2/products/UUID/uploaded
Params
-
none
Example
curl -u "USER:PASSWORD" -X POST -H "Content-Type: application/json" -H "Accept: application/json" "https://app.imajize.com/api/v2/products/123456789/uploaded"
5. Embed
Retrieve an iframe embed URL for a 360° view.
GET https://app.imajize.com/api/v2/products/UUID/embed
Params
-
type
"iframe" or "responsive" -
width
maximum width -
height
maximum height
Note: if type "responsive" is chosen, width and height will be ignored as the embed link adjusts its size responsively.
Example
curl -X GET -H "Accept: application/json" "https://app.imajize.com/api/v2/products/123456789/embed?type=iframe&width=640&height=480"
In return, you'll receive an iframe embed link to paste into a website.
Example
<iframe width="640" height="480" src="http://embed.imajize.com/PQUDbEJO_N4" frameborder="0" scrolling="no" style="background-color: #fff" allowfullscreen></iframe>
Complete Upload Example
The following bash script will upload all images found in the current working directory. Use the first 5 lines to define the user and password for your account, the project UUID, the title for the product to be created, and the host for the API.
Depending on your setup, you might have to install JQ ( https://jqlang.github.io/jq/)
user=<USER> password=<PASSWORD> project=<PROJECT_UUID> title=<PRODUCT_TITLE> host="https://app.imajize.com" count=$(ls -1q * | wc -l) params='{ "title": "'$title'", "project": "'$project'", "images": "'$count'"}' command="curl -u '"$user":"$password"' -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' '"$host"/api/v2/products' -d '"${params}"'" result=$(eval $command) hostname=$(echo $result | jq -r '.hostname') uuid=$(echo $result | jq -r '.uuid') policy=$(echo $result | jq -r '.policy') signature=$(echo $result | jq -r '.signature') directory=$(echo $result | jq -r '.path') for f in * ; do echo "Uploading $f"; curl \ -F "key=$directory/$f" \ -F "acl=private" \ -F "AWSAccessKeyId=AKIAJLYJVDJ7RMESCYNA" \ -F "Policy=$policy" \ -F "Signature=$signature" \ -F "Content-Type=image/jpeg" \ -F "file=@$f" \ https://$hostname ; done curl -u "$user:$password" -X POST -H "Content-Type: application/json" -H "Accept: application/json" "$host/api/v2/products/$uuid/uploaded"
Listing products (360° views) and projects
6. List all Products (360° views)
Retrieve a list of all 360° views.
GET https://app.imajize.com/api/v2/products
Params (optional)
- title
- manufacturer
- sku
- year
Example 1: filter by year
curl -u "USER:PASSWORD" -X GET -H "Accept: application/json" "https://app.imajize.com/api/v2/products?year=2000"
Example 2: no filter
curl -u "USER:PASSWORD" -X GET -H "Accept: application/json" "https://app.imajize.com/api/v2/products"
...returning a list of products, e.g.
[{"uuid":"123456789","title":"My product title","sku":"SKU-0001","manufacturer":"","year":null,"project":"987654321","created_at":"2019-06-03T14:11:42.410Z"}, {...}]
7. List all projects
Retrieve a list of all projects.
GET https://app.imajize.com/api/v2/projects
Params
- No params
Example
curl -u "USER:PASSWORD" -X GET -H "Accept: application/json" "https://app.imajize.com/api/v2/projects"
...returning a list of projects, e.g.
[{"uuid":"123456789","title":"My project title","created_at":"2019-06-03T14:11:42.410Z", products: 5}, {...}]
8. List all products for a given project
Retrieve a list of all products within a certain project.
GET https://app.imajize.com/api/v2/projects/UUID
Params (optional)
- title
- manufacturer
- sku
- year
Example 1: filter by year
curl -u "USER:PASSWORD" -X GET -H "Accept: application/json" "https://app.imajize.com/api/v2/projects/PQUDbEJO_N4?year=2000"
Example 2: no filter
curl -u "USER:PASSWORD" -X GET -H "Accept: application/json" "https://app.imajize.com/api/v2/projects/PQUDbEJO_N4"
... returning a list of products, e.g.
[{"uuid":"123456789","title":"My product title","sku":"SKU-0001","manufacturer":"","year":null,"project":"987654321","created_at":"2019-06-03T14:11:42.410Z"}<br>
9. Update an existing product (360° view)
Updates an existing product, with the option to upload new images.
PATCH https://app.imajize.com/api/v2/products/123456789
Params
title
Titlesku
SKUmanufacturer
Manufacturer nameyear
Yearimages
Number of images (optional, to indicate a reupload)
Example
curl -u "USER:PASSWORD" -X PATCH -H "Content-Type: application/json" -H "Accept: application/json" "https://app.imajize.com/api/v2/products/123456789" -d ' { "title": "VW van", "sku": "10023", "manufacturer": "Lego", "year": "2013", "images": 24 }'
If you provided a value for "images", please proceed from 2. Create a product
Otherwise, you'll receive a JSON object, containing either {notice: "OK"}
or {errors: [...]}
.
10. Delete a product
Deletes a product.
DELETE https://app.imajize.com/api/v2/products/123456789
Params
- No params
Example
curl -u "USER:PASSWORD" -X DELETE -H "Accept: application/json" "https://app.imajize.com/api/v2/products/123456789"
You'll receive a JSON object, containing either {notice: "OK"}
or {errors: [...]}
.
11. Download a product's source files
Downloads all source files for a product.
GET https://app.imajize.com/api/v2/products/123456789.zip
Params
- No params
Example
curl -u "USER:PASSWORD" -X GET -H "Accept: application/zip" "https://app.imajize.com/api/v2/products/123456789.zip"
You'll receive a ZIP-file if successful, or a JSON containing {errors: [...]}
.