API Reference

Version: 2.2.1

13-04-2023

Introduction

This document details the usage of the SpotLight public API.

Applications Available

Gallery – Generate packs of predefined images to support your brand
Brochure – Generate high quality personalised PDFs for customers
Web – Generate a personalised microsite for your customers from a pre-defined template
Video – Generate a video based on a pre-defined sequence template created in the 'Take' application
AR Model – Generate a digital twin of your asset for use in AR experiences

Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

API Fundamentals

The API is available at https://spotlightsuite.com. It follows the JSON API specification.

The API has the following stipulations:

All requests MUST use HTTPS, the API is not available over vanilla HTTP
All routes MUST provide an authorisation token via the x-access-token header
All routes MUST provide a team identifier via an x-team-id header unless explicitly documented as not required for the specific route
Users MUST have API permissions on the given team to perform requests
All routes are prefixed with /api/external/
All Order routes are prefixed with /api/external/orders/
All requests and responses MUST use the application/vnd.api+json content type
All requests support a charset value of UTF-8. Any other value will be rejected. If charset is omitted, it is assumed to be UTF-8

Responses

All routes abide by the JSON API spec, i.e., a response MAY contain a data or errors top level property but will never contain both.

Additionally responses MAY include an OPTIONAL top level meta field. This field, if present, MAY include a non-empty list of warnings. It is recommended that any returned warnings are logged at 'warning' level within the client's application backend. It is the integrators responsibility to monitor these warnings and update their implementation accordingly.

An example of a warning could be advance notice of a deprecation - and has the structure below.

    {
        "data": {
            "id": "5c6acb07ec045209437f1f01",
            "items": [],
            "status": "pending",
            "timestamp": "2019-02-18T15:11:03.591Z",
            "transaction": "5c6acb07ec045209437f1f02"
        },
        "meta": {
            "warnings": [
                {
                    "id": "4059118ff2441cec577a07737c1e819e",
                    "code": "API_MISSING_TEAM",
                    "title": "x-team-id missing from request headers",
                    "detail": "Access to the API endpoint '/external/orders/shutter-packs' without passing an x-team-id will be deprecated after 31-10-2022 and result in a 400 error",
                    "links": {
                        "about": "https://help.spotlightsuite.com/external-api"
                    }
                }
            ]
        }
    }

Note: Warnings may be issued in addition to Errors.

Routes

The following section details the usage of each route and its expected response from requests.

Teams

List team memberships

Note: This route is one of the few routes within the API which the header x-team-id is OPTIONAL. As this route used to interrogate which teams are available to the current x-access-token bearer.

URL

/api/external/teams

Method

GET

Query Parameters

none

Data Parameters

none

Headers

Content-Type: application/vnd.api+json
x-access-token: <YOUR_TOKEN>

Success Response

Code: 200 OK
Headers:

    Content-Type: application/vnd.api+json

Content:

    {
        "data": [
            {
                "teamId": "5ea96707dd4089351817c0dd",
                "teamOem": "zerolight",
                "teamName": "ZeroLight PreLive"
            },
            {
                "teamId": "61c0d89eee02c20fed2eefdd",
                "teamOem": "zerolight",
                "teamName": "ZeroLight Live"
            }
        ]
    }

The client application selects one of the teams and passes that team id in subsequent requests using the x-team-id header.

Error Response

If, for example x-access-token is not provided:

Code: 401 Unauthorized
Headers:

    Content-Type: application/vnd.api+json

Content:

    {
        "errors": [
            {
                "title": "User is not authorised",
                "id": "05500c036ef9952365859a849c36e1ca"
            }
        ],
        "message": "User is not authorised"
    }

Team details

Returns details about the specified team - including a list of assets (cars) available on this team

URL

/api/external/teams/<WORKING_TEAM_ID>

Note: For this route, the URL parameter <WORKING_TEAM_ID> MUST match the x-team-id header.

Method

GET

Query Parameters

none

Data Parameters

none

Headers

Content-Type: application/vnd.api+json
x-access-token: <YOUR_TOKEN>
x-team-id: <WORKING_TEAM_ID>

Success Response

Code: 200 OK
Headers:

    Content-Type: application/vnd.api+json

Content:

    {
        "data": {
            "teamId": "5ea96707dd4089351817c0dd",
            "teamOem": "zerolight",
            "teamName": "ZeroLight PreLive",
            "cars": [
                {
                    "uid": "pagani%20huayra%202015/zerolight_prelive/zerolight%2Fprelive/",
                    "manufacturer": "pagani",
                    "model": "huayra",
                    "year": "2015",
                    "name": "pagani huayra 2015",
                    "displayName": "pagani huayra"
                },
                {...}
            ]
        }
    }

Order Creation

URL

/api/external/orders/create

Method

POST

Headers

