Library overview
The Library API gives your code access to the files stored in an Intellectible project. Use it to supply documents to workflows, retrieve generated reports, or keep application files alongside the rest of your project.
For organising files in the app and using them in workflows, see the Library guide.
Permissions
Send the project's API key in the Authorization header, without a Bearer prefix. Library permissions apply to the whole project Library, not individual files or folders.
| Permission | Operations |
|---|---|
library.read | List files, list directories, and download content. |
library.write | Register files and complete uploads. |
library.delete | Delete files. |
These grants are independent. An upload-only integration does not automatically have permission to list, download, or delete files. See Authentication and permissions.
Paths and IDs
The API uses different identifiers for different purposes:
| Value | Example | Where to use it |
|---|---|---|
| Directory path | Reports/Monthly | The optional path query parameter for listing files or directories. |
| Directory ID | root or an ID from List directories | The dir field when registering an upload. |
| File ID | documentId from creation, or id from a file listing | Download and delete requests, or references passed to your application. |
| Storage path | The path returned when registering an upload | The completion request. Pass it back unchanged. |
Directory paths are relative to the Library root and names are case-sensitive. Use Reports/Monthly, not /Reports/Monthly/. Omit the listing query parameter for the root; root is a directory ID, not a special listing path.
Listings return the immediate contents of one directory, not a recursive tree. There are no public Library endpoints here for creating, renaming, moving, or deleting directories. Organise folders in the app and use their existing IDs when uploading.
Upload lifecycle
Uploading has three steps:
- Create a file — register its metadata and receive a signed upload URL.
- Upload the bytes — PUT the file directly to that URL, using the returned MIME type.
- Complete upload — pass back the returned storage path to finalise the file.
The first response does not mean the content has been uploaded. A file can appear in listings while its upload is still pending. Wait for both the byte upload and completion to succeed before passing it to another operation.
Follow Upload a file for a complete example. Completion records the actual size and handles supported image thumbnails; it is not a document-text extraction or search-indexing endpoint.
Download and retain references
The download endpoint redirects to a temporary signed URL for the file bytes. Store the file ID in your application and request a fresh link when needed, rather than storing a signed URL as a permanent address.
Signed upload and download URLs are credentials in their own right. Use them promptly, keep them out of logs, and do not send your project API key to the storage destination.
Deletion and failures
Deleting a file removes it from the Library; this API has no restore operation. Check dependent workflows and application references first.
Uploads use project file and storage capacity. Report the real file size when registering an upload, and handle failures at each stage. Repeating creation makes a new file record, even when the name is unchanged.
See Errors, limits and retries for shared guidance. Library routes can return plain-text errors, and their individual status mappings are documented below.