Collections

* is a required field

Make sure to use your X-Auth-Token when making a POST request. Your X-Auth-Token is the private key associated to your ERC-20 wallet.

Create Collection

Create a new collection

Create a collection with image url

post

Path parameters

fqGnstringRequired

Fully Qualified Game Name

Example: com.studio.game

Header parameters

X-Auth-KeystringRequiredPattern: [0-9a-fA-F]{64}

X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9

Body

application/json

displayNamestring · max: 255Required

Collection display name

Example: New year cards

descriptionstring · max: 2000Required

Collection description

Example: Super game new year cards

displayInDiscoverybooleanOptional

The flag that controls display in the Discovery

Default: trueExample: true

imageUrlstring · max: 255Required

Main image

Example: Collection imagePattern: ^(http|https)://[-a-zA-Z0-9+&@#/%?=~_|,!:.;]*[-a-zA-Z0-9+@#/%=&_|]\.(?:jpg|jpeg|png)$

qCnstring · max: 64Required

Qualified Collection Name

Example: cardsPattern: (\b[a-z0-9-]{1,20}\b)(:[1-9][0-9]{0,10})?

Responses

201

Created

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

/collections/manage/{fqGn}/create

HTTPcURLJavaScriptPython

POST /collections/manage/{fqGn}/create HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 144

{
  "displayName": "New year cards",
  "description": "Super game new year cards",
  "displayInDiscovery": true,
  "imageUrl": "Collection image",
  "qCn": "cards"
}

{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {}
  }
}

Create a new collection multipart

Create a collection with image upload

post

Path parameters

fqGnstringRequired

Fully Qualified Game Name

Example: com.studio.game

Header parameters

X-Auth-KeystringRequiredPattern: [0-9a-fA-F]{64}

X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9

Body

multipart/form-dataapplication/json

imagestring · binaryRequired

Responses

201

Created

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

/collections/manage/{fqGn}/create-multipart

HTTPcURLJavaScriptPython

POST /collections/manage/{fqGn}/create-multipart HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 140

{
  "data": {
    "displayName": "New year cards",
    "description": "Super game new year cards",
    "displayInDiscovery": true,
    "qCn": "cards"
  },
  "image": "binary"
}

multipart/form-dataapplication/json

{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {}
  }
}

create vs create-multipart

You need to upload the image somewhere and post the URL when you use /collections/manage/{gqGn}/create API. Once it is created, we store image data in our DB.

On the other hand, you can post the image binary directly to us if you use /collections/manage/{fqGn}/create-multipart API.

Collection Metadata

Update collection metadata

Update metadata

post

Path parameters

fqCnstringRequired

Fully Qualified Collection Name

Example: com.studio.game.collection

Header parameters

X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}

Body

application/json

displayNamestringOptional

New display name

descriptionstringOptional

New description

imageUrlstringOptional

New image URL

Responses

200

OK

No content

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

/collections/manage/{fqCn}/update-metadata

HTTPcURLJavaScriptPython

POST /collections/manage/{fqCn}/update-metadata HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "displayName": "text",
  "description": "text",
  "imageUrl": "text"
}

No content

Update collection metadata multipart

Update metadata with image upload

post

Path parameters

fqCnstringRequired

Fully Qualified Collection Name

Example: com.studio.game.collection

Header parameters

X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}

Body

multipart/form-dataapplication/json

imagestring · binaryRequired

Responses

200

OK

No content

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

/collections/manage/{fqCn}/update-metadata-multipart

HTTPcURLJavaScriptPython

POST /collections/manage/{fqCn}/update-metadata-multipart HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 69

{
  "data": {
    "displayName": "text",
    "description": "text"
  },
  "image": "binary"
}

multipart/form-dataapplication/json

No content

Collection Details

List game collections

List Game Collections

get

Path parameters

fqGnstringRequired

Fully qualified game name

Example: com.studio.game

Responses

200

OK

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get

/collections/{fqGn}/

HTTPcURLJavaScriptPython

GET /collections/{fqGn}/ HTTP/1.1
Host: game-api.openvessel.io
Accept: */*

{
  "response": [
    {
      "address": "text",
      "fqCn": "text",
      "displayName": "text",
      "createdAt": 1
    }
  ]
}

Collection Object

Name	Type	Description
displayName	string	User-friendly name of the collection
fqCn	string	Fully qualified collection name
address	string	Blockchain address of the contract backing this collection
createdAt	number	Unix timestamp of the collection creation time

Details of the selected NFT collection

get

Path parameters

fqGnstringRequired

Fully Qualified Game Name

Example: com.studio.game

qcnstringRequired

Qualified Collection Name

Example: armor01

Responses

200

OK

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get

/collections/{fqGn}/{qcn}/

HTTPcURLJavaScriptPython

GET /collections/{fqGn}/{qcn}/ HTTP/1.1
Host: game-api.openvessel.io
Accept: */*

{
  "response": {
    "address": "0x25e4aeeb291b9c73e726ab8ba2dec86ebe467144",
    "fqCn": "com.develop.game.new-year-cards",
    "displayName": "New year cards",
    "createdAt": 1653407651,
    "totalSupply": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "description": "Super game new year cards",
    "imageUrl": "https://static.openvessel.io/com.develop/game/new-year-cards/collection_image.png",
    "status": "ACTIVE"
  }
}

Collection Details Object

Name	Type	Description
address	string	Blockchain address of the contract backing this collection
fqCn	string	Fully qualified collection name
displayName	string	User-friendly name of the collection
createdAt	number	Unix timestamp of the collection creation time
totalSupply	object	Total supply of each qTn under the collection
description	string	Description of this collection
imageUrl	string	Image URL for this collection
status	string	ACTIVE or PAUSED