Request Signed URL for Upload/Download Files

to generate signed URLs both for uploads and downloads

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

Please replace <base_url> as explained here.

This endpoint is the front door for every file your SRRs reference. Thumbnails, images, contract-terms PDFs and attachment files must all be uploaded through the signed URL returned here, and referenced in the issuance request by the returned finalUrl — that is what allows Startrail to compute the file's IPFS CID and publish it permanently to IPFS at issuance. Files hosted anywhere else are rejected by the Issue & Transfer endpoint.

Flow: signed URL (write) → PUT upload → poll /fileMetadata until hash + cid appear → issue using finalUrl.

Pick the right category. It matters in two independent ways — logically (which storage bucket the file lands in, hence who can access it) and semantically (what the file means in the certificate when referenced from attachmentFiles[]):

Rule of thumb: non_attachment_file for anything referenced by URL in the metadata (thumbnail, image, contract terms); artwork only for files that are the (digital) work; private categories for confidential attachments. See also What is an Artwork File.

Category	Logical: bucket	Semantic: meaning in the SRR	In attachmentFiles[*].category	In thumbnailURL / image / contractTerms.fileURL
non_attachment_file	public	Supporting file that is not part of the work — referenced by URL only	❌ not accepted	✅ recommended
artwork	public	A digital component of the artwork itself — its content hash is written into metadata.digitalComponents (part of the authenticity claim)	✅ → folded into digitalComponents	✅ accepted (public), but semantically reserve it for actual artwork files
certificate	private	Certificate document attached to the work	✅ → folded into attachmentFiles	❌ rejected — private bucket, viewers cannot access
for_authenticity	private	Authenticity evidence attached to the work	✅ → folded into attachmentFiles	❌ rejected
installation	private	Installation instructions/records attached to the work	✅ → folded into attachmentFiles	❌ rejected

Precaution

File Size

Our system currently only support file sizes with a maximum limit of strictly less than 2GB, or in other words:

    filesize < 2^31 

This essentially implies that any user interaction with our API involving data transfer would necessitate adherence to this requirement. Manifestly, if a file size exceeds the defined threshold of 2GB, it may possibly impede the operation of the application.

File Name

File name

1. should not contain space.

2. should contain the file extension, including but not limited to .jpg, .png, .pdf, etc.

3. use a unique name for each file. Filename is unique perissuer-address otherwise it will fail.

   This is to avoid modification of files that are already used in SRR. However given the upgrade to the IPFS protocol, there is no need to be concerned for the filename in terms of its look. The filename is not going to exist in the minted SRR since it is going to be converted to IPFS and the filename will be replaced with cid that is a function of the file's content and not file's name.

*In order to make the file names unique anyway, you can prefix/suffix the name with a unique number such as Date.now() .

**Given the underlying usage of IPFS, there is no need to be worried about duplicated contents. Since if two files with different name but same content will eventually be replaced with the same ipfs url.

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
action*	string (write and read)	Field to specify the action of the Signed URL. Value write to request upload signed URL, and read to request download signed URL.
payload*	array	Array of signed URL request.
payload[*].filename*	string	The filename must meet the constraints mentioned above. If the client needs to delete an existing file, please contact Startbahn.
payload[*].category*	string	Please refer to the category table at the top of this page for how each category is treated (bucket + meaning), and this page for product-level background. Use non_attachment_file to upload thumbnails, images and contract terms.

201: Created

The API responds with 201 when the signed URL is created. The validity of the signed URL is 15 minutes after it is created.

The client’s back-end needs to consider its upload speed. If the files that need to be uploaded are many, client’s back-end may consider splitting the signed URL request to ensure that all of the files are uploaded.

Body

Body Attribute	Description	Format
results	results of the request	Array
results[*].filename	Name of the file, same as one in the request	string
results[*].contentType	Content-Type that was chosen and set for the file. You need to set the same value in Content-Type header when uploading or downloading the file with the signed URL. Otherwise, you will get an error about signature mismatch.	string
results[*].url	The signed URL that client can use to perform action such as upload or download. NOTE: This URL is only valid for 15 minutes and should not be saved. Please check the reference below.	string
results[*].finalUrl	The URL that client should save and use when calling issue endpoint. Check below for details	string

Usage of Final URL

category	Usage	example
artwork	On issue endpoint, use it for payload.attachmentFiles[*].url	https://static-files-stg.startrail.startbahn.jp/srr-images/0xf1B51E02804A7AF4Eb4c2f57dc9a05510A513C17/221208_royalty-01-001.jpg
certificate, installation, for_authenticity	On issue endpoint, use it for payload.attachmentFiles[*].url	https://storage.googleapis.com/artwork-staging-images/srr-images/luw-address-1/certificate.tif
non_attachment_file	use it for the field in metadata on the image, payload[*].metadata.thumbnailURL or payload[*].metadata.contractTerms.fileURL	https://storage.googleapis.com/artwork-staging-images/srr-images/0xf1B51E02804A7AF4Eb4c2f57dc9a05510A513C17/Contract_Terms_test.pdf

Example

400: Bad Request

500: Internal Server Error

Swagger Endpoint (Test Environment)

Swagger to test.

Required Permissions

Check parent page.

Request Body Example

Signed URL for upload

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

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

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

Signed URL for Download

{
  "payload": [
    {
      "filename": "certificate.pdf",
      "category": "certificate"
    }
  ],
  "action": "read"
}

Code Example

Check parent page.

Reference

https://cloud.google.com/storage/docs/access-control/signed-urls