Studio API

Find the technical explanation of the endpoints in the Studio API reference.

What is the Studio API?

The Studio API is a RESTful API which is used to

organize and manipulate projects and its targets
create wtc/wto files which can be used to create trackers in the Wikitude SDK with the JavaScript API
generate/publish a cloud archive to the cloud recognition service (image targets only)

Cloud Recognition

Wikitude Cloud Recognition is a cloud-based service which recognizes images sent from Android and iOS apps using the Wikitude SDK. Recognized images are tracked in the live camera feed and are used for implementing augmented reality experiences.

Terminology

Image Target: An image and its associated extracted data that is used to recognize an image.
Object Target: An object, which is created by a set of images and its associated extracted data that is used to recognize an object.
Target Collection: A TargetCollection encapsulates a set of Targets. It is like a directory, which contains all your images/objects used for recognition. The Wikitude SDK can work with two different sorts of TargetCollections
- On-device Target Collection: for image targets, a static wtc file containing the extracted data of your images. Can consist of up to 1,000 images. For object targets, a static wto file which may contain up to 10 different objects.
- Cloud Target Collection: An image target collection stored on the Wikitude server. See Cloud Archive below.
Cloud Archive: An archive stored on the server, optimized for cloud-based image recognition. It is generated from a TargetCollection and is used in combination with the Wikitude SDK AR.CloudRecognitionService.
ImageTracker: Instead of analyzing and computing the live camera feed directly on the device like the combination of AR.ImageTracker and AR.TargetCollectionResource, the combination of AR.ImageTracker and AR.CloudRecognitionService will send the image(s) taken by the camera to the Wikitude Cloud Recognition server. The server will then try to match the image with your targets in the specified cloud archive. Besides the benefit of searching in large image database using the AR.CloudRecognitionService instead of AR.TargetCollectionResource has also a positive impact on the general performance in most cases. Especially when using a large target collection and on older devices.
Manager API: A RESTful web API allowing developers to interact with the Cloud Recognition server for managing Targets/ObjectTargets, TargetCollections/ObjectTargetCollections and Cloud Archives. Only you as a developer uses this API. None of your users of your app shall interact with this API.
Client API: The Client API is the interface between the Wikitude SDK and the Cloud Recognition Service. The API itself is encapsulated in the Wikitude SDK class AR.CloudRecognitionService and not directly accessible. Calls on the client API are called Scans.
Region: Wikitude is providing several hosting locations for its Cloud Recognition services to cut down unwanted network latency. As a developer you need to choose on which Region you and your customers want to operate.

Service Regions and Base URL

This service is available world-wide and hosted in Europe/Ireland. For cloud-recognition relevant endpoints, including the Target and Target Collection creation, we still provide the service in the region Americas. We highly recommend using the Europe region since the Americas region is deprecated. We are working on optimizing performance on a global level. This will work out of the box for the region Europe. For now, note that Targets created in non-default regions are not replicated in Europe. E.g. A Target Collection created on Americas Service is not available in Europe. The servers for each region have separate dedicated domain names and therefore different configurations:

Region	Base URL for Manager API
Americas (deprecated)	`https://api-us.wikitude.com/cloudrecognition`
Europe	`https://api-eu.wikitude.com/cloudrecognition`

Preparation

Create a free Wikitude developer account or log-in if you are a returning developer
Get the API tokens for the Manager API and the Client API to start your project. Read more on authentication
Test the API for free using Wikitude's sample integrations
Once you finished your integration, purchase a commercial token.

First Steps and General Usage

Get familiar with the Manager API calls in this API Reference.
Create a first Target Collection using the Create Target Collection endpoint and note down the ID of the Target Collection
Create targets using the Create Target endpoint for that particular Target Collection
Important: Generate a Cloud Archive for your Target Collection
Go to the Wikitude SDK and create an Android or iOS project
Use the Client API token to authenticate your Android or iOS project
Use your Target Collection ID to recognize images

For more information on the available endpoints and how to work with the Manager API see the workflow section.

Instead of creating a TargetCollection, adding one or more Targets, and generating a Cloud Archive by calling the REST API, the Wikitude Targetmanager can be used to perform these steps (1-4) in the browser alternatively.

In case you would like to immediately test the API calls we recommend the tool Postman. It helps you to quickly construct the requests and analyze the responses.

Authentication

The Cloud Recognition Service knows two authentication tokens, that you need to work with the service.

Manager API token You need this token to authenticate yourself against the RESTful Manager API. The Manager API is used to create, add and delete targets and target collections. The token identifies your developer account. Calls to the Manager API do not count towards your quota limits.
Client API token You need this token to authenticate calls from the Wikitude SDK to the Cloud Recognition services. It validates calls as legitimate. The token is bound to your developer account. Calls from the Wikitude SDK to the service with a wrong or missing token can not access your target collections.

Authentication on the Manager API

The Manager API token must be added to each call towards the Wikitude Cloud Recognition Manager API. The token authenticates the user account that is using the API.

Authentication on the Client API

The Client API token and the Group ID must be added to your app project using the Wikitude SDK. The token is needed additionally besides the SDK license key when working with the AR.CloudRecognitionService class. The Group ID helps us with load-balancing your calls and providing a better service overall. It was introduced with SDK 8.0 and is mandatory since then. It's part of the Client API and needs to be added to your tracker.

Quota and Limits

General Upload Limit

