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

post

https://demo.gardenlab.io/api/v1https://app.gardenlab.io/api/v1http://localhost:5001/gardenlab-test/europe-west1

/saveActionInteraction

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

Autorisations

bearerAuth

AuthorizationstringRequis

Bearer authentication header of the form Bearer <token>.

Corps

application/json

originstringRequis

The partner's name.

Example: spacex

contract_idstringRequis

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

Example: summer_party

interactionIdstringOptionnel

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

Example: 0ER368760G8787238

Réponses

200

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

application/json

idstringOptionnel

The interaction ID

Example: IQ0LuundpiAvnfDcQ21Y

400

The request is malformed. Please verify the content of the body.

application/json

403

The API key is missing or incorrect.

application/json

500

An internal error occured. Check the error message.

application/json

post

/saveActionInteraction

HTTPcURLJavaScriptPython

POST /api/v1/saveActionInteraction HTTP/1.1
Host: demo.gardenlab.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 319

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

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

post

https://demo.gardenlab.io/api/v1https://app.gardenlab.io/api/v1

/newUserForPartner

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.

Autorisations

bearerAuth

AuthorizationstringRequis

Bearer authentication header of the form Bearer <token>.

Corpsobject[]

application/json

originstringRequis

The partner's name.

Example: spacex

emailstringRequis

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

uidstringRequis

The user identification.

user_category_idstringRequis

The user catagory. This defines which NFT to distribute.

Example: VIP

contract_idstringRequis

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

Example: summer_party

Réponses

200

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

application/json

ou

400

The request is not valid or an error occured.

application/json

403

The API key is missing or incorrect.

application/json

500

An internal error occured. Please verify the message

application/json

post

/newUserForPartner

HTTPcURLJavaScriptPython

POST /api/v1/newUserForPartner HTTP/1.1
Host: demo.gardenlab.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 269

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

