Environment API

Environment API is mentioned to provide an alternative for environment assets.

Environment resources could be uploaded by any user. Anyone can use his own private environment or public environments provided by other users.

Environments available in all networks.

Endpoint	Method	Description
/api/v0/asset/upload/environment/link	webRequest	Direct environment resource upload to Google bucket (get upload link)
/api/v0/asset/upload/environment/link/complete	webRequest	Direct environment resource upload to Google bucket (complete upload link)
/api/v0/asset/environment/{id}	webRequest	Get environment resource data
/api/v0/asset/environment/url/{id}	webRequest	Get environment resource url
/api/v0/asset/environment/thumbnail/{size}/{id}	webRequest	Get environment thumbnail data
/api/v0/asset/environment/thumbnail/url/{size}/{id}	webRequest	Get environment thumbnail url
asset:createEnvironment	websocket	Create environment
asset:deleteEnvironment	websocket	Delete environment
asset:updateEnvironment	websocket	Update environment
asset:searchEnvironments	websocket	Search environments
asset:environmentCreated	websocketEvent	Environment created event
asset:environmentResourceUploaded	websocketEvent	Environment resource uploaded event

Direct environment resource upload to Google bucket (get upload link)

HTTP Method: POST

Path: /api/v0/asset/upload/environment/link

Description: Direct upload gives possibility to upload files directly from a client to a storage bucket. It consist of next steps:

1. Client asks the server for upload link. The server initializes an upload session and returns a link which could be used for upload.

2. Client uploads a file to Google bucket.

3. Client sends upload complete acknowledgment to the server.

Request:

{
    "environmentId": string
    "resourceId": string
    "fileName": string
    "contentType": string
}

Response:

Google bucket upload link

Direct environment resource upload to Google bucket (complete upload link)

HTTP Method: POST

Path: /api/v0/asset/upload/environment/link/complete

Description: See direct upload to Google bucket.

Request:

{
    "environmentId": string
    "resourceId": string
}

Response:

{ empty }

Get environment resource data

HTTP Method: GET

Path: /api/v0/asset/environment/

Request:

{ empty }

Response:

Environment resource data

Get environment resource url

HTTP Method: GET

Path: /api/v0/asset/environment/url/

Request:

{ empty }

Response:

Direct url to environment resource

Get environment thumbnail data

HTTP Method: GET

Path: /api/v0/asset/environment/thumbnail/{size}/

Request:

{ empty }

Response:

Environment thumbnail resource data

Get environment thumbnail url

HTTP Method: GET

Path: /api/v0/asset/environment/thumbnail/url/{size}/

Request:

{ empty }

Response:

Direct url to environment thumbnail resource

Create environment

Method: websocket

Endpoint: asset:createEnvironment

Description: Api creates environment resource which could be used instead of environment asset.

By default, environment status will be private, as it couldn't become public while resource is not uploaded.

Resource behaviourType should be on of: image/environment-360, video/environment-360, image/environment-cubemap.

Request:

