> For the complete documentation index, see [llms.txt](https://rareful.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rareful.gitbook.io/documentation/reference/api-reference/minting-and-file-upload.md).

# Minting and File Upload

These endpoints include minting NFTs with urls, minting NFTs with file uploading, and pre-uploading files to speed up minting

## Minting NFTs

## Mint a new NFT with media that is stored in a url

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/mintFromUrl`

Mints a new NFT to the given wallet address/user\_id, or creates a new user and mints to them. This last piece of functionality is useful if a user wants to purchase an NFT from a collection but they do not yet have a wallet they are conected to.

#### Headers

| Name                                           | Type   | Description                                                                                       |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark>     | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json (Required)                                                                       |

#### Request Body

| Name                                                     | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contract\_address                                        | string | The contract address to mint the NFT on. If none provided, your default contract will be used                                                                                                                                                                                                                                                                                                                                                 |
| recipient\_public\_key<mark style="color:red;">\*</mark> | String | The wallet address to mint to. A user with this wallet address will be created if one does not already exists. One of user id and public key must be provided                                                                                                                                                                                                                                                                                 |
| name                                                     | String | The name of the NFT. This will be included in the NFT metadata on the blockchain. It defaults to ""                                                                                                                                                                                                                                                                                                                                           |
| url<mark style="color:red;">\*</mark>                    | String | A link to the image/media that will become your NFT. Must be included if s3\_url and ipfs\_uri are not                                                                                                                                                                                                                                                                                                                                        |
| mint\_price                                              | Int    | How much did you charge to mint this NFT, if at all?                                                                                                                                                                                                                                                                                                                                                                                          |
| description                                              | String | The description of the NFT. This will be included in the NFT metadata on the blockchain. It defaults to "".                                                                                                                                                                                                                                                                                                                                   |
| attributes                                               | JSON   | <p>Many NFTs include an attributes JSON which describes the NFT. </p><p>Refer to the following link to learn more: <a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md"><https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md></a>. </p><p>A sample JSON is:</p><p>\[ { "trait\_type": "Base", "value": "Horse" }, { "trait\_type": "Eyes", "value": "Small" }, { "trait\_type": "Power", "value": 3 } ]</p><p></p> |
| s3\_url<mark style="color:red;">\*</mark>                | String | The s3\_url returned from calling the upload route. Must be included if url is not                                                                                                                                                                                                                                                                                                                                                            |
| ipfs\_uri<mark style="color:red;">\*</mark>              | String | The ipfs\_uri returned from calling the upload route. Must be included if url is not                                                                                                                                                                                                                                                                                                                                                          |
| recipient\_user\_id<mark style="color:red;">\*</mark>    | String | The user id to mint to. A new user will be generated with this id if one does not already exist. One of user id and public key must be provided                                                                                                                                                                                                                                                                                               |
| other\_metadata                                          | JSON   | <p>Arbitrary additional parameters can be passed in as a dictionary. For example:</p><p>{"height": 42, "color": red"}</p>                                                                                                                                                                                                                                                                                                                     |

{% tabs %}
{% tab title="200 NFT has been minted" %}

```javascript
{
    "data": {
        "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
        "contract_owner_public_key": "0x582b7cb2B054A09b8Ee36f95Db285AB34EECED03",
        "token_id": 67014279,
        "token_owner_public_key": "0x4e077a6500a18663d22549D812fCd56A700f3193",
        "transaction_hash": "0x0e16dd6fd3ae885ffcfa11f3b69be98b169a78b6d580fdc8070e3819a01f436c"
    },
    "status": 200,
    "message": "NFT has been minted"
}
```

{% endtab %}

{% tab title="400 Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="401 Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Not Authorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on our end" %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

## Batch mint a series of NFTs

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/batchMintFromUrls`

Mint a series of NFTs. Mostly the same parameters as /mintFromUrl except as arrays, and the contract address is a single parameter. Arrays must be of the same length, and a maximum of 1000 elements. Additionally, a webhook url can also be passed which will receive the entire response once the batch has been minted.

#### Headers

| Name                                           | Type   | Description                                                                                       |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark>     | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json (Required)                                                                       |

#### Request Body

| Name                                                      | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contract\_address                                         | string    | The contract address to mint the NFTs on. If none provided, your default contract will be used                                                                                                                                                                                                                                                                                                                                           |
| recipient\_public\_keys<mark style="color:red;">\*</mark> | \[String] | An array of wallet addresses to mint to. For each address in the array, a user with the wallet address will be created if one does not already exist. Either recipient\_public\_keys *or* recipien&#x74;*\_*&#x75;ser\_ids must be passed                                                                                                                                                                                                |
| names                                                     | \[String] | An array of the names of the NFTs. This will be included in the NFT metadata on the blockchain. It defaults to an array of empty strings.                                                                                                                                                                                                                                                                                                |
| urls<mark style="color:red;">\*</mark>                    | \[String] | An array of links to the image/media that will become the NFT. Must be included if s3\_urls and ipfs\_uris are not                                                                                                                                                                                                                                                                                                                       |
| mint\_prices                                              | \[Int]    | An array of prices for how much you charged to mint each NFT, if at all.                                                                                                                                                                                                                                                                                                                                                                 |
| descriptions                                              | \[String] | An array of descriptions of the NFTs. This will be included in the NFT metadata on the blockchain. It defaults to an array of empty strings                                                                                                                                                                                                                                                                                              |
| attributes                                                | \[JSON]   | <p>An array of attributes in JSON which describes the NFTs. </p><p>Refer to the following link to learn more: <a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md"><https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md></a>. </p><p>A sample JSON is:</p><p>\[ { "trait\_type": "Base", "value": "Horse" }, { "trait\_type": "Eyes", "value": "Small" }, { "trait\_type": "Power", "value": 3 } ]</p><p></p> |
| s3\_urls<mark style="color:red;">\*</mark>                | \[String] | An array of s3\_urls returned from calling the upload route. Must be included if urls are not                                                                                                                                                                                                                                                                                                                                            |
| ipfs\_uris<mark style="color:red;">\*</mark>              | \[String] | An array of ipfs\_uris returned from calling the upload route. Must be included if urls are not                                                                                                                                                                                                                                                                                                                                          |
| recipient\_user\_ids<mark style="color:red;">\*</mark>    | \[String] | An array of user ids to mint to. For each user id, a new user will be generated with the id if one does not already exist. Either Recipient\_public\_keys *or* recipien&#x74;*\_*&#x75;ser\_ids must be passed                                                                                                                                                                                                                           |
| other\_metadatas                                          | \[JSON]   | <p>Arbitrary additional parameters can be passed in as an array of dictionaries. For example:</p><p>\[{"height": 42, "color": red"}, {"height": 35, "color": blue"}, ...]</p>                                                                                                                                                                                                                                                            |
| webhook\_url                                              | String    | A url which will receive all the mint data once the batch has been finished minting. Should take a post request with a json body, and no authorization (you can generate unique webhook links and use that to ensure security). Expects a transaction\_hash strin&#x67;*,* contract\_address strin&#x67;*,* an array of token id integers, an array of wallet address strings.                                                           |

{% tabs %}
{% tab title="200 NFTs are being minted" %}

```javascript
{
    "data": {
        "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
        "contract_owner_public_key": "0x582b7cb2B054A09b8Ee36f95Db285AB34EECED03",
        "token_ids": [1, 2, 3, ...],
        "token_owner_public_keys": ["0x4e077a6500a18663d22549D812fCd56A700f3193","0x4e077a6500a18663d22549D812fCd56A700f3193", "0x4e077a6500a18663d22549D812fCd56A700f3193", ...]
    },
    "status": 200,
    "message": "NFT mints are in progress"
}
```

{% endtab %}

{% tab title="400 Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="401 Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Not Authorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on our end" %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

## Mint a new NFT by uploading a file

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/mintFromFile`

Mints a new NFT to the given wallet address

#### Headers

| Name                                           | Type   | Description                                                                                       |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark>     | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type<mark style="color:red;">\*</mark> | String | multipart/form-data (Required)                                                                    |

#### Request Body

| Name                                   | Type   | Description                                                                                                                                                                                                                                                         |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| file<mark style="color:red;">\*</mark> | file   | The file that will be uploaded to represent the NFT. Max size is 64mb, and accepted formats are png, jpg, jpeg, and gif. (Required)                                                                                                                                 |
| metadata                               | object | <p>This is a json object that matches the fields from the mintFromUrl route (except without the urls). Here is an example:</p><p>{ </p><p>"recipient\_user\_id": "User1", </p><p>"name": "My New NFT", </p><p>"description": "This is a brand new NFT"</p><p> }</p> |

{% tabs %}
{% tab title="200: OK NFT was minted" %}

```javascript
{
    "data": {
        "contract_address": "0xaA481ced0b3554b5cA23d01103A9BD17771dfFd2",
        "contract_owner_public_key": "0x582b7cb2B054A09b8Ee36f95Db285AB34EECED03",
        "token_id": 67014279,
        "token_owner_public_key": "0x4e077a6500a18663d22549D812fCd56A700f3193",
        "transaction_hash": "0x0e16dd6fd3ae885ffcfa11f3b69be98b169a78b6d580fdc8070e3819a01f436c"
    },
    "status": 200,
    "message": "NFT has been minted"
}
```

{% endtab %}

{% tab title="400: Bad Request Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="401: Unauthorized Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on our end" %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Minting from s3\_url and ipfs\_uri (in mintFromUrl) is quicker for large files (since files have been pre-uploaded). A potential flow would be to use the uploadFromURL or uploadFromFile routes ahead of time to convert regular files to decentralized ones, and then use the mintFromUrl route for the minting.
{% endhint %}

## Upload a file to a decentralized IPFS host

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/uploadFromUrl`

Uploads a hosted media file to a decentralized ipfs host and amazon s3. These two links can then be used in the mintFromUrl route to mint. It is recommended to use ipfs to mint your NFTs since then they exist independently from your server and will always be accessible.

#### Headers

| Name                                           | Type   | Description                                                                                       |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark>     | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json (Required)                                                                       |

#### Request Body

| Name                                  | Type | Description                                                                                               |
| ------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------- |
| url<mark style="color:red;">\*</mark> | file | The file that will be uploaded to IPFS as a url. Accepted formats are png, jpg, jpeg, and gif. (Required) |

{% tabs %}
{% tab title="200: OK File was uploaded" %}

```javascript
{
    "data": {
        "cid": "QmeDVja9RxZjddjAh2LNvWUUFJ8SGCrRVewpeyf4MB3axf",
        "ipfs_uri": "ipfs://QmeDVja9RxZjddjAh2LNvWUUFJ8SGCrRVewpeyf4MB3axf",
        "s3_url": "https://rareful-bucket.s3.us-east-2.amazonaws.com/public/QmeDVja9RxZjddjAh2LNvWUUFJ8SGCrRVewpeyf4MB3axf.jpg"
    },
    "message": "File successfully uploaded",
    "status": 200
}
```

{% endtab %}

{% tab title="400: Bad Request Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="401: Unauthorized Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on our end" %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

## Upload a file to a decentralized IPFS host

<mark style="color:green;">`POST`</mark> `https://api.rareful.io/v1/uploadFromFile`

Uploads a file to a decentralized ipfs host and amazon s3. These two links can then be used in the mintFromUrl route to mint. It is recommended to use ipfs to mint your NFTs since then they exist independently from your server and will always be accessible.

#### Headers

| Name                                           | Type   | Description                                                                                       |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| API\_KEY<mark style="color:red;">\*</mark>     | String | Your API Key can found on the dashboard, and will be used to authenticate all requests (Required) |
| Content-Type<mark style="color:red;">\*</mark> | String | multipart/form-data (Required)                                                                    |

#### Request Body

| Name                                   | Type | Description                                                                                               |
| -------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------- |
| file<mark style="color:red;">\*</mark> | file | The file that will be uploaded to IPFS as a url. Accepted formats are png, jpg, jpeg, and gif. (Required) |

{% tabs %}
{% tab title="200: OK File was uploaded" %}

```javascript
{
    "data": {
        "cid": "QmeDVja9RxZjddjAh2LNvWUUFJ8SGCrRVewpeyf4MB3axf",
        "ipfs_uri": "ipfs://QmeDVja9RxZjddjAh2LNvWUUFJ8SGCrRVewpeyf4MB3axf",
        "s3_url": "https://rareful-bucket.s3.us-east-2.amazonaws.com/public/QmeDVja9RxZjddjAh2LNvWUUFJ8SGCrRVewpeyf4MB3axf.jpg"
    },
    "message": "File successfully uploaded",
    "status": 200
}
```

{% endtab %}

{% tab title="400: Bad Request Request was malformed or parameters include wrong data types" %}

```javascript
{
    "data": {},
    "status": 400,
    "message": "There was an error"
}
```

{% endtab %}

{% tab title="401: Unauthorized Likely wrong or missing API Key" %}

```javascript
{
    "data": {},
    "status": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Something went wrong on our end" %}

```javascript
{
    "status": 500,
    "message": "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}