Upload media

Uploading takes three calls: create the asset, send the bytes straight to storage, then complete it. Needs media:upload.

1. Start (startMediaUpload):

   bash / zsh

   curl -X POST "$GHOSTPULL_URL/api/v1/media/assets" \
     -H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
     -d '{"name":"shoe.png","mediaType":"image/png","sizeBytes":48213}'

   fish

   curl -X POST "$GHOSTPULL_URL/api/v1/media/assets" \
     -H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
     -d '{"name":"shoe.png","mediaType":"image/png","sizeBytes":48213}'

   PowerShell

   curl.exe -X POST "$env:GHOSTPULL_URL/api/v1/media/assets" `
     -H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" `
     -d '{"name":"shoe.png","mediaType":"image/png","sizeBytes":48213}'

   The answer has assetId, versionId and upload with a url and headers. The URL works once, for an hour.

2. Send the bytes with PUT to upload.url, with every header from upload.headers, and no API key: the URL itself is the permission.

   bash / zsh

   curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" -H "If-None-Match: *" \
     --data-binary @shoe.png

   fish

   curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" -H "If-None-Match: *" \
     --data-binary @shoe.png

   PowerShell

   curl.exe -X PUT "$env:UPLOAD_URL" -H "Content-Type: image/png" -H "If-None-Match: *" `
     --data-binary "@shoe.png"

   Sending again after a success is refused by storage: the version's file can be written only once (If-None-Match: *). Without that header, storage refuses the upload with 403.

3. Complete (completeMediaUpload):

   bash / zsh

   curl -X POST "$GHOSTPULL_URL/api/v1/media/versions/$VERSION_ID/complete" \
     -H "x-api-key: $GHOSTPULL_API_KEY"

   fish

   curl -X POST "$GHOSTPULL_URL/api/v1/media/versions/$VERSION_ID/complete" \
     -H "x-api-key: $GHOSTPULL_API_KEY"

   PowerShell

   curl.exe -X POST "$env:GHOSTPULL_URL/api/v1/media/versions/$env:VERSION_ID/complete" `
     -H "x-api-key: $env:GHOSTPULL_API_KEY"

   The answer is the asset, now in your library. A 409 means the bytes are not there yet, or the upload was completed before; read the asset with getMediaAsset to see which.

Read your library

listMediaAssets and getMediaAsset (media:read) answer assets with a signed url for each file. These links expire: read the asset again for a fresh one instead of storing links.