Common

Getting Started

User

Logout

Refresh Access Token

Get User Profile

Update Profile

Upload Avatar

Delete User

Reset Password

Reset Password by ID

User Token

List User Tokens

Add User Token

Update Default User Token

Delete User Token

Verify User Token

Reset Verification Code

User vAtom

Get vAtom

Get vAtoms by Ids

Get vAtom Inventory

Search vAtoms

Geo Discover Groups

Geo Discover vAtoms

Update vAtoms

Perform Action

Trash vAtom

User Activity

Get My Threads

Get My Thread Messages

Template

List Templates

Get Template

Create Template

Update Template

Delete Template

Template Variation

List Variations

Get Variation

Create Variation

Update Variation

Delete Variation

vAtom

Emit vAtom

Template Action

List Actions

Get Action

Update Action

Delete Action

Template Face

List Faces

Update Face

Delete Face

Asset

Upload Assets

Get Assets

Delete Assets

Create Variation

POST

https://api.blockv.io/v1/template_variations

Overview

By creating a vAtom template variation the values for the defined structure of the template are specified. No properties can be added or removed, as the structure is defined in the Template.

Overwrite behavior

If a field that is present in the template and is not specified as part of the create template variation payload, then the value that is specified in the template is used.

When creating a template variations the values of fields under vatom can be overwritten with the restriction that for state/resource arrays, only the value field can be overwritten and no elements can be added or removed.

Draft mode

Template variations can be created in draft mode by setting the flag unpublished: true. If a template variation is in draft mode it can be changed/deleted. The changes will also be applied to the vAtoms that are already emitted. While in draft mode, max. 10 vAtoms can be emitted for a template variation.

Once a template variation is published (by setting unpublished: false, all vAtoms in draft mode are deleted and the template variation can no longer be updated.

A template variation can only be published, if the corresponding template is published as well.

Create Variation Request

HTTP Headers

Content-Type: application/json
App-Id: {app_id}

Payload Details

Name	Type	Description
`template` *	string	Specifies the Template-Name and has to be a unique string beginning with the publisher domain name.
`template_variation` *	string	Is the name of the Template-Variation and like the Template, it has to begin with you publisher domain followed by a unique string.
`max_clones_per_instance`	int	Total number of clones that are allowed from a given vatom. There is a hard cap of 100. `max_clones_per_instance` cannot be greater than `max_clones_total` .
`max_clones_total`	int	Total number of clones that can exist for a template variation. range 1 to 2147483647. Number of vatoms emitted * `max_clones_per_instance` cannot be greater than this number.
`max_num`	int	Maximum number of vatoms that can exist for a template. `max_clones_total` should be equal or less than this number. Valid values range from 1 to 2147483647. Also see `auto_create_on_acquire` .
`per_clone_gain`	int	How much the cloning score is increased when the vAtom is cloned. The increase is `per_clone_gain/100` .
`per_clone_gain_deduction`	int	The divisor by which the `per_clone_gain` is divided for each indirect clone.
`redeemable`	object	Required only if the template has `redeemable` set to `true` .
`auto_create_on_acquire`	boolean	false by default, if set to true, a AcquirePubVariation Action will automatically generate a new vAtom
`public`	boolean	false by default, if set to true then the template variation will be publicly accessible (read only)
`vatom` *	object	Define vatom object

Clone gain and clone gain deduction example

The initial cloning score for a vAtom is 0, the template variation of the vAtom has the following configuration:

per_clone_gain: 20
per_clone_gain_deduction: 2

When a user A clones the vAtom 1 and shares it with a friend user B, the friend gets vAtom 2. vAtom 1 now has a cloning score of 0 + (20/100) = 0.2 and vAtom 2 has a cloning score of 0. Now user B clones vAtom 2 and shared it with another friend user C, the friend gets vAtom 3. vAtom 1 now has a cloning score of 0 + 20/100 + 20/2/100 = 0.3, vAtom 2 has a cloning score of 0 + (20/100) = 0.2 and vAtom 3 has a cloning score of 0.

redeemable object

Name	Type	Description
`org_change`	object	The update that is applied when a vAtom is returned as part of the redeemable action. The changes are applied to the original vAtom.
`return_change`	object	The update that is applied when a vAtom is returned as part of the redeemable action. The changes are applied to the returned vAtom.
`return_name`	string	The name of the template variation that is used to issue a return vAtom when the user redeems the vAtom.
`valid_from`	date	From when on the vAtom can be redeemed. ISO Date or '*' for no limit.
`valid_until`	date	Until when the vAtom can be redeemed. ISO Date or '*' for not limit.

Reactor update object

Name	Type	Description
parent_id	string	ID of the parent vAtom, for example a folder
transferable	bool	true or false defines if the vAtom can be transferred with a Transfer Action
acquirable	bool	true or false defines if the vAtom can be acquired with a Acquire Action
redeemable	bool	true or false defines if a vAtom can be redeemed with a Redeem Action
visibility	object	Defines who can see the vAtom
geo_pos	object	The geo position of the vAtom when it is dropped
private	object	Changes to the private section of the vAtom. Any key that is defined in the template variation can be updated.

Sample Request

{
  "template": "publisher_fqdn::Template_Name::v1",
  "template_variation": "publisher_fqdn::Template_Name::v1::Variation_Name::v1",
  "public": false,
  "max_clones_per_instance": 10000,
  "max_clones_total": 10000,
  "max_num": 10000,
  "per_clone_gain": 1,
  "redeemable": {
    "org_change": {
      "GeoPos": "",
      "redeemable": false
    },
    "return_change": {
      "GeoPos": ""
    },
    "return_name": "publisher_fqdn::Template_Name::v1::Variation_Name::v1",
    "valid_from": "0001-01-01T00:00:00Z",
    "valid_until": "0001-01-01T00:00:00Z"
  },
  "auto_create_on_acquire": false,
  "unpublished": true,
  "vatom": {
    "vAtom::vAtomType": {
      "transferable": true,
      "acquirable": false,
      "redeemable": false,
      "title": "Example",
      "category": "Utilities",
      "description": "This is just a demo",
      "commerce": {
        "pricing": {
          "pricingType": "Fixed",
          "value": {
            "currency": "",
            "price": "0",
            "valid_from": "*",
            "valid_through": "*",
            "vat_included": false
          }
        }
      },
      "resources": [
        {
          "name": "ActivatedImage",
          "resourceType": "ResourceType::Image::PNG",
          "value": {
            "resourceValueType": "ResourceValueType::URI",
            "value": "https://cdn.blockv.io/blockv.templates/publisher_fqdn/Template_Name/v1/Variation_Name/v1/icon.png"
          }
        },
        {
          "name": "CardImage",
          "resourceType": "ResourceType::Image::JPEG",
          "value": {
            "resourceValueType": "ResourceValueType::URI",
            "value": "https://cdn.blockv.io/blockv.templates/publisher_fqdn/Template_Name/v1/Variation_Name/v1/example.jpg"
          }
        }
      ],
      "visibility": {
        "type": "owner",
        "value": "*"
      }
    },
    "private": {}
  }
}

Create Variation Response

Return & Error Codes

Error	Type	Description
`200`	http	Everything is OK
`400`	http	Invalid data
`403`	http	Not Authorized

Sample Response

{
    "payload": {
        "success_message": "created TemplateVariation successfully",
    }
}

Info