Skip to content

VuMark Generation Web API

The VuMark Generation Web API allows the generation of printable instances from a VuMark template. These instances are delivered as a graphics file that encodes the instance ID provided with the generation request, which 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 on the Plans & Licenses tab. Once you have created a license, go to the Target Manager, create a VuMark database, and upload your VuMark template as an SVG file; this provides 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 still need to make a VuMark template, consult the following articles on designing one in Adobe Illustrator. 

See:

VuMark Design Guide

Designing a VuMark in Adobe Illustrator

How to Add a VuMark to a Database

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: A VWS Authentication header using the access-key/secret-key associated with 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:

1
2
3
{
  "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: The Standard HTTP error codes and an unspecified body can also be returned by the web API.

Response body example (failure):

1
2
3
4
{
  "transaction_id": "a8b8c78b856c56a",
  "result_code": "LicenseCheckFailed"
}

Learn More

Vuforia Web Services API

Vuforia Web API Authentication

Cloud Targets Web API

Vuforia Query Web API

VuMark API Overview

How to Work with VuMark Databases