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:

1. Create a project
2. Create a product (360° view)
3. Upload images
4. Finish upload
5. Embed

Furthermore, to list projects and products:


6. List all products (360° views)
7. List all projects
8. List all products for a given project

Additional API endpoints: 


9. Update a product
10. Delete a product
11. Download a product's source files

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 Title
• sku SKU
• manufacturer Manufacturer name
• year Year
• images 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: [...]}.