Skip to main content

Library API Overview

The Informer Library API provides comprehensive endpoints for managing document libraries, file storage, vector indexing, and AI assistant knowledge bases. Libraries support local file storage and cloud integrations (Google Drive, OneDrive, SharePoint, Dropbox) with automatic sync, versioning via snapshots, and semantic search through vector embeddings. All routes are prefixed with /api.

Features​

  • CRUD Operations - Create, read, update, and delete libraries
  • File Management - Upload, list, read, write, and delete files with directory support
  • Cloud Integration - Connect to Google Drive, OneDrive, SharePoint, Dropbox via OAuth
  • Vector Indexing - Automatic embeddings generation for semantic search
  • Snapshots - Point-in-time library backups with restore capability
  • Sync Operations - Automatic and manual sync from connected cloud services
  • Assistant Knowledge - Associate libraries with AI assistants for RAG
  • Sharing & Permissions - Team-based access control with read/write levels
  • Favorites - User-specific library favoriting

Library Types​

Libraries are created with different driver types:

TypeDescription
localLocal file storage managed by Informer
google-driveIntegration with Google Drive
onedriveIntegration with Microsoft OneDrive
sharepointIntegration with Microsoft SharePoint
dropboxIntegration with Dropbox

Authentication​

All Library API endpoints require authentication via session cookies or API tokens. Most endpoints verify library permissions before allowing access.

Common Permission Patterns​

  • Read access - View library metadata and indexed files (requires ownership or share)
  • Write permission - Required for library:write (create, update, delete, file uploads, sync)
  • Sync permission - Required for library:sync (trigger sync from cloud integrations)
  • Connection access - Only connection owners can see unindexed files

File Indexing​

Libraries automatically index uploaded files for semantic search:

  • Supported Formats - PDF, DOCX, TXT, MD, CSV, XLSX, HTML, and more
  • Vector Embeddings - Generated via OpenAI embeddings API
  • Status Tracking - indexed, indexingStartedAt, indexingErroredAt fields
  • Retry Logic - Manual retry via POST /api/libraries/{id}/files/{fileId}/_retry-indexing

Indexing States​

StateDescription
indexed: trueFile successfully indexed, searchable by assistants
indexingStartedAt != null, indexed: falseCurrently indexing
indexingErroredAt != nullIndexing failed, see indexingErrorMessage
indexed: false, indexingStartedAt: nullNot yet indexed or skipped (e.g., embedded libraries)

Snapshots​

Libraries support versioned snapshots for backup and restore:

  1. Create snapshot - POST /api/libraries/{id}/snapshots
  2. List snapshots - GET /api/libraries/{id}/snapshots
  3. Restore snapshot - POST /api/libraries/{id}/snapshots/{snapshotId}/_restore
  4. Delete snapshot - DELETE /api/libraries/{id}/snapshots/{snapshotId}

Snapshots include:

  • All files and directory structure
  • Metadata (created date, trigger type)
  • Automatic limit enforcement (default: keep 10 most recent)

Cloud Integration​

Libraries can connect to cloud storage providers:

  1. Create library with cloud driver type (google-drive, onedrive, etc.)
  2. Connect via OAuth - POST /api/libraries/{id}/integration
  3. Sync files - POST /api/libraries/{id}/_sync
  4. Auto-sync - Configure syncInterval (in minutes) for periodic updates

Integration Workflow​

graph LR
    A[Create Library] --> B[Set Integration]
    B --> C[OAuth Connect]
    C --> D[Sync Files]
    D --> E[Index Files]
    E --> F[Associate with Assistant]

Assistant Access​

Libraries can be shared with AI assistants for knowledge retrieval:

  • Enable assistant access - PUT /api/libraries/{id}/assistant-access with { "enabled": true }
  • Associate with assistant - POST /api/libraries/{id}/assistants creates embedded assistant
  • File-level RAG - Assistants use vector embeddings to answer questions about library content

File Paths​

Files support hierarchical directory structure:

  • Upload to path - POST /_library-upload with path: "assets/index.js"
  • List by directory - GET /api/libraries/{id}/files?dir=/assets
  • Read by path - GET /api/libraries/{id}/contents/{path*}
  • Write by path - PUT /api/libraries/{id}/contents/{path*} (creates parent dirs)

Common Query Parameters​

Many list endpoints support:

ParameterTypeDefaultDescription
qstring-Search query (filters files by filename)
startinteger0Pagination offset
endinteger100Pagination limit (max results)
sortarray[{colId: "filename", sort: "ASC"}]Sort configuration
parentIdstring-Filter files by parent directory ID
dirstring-Filter files by directory path (e.g., /assets)
dirOnlybooleanfalseReturn only directories

Error Responses​

Standard HTTP status codes:

  • 200 - Success
  • 201 - Created (resource created successfully)
  • 204 - No Content (successful delete)
  • 400 - Bad request (validation error)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Resource not found
  • 409 - Conflict (duplicate, constraint violation)
  • 500 - Internal server error

Error responses include:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions to modify library"
}

Long-Running Operations​

Several endpoints support long-running operations with progress tracking:

  • POST /api/libraries - Create with integration setup
  • POST /api/libraries/{id}/_sync - Sync from cloud integration
  • POST /_library-upload - Upload and index files

These endpoints accept a progress parameter in the payload for progress updates.

Next Steps​

Explore the specific endpoint categories: