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