Partners API

Description of the API that can be used by partners to update the NFT

Introduction

A partner API is being developed and allows third party to trigger actions in a NFT collection on Gardenlab.

For now, the API allows partners to trigger NFT creation and reservation for later claim by the user. The claim shall be performed by the user, after logging in with its email. It also allows to consume an interaction on a NFT, designated by the owner's email address. The interaction shall be created and configured beforehand on the collection admin tool.

An API key and a configured collection are required to properly perform those actions.

Swagger demo API : https://api-docs-demo.gardenlab.io/

Description

Configuration

Interactions

Create or update a new interaction and specify the action_id to use to apply the interaction.

POSThttps://demo.gardenlab.io/api/v1/saveActionInteraction

Authorization

bearerAuth

Body

application/json

The information about the interaction to create or update.

origin*string

The partner's name.

Example: "spacex"

contract_id*string

The contract ID associated with a specific contract/collection/customer (ex: the event ID or 'subscription')

Example: "summer_party"

interactionIdstring

(optional) The interaction ID to edit. Leave empty to create.

Example: "0ER368760G8787238"

interaction*Interaction (object)

Response

200400403500

Returns an object containing the interaction information along with its id.

Body

application/json

interactionInteraction (object)

idstring

The interaction ID

Example: "IQ0LuundpiAvnfDcQ21Y"

Request

JavaScriptCurlPython

const response = await fetch('https://demo.gardenlab.io/api/v1/saveActionInteraction', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "origin": "spacex",
      "contract_id": "summer_party",
      "interaction": {
        "type": "IRL Event",
        "name": "Event checkin"
      }
    }),
});
const data = await response.json();

Response

200400403500

{
  "interaction": {
    "type": "IRL Event",
    "name": "Event checkin",
    "description": "The interaction applied when a user get access to the event",
    "xpIncrement": 5,
    "noXp": false,
    "customXpIncrement": false,
    "authScanCount": 1,
    "action_id": "event_checkin"
  },
  "id": "IQ0LuundpiAvnfDcQ21Y"
}

Operation

User creation

Notifies Gardenlab that a user has been created in the database. Create and reserve a NFT for the user, if the conditions are respected. The NFT associated to user_category_id will be used for this user. This endpoint supports body with an array of requests or a single request. The response will be an array or a single body accordingly.

POSThttps://demo.gardenlab.io/api/v1/newUserForPartner

Authorization

bearerAuth

Body

application/json

The information about the event and the user to create a NFT for.

origin*string

The partner's name.

Example: "spacex"

email*string

The user's email address. The NFT created will be reserved to this email.

uid*string

The user identification.

user_category_id*string

The user catagory. This defines which NFT to distribute.

Example: "VIP"

contract_id*string

The contract ID associated with a specific contract/collection/customer (ex: the event ID or 'subscription')

Example: "summer_party"

additional_fieldsobject

Additionnal fields that can be set for customized behaviors.

nft_infoobject

Optional NFT information that must be set for this user

Response

200400403500

Returns an array of object containing the NFTs created for the user.

Body

application/json

itemsstring

objectError (object)

Request

JavaScriptCurlPython

const response = await fetch('https://demo.gardenlab.io/api/v1/newUserForPartner', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "origin": "spacex",
        "email": "text",
        "uid": "text",
        "user_category_id": "VIP",
        "contract_id": "summer_party"
      }
    ]),
});
const data = await response.json();

Response

200400403500

[
  "text"
]

Note: When creating a NFT for a user, this NFT is prepared but not minted. The mint of the NFT occurs when the user claims it using the email address.

Action

Notifies Gardenlab that a user has performed an action in the partner ecosystem

POSThttps://demo.gardenlab.io/api/v1/newActionForUser

Authorization

bearerAuth

Body

application/json

The information about the action the user performed.

originstring

The partner's name.

Example: "spacex"

contract_idstring

The contract ID associated with a specific contract/collection/customer (ex: the event ID or 'subscription')

Example: "summer_party"

action_idstring

The action ID.

Example: "eshop_purchase"

xpIncrementnumber

The XP value to add on the NFT. Applied only if the interaction allows it.

Example: 5

guestobject

Response

200400403500

Returns an object containing the NFT created for the user.

Body

application/json

contractstring

The NFT's smart contract address.

Example: "0x0123456789abcdef0123456789abcdef01234567"

tokenIdstring

The NFT token ID.

Example: "123"

attributesobject

The NFT attributes.

urlstring

The NFT page URL.

uidstring

The owner User ID.

emailstring