[
  {
    "contract": "0x0123456789abcdef0123456789abcdef01234567",
    "tokenId": "123",
    "attributes": {},
    "url": "text",
    "uid": "text",
    "email": "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

post

https://demo.gardenlab.io/api/v1https://app.gardenlab.io/api/v1http://localhost:5001/gardenlab-test/europe-west1

/newActionForUser

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

Autorisations

bearerAuth

AuthorizationstringRequis

Bearer authentication header of the form Bearer <token>.

Corps

application/json

originstringOptionnel

The partner's name.

Example: spacex

contract_idstringOptionnel

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

Example: summer_party

action_idstringOptionnel

The action ID.

Example: eshop_purchase

xpIncrementnumberOptionnel

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

Example: 5

Réponses

200

Returns an object containing the NFT created for the user.

application/json

contractstringOptionnel

The NFT's smart contract address.

Example: 0x0123456789abcdef0123456789abcdef01234567

tokenIdstringOptionnel

The NFT token ID.

Example: 123

attributesobjectOptionnel

The NFT attributes.

urlstringOptionnel

The NFT page URL.

uidstringOptionnel

The owner User ID.

emailstringOptionnel

The owner email address.

400

The request is malformed. Please verify the content of the body.

application/json

403

The API key is missing or incorrect.

application/json

500

An internal error occured. Check the error message.

application/json

post

/newActionForUser

HTTPcURLJavaScriptPython

POST /api/v1/newActionForUser HTTP/1.1
Host: demo.gardenlab.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 131

{
  "origin": "spacex",
  "contract_id": "summer_party",
  "action_id": "eshop_purchase",
  "xpIncrement": 5,
  "guest": {
    "email": "text",
    "uid": "text"
  }
}

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

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

Mint token

post

https://demo.gardenlab.io/api/v1https://app.gardenlab.io/api/v1

/mintTokenForUser

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.

Autorisations

bearerAuth

AuthorizationstringRequis

Bearer authentication header of the form Bearer <token>.

Corps

application/json

originstringRequis

The partner's name.

Example: spacex

emailstringRequis

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

Example: [email protected]

uidstringRequis

The user identification.

Example: u123456789

user_addrstringRequis

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

Example: 0x0123456789abcdef0123456789abcdef01234567

contract_idstringRequis

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

Example: summer_party

contractstringOptionnel

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

Example: 0x0123456789abcdef0123456789abcdef01234567

token_idstringOptionnel

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

Réponses

200

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

application/json

userAddrstringRequis

The user address to which the NFT will be minted.

Example: 0x0123456789abcdef0123456789abcdef01234567

contractstringRequis

The contract address

Example: 0x0123456789abcdef0123456789abcdef01234567

tokenIdstringRequis

The token ID being minted

Example: 123

tokenUrlstringRequis

The token URL.

Example: ipfs://bafyreid2zqtuvrcemlhesksvibci7xaphbvw4ytun5xykdjancfaum2l3i/metadata.json

400

The request is not valid or an error occured.

application/json

403

The API key is missing or incorrect.

application/json

500

An internal error occured. Please verify the message

application/json

post

/mintTokenForUser

HTTPcURLJavaScriptPython

POST /api/v1/mintTokenForUser HTTP/1.1
Host: demo.gardenlab.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 224

{
  "origin": "spacex",
  "email": "[email protected]",
  "uid": "u123456789",
  "user_addr": "0x0123456789abcdef0123456789abcdef01234567",
  "contract_id": "summer_party",
  "contract": "0x0123456789abcdef0123456789abcdef01234567",
  "token_id": "123"
}

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

Getters

get

https://demo.gardenlab.io/api/v1https://app.gardenlab.io/api/v1http://localhost:5001/gardenlab-test/europe-west1

/getNftByTokenId

Retrieve the information on a specific NFT of a contract.

Autorisations

bearerAuth

AuthorizationstringRequis

Bearer authentication header of the form Bearer <token>.

Paramètres de requête

contractstringOptionnel

The contract address of the token.

tokenIdintegerOptionnel

The token ID

Réponses

200

Returns an object containing the NFT information.

Aucun contenu

400

There is an error in the query.

application/json

403

The API key is missing or incorrect.

application/json

404

The specified NFT cannot be found in Gardenlab database.

application/json

get

/getNftByTokenId

HTTPcURLJavaScriptPython

GET /api/v1/getNftByTokenId HTTP/1.1
Host: demo.gardenlab.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

Aucun contenu

get

https://demo.gardenlab.io/api/v1https://app.gardenlab.io/api/v1http://localhost:5001/gardenlab-test/europe-west1

/getAllInteractions

Retrieve all the interactions for a contract.

Autorisations

bearerAuth

AuthorizationstringRequis

Bearer authentication header of the form Bearer <token>.

Paramètres de requête

originstringRequis

The partner's name.

Example: spacex

contractstringOptionnel

The contract for which to retrieve the interactions

Example: 0x0123456789abcdef0123456789abcdef01234567

contract_idstringOptionnel

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

Example: summer_party

Réponses

200

Returns a list with all the interactions

application/json

typestringRequis

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

Example: IRL Event

namestringRequis

The interaction name

Example: Event checkin

descriptionstringOptionnel

The interaction description

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

xpIncrementnumberOptionnel

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

Example: 5

noXpbooleanOptionnel

Whether the interaction adds XP or just an attribute type

Example: false

customXpIncrementbooleanOptionnel

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

Example: false

authScanCountnumberOptionnel

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

Example: 1

action_idstringOptionnel

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

Example: event_checkin

400

There is an error in the query.

application/json

403

The API key is missing or incorrect.

application/json

500

An internal error occured. Check the error message.

application/json

get

/getAllInteractions

HTTPcURLJavaScriptPython

GET /api/v1/getAllInteractions?origin=text HTTP/1.1
Host: demo.gardenlab.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

get

https://demo.gardenlab.io/api/v1https://app.gardenlab.io/api/v1http://localhost:5001/gardenlab-test/europe-west1

/getAllInteractionScansForToken

Getting all the actions applied on a NFT

Autorisations

bearerAuth

AuthorizationstringRequis

Bearer authentication header of the form Bearer <token>.

Paramètres de requête

originstringRequis

The partner's name.

Example: spacex

tokenIdstringRequis

The token ID to fetch the interactions for

Example: 123

contractstringOptionnel

The contract for which to retrieve the interactions

Example: 0x0123456789abcdef0123456789abcdef01234567

contract_idstringOptionnel

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

Example: summer_party

Réponses

200

Returns a list with all the interactions

application/json

A list of the interactions

xpBeforenumberRequis

XP before the interaction

xpAfternumberRequis

XP after the interaction

lvlBeforenumberRequis

Level before the interaction

lvlAfternumberRequis

Level after the interaction

maxLvlReachedbooleanRequis

Flag indicating the max level has been reached

interactionNamestringRequis

The name of the interaction

typestringRequis

The type of the interaction (attribute name)

400

There is an error in the query.

application/json

403

The API key is missing or incorrect.

application/json

500

An internal error occured. Check the error message.

application/json

get

/getAllInteractionScansForToken

HTTPcURLJavaScriptPython

GET /api/v1/getAllInteractionScansForToken?origin=text&tokenId=text HTTP/1.1
Host: demo.gardenlab.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

get

https://demo.gardenlab.io/api/v1https://app.gardenlab.io/api/v1

/getBlockchainTxForToken

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

Autorisations

bearerAuth

AuthorizationstringRequis

Bearer authentication header of the form Bearer <token>.

Paramètres de requête

originstringRequis

The partner's name.

Example: spacex

contract_idstringRequis

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

Example: summer_party

token_idstringRequis

The token ID for which to retrieve the blockchain transactions

Example: summer_party

Réponses

200

Returns a list with all the blockchain transactions

application/json

The interaction details

txHashstringRequis

The blockchain transaction hash

transactionUrlstringRequis

The blockchain explorer url

newUristringRequis

The URI of the token

xpBeforenumberRequis

XP before the interaction

xpAfternumberRequis

XP after the interaction

lvlBeforenumberRequis

Level before the interaction

lvlAfternumberRequis

Level after the interaction

maxLvlReachedbooleanRequis

Flag indicating the max level has been reached

interactionNamestringRequis

The name of the interaction

typestringRequis

The type of the interaction (attribute name)

400

There is an error in the query.

application/json

403

The API key is missing or incorrect.

application/json

500

An internal error occured. Check the error message.

application/json

get

/getBlockchainTxForToken

HTTPcURLJavaScriptPython

GET /api/v1/getBlockchainTxForToken?origin=text&contract_id=text&token_id=text HTTP/1.1
Host: demo.gardenlab.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

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
}