Skip to main content

Upload media

Create the asset, send its bytes directly to storage, then complete it. Uploads need media:upload; checking an asset after an interrupted request also needs media:read.

Before you start​

Set GHOSTPULL_URL and GHOSTPULL_API_KEY as in the quickstart. Put a PNG named shoe.png in the current directory. The bash/zsh and fish examples also need jq; PowerShell 7 uses its built-in JSON commands.

The API reference lists supported media types and size limits. The file's declared size must cover its actual size.

1. Create an upload​

startMediaUpload returns where to upload. Build its request from the file's actual size, and save the response:

SIZE_BYTES=$(wc -c < shoe.png)
jq -n --argjson size "$SIZE_BYTES" '{name:"shoe.png",mediaType:"image/png",sizeBytes:$size}' > upload-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/media/assets" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @upload-request.json --output upload.json

Check that the call succeeded before continuing. upload.json contains assetId, versionId, and upload with url and headers. Keep this response private: the signed URL grants permission to upload for one hour.

2. Send the bytes​

Read the returned values and send every upload header, without an API key:

UPLOAD_URL=$(jq -r '.upload.url' upload.json)
ASSET_ID=$(jq -r '.assetId' upload.json)
VERSION_ID=$(jq -r '.versionId' upload.json)
jq -r '.upload.headers | to_entries[] | "\(.key): \(.value)"' upload.json > upload-headers.txt
curl --fail-with-body -X PUT "$UPLOAD_URL" -H @upload-headers.txt --data-binary @shoe.png

The headers include Content-Type and If-None-Match: *. A successful PUT cannot be overwritten. Storage errors can be XML; they do not follow the API's JSON error format.

3. Complete the upload​

After the PUT succeeds, call completeMediaUpload with the saved version ID:

curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/media/versions/$VERSION_ID/complete" \
-H "x-api-key: $GHOSTPULL_API_KEY" --output asset.json

The answer in asset.json is the ready asset, now listed in the library. Keep its id; the asset.url download link expires.

Recover an upload​

What happenedWhat to do
The create-upload response was lostA repeated POST creates another asset; it does not recover the first one. Keep the new response and use only its upload target.
The PUT response was lostA retry can answer 412 because the bytes already exist. Try completing the saved version.
Completion answers 409 media.upload_missingStorage has no file yet. Finish the PUT, then complete again.
Completion answers 409 media.version_not_pendingCheck details.status. ready means it was already completed; failed needs a new upload.
Completion answers 400 media.upload_rejectedCheck details.reason, correct the file or declared size, and start a new upload.
The completion response was lostRead the saved asset ID with getMediaAsset to see whether it became ready. This requires media:read.

To read that asset:

curl --fail-with-body "$GHOSTPULL_URL/api/v1/media/assets/$ASSET_ID" -H "x-api-key: $GHOSTPULL_API_KEY"

listMediaAssets and getMediaAsset need media:read and return signed download links. Read again for a fresh link instead of storing the URL.

Download an original​

Request an attachment link with getMediaDownloadUrl, which needs media:read, then download from that link without your API key:

curl --fail-with-body "$GHOSTPULL_URL/api/v1/media/assets/$ASSET_ID/download-url" \
-H "x-api-key: $GHOSTPULL_API_KEY" --output download.json
curl --fail --output "$(basename "$(jq -r .name download.json)")" "$(jq -r .url download.json)"

The commands save the file under its library name, without any folders in it. Whoever has the link can download the file until it expires after 15 minutes, so do not share or store it; request a new one instead. Deleted assets have no download.

To upload or download several files, repeat these calls per file and limit how many run at once. There is no call that uploads or downloads several files and no ZIP from the API.

Next​