The owner email address.

Request

JavaScriptCurlPython

const response = await fetch('https://demo.gardenlab.io/api/v1/newActionForUser', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400403500

{
  "contract": "0x0123456789abcdef0123456789abcdef01234567",
  "tokenId": "123",
  "url": "text",
  "uid": "text",
  "email": "text"
}

Note: The action saved for a NFT is applied if the NFT is minted or not.

Mint token

Mint an existing token to a user. The token must be created and allocated to a user, through his email address. The NFT will then be minted to the blockchain address specified in the request. The UID of the user must also be specified for additional security.

POSThttps://demo.gardenlab.io/api/v1/mintTokenForUser

Authorization

bearerAuth

Body

application/json

origin*string

The partner's name.

Example: "spacex"

email*string

The user's email address. The NFT must have been created with this email.

Example: "[e-mail]"

uid*string

The user identification.

Example: "u123456789"

user_addr*string

The blockchain address of the user. The NFT will be minted to this address.

Example: "0x0123456789abcdef0123456789abcdef01234567"

contract_id*string

The contract ID associated with a specific contract/collection/customer (ex: the event ID or 'subscription')

Example: "summer_party"

contractstring

The contract address. Required if contract_id is not specified. The contract must be associated to the partner.

Example: "0x0123456789abcdef0123456789abcdef01234567"

token_idstring

The token ID to be minted. It must be reserved to the user. If not specified, the token ID will be searched using the user email.

Example: "123"

Response

200400403500

Returns the basic information of the mint. The mint is not yet processed in the blockchain.

Body

application/json

userAddr*string

The user address to which the NFT will be minted.

Example: "0x0123456789abcdef0123456789abcdef01234567"

contract*string

The contract address

Example: "0x0123456789abcdef0123456789abcdef01234567"

tokenId*string

The token ID being minted

Example: "123"

tokenUrl*string

The token URL.

Example: "ipfs://bafyreid2zqtuvrcemlhesksvibci7xaphbvw4ytun5xykdjancfaum2l3i/metadata.json"

Request

JavaScriptCurlPython

const response = await fetch('https://demo.gardenlab.io/api/v1/mintTokenForUser', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "origin": "spacex",
      "contract_id": "summer_party",
      "user_addr": "0x0123456789abcdef0123456789abcdef01234567",
      "email": "[e-mail]",
      "uid": "u123456789"
    }),
});
const data = await response.json();

Response

200400403500

{
  "userAddr": "0x0123456789abcdef0123456789abcdef01234567",
  "contract": "0x0123456789abcdef0123456789abcdef01234567",
  "tokenId": "123",
  "tokenUrl": "ipfs://bafyreid2zqtuvrcemlhesksvibci7xaphbvw4ytun5xykdjancfaum2l3i/metadata.json"
}

Getters

Retrieve the information on a specific NFT of a contract.

GEThttps://demo.gardenlab.io/api/v1/getNftByTokenId

Authorization

bearerAuth

Query parameters

Response

200400403404

Returns an object containing the NFT information.

Request

JavaScriptCurlPython

