Storage

Quickstart: upload and download a file

Create a bucket, upload a file from the command line, then download it again.

This quickstart creates a bucket, uploads a small text file, and downloads it again. It uses curl and jq.

Before you begin

Set up your environment, so STORAGE_API_KEY and STORAGE_URL are set.

Upload and download a file

  1. Create a bucket

    curl -X POST "$STORAGE_URL/buckets" \
  -H "Authorization: Bearer $STORAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart"}'

  2. Start the upload

    Make a file, then tell us its key, size, and type:

    echo "Habari from Digitospace" > hello.txt

UPLOAD=$(curl -s -X POST "$STORAGE_URL/buckets/quickstart/uploads" \
  -H "Authorization: Bearer $STORAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"key\": \"notes/hello.txt\",
    \"size\": $(wc -c < hello.txt),
    \"contentType\": \"text/plain\"
  }")

    The answer holds the upload’s id, and in upload, the link to send the file to and the headers to send with it.

  3. Send the file

    Send the file to the link, with every header the answer gave:

    HEADERS=()
while IFS= read -r header; do HEADERS+=(-H "$header"); done < <(
  echo "$UPLOAD" |
    jq -r '.data.upload.headers | to_entries[] | "\(.key): \(.value)"'
)
curl -X PUT "$(echo "$UPLOAD" | jq -r .data.upload.url)" "${HEADERS[@]}" \
  --data-binary @hello.txt

  4. Finish the upload

    UPLOAD_ID=$(echo "$UPLOAD" | jq -r .data.id)

curl -X POST "$STORAGE_URL/buckets/quickstart/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $STORAGE_API_KEY"

    The answer is the stored file, with its size and etag.

  5. Download it

    Ask for a download link, then fetch the file:

    LINK=$(curl -s -X POST "$STORAGE_URL/buckets/quickstart/downloads" \
  -H "Authorization: Bearer $STORAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "notes/hello.txt"}' | jq -r .data.url)

curl "$LINK"

Clean up

Delete the bucket and everything in it. This cannot be undone:

curl -X DELETE "$STORAGE_URL/buckets/quickstart?force=true" \
  -H "Authorization: Bearer $STORAGE_API_KEY"

What’s next

Last updated