Core CRUD

Basic library creation, retrieval, update, and deletion operations.

GET /api/libraries

Search and filter libraries with pagination.

Authentication: Required

Permissions: Returns libraries owned by or shared with the authenticated user (excludes embedded libraries)

Query Parameters:

Parameter	Type	Default	Description
q	string	-	Full-text search query (searches name, description)
sort	string	name	Sort field (prefix with - for descending)
limit	integer	30	Results per page
start	integer	0	Pagination offset

Response:

The response is a paginated HAL collection. Library items are returned under _embedded["inf:library"].

{
  "_links": {
    "self": { "href": "/api/libraries{?sort,limit,start,q}", "templated": true }
  },
  "_embedded": {
    "inf:library": [
      {
        "_links": {
          "self": { "href": "/api/libraries/550e8400-..." },
          "inf:files": { "href": "/api/libraries/550e8400-.../files" },
          "inf:sync": { "href": "/api/libraries/550e8400-.../_sync" }
        },
        "id": "550e8400-...",
        "type": "google-drive",
        "name": "Project Documentation",
        "slug": "project-documentation",
        "description": "Team knowledge base and design docs",
        "ownerId": "engineering",
        "shared": true,
        "assistantAccess": true,
        "embedded": false,
        "syncedAt": "2024-02-08T14:30:00.000Z",
        "syncInterval": 60,
        "createdAt": "2024-01-10T09:00:00.000Z",
        "updatedAt": "2024-02-08T15:00:00.000Z"
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 42
}

Embedded Libraries

This endpoint excludes embedded libraries (like App assets or chat-specific libraries). To access embedded libraries, use lookup by ID.

---

GET /api/libraries-list

Get a complete flat list of readable libraries with minimal pagination.

Authentication: Required

Permissions: Same as GET /api/libraries (excludes embedded libraries)

Response:

[
  {
    "id": "550e8400-...",
    "name": "Project Documentation",
    "type": "google-drive",
    "shared": true,
    "assistantAccess": true,
    "ownerId": "engineering",
    "ownerName": "Engineering Team",
    "naturalId": "engineering:project-documentation",
    "tags": ["tag-uuid-1"],
    "sharing": [
      { "principalId": "marketing", "accessLevel": 2 }
    ],
    "permissions": {
      "edit": true,
      "write": true,
      "delete": true,
      "share": true
    }
  }
]

Use Case:

This endpoint returns a lightweight list for building library picker UIs or dropdowns.

---

GET /api/libraries/{id}

Get a single library with full details including driver info, integration, and connection status.

Authentication: Required

Permissions: User must own the library or have read access via share

Path Parameters:

Parameter	Type	Description
id	string	Library ID or {ownerId}:{slug} natural ID

Query Parameters:

Parameter	Type	Default	Description
includeJobAccess	boolean	false	Include libraries accessible via job ownership

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "google-drive",
  "name": "Project Documentation",
  "slug": "project-documentation",
  "description": "Team knowledge base and design docs",
  "ownerId": "team:engineering",
  "data": {
    "folderId": "1A2B3C4D5E6F7G8H9I0J"
  },
  "folderId": null,
  "shared": true,
  "assistantAccess": true,
  "embedded": false,
  "syncedAt": "2024-02-08T14:30:00Z",
  "syncInterval": 60,
  "snapshotOfId": null,
  "chatId": null,
  "createdAt": "2024-01-10T09:00:00Z",
  "updatedAt": "2024-02-08T15:00:00Z",
  "_embedded": {
    "inf:library-driver": {
      "id": "google-drive",
      "name": "Google Drive",
      "supportsSync": true,
      "supportsUpload": false,
      "isLocal": false
    },
    "inf:integration": {
      "id": "abc-integration-123",
      "name": "Google Drive - Engineering Team",
      "type": "google-drive",
      "embedded": true,
      "libraryId": "550e8400-e29b-41d4-a716-446655440000"
    },
    "inf:connection": {
      "id": "conn-xyz-789",
      "ownerId": "alice",
      "integrationId": "abc-integration-123",
      "tokenExpiresAt": "2024-02-09T14:30:00Z",
      "lastAuthorizedAt": "2024-02-08T14:30:00Z"
    }
  },
  "_links": {
    "self": { "href": "/api/libraries/550e8400-e29b-41d4-a716-446655440000" },
    "inf:files": { "href": "/api/libraries/550e8400-e29b-41d4-a716-446655440000/files" },
    "inf:sync": { "href": "/api/libraries/550e8400-e29b-41d4-a716-446655440000/_sync" },
    "inf:assistants": { "href": "/api/libraries/550e8400-e29b-41d4-a716-446655440000/assistants" },
    "inf:library-shares": { "href": "/api/libraries/550e8400-e29b-41d4-a716-446655440000/shares" },
    "inf:comments": { "href": "/api/libraries/550e8400-e29b-41d4-a716-446655440000/comments" },
    "inf:favorite": { "href": "/api/libraries/550e8400-e29b-41d4-a716-446655440000/favorite" }
  },
  "permissions": {
    "read": true,
    "write": true,
    "delete": true,
    "sync": true
  }
}

Job Access

Set includeJobAccess=true to include libraries that are referenced in jobs you own, even if you don't directly own or have shares to the library.

---

POST /api/libraries

Create a new library.

Authentication: Required

Permissions: Requires permission.libraries.create

Request Body:

Field	Type	Required	Description
id	string (UUID)	No	Pre-generated library ID (auto-generated if omitted)
name	string	Yes	Library name
description	string	No	Library description
type	string	Yes	Library driver type (local, google-drive, onedrive, sharepoint, dropbox)
integrationId	string	No	Existing integration ID (for non-local libraries)
shared	boolean	No	Enable sharing (default: false)
data	object	No	Driver-specific configuration data
readOnly	boolean	No	Create read-only integration (default: true)
clientId	string	No	OAuth client ID (for cloud integrations)
clientSecret	string	No	OAuth client secret (for cloud integrations)

Example - Local Library:

{
  "name": "Team Documents",
  "description": "Shared team resources",
  "type": "local",
  "shared": true
}

Example - Google Drive Library:

{
  "name": "Engineering Docs",
  "type": "google-drive",
  "data": {
    "folderId": "1A2B3C4D5E6F7G8H9I0J"
  },
  "clientId": "123456789-abcdefg.apps.googleusercontent.com",
  "clientSecret": "GOCSPX-xyz123abc456",
  "readOnly": true
}

Response:

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "local",
  "name": "Team Documents",
  "description": "Shared team resources",
  "ownerId": "alice",
  "shared": true,
  "assistantAccess": false,
  "embedded": false,
  "syncInterval": null,
  "createdAt": "2024-02-09T10:00:00Z",
  "updatedAt": "2024-02-09T10:00:00Z"
}

Integration Creation

For cloud library types, creating the library also creates an embedded integration with the provided clientId and clientSecret. The integration must then be connected via OAuth (see Integration & Sync).

---

PUT /api/libraries/{id}

Update an existing library's metadata.

Authentication: Required

Permissions: Requires library:write permission on the target library

Path Parameters:

Parameter	Type	Description
id	string	Library ID or {ownerId}:{slug} natural ID

Request Body:

Field	Type	Description
name	string	Updated library name
description	string	Updated description
data	object	Driver-specific data
shared	boolean	Enable/disable sharing
syncInterval	integer	Sync interval in minutes (min: 1)

Example:

{
  "name": "Updated Library Name",
  "description": "New description",
  "shared": true,
  "syncInterval": 120
}

Response:

200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Library Name",
  "description": "New description",
  "shared": true,
  "syncInterval": 120,
  "updatedAt": "2024-02-09T11:00:00Z"
}

Client Credentials

clientId and clientSecret cannot be updated via this endpoint. They are stripped from the payload for security.

---

DELETE /api/libraries/{id}

Delete a library and all its files.

Authentication: Required

Permissions: Requires library:delete permission on the target library

Path Parameters:

Parameter	Type	Description
id	string	Library ID or {ownerId}:{slug} natural ID

Response:

204 No Content

Cascade Delete

Deleting a library permanently removes all files, snapshots, shares, and assistant associations. This action cannot be undone.

---

GET /api/libraries/{id}/owner

Get the current owner of a library.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Response:

{
  "ownerId": "team:engineering"
}

---

PUT /api/libraries/{id}/owner

Change the owner of a library.

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
ownerId	string	Yes	New owner principal ID (user or team)

Example:

{
  "ownerId": "team:data-science"
}

Response:

200 OK

{
  "ownerId": "team:data-science"
}