Badge | Quest Protocol

Quest Protocol

Get all badges of a user

This endpoint retrives all the badges that the user is associated with.

get

/badges

Query parameters

userIdstringrequired

The Id of the user performing the request.

Example: dummy-userid

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.questprotocol.xyz/api/badges?userId=dummy-userid' \
  --header 'apikey: test'

200

401

500

{
  "success": true,
  "data": [
    {
      "inDyNFT": false,
      "claimed": false,
      "claimStatus": "UNCLAIMED",
      "data": {
        "xp": 10,
        "visibility": "OPEN",
        "type": "NONE",
        "remainingCount": 100,
        "createdAt": "2023-05-26T14:44:19.220Z",
        "badgeId": "dummy-id",
        "entityId": "e-000001",
        "name": "dummy-badge-name",
        "imageIPFS": "QmXdzQQ238rkdiM7i9YgXXEtm5n3Fypw9r6QPVtwjNMGzW",
        "description": "dummy-description",
        "badgeContractTokenId": "dummy-token",
        "endsAt": 1685198841965,
        "proofType": "Proof of Appreciation",
        "createdBy": "u-0000001",
        "typeData": [
          "t"
        ],
        "skills": [
          {
            "skillId": "123",
            "score": 123
          }
        ]
      }
    }
  ]
}

Successful response

Get all badges created by a user

This endpoint retrives all the badges a user has created.

get

/users/{userId}/created-badges

Path parameters

userIdstringrequired

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

useridstringrequired

The Id of the user performing the request.

Example: dummy-userid

tokenstringrequired

The token for user authentication.

Example: dummy-token

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.questprotocol.xyz/api/users/{userId}/created-badges' \
  --header 'apikey: test' \
  --header 'userid: dummy-userid' \
  --header 'token: dummy-token'

200

401

500

{
  "success": true,
  "data": [
    {
      "inDyNFT": false,
      "claimed": false,
      "claimStatus": "UNCLAIMED",
      "data": {
        "xp": 10,
        "visibility": "OPEN",
        "type": "NONE",
        "remainingCount": 100,
        "createdAt": "2023-05-26T14:44:19.220Z",
        "badgeId": "dummy-id",
        "entityId": "e-000001",
        "name": "dummy-badge-name",
        "imageIPFS": "QmXdzQQ238rkdiM7i9YgXXEtm5n3Fypw9r6QPVtwjNMGzW",
        "description": "dummy-description",
        "badgeContractTokenId": "dummy-token",
        "endsAt": 1685198841965,
        "proofType": "Proof of Appreciation",
        "createdBy": "u-0000001",
        "typeData": [
          "t"
        ],
        "skills": [
          {
            "skillId": "123",
            "score": 123
          }
        ]
      }
    }
  ]
}

Successful response

Get all badges of an entity

This endpoint retrives all the badges associated with an entity.

get

/entities/{entityId}/badges

Path parameters

entityIdstringrequired

Query parameters

userIdstringrequired

The Id of the user performing the request.

Example: dummy-userid

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.questprotocol.xyz/api/entities/{entityId}/badges?userId=dummy-userid' \
  --header 'apikey: test'

200

500

{
  "success": true,
  "data": [
    {
      "inDyNFT": false,
      "claimed": false,
      "claimStatus": "UNCLAIMED",
      "data": {
        "xp": 10,
        "visibility": "OPEN",
        "type": "NONE",
        "remainingCount": 100,
        "createdAt": "2023-05-26T14:44:19.220Z",
        "badgeId": "dummy-id",
        "entityId": "e-000001",
        "name": "dummy-badge-name",
        "imageIPFS": "QmXdzQQ238rkdiM7i9YgXXEtm5n3Fypw9r6QPVtwjNMGzW",
        "description": "dummy-description",
        "badgeContractTokenId": "dummy-token",
        "endsAt": 1685198841965,
        "proofType": "Proof of Appreciation",
        "createdBy": "u-0000001",
        "typeData": [
          "t"
        ],
        "skills": [
          {
            "skillId": "123",
            "score": 123
          }
        ]
      }
    }
  ]
}

Successful response

Add badge for an entity

This endpoint adds a badge for an entity.

post

/entities/{entityId}/badges

Path parameters

entityIdstringrequired

Query parameters

userIdstringrequired

The Id of the user performing the request.

Example: dummy-userid

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

tokenstringrequired

The token for user authentication.

Example: dummy-token

useridstringrequired

The Id of the user performing the request.

Example: dummy-userid

Body

namestringrequired

Example: dummy-name

imageIPFSstringrequired

Example: dummy-hash

descriptionstringrequired

Example: dummy-description

endsAtinteger · int64

Example: 1685198841965

xpnumber

Example: 0

airdropEnabledboolean

Example: false

typestring

Example: NONE

totalCountnumber

Example: 10

