Skip to main content

Download a file

GET /projects/:projectid/library/files/:fileid/download

Returns a redirect to a temporary signed URL for the file bytes. The API response is not a JSON object containing the content or URL.

Authentication and request​

Use a project key with library.read in Authorization, without Bearer. Replace :projectid with the key's project ID and :fileid with a file ID from List files or the documentId returned during creation.

There is no request body.

Follow the redirect safely​

The API returns 302 Found with a Location header containing the signed URL. Fetch that URL without the project API key. If your HTTP client follows redirects automatically, ensure it does not forward the Authorization header to the storage host.

This Bash/Zsh example uses two separate requests so the credential is sent only to Intellectible. It uses the Quickstart variables:

(
set -eu
FILE_ID="YOUR_FILE_ID"
DOWNLOAD_URL=$(curl --fail --silent --show-error \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/library/files/${FILE_ID}/download")
test -n "$DOWNLOAD_URL"

curl --fail --silent --show-error \
--output "./downloaded-file.bin" \
"$DOWNLOAD_URL"
)

Choose an output filename that does not overwrite a file you want to keep. The second response contains raw file bytes. Do not use --include when writing those bytes to a file, since it would also write HTTP headers.

URL lifetime​

Download links currently expire after ten minutes. Request a new link through the API when needed. Store the file ID, not the signed URL, as your durable reference.

Anyone holding a valid signed URL can use it until it expires. Keep it out of logs and public pages; do not assume disabling the API key invalidates a link already issued.

Errors​

  • 401: missing or invalid project credential.
  • 403: missing library.read.
  • 429: request-rate limit reached.
  • 500: metadata or stored content could not be found, or another download-link error occurred.

Missing files currently reach a 500 response rather than a guaranteed 404. If a download fails, confirm the file ID and that the upload completed.

The storage request has its own status and error body. An expired or altered signed URL can fail there even when the initial API request succeeded. Request a fresh URL rather than editing its query parameters.