{
    "data": {
        "resource": { resource structure }
        "status": string  // public/private/pending
        "title": string  // environment title
        "networkId": string  // if present, resource is available only in provided network
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "environment": {
            "id": string
            "created": timestamp
            "updated": timestamp
            "status": string  // public/private/pending
            "title": string  // environment title
            "networkId": string  // if present, resource is available only in provided network
            "resource": { resource structure }  // actual resource
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Delete environment

Method: websocket

Endpoint: asset:deleteEnvironment

Description: Api deletes environment. Only admin user can delete environment of other user.

Request:

{
    "data": {
        "environmentId": string
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "error": { "status": bool, "code": int, "message": string }
}

Update environment

Method: websocket

Endpoint: asset:updateEnvironment

Description: Api updates environment.

Environment status can be one of:

• private - available only for environment owner
• pending - admin will review environment in order to make it make public
• public - available for all users system-wide

Actual resource should be uploaded before changing status from private to something else. Only admin user can set environment status to public.

Request:

{
    "data": {
        "environmentId": string
        "status": string  // public/private/pending
        "title": string  // environment title
        "networkId": string  // if present, resource is available only in provided network
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "environment": {
            "id": string
            "created": timestamp
            "updated": timestamp
            "status": string  // public/private/pending
            "title": string  // environment title
            "networkId": string  // if present, resource is available only in provided network
            "resource": { resource structure }  // actual resource
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Search environments

Method: websocket

Endpoint: asset:searchEnvironments

Description: Api returns list of environments.

Status could be one of:

• own - return environments owned by user
• pending - return pending environments (only for admins)
• public - return all public environments

Content types could be combination of:

• image/environment-360
• image/environment-cubemap
• video/environment-360

Request:

{
    "data": {
        "status": string
        "query": string
        "contentTypes": [ string ]
        "offset": int
        "size": int
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "environments": [{
            "id": string
            "created": timestamp
            "updated": timestamp
            "status": string  // public/private/pending
            "title": string  // environment title
            "networkId": string  // if present, resource is available only in provided network
            "resource": { resource structure }  // actual resource
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

Environment created event

Event: asset:environmentCreated

Data:

{
    "data": {
        "environment": {
            "id": string
            "created": timestamp
            "updated": timestamp
            "status": string  // public/private/pending
            "title": string  // environment title
            "networkId": string  // if present, resource is available only in provided network
            "resource": { resource structure }  // actual resource
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Environment resource uploaded event

Event: asset:environmentResourceUploaded

Data:

{
    "data": {
        "environment": {
            "id": string
            "created": timestamp
            "updated": timestamp
            "status": string  // public/private/pending
            "title": string  // environment title
            "networkId": string  // if present, resource is available only in provided network
            "resource": { resource structure }  // actual resource
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Models

Resource

{
    "id": string
    "created": timestamp
    "updated": timestamp
    "title": string
    "description": string
    "location": string
    "date": string
    "category": string
    "linkId": string  // id of resource link is pointing to
    "linkType": string  // global/local
    "encryptionVersion": string  // encryption version, like 'verus.v1'
    "encryptionEpoch": int  // epoch defines key bundle that was used for encryption
    "encryptionEpk": string  // ephemeral public key that should be used to decrypt cypher data
    "belonging": string  // determines resource location in the system in a way 'belongingType:belongingPath(networkId)'
    "status": string  // pending/processing/ready/failed
    "metadata": {
        "fileName": string
        "fileSize": int
        "fileDate": timestamp
        "behaviourType": string
        "contentType": string
        "convertedFrom": string
        "link": string
        "origin": { resource origin structure }
        "geolocation": { geolocation structure }
        "dimensions": { dimensions structure }
    }
    "thumbnail": string
    "fromTemplate": bool
    "totalReactions": int  // amount of users who reacted to the resource
    "data": {
        "audio": { resource data audio structure }
        "video": { resource data video structure }
        "amazon": { resource data amazon structure }
        "imdb": { resource data imdb structure }
        "youtube": { resource data youtube structure }
        "pinterest": { resource data pinterest structure }
        "pixabay": { resource data pixabay structure }
        "facebook": { resource data facebook structure }
        "remoteUrl": { resource data remote url structure }
        "liveStream": { live stream data structure }
        "aiGeneration": { ai generation data structure }
        "thumbnailUrl": string
        "downloadUrl": string
        "directory": { resource data directory structure }
        "channel": { channel data structure }
        "googleDrive": { google drive structure }
    }
    "customParams": map[string]{ custom structure }  // client defined parameters
    "actions": [{ programmatic action with children structure }]  // custom programmatic actions from users
}

Resource Origin

{
    "type": string
    "device": string
    "deviceName": string
    "path": string
}

Geolocation

{
    "latitude": float
    "longitude": float
}

Dimensions

{
    "width": int
    "height": int
    "orientation": int
}

Resource Data Audio

{
    "title": string
    "artist": string
    "album": string
    "genre": string
    "duration": int
    "durationFloat": float
}

Resource Data Video

{
    "duration": int
    "durationFloat": float
    "hasAlphaChannel": bool  // true, if video generated from gif with transparent pixels
    "alphaChannel": string  // alpha channel video resource (if generated from gif)
}

Resource Data Amazon

{
    "asin": string
    "summary": string
    "author": [ string ]
    "manufacturer": string
    "title": string
    "publicationDate": string
    "url": string
}

Resource Data Imdb

{
    "Actors": string
    "Genre": string
    "Ratings": [{
        "Source": string
        "Value": string
    }]
    "Released": string
    "Runtime": string
    "Website": string
    "Year": string
    "Trailers": [ string ]
    "imdbID": string
}

Resource Data Youtube

{
    "videoId": string
    "formatId": string
}

Resource Data Pinterest

{
    "pin": string
    "url": string
}

Resource Data Pixabay

{
    "id": string
    "pageUrl": string
}

Resource Data Facebook

{
    "id": string
}

Resource Data Remote Url

{
    "url": string
    "urlType": string
    "favicon": string
    "title": string
}

Live Stream Data

{
    "streamId": string
    "assetId": string
    "playbackUrl": string
    "masterUrl": string
}

AI Generation Data

{
    "generationModel": string  // the model used for image generation [dall-e-3]
    "prompt": string  // a text description of the desired image
    "revisedPrompt": string  // the prompt that was used to generate the image, if there was any revision to the prompt
    "url": string  // the URL of the generated image
}

Resource Data Directory

{
    "innerContentType": string
    "innerContentCount": int
}

Channel Data

{
    "communityId": string
    "channelId": string
    "subChannelId": string
    "messageId": string
}

Google Drive

{
    "fileId": string
    "name": string
    "mimeType": string
}

Programmatic Action with children

{
    "localId": string  // local action id, operated by client side only
    "eventName": string
    "actionName": string
    "actionData": {
        "usedPropId": string
        "usedRoomId": string
        "usedNetworkId": string
        "usedStorylineId": string
        "usedQuestionId": int
        "usedQuestionnaireId": int
        "usedSegmentId": string
        "usedPlacementAreaId": string
        "usedRoomPoint": string
        "animationData": map[string]{ custom structure }
    }
    "childActions": [{ programmatic action structure }]
}

Programmatic Action

{
    "localId": string  // local action id, operated by client side only
    "eventName": string
    "actionName": string
    "actionData": {
        "usedPropId": string
        "usedRoomId": string
        "usedNetworkId": string
        "usedStorylineId": string
        "usedQuestionId": int
        "usedQuestionnaireId": int
        "usedSegmentId": string
        "usedPlacementAreaId": string
        "usedRoomPoint": string
        "animationData": map[string]{ custom structure }
    }
}