VuMark Generation Web API

The VuMark Generation Web API allows generating printable instances of a VuMark. These instances are delivered as a graphics file that encodes the instance ID provided with the generation request. This ID may be in one of several data formats.

To create VuMark instances, you will need to have a Vuforia Engine developer account, and a license for your app from the License Manager. Once you have created a license, go to the Target Manager and create a VuMark database and upload your VuMark template as an SVG file; this will provide you with a server-access key to authenticate your calls to the VuMark generation service.

See: How To Create a New VuMark Database

If you are yet to have made a VuMark template, consult the following articles on how to design one in Adobe Illustrator. 

See:

VuMark Design Guide

Designing a VuMark in Adobe Illustrator

How to Add a VuMark to a Database

API Specification 

Authentication

All requests to the VuMark Generation API need to be authenticated using the Vuforia Web Services (VWS) signature scheme described in the Vuforia Web API Authentication.

Instance Generation

Request:

  • Method and URL: POST https://vws.vuforia.com/targets/<target-uuid>/instances.
  • Authentication header: VWS Authentication header using the access-key/secret-key associated to a VuMark database.
  • Date header.
  • Content-Type header: application/json.
  • Accept header: Specifies desired output format. One of image/svg+xml, image/png or application/pdf.
  • Body encoded as JSON with the following fields:

Field name

Type

Mandatory

Description

instance_id

String

yes

Instance ID to be encoded in the VuMark bits.
The maximum length of the instance_id is determined by the ID length property of the VuMark target. The ID length is defined in the VuMark's SVG file as part of the Illustrator design workflow.

Depending on the VuMark type the following characters and string lengths are allowed:

  • Numeric type: decimal digits 0-9 are allowed, e.g. 123456 . The submitted instance_id must be positive and smaller or equal to the max ID property of the vumark. The ID length specifies the number of bits used to encode the instance_id.
  • Bytes type: HEX representation, 0-9, a-f lowercase characters are allowed, e.g. 3fa50b . ID length determines the number of bytes in the instance id; the submitted hex-string must have exactly 2 * ID length hex characters.
  • String type: Printable ASCII characters are allowed, e.g. TAR-0003 . The submitted instance_id must have between 1 and ID length characters.

Request body example:

{
  "instance_id": "TAR-0003"
}

Response (Success case):

  • Content-type header: One of image/svg+xml, image/png or application/pdf.
  • HTTP Status Code: 200 OK.
  • Binary body containing the file in SVG, PNG or PDF format.

Response (Error case):

  • Content-type header: application/json.
  • HTTP Status Code: 4xx or 5xx (see table below).
  • Body: JSON object with the following fields:
    • transaction_id: unique transaction id.
    • result_code: Predefined string specifying the error cause (see below).

Error Code

HTTP Status Code

Description

InvalidInstanceId

Unprocessable Entity (422)

Specified instance ID has illegal characters for the given VuMark type, or id is too short or too long.

QuotaExceeded

Forbidden (403)

No more instances can be created using the license that is associated to the VuMark database.

TargetStatusNotSuccess

Forbidden (403)

The request could not be completed because the target is not in the success state.

InvalidTargetType

Unprocessable Entity (422)

Target Type is invalid (e.g. trying to generate a VuMark of a Cloud Target).

LicenseCheckFailed

Forbidden (403)

According to the license state and/or type, this request can not be executed.

AuthorizationFailed

Unauthorized (401)

General authentication problem.

InvalidAcceptHeader

Bad Request (400)

The accept header does not contain a valid VuMark output format. See the description of the Accept header for the list of valid output formats

Note: Standard HTTP error codes and unspecified body may also be returned by the API.

Response body example (failure):

{
  "transaction_id": "a8b8c78b856c56a",
  "result_code": "LicenseCheckFailed"
}