visibilitystring

Example: LIMITED

proofTypestring

Example: dummy proof

typeDataobject

userIdsstring[]

skillsobject[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.questprotocol.xyz/api/entities/{entityId}/badges?userId=dummy-userid' \
  --header 'apikey: test' \
  --header 'token: dummy-token' \
  --header 'userid: dummy-userid' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "dummy-name",
    "imageIPFS": "dummy-hash",
    "description": "dummy-description",
    "endsAt": 1685198841965,
    "xp": 0,
    "airdropEnabled": false,
    "type": "NONE",
    "totalCount": 10,
    "visibility": "LIMITED",
    "proofType": "dummy proof",
    "typeData": {},
    "userIds": [
      "u-00000001"
    ],
    "skills": [
      {
        "skillId": "dummy-id",
        "score": 100
      }
    ]
  }'

200

400

401

500

{
  "success": true,
  "badgeId": "badge-1212122"
}

Successful response

Get badge details of an entity

This endpoint retrives the badge details associated with an entity.

get

/entities/{entityId}/badges/{badgeId}

Path parameters

entityIdstringrequired

badgeIdstringrequired

Query parameters

userIdstringrequired

The Id of the user performing the request.

Example: dummy-userid

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

useridstringrequired

The Id of the user performing the request.

Example: dummy-userid

tokenstringrequired

The token for user authentication.

Example: dummy-token

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.questprotocol.xyz/api/entities/{entityId}/badges/{badgeId}?userId=dummy-userid' \
  --header 'apikey: test' \
  --header 'userid: dummy-userid' \
  --header 'token: dummy-token'

200

400

401

500

{
  "success": true,
  "data": {
    "badge_data": {
      "badgeId": "badge123",
      "entityId": "entity123",
      "badgeContractTokenId": "token123",
      "name": "My Badge",
      "imageIPFS": "https://example.com/badge-image.jpg",
      "description": "This is my badge description.",
      "xp": 100,
      "isEnabled": true,
      "visibility": "LIMITED",
      "type": "DISCORD",
      "proofType": "Type A",
      "endsAt": 1678900000,
      "remainingCount": 5,
      "createdBy": "user123",
      "createdAt": "2023-06-27T12:45:00Z",
      "typeData": {
        "key1": "value1",
        "key2": "value2"
      },
      "skills": [
        {
          "skillId": "skill1",
          "score": 80
        },
        {
          "skillId": "skill2",
          "score": 60
        }
      ]
    },
    "entity_data": {
      "id": "entity123",
      "entityURLAlias": "my-entity",
      "badgeContractAddress": "0x123abc",
      "dyNFTContractAddress": "0x456def",
      "themeContractAddress": "0x789ghi",
      "name": "My Entity",
      "openseaSlug": "my-entity-slug",
      "description": "This is my entity description.",
      "twitter": "myentity",
      "discord": "myentity#1234",
      "telegram": "myentity",
      "instagram": "myentity",
      "website": "https://myentity.com",
      "medium": "myentity",
      "imageUrl": "https://example.com/myentity.jpg",
      "bannerUrl": "https://example.com/myentity-banner.jpg",
      "isEnabled": false,
      "isPrivate": false,
      "defaultDyNftThemeId": "0",
      "discordQuestWebhookURL": "https://example.com/discord-webhook",
      "modifiedAt": "2023-06-27T12:45:00Z",
      "createdAt": "2023-06-25T09:00:00Z",
      "theme": {},
      "parentEntityId": "e-0000001",
      "chainSource": "OFF_CHAIN",
      "plan": "FREE",
      "entityRecordIds": [
        "record1",
        "record2"
      ],
      "contracts": [
        "contract1",
        "contract2"
      ]
    },
    "isOwner": true,
    "claimStatus": "NOT_WHITELISTED",
    "stats": {
      "claimedCount": 10,
      "unclaimedCount": 5
    },
    "skills_data": [
      {
        "skillId": "skil-12",
        "score": 20,
        "name": "Java",
        "description": "sun-microsystem's java",
        "isEnabled": true
      }
    ],
    "claimedUsers": [
      {
        "userId": "user-123"
      }
    ],
    "unclaimedUsers": [
      {
        "userId": "user-123"
      }
    ]
  }
}

Successful response

Update badge

This endpoint updates a badge of an entity.

post

/entities/{entityId}/badges/{badgeId}/update

Path parameters

entityIdstringrequired

badgeIdstringrequired

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

useridstringrequired

The Id of the user performing the request.

Example: dummy-userid

tokenstringrequired

The token for user authentication.

Example: dummy-token

Body

namestring

Example: dummy badge

imageIPFSstring

Example: ipfa-hash

descriptionstring

Example: updated the description

typestring

Example: DISCORD

endsAtnumber

Example: 720000

xpnumber

Example: 20

typeDataobject

