Mythical Platform
Mythical Platform
  • The Mythical Platform API
  • Quick start
    • Authenticate
    • Create a guest player
    • Create an item type
    • Grant an item to a player
    • Update item metadata
    • Use webhooks for real time messages
    • Buy a listed item
  • API Reference
    • Players
    • Item Types
    • Items
    • Marketplace
      • Listings
      • Offers
      • Quick trade
      • Transaction history
      • Exchange rate
    • Webhook management
    • System
Powered by GitBook
On this page
  1. API Reference

Items

PreviousItem TypesNextMarketplace

Last updated 8 months ago

Get an item

get

Retrieve a single item by id.

Authorizations
Path parameters
itemIdstringRequired
Header parameters
x-mythical-environment-idstring · uuidRequired

Identifier for the environment that this request should interact with

Responses
200
Success
application/json
get
GET /v1/items/{itemId} HTTP/1.1
Host: 
Authorization: Bearer JWT
x-mythical-environment-id: 123e4567-e89b-12d3-a456-426614174000
Accept: */*
200

Success

{
  "id": "text",
  "itemTypeId": "text",
  "ownerPlayerId": "text",
  "tokenId": 1,
  "state": "pending",
  "metadataUrl": "http://url.com/1",
  "metadata": {
    "name": "text",
    "description": "text",
    "image": "text",
    "attributes": [
      {
        "type": "attributeName",
        "value": "attrValue",
        "displayType": "number, boolean, string",
        "maxValue": 255
      }
    ]
  },
  "tags": [
    "text"
  ]
}

Burn an item

post

On-chain, this will irreversably transfer the item to the zero address (0x000...), effectively destroying the item.

Authorizations
Path parameters
itemIdstringRequired
Header parameters
x-mythical-environment-idstring · uuidRequired

Identifier for the environment that this request should interact with

x-idempotency-keystring · max: 64Required

A unique identifier for the request. If the request is repeated with the same idempotency key, the response will be the same as the first request. Recommend using a UUID or ULID

Responses
200
Success
application/json
post
POST /v1/items/{itemId}/burn HTTP/1.1
Host: 
Authorization: Bearer JWT
x-mythical-environment-id: 123e4567-e89b-12d3-a456-426614174000
x-idempotency-key: text
Accept: */*
200

Success

{
  "id": "text",
  "itemTypeId": "text",
  "ownerPlayerId": "text",
  "tokenId": 1,
  "state": "pending",
  "metadataUrl": "http://url.com/1",
  "metadata": {
    "name": "text",
    "description": "text",
    "image": "text",
    "attributes": [
      {
        "type": "attributeName",
        "value": "attrValue",
        "displayType": "number, boolean, string",
        "maxValue": 255
      }
    ]
  },
  "tags": [
    "text"
  ]
}
  • POSTGrant an item to a player
  • POSTSearch items
  • GETGet an item
  • PUTUpdate an item
  • POSTTransfer an item from one player to another
  • POSTBurn an item

Grant an item to a player

post

Mints an item of a given item type to the specified player. If name, description, image, or attributes are not provided, the item will be granted with the default metadata configured on the item type. On-chain, granting an item means an NFT is minted from the collection associated with the item type to the wallet of the given player.

Authorizations
Header parameters
x-mythical-environment-idstring · uuidRequired

Identifier for the environment that this request should interact with

x-idempotency-keystring · max: 64Required

A unique identifier for the request. If the request is repeated with the same idempotency key, the response will be the same as the first request. Recommend using a UUID or ULID

Body
itemTypeIdstring · max: 64Required

Unique identifier of the item

ownerPlayerIdstring · max: 64Required

The id of the player who owns the item

tokenIdintegerOptional

The on-chain unique identifier of the item within its given collection. The token id of the item is displayed in the Mythical Marketplace.

Example: 1
tagsstring[]Optional
Responses
200
Success
application/json
400
Bad Request
application/json
500
Internal Server Error
application/json
post
POST /v1/items HTTP/1.1
Host: 
Authorization: Bearer JWT
x-mythical-environment-id: 123e4567-e89b-12d3-a456-426614174000
x-idempotency-key: text
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "itemTypeId": "f4e5d3a4-2a9b-4d9f-bc5a-73b3f0c47b5e",
  "ownerPlayerId": "9779f02d-5193-4ab1-ae15-f18e091f38e1",
  "tags": [
    "reward"
  ]
}
{
  "id": "text",
  "itemTypeId": "text",
  "ownerPlayerId": "text",
  "tokenId": 1,
  "state": "pending",
  "metadataUrl": "http://url.com/1",
  "metadata": {
    "name": "text",
    "description": "text",
    "image": "text",
    "attributes": [
      {
        "type": "attributeName",
        "value": "attrValue",
        "displayType": "number, boolean, string",
        "maxValue": 255
      }
    ]
  },
  "tags": [
    "text"
  ]
}

