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:
- bash / zsh
- fish
- PowerShell
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
set SIZE_BYTES (wc -c < shoe.png | string trim)
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
$body = @{ name = "shoe.png"; mediaType = "image/png"; sizeBytes = (Get-Item ./shoe.png).Length } | ConvertTo-Json -Compress
$body | Set-Content -Encoding utf8NoBOM upload-request.json
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/media/assets" `
-H "x-api-key: $env: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:
- bash / zsh
- fish
- PowerShell
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
set UPLOAD_URL (jq -r '.upload.url' upload.json)
set ASSET_ID (jq -r '.assetId' upload.json)
set 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
$upload = Get-Content upload.json -Raw | ConvertFrom-Json
$env:ASSET_ID = $upload.assetId
$env:VERSION_ID = $upload.versionId
$upload.upload.headers.psobject.Properties | ForEach-Object { "$($_.Name): $($_.Value)" } | Set-Content -Encoding utf8NoBOM upload-headers.txt
curl.exe --fail-with-body -X PUT "$($upload.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:
- bash / zsh
- fish
- PowerShell
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
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
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/media/versions/$env:VERSION_ID/complete" `
-H "x-api-key: $env: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 happened | What to do |
|---|---|
| The create-upload response was lost | A 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 lost | A retry can answer 412 because the bytes already exist. Try completing the saved version. |
Completion answers 409 media.upload_missing | Storage has no file yet. Finish the PUT, then complete again. |
Completion answers 409 media.version_not_pending | Check details.status. ready means it was already completed; failed needs a new upload. |
Completion answers 400 media.upload_rejected | Check details.reason, correct the file or declared size, and start a new upload. |
| The completion response was lost | Read the saved asset ID with getMediaAsset to see whether it became ready. This requires media:read. |
To read that asset:
- bash / zsh
- fish
- PowerShell
curl --fail-with-body "$GHOSTPULL_URL/api/v1/media/assets/$ASSET_ID" -H "x-api-key: $GHOSTPULL_API_KEY"
curl --fail-with-body "$GHOSTPULL_URL/api/v1/media/assets/$ASSET_ID" -H "x-api-key: $GHOSTPULL_API_KEY"
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/media/assets/$env:ASSET_ID" -H "x-api-key: $env: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:
- bash / zsh
- fish
- PowerShell
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)"
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)
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/media/assets/$env:ASSET_ID/download-url" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" --output download.json
$download = Get-Content download.json | ConvertFrom-Json
curl.exe --fail --output (Split-Path -Leaf $download.name) $download.url
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.