skillsobject[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.questprotocol.xyz/api/entities/{entityId}/badges/{badgeId}/update' \
  --header 'apikey: test' \
  --header 'userid: dummy-userid' \
  --header 'token: dummy-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "dummy badge",
    "imageIPFS": "ipfa-hash",
    "description": "updated the description",
    "type": "DISCORD",
    "endsAt": 720000,
    "xp": 20,
    "typeData": {},
    "skills": [
      {
        "skillId": "java",
        "score": 100
      }
    ]
  }'

200

400

401

500

{
  "success": true
}

Successful response

Claim badge for an entity

This endpoint allows users to claim a badge for an entity

post

/entities/{entityId}/badges/{badgeId}/claim

Path parameters

entityIdstringrequired

badgeIdstringrequired

Query parameters

userIdstringrequired

The Id of the user performing the request.

Example: dummy-userid

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

useridstringrequired

The Id of the user performing the request.

Example: dummy-userid

tokenstringrequired

The token for user authentication.

Example: dummy-token

Body

addToDynamicNFTboolean

Example: true

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.questprotocol.xyz/api/entities/{entityId}/badges/{badgeId}/claim?userId=dummy-userid' \
  --header 'apikey: test' \
  --header 'userid: dummy-userid' \
  --header 'token: dummy-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "addToDynamicNFT": true
  }'

200

400

401

500

{
  "success": true,
  "nftMinted": true,
  "calculatedDynamicNFT": true
}

Successful response

Add users to badge

This endpoint allows an admin to add users to a Badge.

post

/entities/{entityId}/badges/{badgeId}/users

Path parameters

entityIdstringrequired

badgeIdstringrequired

Query parameters

userIdstringrequired

The Id of the user performing the request.

Example: dummy-userid

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

tokenstringrequired

The token for user authentication.

Example: dummy-token

Body

userIdsstring[]required

Example: ["user-1","user-2"]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.questprotocol.xyz/api/entities/{entityId}/badges/{badgeId}/users?userId=dummy-userid' \
  --header 'apikey: test' \
  --header 'token: dummy-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "userIds": [
      "user-1",
      "user-2"
    ]
  }'

200

400

500

{
  "success": true
}

Successful response

Get Badges Count for User

Retrieve the number of badges earned by a specific user within a particular entity.

get

/entities/{entityId}/users/{userId}/badges-count

Path parameters

entityIdstringrequired

The unique identifier of the entity.

userIdstringrequired

The unique identifier of the user within the entity.

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

useridstringrequired

The Id of the user performing the request.

Example: dummy-userid

tokenstringrequired

The token for user authentication.

Example: dummy-token

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.questprotocol.xyz/api/entities/{entityId}/users/{userId}/badges-count' \
  --header 'apikey: test' \
  --header 'userid: dummy-userid' \
  --header 'token: dummy-token'

200

401

500

{
  "success": true,
  "data": 5
}

Successful response

Get User Earned Badges for Entity

Retrieve the badges earned by a specific user within a particular entity.

get

/entities/{entityId}/users/{userId}/badges

Path parameters

entityIdstringrequired

The unique identifier of the entity.

userIdstringrequired

The unique identifier of the user within the entity.

Query parameters

prefixBadgeIpfsstring

Specify 'true' to prefix Badge IPFS URLs with the base URL.

pageinteger

The page number for paginated results (default: 1).

limitinteger

The number of items per page (default: 20).

Header parameters

apikeystringrequired

The API key for authentication

Example: test

apisecretstring

The secret key for authentication

Example: test-secret

useridstringrequired

The Id of the user performing the request.

Example: dummy-userid

tokenstringrequired

The token for user authentication.

Example: dummy-token

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.questprotocol.xyz/api/entities/{entityId}/users/{userId}/badges' \
  --header 'apikey: test' \
  --header 'userid: dummy-userid' \
  --header 'token: dummy-token'

200

401

500

{
  "success": true,
  "page": 1,
  "totalCount": 10,
  "totalPages": 1,
  "data": [
    {
      "badgeId": "badge123",
      "entityId": "entity123",
      "badgeContractTokenId": "token123",
      "name": "My Badge",
      "imageIPFS": "https://example.com/badge-image.jpg",
      "description": "This is my badge description.",
      "xp": 100,
      "isEnabled": true,
      "visibility": "LIMITED",
      "type": "DISCORD",
      "proofType": "Type A",
      "endsAt": 1678900000,
      "remainingCount": 5,
      "createdBy": "user123",
      "createdAt": "2023-06-27T12:45:00Z",
      "typeData": {
        "key1": "value1",
        "key2": "value2"
      },
      "skills": [
        {
          "skillId": "skill1",
          "score": 80
        },
        {
          "skillId": "skill2",
          "score": 60
        }
      ]
    }
  ]
}

Successful response