Using the VuMark Generation API

The VuMark Generation API is part of Vuforia Web Services for 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.

In order 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

NOTE: Unlimited use of the VuMark Generation API is only available for Pro licensees.


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


VuMark Design Guide

Designing a VuMark in Adobe Illustrator

How To Add a VuMark to a Database


API Specification


All requests to the Vumark Generation API need to be authenticated. The authentication scheme is described in this section.

Authentication uses a server-access key pair in the form of {server_access_keyserver_secret_key} which authenticates the user and authorizes him/her to access a VuMark database for instance generation. You can find this key pair in the Database Access Keys tab of your VuMark database.

The standard HTTP Authorization header is used to pass authentication information. It has the following form:

Authorization: VWS {server_access_key}:{Signature}


  • VWS stands for Vuforia Web Service.
  • The server_access_key identifies the server_secret_key that was used to compute the signature, and (indirectly) the VuMark database for which the request is.
  • The signature is a hash-based Message Authentication Code (MAC) [2]. The following example is pseudo-grammar that illustrates the construction of the signature (\n means the Unicode code point U+000A).
Signature = Base64(HMAC-SHA1(server_secret_key, StringToSign ) ) );
  StringToSign = 
    HTTP-Verb + "\n" +
    Content-MD5 + "\n" +
    Content-Type + "\n" +
    Date + "\n" +


  • HTTP-Verb: The HTTP method used for the action. Example: GETPOST, etc.
  • Content-MD5: The hexadecimal MD5 hash of the whole request body (from first boundary to last one, including the boundary itself). Use an empty string for request types without request body, i.e. MD5( ).
  • Content-Type: the content-type of the request body (e.g. multipart/form-data). Use an empty string for request types without request body.
  • Date: Current date, e.g.:Sun, 22 April 08:49:37 GMT. The data format must exactly match the Date that is sent in the Date header.
  • Request-Path: The path needs to include the entire URL of the request, so when generating a specific VuMark instance the Request-Path would be "{target-id}/instances/{instance_id}", where target_id is the specific ID of the template from which the instance with the instance_id is generated.


  • A valid time-stamp (using the HTTP Date header) is mandatory for authenticated requests.
  • TLS 1.2 or above with server authentication is required for the API. Plain HTTP requests and requests sent to another port than 443 will be rejected.

Instance Generation


  • Method and URL: POST<target-uuid>/instances
  • Authentication header: VWS Authentication header using the access-key/secret-key associated to a VuMark database (see above)
  • 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




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


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