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.

post

/saveActionInteraction

Authorizations

Body

originstringrequired

The partner's name.

Example: spacex

contract_idstringrequired

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

interactionobjectrequired

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://demo.gardenlab.io/api/v1/saveActionInteraction' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "origin": "spacex",
    "contract_id": "summer_party",
    "interactionId": "0ER368760G8787238",
    "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"
    }
  }'

200

400

403

500

200

{
  "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"
}

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

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.

post

/newUserForPartner

Authorizations

Body

originstringrequired

The partner's name.

Example: spacex

emailstringrequired

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

uidstringrequired

The user identification.

user_category_idstringrequired

The user catagory. This defines which NFT to distribute.

Example: VIP

contract_idstringrequired

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

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://demo.gardenlab.io/api/v1/newUserForPartner' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "origin": "spacex",
      "email": "text",
      "uid": "text",
      "user_category_id": "VIP",
      "contract_id": "summer_party",
      "additional_fields": {
        "expiration_date": "2023-09-18T12:34:56.123Z",
        "max_level": 15
      },
      "nft_info": {
        "imgUrl": "text",
        "name": "text",
        "description": "text",
        "attributes": "text"
      }
    }
  ]'

200

400

403

500

200

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

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

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

post

/newActionForUser

Authorizations

Body

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

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://demo.gardenlab.io/api/v1/newActionForUser' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "origin": "spacex",
    "contract_id": "summer_party",
    "action_id": "eshop_purchase",
    "xpIncrement": 5,
    "guest": {
      "email": "text",
      "uid": "text"
    }
  }'

200

400

403

500

200

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

Returns an object containing the NFT created for the user.

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.

post

/mintTokenForUser

Authorizations

Body

originstringrequired

The partner's name.

Example: spacex

emailstringrequired

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

Example: [e-mail]

uidstringrequired

The user identification.

Example: u123456789

user_addrstringrequired

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

Example: 0x0123456789abcdef0123456789abcdef01234567

contract_idstringrequired

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

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://demo.gardenlab.io/api/v1/mintTokenForUser' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "origin": "spacex",
    "email": "[e-mail]",
    "uid": "u123456789",
    "user_addr": "0x0123456789abcdef0123456789abcdef01234567",
    "contract_id": "summer_party",
    "contract": "0x0123456789abcdef0123456789abcdef01234567",
    "token_id": "123"
  }'

200

400

403

500

200

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

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

Getters

Retrieve the information on a specific NFT of a contract.

get

/getNftByTokenId

Authorizations

Query parameters

contractstring

The contract address of the token.

tokenIdinteger

The token ID

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://demo.gardenlab.io/api/v1/getNftByTokenId' \
  --header 'Authorization: Bearer JWT'

200

400

403

404

200

No body

Returns an object containing the NFT information.

Retrieve all the interactions for a contract.

get

/getAllInteractions

Authorizations

Query parameters

originstringrequired

The partner's name.

Example: spacex

contractstring

The contract for which to retrieve the interactions

Example: 0x0123456789abcdef0123456789abcdef01234567

contract_idstring

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

Example: summer_party

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://demo.gardenlab.io/api/v1/getAllInteractions?origin=text' \
  --header 'Authorization: Bearer JWT'

200

400

403

500

200

[
  {
    "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"
  }
]

Returns a list with all the interactions

Getting all the actions applied on a NFT

get

/getAllInteractionScansForToken

Authorizations

Query parameters

originstringrequired

The partner's name.

Example: spacex

tokenIdstringrequired

The token ID to fetch the interactions for

Example: 123

contractstring

The contract for which to retrieve the interactions

Example: 0x0123456789abcdef0123456789abcdef01234567

contract_idstring

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

Example: summer_party

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://demo.gardenlab.io/api/v1/getAllInteractionScansForToken?origin=text&tokenId=text' \
  --header 'Authorization: Bearer JWT'

200

400

403

500

200

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

Returns a list with all the interactions

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

get

/getBlockchainTxForToken

Authorizations

Query parameters

originstringrequired

The partner's name.

Example: spacex

contract_idstringrequired

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

Example: summer_party

token_idstringrequired

The token ID for which to retrieve the blockchain transactions

Example: summer_party

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://demo.gardenlab.io/api/v1/getBlockchainTxForToken?origin=text&contract_id=text&token_id=text' \
  --header 'Authorization: Bearer JWT'

200

400

403

500

200

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

Returns a list with all the blockchain transactions

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
}