Skip to content

Basic Queries

GraphQL

The Freeverse API is accessed via GraphQL. We recommend using a playground such as GraphQL Playground to create test queries and view the entire API documentation.

GraphQL Playground exposes all documentation for our API

Note

Contact us so that we can provide you with a url endpoint with which you can access the API via GraphQL.

Example: Getting all registered assets in your universe

Below is a simple example of a query that returns all the assets in your universe. $universe is the integer variable that represents your universe, which we will provide you; along with the url for your sandbox and/or production environment.

query getAllAssets($universe: Int!) {
    allAssets(condition: { universeId: $universe } ) {
        nodes {
            id
            nonce
            props
            metadata
            ownerId
        }
    }
}
curl 'https://freeverse_api_address' \
-X POST \
-H "Content-Type: application/json" \
-d '{ 
    "query": "query getAllAssets($universe: Int!) { allAssets(condition: { universeId: $universe } ) { nodes { id nonce props metadata ownerId } } }",
    "variables": {"universe": <universe_id_provided_by_freeverse>} 
}'
const allAssetsQuery = `
query getAllAssets($universe: Int!) {
    allAssets(condition: { universeId: $universe } ) {
        nodes {
            id
            nonce
            props
            metadata
            ownerId
        }
    }
}`;

const api_address = "https://freeverse_api_address";
const universeId = xxxx; //provided by Freeverse
const response = await fetch(api_address, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
        query: allAssetsQuery,
        variables: {
            universe: universeId
        }
    }),
});
const resultJson = await response.json();

This query returns a JSON object with an array of nodes with information about all assets in your universe:

{
  "data": {
    "allAssets": {
      "nodes": [
        {
          "id": "100181401110744947689046299210394596780073533182683",
          "nonce": 6,
          "props": "{\"game\":\"FV0\",\"name\":\"Johanna Rimanova\",\"description\":\"Asset of FV0\",\"level\":\"1987\",\"imgUrl\":\"/static/media/default.d1deeeb2.png\"}",
          "metadata": "{\"this_data\":\"is_for_my_eyes_only\"}",
          "ownerId": "0x8C016499db1685a522dE043d98092091dE2212DB"
        },
        ...
      ]
    }
  }
}
In this example, the query returns a series of properties for each asset.

  • id: the unique identifier of this asset in the Freeverse platform.
  • nonce: the Number-used Once that should be used when this asset is next edited.
  • props: a JSON string of all the publicly accessible properties of an asset. These can be used, for example, to determine how an asset can be used in your application or game. The props are visible to the end user in the Marketplace.
  • metadata: a private JSON string which you can fill with whatever properties you wish, not to be shown in Marketplaces.
  • ownerId: the Freeverse ID of the owner (your user) of this asset.

Example: Querying a user nonce value

Whenever you modify anything in your universe (whether it's to edit an asset properties, or to create a new asset and assign its initial ownership to a user), you must pass in the Number-Used-Once (nonce) which is stored on our server. You may also store it, or query it from us when needed. In this example, we show how it is possible to query a user's nonce value, which can then be used to assign a new asset to that user:

query($freeverseId: String!, $universe: Int!) {
    usersUniverseByUserIdAndUniverseId(universeId: $universe, userId: $freeverseId){
        nonce
    }
}
curl 'https://freeverse_api_address' \
-X POST \
-H "Content-Type: application/json" \
-d '{ 
    "query($freeverseId: String!, $universe: Int!) {usersUniverseByUserIdAndUniverseId(universeId:$universe, userId: $freeverseId){ nonce } }",
    "variables": {"universe": <universe_id_provided_by_freeverse>, "freeverseId": <user_freeverse_id>} 
}'
const getNonceQuery = `
query($freeverseId: String!, $universe: Int!) {
    usersUniverseByUserIdAndUniverseId(universeId: $universe, userId: $freeverseId){
      nonce
    }
  }
`;

const response = await fetch(api_address, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
        query: getNonceQuery,
        variables: {
            freeverseId: user_freeverse_id,
            universe: universe_id_provided_by_freeverse
        }
    }),
});
const resultJson = await response.json();

Example: Filtering Asset Queries By Properties

query {
    allAssets(
        condition: { props: { key: "name", containedValue: "Cat" } }
    ) {
        nodes {
            id
            ownerId
            props
            metadata
        }
    }
}

Next: Creating and Updating Assets...