const response = await fetch('https://demo.gardenlab.io/api/v1/getNftByTokenId', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

400403404

{
  "error": {
    "status": 123,
    "code": "NFT_IS_EXPIRED",
    "message": "The NFT is expired and cannot be modified"
  }
}

Retrieve all the interactions for a contract.

GEThttps://demo.gardenlab.io/api/v1/getAllInteractions

Authorization

bearerAuth

Query parameters

Response

200400403500

Returns a list with all the interactions

Body

application/json

type*string

The interaction type (the NFT attribute to make an evolution on)

Example: "IRL Event"

name*string

The interaction name

Example: "Event checkin"

descriptionstring

The interaction description

Example: "The interaction applied when a user get access to the event"

xpIncrementnumber

The default number of XP points to add on the NFT, when applying this interaction

Example: 5

noXpboolean

Whether the interaction adds XP or just an attribute type

Example: false

customXpIncrementboolean

Whether the interaction accepts a custom XP increment (passed in the request parameters)

Example: false

authScanCountnumber

Number of interactions that can be applied on one NFT. (-1 if infinity)

Example: 1

action_idstring

The action id keyword to call this interaction with in the API request

Example: "event_checkin"

Request

JavaScriptCurlPython

const response = await fetch('https://demo.gardenlab.io/api/v1/getAllInteractions?origin=text', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200400403500

[
  {
    "type": "IRL Event",
    "name": "Event checkin",
    "description": "The interaction applied when a user get access to the event",
    "xpIncrement": 5,
    "noXp": false,
    "customXpIncrement": false,
    "authScanCount": 1,
    "action_id": "event_checkin"
  }
]

Getting all the actions applied on a NFT

GEThttps://demo.gardenlab.io/api/v1/getAllInteractionScansForToken

Authorization

bearerAuth

Query parameters

Response

200400403500

Returns a list with all the interactions

Body

application/json

at*object

Date at which the interaction occured

xpBefore*number

XP before the interaction

xpAfter*number

XP after the interaction

lvlBefore*number

Level before the interaction

lvlAfter*number

Level after the interaction

maxLvlReached*boolean

Flag indicating the max level has been reached

interactionName*string

The name of the interaction

type*string

The type of the interaction (attribute name)

Request

JavaScriptCurlPython

const response = await fetch('https://demo.gardenlab.io/api/v1/getAllInteractionScansForToken?origin=text&tokenId=text', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200400403500

[
  {
    "at": {
      "_seconds": 0,
      "_nanoseconds": 0
    },
    "xpBefore": 0,
    "xpAfter": 0,
    "lvlBefore": 0,
    "lvlAfter": 0,
    "maxLvlReached": false,
    "interactionName": "text",
    "type": "text"
  }
]

Getting all the blockchain transactions for a specific token, with the information related to the transaction.

GEThttps://demo.gardenlab.io/api/v1/getBlockchainTxForToken

Authorization

bearerAuth

Query parameters

Response

200400403500

Returns a list with all the blockchain transactions

Body

application/json

txHash*string

The blockchain transaction hash

transactionUrl*string

The blockchain explorer url

newUri*string

The URI of the token

at*object

Date at which the interaction occured

xpBefore*number

XP before the interaction

xpAfter*number

XP after the interaction

lvlBefore*number

Level before the interaction

lvlAfter*number

Level after the interaction

maxLvlReached*boolean

Flag indicating the max level has been reached

interactionName*string

The name of the interaction

type*string

The type of the interaction (attribute name)

Request

JavaScriptCurlPython

const response = await fetch('https://demo.gardenlab.io/api/v1/getBlockchainTxForToken?origin=text&contract_id=text&token_id=text', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200400403500

[
  {
    "txHash": "text",
    "transactionUrl": "text",
    "newUri": "text",
    "at": {
      "_seconds": 0,
      "_nanoseconds": 0
    },
    "xpBefore": 0,
    "xpAfter": 0,
    "lvlBefore": 0,
    "lvlAfter": 0,
    "maxLvlReached": false,
    "interactionName": "text",
    "type": "text"
  }
]

Webhooks

It is also possible to set up webhooks to get notified about some specific events occuring in Gardenlab.

The failure object is sent only when there is no "hope" about succeeding in performing the blockchain transactions. Gardenlab system is designed to try multiple times to perform a transaction if no fatal error occurs on the transaction.

New interaction with blockchain update:

Type :

newBcInteraction

Header:

"X-API-key": string // The API key configured by the partner

Success Content:

{
    sucess: true,
    contract: string, // The contract address
    tokenId: string, // The token ID
    actionType: string, // The webhook/action type (newBcInteraction)
    actionAtInSeconds: string, // The date of the action in seconds
    at: {"_seconds": number, "_nanoseconds": number}, // The date in an object
    transactionUrl: string, // The blockchain explorer page for this transaction
    txHash: string, // The blockchain transaction hash
    newUri: string, // The new URI of the token
}

Failure Content:

{
    sucess: false,
    error: string,
    contract: string, // The contract address
    tokenId: string, // The token ID
    actionType: string, // The webhook/action type (newBcInteraction)
    actionAtInSeconds: string, // The date of the action in seconds
    at: {"_seconds": number, "_nanoseconds": number}, // The date in an object
}

New NFT minted

Type :

newBcNftMint

Header:

"X-API-key": string // The API key configured by the partner

Success content:

{
    success: true,
    contract: string, // The contract address
    tokenId: string, // The token ID
    actionType: string, // The webhook/action type (newBcNftMint)
    at: {"_seconds": number, "_nanoseconds": number}, // The date in an object
    transactionUrl: string, // The blockchain explorer page for this transaction
    txHash: string, // The blockchain transaction hash
}

Failure content:

{
    success: false,
    error: string, // The error message
    contract: string, // The contract address
    tokenId: string, // The token ID
    actionType: string, // The webhook/action type (newBcNftMint)
    at: {"_seconds": number, "_nanoseconds": number}, // The date in an object
}