API

Common

Getting Started

User

Register New User
Login
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
Register Action Handler
Register Action
Update Action
Delete Action

Template Face

List Faces
Register Face
Update Face
Delete Face

Asset

Upload Assets
Get Assets
Delete Assets

Create Template

POST
https://api.blockv.io/v1/templates

Overview

To create a vAtom, a template and a template variation is needed. Those are blueprints which are used to create vAtoms.

The template provides the structure of the vAtom with defaults, whereas the template variation can overwrite most of the values defined by the template. A template can for example define attributes for a pizza object, the template variation then describes a pizza margarita or a pizza prosciutto.

A template mainly consists of three sections:

Configuration fields in the root section

This section contains fields that are used to configure the template like its name or if the template is published.

There is one special case: cloneable is not used to configure the template, but defines if vAtoms that are based on this template can be cloned. This field cannot be overwritten in the template variation. The difference to other boolean fields that are part of the vAtom object is that cloneable is either true or false and is not changed by an action. The template variation keeps track of the number of clones and if the maximum is reached. Whereas fields like acquirable might initially be set to true, but can be changed for each vAtom individually after an action was executed because after a user acquired a vAtom from a publisher, other users should not be able to acquire that vAtom anymore.

vAtom section

This section contains the structure of a vAtom that will be used to create vAtoms when they are emitted.

The structure of this section is predefined, no fields can be added or removed. The only mandatory field is root_type, which defines what type of vAtoms will be created.

For fields of type array (states and resources) the allowed list entries can be defined. For example for resources an entry could look like this:

Sample Resource

[
  {
      "name": "ActivatedImage" ,
      "resourceType": "ResourceType::Image::JPEG" ,
      "value": {
          "resourceValueType": "ResourceValueType::URI",
          "value": ""
      }
  }
]

In this case the template variation is only allowed to contain resources with the name ActivatedImage and the only field that can be overwritten in the template variation is value.

Private section

This section contains fields that are defined by the publisher. Built in actions will not modify custom fields in this section. When a template variation is created, only fields that are defined in the template are allowed in the template variation.

ETH section

Fields defined in the ETH section will be recorded on the Ethereum blockchain. Each time a value of a field in the ETH section changes, the value will also be changed in the smart contract. The publisher will be charged in VEEs for those operations (smart contract creation, transactions, etc.).

Draft mode

Templates can be created in draft mode by setting the flag unpublished: true. Templates can be deleted, while they are not published.

A template can be published by setting unpublished: false. Once published, a template cannot be deleted anymore.

Create Template Request

HTTP Headers

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

Payload Details

NameTypeDescription
template * stringspecifies the Template Name and has to be a unique string beginning with the publisher domain name publisher_fqdn
cloneablebooleantrue or false , default: false defines if the vAtoms based on this template can be shared with other users by sending them a clone of your vAtom using a Clone Action
unpublishedbooleantrue or false defines if the template can still be changed (unpublished=true) or if it is the final version (unpublished=false)
publicbooleanfalse by default, if set to true then the template will be publicly accessible (read only)
ethobjectOptional section to define custom properties that will be recorded on the Ethereum Blockchain.
vatom * objectThe vAtom object

eth object

NameTypeDescription
network * stringThe network on which the data is stored ( mainnet or testnet ). If the data is stored on mainnet , then the transaction costs will be charged in VEE.
symbolstringThe symbol that is used in the smart contract. If no symbol is provided, the publishers fully qualified domain name is used.
fields * objectA map of fields that will be stored on the Ethereum Blockchain. The field name is they key and the value contains the datatype and the value.
fields object

Each field has a unique identifier, which is the field name, for example my_field, with the following values:

NameTypeDescription
type * stringThe datatype that is used to store the field on the Ethereum blockchain: bool , uint and string are supported.
value * stringThe initial value of the field.

Sample ETH section

 {
    "eth": {
        "fields": {
            "my_flag": {
                "type": "bool",
                "value": true
            },
            "my_number": {
                "type": "uint",
                "value": 0
            },
            "my_field": {
                "type": "string",
                "value": "test"
            }
        },
        "network": "testnet"
  }
 }

vatom object

