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...", "bucket": "imajize-production-source", "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://s3.amazonaws.com/BUCKET/
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://s3.amazonaws.com/imajize-production-source/
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>
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 POST -H "Content-Type: application/json" -H "Accept: application/json" "https://app.imajize.com/api/v2/products" -d ' { "uuid" : "123456789", "title": "VW van", "sku": "10023", "manufacturer": "Lego", "year": "2013", "project": "sAQizc_u9gM", "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
Deletes 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: [...]}
.