Upload a file
A Library upload has three stages: register the file, transfer its bytes, and complete the upload. All three must succeed before your application treats the file as ready.
Before you begin
You need:
- The environment variables from the Quickstart.
- A project key with Library → Upload (
library.write). - A local file to upload.
- An existing destination directory ID, or
rootfor the Library root.
If you need to discover a destination, use List directories with library.read. Uploading itself does not require read permission. Create missing directories in the app first.
The three requests
- Register: POST metadata to
/projects/:projectid/library/files. Send the filename, extension, destination directory ID, and actual byte size. Retain the returneddocumentId,storageLink,mimeType, andpath. - Transfer: PUT the raw bytes to
storageLink. Use the returnedmimeTypeasContent-Type. Do not send a project API key, multipart form data, or base64 text to this URL. - Complete: POST
{"path":"THE_RETURNED_STORAGE_PATH"}to/projects/:projectid/library/files:complete, authenticated with the project key.
The signed URL expires after ten minutes, so perform the transfer promptly. Pass the returned URL and path unchanged; neither should be reconstructed from the filename.
Complete example
This Bash/Zsh example uses curl and jq. Prepare an existing plain-text file named notes.txt in the current directory, then run the block below. It uploads that file to the Library root without changing the local file.
The commands run in a subshell and stop on a failed request or missing response field. They print the file ID for recovery, but do not print the key or signed URL.
(
set -eu
LOCAL_FILE="./notes.txt"
FILE_BYTES=$(wc -c < "$LOCAL_FILE" | tr -d '[:space:]')
# 1. Register a new file.
REQUEST_JSON=$(jq -n --argjson size "$FILE_BYTES" \
'{originalname:"notes.txt",fileType:"txt",dir:"root",size:$size}')
UPLOAD_JSON=$(curl --fail --silent --show-error \
--request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data "$REQUEST_JSON" \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/library/files")
FILE_ID=$(printf '%s' "$UPLOAD_JSON" | jq -er '.documentId | select(type == "string" and length > 0)')
UPLOAD_URL=$(printf '%s' "$UPLOAD_JSON" | jq -er '.storageLink | select(type == "string" and length > 0)')
MIME_TYPE=$(printf '%s' "$UPLOAD_JSON" | jq -er '.mimeType | select(type == "string" and length > 0)')
STORAGE_PATH=$(printf '%s' "$UPLOAD_JSON" | jq -er '.path | select(type == "string" and length > 0)')
printf 'Registered file ID: %s\n' "$FILE_ID"
# 2. PUT the bytes. No project API key is sent to storage.
curl --fail --silent --show-error \
--request PUT \
--header "Content-Type: $MIME_TYPE" \
--upload-file "$LOCAL_FILE" \
"$UPLOAD_URL"
# 3. Finalise the uploaded file.
COMPLETE_JSON=$(jq -n --arg path "$STORAGE_PATH" '{path:$path}')
curl --fail --silent --show-error \
--request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data "$COMPLETE_JSON" \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/library/files:complete"
printf '\nCompleted file ID: %s\n' "$FILE_ID"
)
To adapt it, change the local file, originalname, fileType, and destination dir together. Use a file extension such as pdf, not application/pdf, in fileType. Always use the returned MIME type for the PUT.
The completion response is plain-text OK, not JSON. Retain the completed file ID in your application.
Verify and use the file
After completion succeeds, check the file in the Library. With library.read, you can also list its metadata or download it.
Completion finalises storage metadata and supported thumbnails. To extract text, analyse a document, or use it as workflow input, explicitly run the appropriate processing step. Uploading does not itself guarantee that every file format can be previewed or parsed.
If something goes wrong
- Registration fails: check the key's write permission, filename/extension, destination ID, and available project capacity.
- PUT fails: verify that the URL has not expired and that the exact returned MIME type was used. Do not modify the signed URL or add your project key.
- Completion fails: verify that the PUT succeeded and the returned storage path was passed unchanged. Capacity reconciliation can fail at this stage and may remove the pending file.
- The file appears before completion: registration creates metadata before bytes arrive. A listing entry alone does not prove the upload succeeded.
Do not blindly rerun the whole example after an uncertain result. Each registration creates a new file ID, even if the filename is identical. Check the recorded ID and any pending Library entry before starting again. Remove unwanted pending or duplicate files through the app or Delete a file with the appropriate permission.
The example stops on HTTP errors but does not implement automatic retries or resumable uploads. See Errors, limits and retries before adding either to a production integration.