NameTypeDescription
vAtom::vAtomTypeobjectIn the vAtom::vAtomType section the built in properties are defined
privateobjectIn the private section you can define custom properties, states and resources. Built-in action will not modify private
vAtom::vAtomType object
NameTypeDescription
root_typestringdefines the vAtomType and version e.g. vAtom::vAtomType . For more types
transferablebooleantrue or false defines if the vAtom can be transferred with a Transfer Action
acquirablebooleantrue or false defines if the vAtom can be acquired with a Acquire Action e.g. Billboard use-case
redeemablebooleantrue or false defines if a vAtom can be redeemed with a Redeem Action
titlestringspecifies a title or name of the vAtom
descriptionstringyou can add a text to describe the function of the vAtom
categorystringyou can define a category for the vAtom
commerceobjectoptional if redeemable is false. Defines the pricing of the vAtom based on a currency and price
statesarrayincludes the states defined for the vAtom. At least one State has to be defined, otherwise the default Activated State will automatically be assigned
resourcesarrayDefines an array of Resource objects
visibilityobjectDefines who can see the vAtom
root_type details
root_typeDescription
vAtom::vAtomTypeA regular vAtom/object. Most common type
vAtom::vAtomType::FolderContainerTypeA folder that can contain child vAtoms. At emit step, the folder is empty. The publisher needs to pack vatoms before using. To fill the folder - pre- and post- actions can be defined to fill it. e.g.?
vAtom::vAtomType::PackageContainerTypeSame as the folder, it also contains children, but once it is opened it will vanish e.g. like a gift box or a fortune cookie. At emit step, the folder is empty. The publisher needs to pack vatoms before using. To fill the folder - pre- and post- actions can be defined to fill it.
vAtom::vAtomType::DiscoverContainerTypeDynamically queries the child vAtoms by using a discover query . It has the same fields as vAtom::vAtomType::FolderContainerType , except for the query field that is nested under vAtom::vAtomType .
vAtom::vAtomType::DefinedFolderContainerTypeSame as a folder, but it has predefined vAtoms in it when it is created. They will be created based on the child_policy. Rules can be defined that govern the membership.
Supported categories

Categories can be used by viewers to group vAtoms. The following categories are supported.

  • Coupons
  • Gifts
  • Collectibles
  • Food & Drink
  • Entertainment
  • Music
  • Lifestyle
  • Travel
  • Sports
  • Utilities
  • Documents
  • Kids
  • Miscellaneous
commerce object
NameTypeDescription
pricingobjectPricing object is optional. When not present vAtom can be redeemed with the merchant with out of band pricing terms.
pricing object

Pricing can be based on fiat currency like USD

NameTypeDescription
pricingTypestring"Fixed" is the only type supported
valueobjectvalue object
value object
NameTypeDescription
valueobjectValue object.
currencystring
pricefloat
valid_fromISO DateDate or an *
valid_throughISO DateDate or an *
vat_includedbooleantrue or false
states array
NameTypeDescription
namestringselect between valid values: "Activated"
on_state_changeobjectNot yet implemented
valueobjectcurrently boolean is supported via {"type": "boolean", "value": "true"}
resources array

Resources are used by faces to display a vAtom. The resources are the building blocks for faces to put together a representation of a vAtom for a specific kind of device.

For example multiple ResourceType::Image::JPEG resources can be used to create a faces that shows the vAtom on a website.

Supported resource types:

  • ResourceType::Image::GIF
  • ResourceType::Image::PNG
  • ResourceType::Image::JPEG
  • ResourceType::Text::Plain
  • ResourceType::Text::HTML
  • ResourceType::Code::Javascript
  • ResourceType::Code::Golang
  • ResourceType::Audio::MPEG
  • ResourceType::Audio::WAV
  • ResourceType::Video::AVI
  • ResourceType::Video::MPEG
  • ResourceType::Video::Quicktime
  • ResourceType::Video::ASF
  • ResourceType::3D::Scene
visibility object
NameTypeDescription
typestring
valuestringFiner grained control for the selected visibility type. Currently only * is supported, which means no further restrictions.
visibility types

Currently supported visibility types:

  • owner the vAtom can only be discovered by the current owner
  • public the vAtom is visible to all users
  • container If the vAtom is part of a folder, then it inherits the visibility of the folder

Sample Request

{
    "template": "publisher_fqdn::Template_Name::v1",
    "public": false,
    "cloneable": false,
    "unpublished": true,
    "vatom": {
        "vAtom::vAtomType": {
            "root_type": "vAtom::vAtomType",
            "redeemable": true,
          	"states": [
              	{
                  	"name": "Activated",
                  	"value": {
                      "type": "boolean",
                      "value": "true"
                  	}
              	}
        	],
          	"resources": [
                {
                    "name": "ActivatedImage",
                    "resourceType": "ResourceType::Image::JPEG",
                    "value": {
                        "resourceValueType": "ResourceValueType::URI",
                        "value": ""
                    }
                },
                {
                    "name": "CardImage",
                    "resourceType": "ResourceType::Image::JPEG",
                    "value": {
                        "resourceValueType": "ResourceValueType::URI",
                        "value": ""
                    }
                }
            ]
        },
        "private": {}
    }
}

Create Template Response

Return & Error Codes

ErrorTypeDescription
200httpEverything is OK
400httpInvalid data
403httpNot Authorized

Sample Response

{
    "payload": {
        "success_message": "created Template successfully",
    }
}
©2020 BLOCKv
Info