File Information Metadata

to get file metadata

POST <base_url>/port/api/v1/commerce/fileMetadata

Please replace <base_url> as explained here. Please note that file information metadata is different from SRR metadata.

Precaution

Multiple files

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.

Use case

Use this endpoint to confirm an uploaded file is ready for issuance: readiness means the response includes both the hash (SHA-256) and the cid (IPFS content ID) for the file. Until then, referencing the file in Issue & Transfer fails with Attachment hash not ready … (attachments) or Metadata file(s) not ready for IPFS publication … (thumbnailURL / image / contractTerms.fileURL) — poll this endpoint and retry once both values appear. Hash/CID calculation runs asynchronously after upload and normally completes within a few minutes.

Headers

Name	Type	Description
commerce-api-key*	string	Commerce API Key
issuer-address*	string	Contract Address of API Key owner

Request Body

Name	Type	Description
payload*	array	Array of the request. Each element of the array corresponds to a file.
payload[*].filename*	string	Name of the file. Should contain file extensions (.jpg, .png, .pdf, etc). Should not contain space. Use a unique name for each file. 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). This is to avoid modification of files that are already used in SRR. If the client needs to delete an existing file, please contact Startbahn.
payload[*].category*	string	Please refer to the category table for how each category is treated, and this page for product-level background. Use non_attachment_file to upload thumbnails, images and contract terms. Use the same category here that you used when generating the signed URL.

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.

Body

Body Attribute	Description	Format
payload	Array of the results. The order of the array is same as the request.	array
payload[*].filename	The value will be same as parameter sent in request.	string
payload[*].hash	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.	string
payload[*].cid	The value of IPFS CID v1. Like the hash, ones for very large files need to be contacted to Startbahn.	string
payload[*].size	The size in bytes.	number
payload[*].message	Exist if there is problem describing it.	string

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"
    }
  ]
}

400: Bad Request

The API responds with 400 if the request body is invalid.

// 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"
  ]
}

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"
}

404: Not Found

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

Swagger Endpoint (Test Environment)

Swagger to test

Required Permissions

Check the parent page.

Request Body Example

// 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.