> For the complete documentation index, see [llms.txt](https://docs.labs.zelus.io/zelus-labs-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.zelus.io/zelus-labs-api/reference/nft/getnftmetadata.md).

# Get NFT metadata

This API endpoint allows you to retrieve metadata for a specific NFT based on the `contractId` and `nftTokenId`. It also supports optional parameters for token ID formatting.

## Endpoint Details

| Description | Data                                                                               |
| ----------- | ---------------------------------------------------------------------------------- |
| API Name    | [getNftMetadata](https://sandbox.api.labs.zelus.io/docs/#/NFT/get_v1_nft_metadata) |
| HTTP Method | GET                                                                                |
| URL         | `/v1/nft/metadata`                                                                 |

{% tabs %}
{% tab title="Request" %}

#### Headers

| Key          | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| x-api-key    | API\_KEY           |

#### Query Parameters

| Parameter         | Type             | Description                                                                                            |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |
| **contractId**    | string           | Contract ID to get metadata for                                                                        |
| **nftTokenId**    | string           | the smart contract that the NFT belongs to (See the note above)                                        |
| **tokenIdFormat** | string, optional | NFT token id format. Possible values `decimal` or `hex`. Defaults to `decimal` if it is not specified. |

As a prerequisite, you must have one or more NFT contracts that can be managed by your account (see [getAccountContracts](https://github.com/zelusio/alpha-api-docs/blob/master/getAccounContracts.md).
{% endtab %}

{% tab title="Response" %}
The response will contain the metadata of the specified NFT.

```tsx
{
    result: INftMetadata
    | error?: IResponseError   // Optional error information
}

export interface INftTraits {
  displayType: number,
  traitType: string,
  value?: any
}

export interface INftMetadata {
  externalUrl?: string;
  traits: INftTraits[];
  name: string;
  description: string;
  imageUrl: string;
  thumbnailUrl?: string;
  imageMimeType: string;
  thumbnailMimeType?: string;
}
```

#### Success result

```json
{
  "result": {
    "traits": [
      {
        "displayType": "number",
        "traitType": "Member Since",
        "value": 2023
      },
      {
        "displayType": "string",
        "traitType": "Member Tier",
        "value": "Pearl"
      }
    ],
    "name": "SMOOTH Pass",
    "description": "This pass is your key to unlock rewards and more through Smooth's cutting-edge loyalty platform",
    "imageUrl": "https://assets.nft.zelus.io/Smooth-Collectibles-dev/1/image1.png",
    "imageMimeType": "image/png",
    "externalUrl": "https://zelus.io"
  }
}

```

#### Error Messages

* Incorrect or missing `contractId`
  * `{ "code": 400, "message": "Contract not found" }`
* Missing `nftTokenId` or invalid format based on `tokenIdFormat`
  * `{ "code": 404, "message": "NFT not found!" }`
    {% endtab %}
    {% endtabs %}

## Examples

{% tabs %}
{% tab title="CURL" %}

```bash
curl -X GET 'https://sandbox.api.labs.zelus.io/v1/nft/metadata?contractId=yourContractId&nftTokenId=yourTokenId' \
     -H "x-api-key: YOUR_API_KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://sandbox.api.labs.zelus.io/v1/nft/metadata"
headers = {
    "x-api-key": "YOUR_API_KEY"
}
params = {
    "contractId": "yourContractId",
    "nftTokenId": "yourTokenId"
}

response = requests.get(url, headers=headers, params=params)
nft_metadata = response.json() # Assuming INftMetadata format
print(f"NFT Metadata: {nft_metadata}")
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
const axios = require('axios');

const url = "https://sandbox.api.labs.zelus.io/v1/nft/metadata";
const headers = {
    "x-api-key": "YOUR_API_KEY"
};
const params = {
    contractId: "yourContractId",
    nftTokenId: "yourTokenId"
};

axios.get(url, { headers: headers, params: params }).then(response => {
    const nft_metadata = response.data; // Assuming INftMetadata format
    console.log(`NFT Metadata: ${JSON.stringify(nft_metadata)}`);
}).catch(error => {
    console.error('Error:', error.response.data);
});
```

{% endtab %}
{% endtabs %}

## Notes

* Make sure to either provide a `contractId` when making the request.
* Token ID is always required and its format can be controlled using the `tokenIdFormat` parameter.
* If using the `hex` format for the token ID, ensure it's a valid hexadecimal value.
* If a `contractId` is used, the base metadata URL retrieved from it combined with the token ID will be used to fetch the metadata.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.labs.zelus.io/zelus-labs-api/reference/nft/getnftmetadata.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.