Search items

post

Retrieve a list of items. Supports filtering, sorting, and pagination.

Authorizations
Header parameters
x-mythical-environment-idstring · uuidRequired

Identifier for the environment that this request should interact with

Body
idsstring[]Optional

An array of items ids to search for.

itemTypeIdsstring[]Optional

An array of item type ids to find matching item instances for

ownerPlayerIdsstring[]Optional

An array of player ids who own the items you are interested in searching for

statesstring · string[]Optional

The current blockchain state of the items you are searching for

limitintegerOptional

The maximum number of items you would like returned in this search

Example: 10
skipintegerOptional

How many records should be skipped in the result set before returning results?

Example: 10
Responses
200
Success
application/json
post
POST /v1/items/search HTTP/1.1
Host: 
Authorization: Bearer JWT
x-mythical-environment-id: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "itemTypeIds": [
    "f4e5d3a4-2a9b-4d9f-bc5a-73b3f0c47b5e",
    "09babafe-3fe1-4913-94c3-eb79fc5acf00"
  ],
  "limit": 100,
  "skip": 0
}
200

Success

[
  {
    "id": "text",
    "itemTypeId": "text",
    "ownerPlayerId": "text",
    "tokenId": 1,
    "state": "pending",
    "metadataUrl": "http://url.com/1",
    "metadata": {
      "name": "text",
      "description": "text",
      "image": "text",
      "attributes": [
        {
          "type": "attributeName",
          "value": "attrValue",
          "displayType": "number, boolean, string",
          "maxValue": 255
        }
      ]
    },
    "tags": [
      "text"
    ]
  }
]

Update an item

put

Update an item

Authorizations
Path parameters
itemIdstringRequired
Header parameters
x-mythical-environment-idstring · uuidRequired

Identifier for the environment that this request should interact with

x-idempotency-keystring · max: 64Required

A unique identifier for the request. If the request is repeated with the same idempotency key, the response will be the same as the first request. Recommend using a UUID or ULID

Body
Responses
200
Success
application/json
put
PUT /v1/items/{itemId} HTTP/1.1
Host: 
Authorization: Bearer JWT
x-mythical-environment-id: 123e4567-e89b-12d3-a456-426614174000
x-idempotency-key: text
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "metadata": {
    "name": "itemName",
    "description": "itemDescription",
    "image": "http://url.com/image",
    "attributes": [
      {
        "type": "attribute1",
        "value": "20",
        "displayType": "number",
        "maxValue": 100
      },
      {
        "type": "attribute2",
        "value": "value",
        "displayType": "string"
      }
    ]
  }
}
200

Success

{
  "id": "text",
  "itemTypeId": "text",
  "ownerPlayerId": "text",
  "tokenId": 1,
  "state": "pending",
  "metadataUrl": "http://url.com/1",
  "metadata": {
    "name": "text",
    "description": "text",
    "image": "text",
    "attributes": [
      {
        "type": "attributeName",
        "value": "attrValue",
        "displayType": "number, boolean, string",
        "maxValue": 255
      }
    ]
  },
  "tags": [
    "text"
  ]
}

Transfer an item from one player to another

post

On-chain, this will transfer the item between the wallets of the provided players.

Authorizations
Path parameters
itemIdstringRequired

The id of the item to transfer

Header parameters
x-mythical-environment-idstring · uuidRequired

Identifier for the environment that this request should interact with

x-idempotency-keystring · max: 64Required

A unique identifier for the request. If the request is repeated with the same idempotency key, the response will be the same as the first request. Recommend using a UUID or ULID

Body
fromPlayerIdstring · max: 64Required

Player from which the item will be transferred

toPlayerIdstring · max: 64Required

Player to which the item will be transferred

Responses
200
Success
application/json
post
POST /v1/items/{itemId}/transfer HTTP/1.1
Host: 
Authorization: Bearer JWT
x-mythical-environment-id: 123e4567-e89b-12d3-a456-426614174000
x-idempotency-key: text
Content-Type: application/json
Accept: */*
Content-Length: 107

{
  "fromPlayerId": "b915c482-1170-4dc7-819e-8ebf83569bc4",
  "toPlayerId": "3616cde1-fb31-48aa-8a31-32aed792cb7d"
}
200

Success

{
  "id": "text",
  "itemTypeId": "text",
  "ownerPlayerId": "text",
  "tokenId": 1,
  "state": "pending",
  "metadataUrl": "http://url.com/1",
  "metadata": {
    "name": "text",
    "description": "text",
    "image": "text",
    "attributes": [
      {
        "type": "attributeName",
        "value": "attrValue",
        "displayType": "number, boolean, string",
        "maxValue": 255
      }
    ]
  },
  "tags": [
    "text"
  ]
}