The Wikitude Cloud Recognition will not accept images bigger than 1024kB (1 MB). Trying to upload images exceeding this file size will result in a HTTP status code 400 together with an error message FILE_SIZE_LIMIT_EXCEED.

Limits for the Wikitude Cloud Recognition Service

There are two main limitations for the Wikitude Cloud Recognition service that you need to be aware of:

Targets Your token has a certain number of targets that you can upload and store on the cloud service under your developer account. The limit is always counted for your entire developer account and not for a single target collection. The service is not counting single uploads, but how many targets are currently stored in target collections under your account.
Scans Scans are in effect calls from the Wikitude SDK via the Client API to the Cloud Recognition servers. A commercial license contains 1,000,000 scans per month per developer account. Note: When using Continuous Search mode multiple calls are made to the server.

Maximum Number of Targets in a Target Collection

A target collection can't exceed 50,000 targets.

Free Trial License for Cloud Recognition

Wikitude provides a trial token for each developer account to try out the Cloud Recognition for free. This trial token has set a quota limit that allows developers to try and test the functionality of the service. Limitations for trial accounts

Targets: 50,000
Scans: 1,000 per month

To get your trial token for the REST API, please visit the License page. The trial token is directly integrated into the Studio Manager.

Commercial Licenses

For production systems, we offer commercial licenses with various quota limits for purchase.

Studio API Clients

You can find automatically generated clients to communicate with our API endpoints on our Studio API reference page. Refer to the included README-markdown file on how to incorporate the libraries in your projects and your associated programming language.

Keep in mind that a Manager API token is mandatory to send requests through our API clients, which is part of the Enterprise subscription. To generate a Manager API token, please get in contact with us via info@wikitude.com.

General Response Structure

Response Codes

The response code determines whether a request was successful. Any successful call will respond with code 200 ("OK") or 204 ("No content"). In case of an error, a different response code is used, along with an error message (see below). Each API enpoint specifies the error types it may return.

Response

Three main kinds of JSON objects are used in the endpoints:

An Image/Object Target or an Array of Targets
A Image/Object Target Collection or an Array of Target Collections
An Error

Each particular API specifies its response structure.

Image Target Collection

An Image TargetCollection contains the following properties:

id (String): An ID that uniquely identifies the Target Collection
name (String): The Name of the Target Collection, as defined by the user
creDat (Number): A timestamp when the Target Collection was created (as returned by JavaScript's Date.now function)
modDat (Number): A timestamp when the Target Collection was last modified
metadata (JSON): Arbitrary JSON data that is stored together with the TargetCollection.
wtc (Array): An array of wtc files that were generated out of the Target Collection already. Every element contains "version", "url", "nrOfTargets" and "creDat". Only latest wtcFiles are stored, list is cleared on target modifications. Check "Generate WTC File" Endpoint for more details

Image Target

An Image Target contains the following properties:

id (String): An ID that uniquely identifies the Target
name (String): The Name of the Target, as defined by the user
imageUrl (String): The URL pointing to the original, uncompressed and uncropped Target binary file
thumbnailUrl (String): The URL pointing to a thumbnail representation of the Target
rating (Number): The rating (from 0 to 3) of the Target
distribution (Number): The distribution rating (from 0 to 3) of the Target
fileSize (Number): The file size of the original Target binary image file in bytes
physicalHeight (Number): The physical (real world) height of the target. For more information check class CloudTracker of the Wikitude SDK
creDat (Number): A timestamp when the Target was created
modDat (Number): A timestamp when the Target was last modified
metadata (JSON): Arbitrary JSON data that is stored together with the target.

Object Target Collection

An Object Target Collection contains the following properties:

id (String): An ID that uniquely identifies the Target Collection
name (String): The Name of the Target Collection, as defined by the user
creDat (Number): A timestamp when the Target Collection was created
modDat (Number): A timestamp when the Target Collection was last modified
metadata (JSON): Arbitrary JSON data that is stored together with the TargetCollection.
wto (Array): An array of wto files that were generated out of the Target Collection already. Every element contains "version", "url", "nrOfTargets" and "creDat". Only latest wtcFiles are stored, list is cleared on target modifications. Check "Generate WTO File" Endpoint for more details

Object Target

An Object Target contains the following properties:

id (String): An ID that uniquely identifies the Target
name (String): The Name of the Target, as defined by the user
resource (JSON): Contains attributes uri and fov, the URLs to the image assets and the field of view.
thumbnailUrl (String): The URL pointing to a thumbnail representation of the Target
rating (Number): The rating (from 0 to 3) of the Target
creDat (Number): A timestamp when the Target was created (as returned by JavaScript's Date.now() function)
modDat (Number): A timestamp when the Target was last modified (as returned by JavaScript's Date.now() function)

Error

In case the server cannot serve the request successfully, it responds with an error object, consistaining of the following properties:

code (Number): An internal error code that further specifies the error (currently, we copy the response code from the HTTP response in here, but we might want to change this in the future)
reason (String): A short title that tells the developer what has gone wrong
message (String): A more detailed explanation of what has gone wrong, and what needs to be done to prevent the error.
cause (JSON): The exact cause of the error
moreInfo (String): Optional more information how to resolve the error

Example

{
 "code": 400,
 "reason": "HEADER_PROPERTY_MISSING",
 "message": "One or more mandatory header properties are missing.",
 "cause": [
    {
        "item": "X-Token",
        "value": ""
    }
 ],
 "moreInfo": "http://www.wikitude.com/developer/documentation/cloud"
}

User Manual

Wikitude Studio