Content-Type: application/vnd.api+json
x-access-token: <YOUR_TOKEN>
x-team-id: <WORKING_TEAM_ID>

Query Parameters

none

Data Parameters

The following parameters can be defined in the data request object.

Parameter	Type	Description	Required
type	`string`	Order type (see Order Types)	`true`
car	`string`	Asset UID string – representing manufacturer, model & year	`true`
prcodes	`string`	Comma separated string. `shortcode` is ignored if this field is provided	`false`
shortcode	`string`	Must be provided if `prcodes` field is omitted.	`false`
callback	`string \| Object`	See section regarding Order Callbacks	`false`
. . .	`...`	Additional parameters may be required depending on the specified type	`false`

Example call using JavaScript

const response = await fetch('https://spotlightsuite.com/api/external/orders/create', {
    method: 'POST',
    headers: new Headers({
        'Content-Type': 'application/vnd.api+json',
        'x-access-token': '<YOUR_TOKEN>',
        'x-team-id': '<WORKING_TEAM_ID>',
    }),
    credentials: 'include',
    body: JSON.stringify({
        data: {
            type: 'frame_pack',
            car: 'volkswagen%20golf_mp1%202024',
            prcodes: 'F14 0E0E,GPC0PC0,GPGMPGM,GPGOPGO,GPGYPGY,GPH8PH8,GPH9PH9',
            template: 'frame-pack-volkswagen-golf_mp1-2024-pilot',
        },
    }),
});

// if request was unsuccessful
if (response.body.errors) {
    // parse errors
    return;
}

console.info(response.data.id); // '5af2f55e8c38f758afef6ef7'

Example Success Response

Code: 202 Accepted
Headers:

    Content-Type: application/vnd.api+json

Content:

    {
        "data": {
            "id": "5c6acb07ec045209437f1f01",
            "items": [],
            "status": "pending",
            "timestamp": "2019-02-18T15:11:03.591Z",
            "transaction": "5c6acb07ec045209437f1f02"
        }
    }

Notes

A successful response returns a 202 Accepted HTTP status not 200, this is because the order has been accepted for processing but doesn't instantly complete.

Example Error Response

If, for example, car is not provided:

Code: 400 Bad Request
Headers:

    Content-Type: application/vnd.api+json

Content:

    {
        "errors": [
            {
                "title": "Car is invalid",
                "detail": "Invalid property 'car' (string) is required, got 'undefined'",
                "id": "7fe691b0-5838-11e8-a129-db216eb107b5"
            }
        ]
    }

Order Types

Gallery (type=`frame_pack`)

Generate packs of predefined images to support your brand.

Data Parameters

Parameter	Type / Value	Description	Required
type	`frame_pack`	Order type	`true`
car	`string`	Asset UID string – representing manufacturer, model & year	`true`
prcodes	`string`	Comma separated string. `shortcode` is ignored if this field is provided	`false`
shortcode	`string`	Must be provided if `prcodes` field is omitted.	`false`
template	`string`	Template UID	`true`

Web (type=`microsite`)

Generate a personalised microsite for your customers from a pre-defined template

Data Parameters

Parameter	Type / Value	Description	Required
type	`microsite`	Order type	`true`
car	`string`	Asset UID string – representing manufacturer, model & year	`true`
prcodes	`string`	Comma separated string. `shortcode` is ignored if this field is provided	`false`
shortcode	`string`	Must be provided if `prcodes` field is omitted.	`false`
template	`string`	Template UID	`true`
parameters	`Array`	List of template mapping objects, see Customising Templates	`false`

Video (type=`bespoke_video`)

Generate a video based on a pre-defined sequence template created in the 'Take' application.

Data Parameters

Parameter	Type / Value	Description	Required
type	`bespoke_video`	Order type	`true`
car	`string`	Asset UID string – representing manufacturer, model & year	`true`
prcodes	`string`	Comma separated string. `shortcode` is ignored if this field is provided	`false`
shortcode	`string`	Must be provided if `prcodes` field is omitted.	`false`
template	`string`	Template UID	`true`

Brochure (type=`brochure`)

Generate high quality personalised PDFs for customers

Data Parameters

Parameter	Type / Value	Description	Required
type	`brochure`	Order type	`true`
car	`string`	Asset UID string – representing manufacturer, model & year	`true`
prcodes	`string`	Comma separated string. `shortcode` is ignored if this field is provided	`false`
shortcode	`string`	Must be provided if `prcodes` field is omitted.	`false`
template	`string`	Template UID	`true`
renderQualityPreset	`string` `enum`	Output quality, `['low', 'medium', 'high']`	`false`
parameters	`Array`	List of template mapping objects, see Customising Templates	`false`

Render Quality Presets

The renderQualityPreset property defines the PPI of the output, it defaults to low.

The presets are as follows:

