# File Information Metadata

<mark style="color:green;">`POST`</mark> `<base_url>/port/api/v1/commerce/fileMetadata`

Please replace `<base_url>` as explained [here](/readme/url-per-environment.md). Please note that file information metadata is different from SRR metadata.

### Precaution

#### Multiple files

{% hint style="info" %}
When requesting for multiple files:

If all files are found in our buckets and the requested is authorized for the access, the response is going to succeed and include the respective information per requested file. However in any other case the response status is not 200 and the return information will be only including inaccessible files that is <= the requested files.
{% endhint %}

#### Use case

{% hint style="info" %}
If the file information metadata exists, it means the file is ready to be included in Issue & Transfer SRR call.
{% endhint %}

#### Headers

| Name                                               | Type   | Description                       |
| -------------------------------------------------- | ------ | --------------------------------- |
| commerce-api-key<mark style="color:red;">\*</mark> | string | Commerce API Key                  |
| issuer-address<mark style="color:red;">\*</mark>   | string | Contract Address of API Key owner |

#### Request Body

| Name                                                    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| payload<mark style="color:red;">\*</mark>               | array  | Array of the request. Each element of the array corresponds to a file.                                                                                                                                                                                                                                                                                                                                                                                        |
| payload\[\*].filename<mark style="color:red;">\*</mark> | string | <p>Name of the file. Should contain file extensions (.jpg, .png, .pdf, etc).</p><p>Should not contain space. Use a unique name for each file.</p><p>If the filename is already used by the client, then it will fail when uploading. (unique for each LUW, but can be same for different LUW).</p><p>This is to avoid modification of files that are already used in SRR.</p><p>If the client needs to delete an existing file, please contact Startbahn.</p> |
| payload\[\*].category<mark style="color:red;">\*</mark> | string | <p>Please refer to <a href="https://help.port.startrail.io/hc/en-us/articles/7720691967767-What-is-an-Artwork-File-">this page</a> to understand the difference among the categories.</p><p>Use <code>non\_attachment\_file</code> to upload thumbnails and contract terms.</p>                                                                                                                                                                               |

{% tabs %}
{% tab title="200: OK " %}
The API responds with 200 if the check to the storage provider success. Bear in mind that client’s back end needs to check the `results[*].message` if there is a problem with each file.

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

<table><thead><tr><th width="211">Body Attribute</th><th width="356">Description</th><th width="253">Format</th></tr></thead><tbody><tr><td>payload</td><td>Array of the results. The order of the array is same as the request.</td><td>array</td></tr><tr><td>payload[*].filename</td><td>The value will be same as parameter sent in request.</td><td>string</td></tr><tr><td>payload[*].hash</td><td>The value of calculated hash. If the hash still in calculation, file is not ready yet. If the file size is above 20 GB, you need to contact to Startbahn to calculate hash manually.</td><td>string</td></tr><tr><td>payload[*].cid</td><td>The value of IPFS CID v1. Like the <code>hash</code>, ones for very large files need to be contacted to Startbahn.</td><td>string</td></tr><tr><td>payload[*].size</td><td>The size in bytes.</td><td>number</td></tr><tr><td>payload[*].message</td><td>Exist if there is problem describing it.</td><td>string</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```
// Example result
{
  "results": [
    // correct result
    {
      "filename": "test.jpg",
      "hash": "sha256-a63238ce3b8c4f8a99fb453d716d5451f75508c2e403a58af0412014187e7a61",
      "cid": "bafkreiehikh4kiuahuyqmxt3zy6pap7eouewmmpf4b5326qp3zqmjtzfy4"
      "size": 712
    },
    // if hash calculation is not yet finished
    {
      "filename": "hash-not-yet-calulated.jpg",
      "message": "HASH_STILL_IN_CALCULATION"
    }
  ]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request " %}
The API responds with 400 if the request body is invalid.

```javascript
// If payload is invalid
{
  "statusCode": 400,
  "message": [
    "payload.0.category must be one of the following values: certificate,for_authenticity,artwork,installation,non_attachment_file"
  ]
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}
The API responds with 5xx if there is an issue between the network or storage provider, currently, it uses Google Cloud Storage.

```
// If the network is error or unknown error. Startbahn side need to check.
{
  "statusCode": 502,
  "message": "Bad Gateway"
}
```

{% endtab %}

{% tab title="404: Not Found " %}
{% code fullWidth="true" %}

```json
// If one or more files are not found
{
  "statusCode": 404,
  "message": [
    {
      "index": 0,
      "filePath": "srr-images/0x0000000000000000000000000000000000000000/not-found.png"
    }
  ]   
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Swagger Endpoint (Test Environment)

[Swagger to test](https://api-stg.startrail.startbahn.jp/port/api#/public/CommerceController_bulkGetFileMetadata)

## Required Permissions

Check the [parent page](/issue-transfer-api/issue-and-transfer-srr-nft.md).

### Request Body Example

```json
// Example for thumbnail
{
  "payload": [
    {
      "filename": "thumbnail.jpg",
      "category": "non_attachment_file"
    }
  ]
}

// Example for contract terms
{
  "payload": [
    {
      "filename": "contract.pdf",
      "category": "non_attachment_file"
    }
  ]
}

// Example for other categories
{
  "payload": [
    {
      "filename": "certificate.pdf",
      "category": "certificate"
    }
  ]
}
```

## Code Example

Check [parent page](/issue-transfer-api/issue-and-transfer-srr-nft.md).


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/file-information-metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.