File Management

Endpoints for uploading, listing, reading, writing, and deleting files within libraries.

POST /_library-upload

Upload a file to a library with optional path and vector indexing.

Authentication: Required

Permissions: Requires write access to target library (or defaults to user's uploads library)

Request Body:

Field	Type	Required	Description
uploadId	string	Yes	Upload ID from prior upload session
libraryId	string (UUID)	No	Target library ID (defaults to uploads library)
path	string	No	File path within library (e.g., "assets/index.js") - creates parent directories
progress	string	No	Progress tracking identifier

Example:

{
  "uploadId": "upload-abc123",
  "libraryId": "550e8400-e29b-41d4-a716-446655440000",
  "path": "docs/api/overview.md"
}

Response:

201 Created

{
  "id": "file-xyz-789",
  "filename": "overview.md",
  "libraryId": "550e8400-e29b-41d4-a716-446655440000",
  "parentId": "dir-docs-api",
  "directory": false,
  "contentType": "text/markdown",
  "size": 4096,
  "indexed": true,
  "indexedAt": "2024-02-09T10:05:00Z",
  "modifiedAt": "2024-02-09T10:05:00Z",
  "ownerId": "alice",
  "embedded": true,
  "expiresAt": "2024-05-09T10:05:00Z",
  "createdAt": "2024-02-09T10:05:00Z"
}

Indexing

For non-embedded libraries, files are automatically indexed for vector search. Embedded libraries (like App assets) skip indexing by setting indexed: true immediately.

---

GET /api/libraries/{id}/files

List files in a library with filtering, sorting, and pagination.

Authentication: Required

Permissions: User must have read access to the library

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Query Parameters:

Parameter	Type	Default	Description
parentId	string	null	Filter by parent directory ID
dir	string	null	Filter by directory path (e.g., /assets)
q	string	-	Search query (filters by filename)
start	integer	0	Pagination offset
end	integer	100	Pagination limit (max results)
sort	array	[{colId: "filename", sort: "ASC"}]	Sort configuration
dirOnly	boolean	false	Return only directories

Response:

[
  {
    "id": "file-xyz-789",
    "filename": "overview.md",
    "path": "/docs/api/overview.md",
    "directory": false,
    "contentType": "text/markdown",
    "size": 4096,
    "indexed": true,
    "indexedAt": "2024-02-09T10:05:00Z",
    "indexingStartedAt": null,
    "indexingErroredAt": null,
    "indexingErrorMessage": null,
    "modifiedAt": "2024-02-09T10:05:00Z",
    "remoteUrl": "https://drive.google.com/file/d/abc123",
    "canIndex": true,
    "runningDescendantsCount": 0
  },
  {
    "id": "dir-docs-api",
    "filename": "api",
    "path": "/docs/api",
    "directory": true,
    "indexed": false,
    "modifiedAt": "2024-02-09T10:00:00Z",
    "canIndex": true,
    "runningDescendantsCount": 3
  }
]

Directory Indexing

runningDescendantsCount shows how many files within a directory are currently being indexed. Use this for progress indicators.

---

GET /api/libraries/{id}/files-list

Get a simpler flat list of files without recursive queries (faster for large libraries).

Authentication: Required

Permissions: User must have read access to the library

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Response:

{
  "_links": {
    "self": { "href": "/api/libraries/{id}/files-list" }
  },
  "_embedded": {
    "inf:file": [
      {
        "id": "file-xyz-789",
        "filename": "overview.md",
        "directory": false,
        "size": 4096,
        "indexed": true
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

---

PATCH /api/libraries/{id}/files

Bulk update file metadata using JSON Patch operations with glob pattern matching.

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Request Body:

Array of JSON Patch operations where path supports glob patterns:

Field	Type	Description
op	string	Operation type (only replace is supported)
path	string	Glob pattern for file path + property (e.g., /docs/*.md/modifiedAt)
value	any	New value for the property

Allowed Properties:

filename, directory, contentType, remoteUrl, modifiedAt, indexingErroredAt, indexingErrorMessage, indexingStartedAt, indexedAt, size

Example:

[
  {
    "op": "replace",
    "path": "/docs/**/*.md/modifiedAt",
    "value": "2024-02-09T12:00:00Z"
  },
  {
    "op": "replace",
    "path": "/assets/images/*.png/contentType",
    "value": "image/png"
  }
]

Response:

{
  "status": "success"
}

Indexing Operations

To bulk update indexed status, use POST /api/libraries/{id}/files/_bulk-index instead. This route does not accept indexed in patch operations.

---

GET /api/libraries/{id}/files/{fileId}

Get metadata for a specific file.

Authentication: Required

Permissions: User must have read access to the library and file

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Response:

{
  "id": "file-xyz-789",
  "filename": "overview.md",
  "libraryId": "550e8400-e29b-41d4-a716-446655440000",
  "parentId": "dir-docs-api",
  "directory": false,
  "contentType": "text/markdown",
  "size": 4096,
  "indexed": true,
  "indexedAt": "2024-02-09T10:05:00Z",
  "modifiedAt": "2024-02-09T10:05:00Z",
  "remoteUrl": "https://drive.google.com/file/d/abc123",
  "remoteId": "abc123",
  "ownerId": "alice",
  "createdAt": "2024-02-09T10:05:00Z"
}

---

PATCH /api/libraries/{id}/files/{fileId}

Update file metadata (rename, move, etc.).

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Request Body:

JSON Patch operations:

Field	Type	Description
op	string	Operation type (only replace supported)
path	string	Property path (e.g., /filename, /parentId)
value	any	New value

Example - Rename File:

[
  {
    "op": "replace",
    "path": "/filename",
    "value": "new-name.md"
  }
]

Example - Move File:

[
  {
    "op": "replace",
    "path": "/parentId",
    "value": "new-parent-directory-id"
  }
]

Response:

200 OK with updated file metadata

---

DELETE /api/libraries/{id}/files/{fileId}

Delete a file from the library.

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Response:

204 No Content

Recursive Delete

Deleting a directory also deletes all files and subdirectories within it.

---

GET /api/libraries/{id}/files/{fileId}/contents

Download file contents as a stream.

Authentication: Required

Permissions: User must have read access to the library and file

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Response:

Binary stream with appropriate Content-Type header.

---

PUT /api/libraries/{id}/files/{fileId}/contents

Replace file contents (upload new version).

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Request Body:

Binary file data (multipart/form-data or raw stream)

Response:

200 OK with updated file metadata

---

GET /api/libraries/{id}/contents/{path*}

Read file contents by path (supports nested paths).

Authentication: Required

Permissions: User must have read access to the library and file

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
path	string	File path (e.g., assets/index.js)

Response:

Binary stream with appropriate Content-Type header.

Example:

GET /api/libraries/my-lib/contents/assets/images/logo.png

Returns the PNG image file.

---

PUT /api/libraries/{id}/contents/{path*}

Write file contents by path (creates file and parent directories if needed).

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
path	string	File path (e.g., docs/new-file.md)

Request Body:

Binary file data

Response:

200 OK or 201 Created with file metadata

Example:

PUT /api/libraries/my-lib/contents/docs/new-file.md
Content-Type: text/markdown

# New Documentation
This is a new file.

---

PATCH /api/libraries/{id}/contents/{path*}

Partially update file contents by path (useful for AI-generated content updates).

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
path	string	File path

Request Body:

JSON Patch operations or partial content update

Response:

200 OK with updated file metadata

---

POST /api/libraries/{id}/files/_bulk-index

Bulk update indexed status for multiple files matching glob patterns.

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Request Body:

Field	Type	Required	Description
files	array	Yes	Array of file path glob patterns
value	boolean	Yes	New indexed status (true or false)

Example:

{
  "files": ["/docs/**/*.md", "/assets/*.pdf"],
  "value": true
}

Response:

{
  "updated": 42
}

---

GET /api/libraries/{id}/files/{fileId}/indexed

Get the current indexed status of a file.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Response:

{
  "indexed": true,
  "indexedAt": "2024-02-09T10:05:00Z",
  "indexingStartedAt": null,
  "indexingErroredAt": null,
  "indexingErrorMessage": null
}

---

PUT /api/libraries/{id}/files/{fileId}/indexed

Manually mark a file as indexed (or unindexed).

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Request Body:

Field	Type	Required	Description
indexed	boolean	Yes	New indexed status

Example:

{
  "indexed": true
}

Response:

200 OK with updated indexed status

---

DELETE /api/libraries/{id}/files/{fileId}/indexed

Clear indexed status and embeddings for a file.

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Response:

204 No Content

---

POST /api/libraries/{id}/files/{fileId}/_retry-indexing

Retry indexing for a file that previously failed.

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID
fileId	string (UUID)	File ID

Response:

200 OK

{
  "status": "queued",
  "indexingStartedAt": "2024-02-09T11:00:00Z"
}

Error Recovery

Use this endpoint when indexingErroredAt is set and you want to retry the indexing operation after fixing the underlying issue.