ID	PPI	Notes
`low`	`96`	Default, web quality, jpg
`medium`	`150`	Medium quality, jpg
`high`	`300`	Print quality, png, ray traced reflections

AR Model (type=`bespoke_ar`)

Generate a digital twin of your asset for use in AR experiences

Data Parameters

Parameter	Type / Value	Description	Required
type	`bespoke_ar`	Order type	`true`
car	`string`	Asset UID string – representing manufacturer, model & year	`true`
prcodes	`string`	Comma separated string. `shortcode` is ignored if this field is provided	`false`
shortcode	`string`	Must be provided if `prcodes` field is omitted.	`false`
outputFormat	`string`	One of two file types (`glb` or `usdz`)	`true`
targetFileSizeMB	`number`	A number 1-50 representing MB	`false`

Order Callbacks (Webhooks)

It is possible to request that a webhook is hit on completion (success, failure, cancellation) of your order-request. This method of notification is preferred over polling the order status endpoint.

The callback entry is either a string or an Object. Specifying a string is the shortcut to use a simple GET request callback with no headers. The advanced method using an Object it is possible to specify either GET or POST https verbs, up to 5 headers and 2048 bytes of body data are permitted. The body data may be specified as a raw string or as an Object. The system will add an application/json content header if a body Object is specified.

The values for orderId and status are replaceable using template string syntax ("${orderId}" and "${status}"). These values are replaceable in the uri, and header and body values only (not keys). For security, no additional data is passed to the callback. Once the callback has been received the integration can query the SpotLight API with their authentication credentials to receive the full data for the completed order.

It is the integrator's responsibility to ensure the validity of the callback. And that the callback has not been spoofed from elsewhere on the internet. This can be achieved by passing and verifying a secret token used only for this purpose (the orderId is not sufficient on its own)

SpotLight will attempt to hit the callback one time only. It will log the status of the callback request into its logging system for debugging purposes.

Examples

In the following simple example the callback is a GET request with the secret and orderId in the uri.

{
    "data": {
        "type": "frame_pack",
        "car": "volkswagen%20golf_mp1%202024",
        "prcodes": "F14 0E0E,GPC0PC0,GPGMPGM,GPGOPGO,GPGYPGY,GPH8PH8,GPH9PH9",
        "template": "frame-pack-volkswagen-golf_mp1-2024-pilot",
        "callback": "https://my.webhookhandler.com/spotlight/order/${orderId}?secret=abcd1234abcd1234"
    },
}

In the following advanced example the callback is a POST request with a secret token in the header and both the orderId and status in the body.

{
    "data": {
        "type": "frame_pack",
        "car": "volkswagen%20golf_mp1%202024",
        "prcodes": "F14 0E0E,GPC0PC0,GPGMPGM,GPGOPGO,GPGYPGY,GPH8PH8,GPH9PH9",
        "template": "frame-pack-volkswagen-golf_mp1-2024-pilot",
        "callback": {
            "uri": "https://my.webhookhandler.com/spotlight/order",
            "method": "POST",
            "headers": {
                "x-secret": "abcd1234abcd1234"
            },
            "body": {
                "orderId": "${orderId}",
                "status": "${status}"
            }
        }
    }
}

Introduction​

Applications Available​

Conventions​

API Fundamentals​

Responses​

Routes​

Teams​

List team memberships​

URL​

Method​

Query Parameters​

Data Parameters​

Headers​

Success Response​

Error Response​

Team details​

URL​

Method​

Query Parameters​

Data Parameters​

Headers​

Success Response​

Order Creation​

URL​

Method​

Headers​

Query Parameters​

Data Parameters​

Example call using JavaScript​

Example Success Response​

Notes​

Example Error Response​

Order Types​

Gallery (type=frame_pack)​

Data Parameters​

Web (type=microsite)​

Data Parameters​

Video (type=bespoke_video)​

Data Parameters​

Brochure (type=brochure)​

Data Parameters​

Render Quality Presets​

AR Model (type=bespoke_ar)​

Data Parameters​

Order Callbacks (Webhooks)​

Examples​

Introduction

Applications Available

Conventions

API Fundamentals

Responses

Routes

Teams

List team memberships

URL

Method

Query Parameters

Data Parameters

Headers

Success Response

Error Response

Team details

URL

Method

Query Parameters

Data Parameters

Headers

Success Response

Order Creation

URL

Method

Headers

Query Parameters

Data Parameters

Example call using JavaScript

Example Success Response

Notes

Example Error Response

Order Types

Gallery (type=`frame_pack`)

Data Parameters

Web (type=`microsite`)

Data Parameters

Video (type=`bespoke_video`)

Data Parameters

Brochure (type=`brochure`)

Data Parameters

Render Quality Presets

AR Model (type=`bespoke_ar`)

Data Parameters

Order Callbacks (Webhooks)

Examples