# Libraries API

Source: https://frameleaf.app/docs/api/reference/libraries/

Use your own server and its scoped API keys.

## Retrieve libraries

GET /api/libraries

Retrieve a list of external libraries, each with its latest scan.

```json
{
  "description": "Retrieve a list of external libraries, each with its latest scan.",
  "operationId": "getAllLibraries",
  "parameters": [
    {
      "name": "withDeleted",
      "required": false,
      "in": "query",
      "description": "Include libraries whose removal is still in progress",
      "schema": {
        "type": "boolean"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/LibraryResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve libraries",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.read"
}
```

## Create a library

POST /api/libraries

Create a new external library.

```json
{
  "description": "Create a new external library.",
  "operationId": "createLibrary",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateLibraryDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/LibraryResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Create a library",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.create"
}
```

## Retrieve managed upload statistics

GET /api/libraries/managed-uploads

Retrieve, for every active account, the photos, videos and original sizes it keeps in managed upload storage rather than in external libraries.

```json
{
  "description": "Retrieve, for every active account, the photos, videos and original sizes it keeps in managed upload storage rather than in external libraries.",
  "operationId": "getManagedUploadStatistics",
  "parameters": [],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/ManagedUploadsStatsResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve managed upload statistics",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.statistics"
}
```

## Delete a library

DELETE /api/libraries/{id}

Delete an external library by its ID.

```json
{
  "description": "Delete an external library by its ID.",
  "operationId": "deleteLibrary",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete a library",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.delete"
}
```

## Retrieve a library

GET /api/libraries/{id}

Retrieve an external library by its ID.

```json
{
  "description": "Retrieve an external library by its ID.",
  "operationId": "getLibrary",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/LibraryResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve a library",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.read"
}
```

## Update a library

PUT /api/libraries/{id}

Update an existing external library.

```json
{
  "deprecated": true,
  "description": "Update an existing external library.",
  "operationId": "updateLibrary",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateLibraryDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/LibraryResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Update a library",
  "tags": [
    "Libraries",
    "Deprecated"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.update"
}
```

## Review a library removal

GET /api/libraries/{id}/removal

The first stage of removing an external library: the indexed items, albums, shared links and faces the removal takes with it, and a token to confirm it with. Source files are never deleted.

```json
{
  "description": "The first stage of removing an external library: the indexed items, albums, shared links and faces the removal takes with it, and a token to confirm it with. Source files are never deleted.",
  "operationId": "getLibraryRemovalReview",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/LibraryRemovalReviewDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Review a library removal",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.delete"
}
```

## Remove a library

POST /api/libraries/{id}/removal

The second stage of removing an external library: confirm with the typed name and the review token. Refused when the library changed after the review.

```json
{
  "description": "The second stage of removing an external library: confirm with the typed name and the review token. Refused when the library changed after the review.",
  "operationId": "removeLibrary",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LibraryRemovalDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Remove a library",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.delete"
}
```

## Cancel a library scan

DELETE /api/libraries/{id}/scan

Stop the external library's waiting, running or paused scan. Items it already handled stay as they are.

```json
{
  "description": "Stop the external library's waiting, running or paused scan. Items it already handled stay as they are.",
  "operationId": "cancelLibraryScan",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Cancel a library scan",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.update"
}
```

## Scan a library

POST /api/libraries/{id}/scan

Queue a scan for the external library to find and import new assets.

```json
{
  "description": "Queue a scan for the external library to find and import new assets.",
  "operationId": "scanLibrary",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Scan a library",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.update"
}
```

## Retrieve library statistics

GET /api/libraries/{id}/statistics

Retrieve statistics for a specific external library, including number of videos, images, and storage usage.

```json
{
  "description": "Retrieve statistics for a specific external library, including number of videos, images, and storage usage.",
  "operationId": "getLibraryStatistics",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/LibraryStatsResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve library statistics",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "library.statistics"
}
```

## Validate library settings

POST /api/libraries/{id}/validate

Validate the settings of an external library.

```json
{
  "description": "Validate the settings of an external library.",
  "operationId": "validate",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ValidateLibraryDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ValidateLibraryResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Validate library settings",
  "tags": [
    "Libraries"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "all"
}
```