Libraries API

Ask about this page View Markdown

Base URL: https://YOUR-SERVER/api. Send your API key in x-api-key where authentication is required. A key also needs the listed permission; your account's access rules still apply.

API guide · All endpoints · OpenAPI JSON

GET /libraries — Retrieve libraries
POST /libraries — Create a library
GET /libraries/managed-uploads — Retrieve managed upload statistics
DELETE /libraries/{id} — Delete a library
GET /libraries/{id} — Retrieve a library
PUT /libraries/{id} — Update a library
GET /libraries/{id}/removal — Review a library removal
POST /libraries/{id}/removal — Remove a library
DELETE /libraries/{id}/scan — Cancel a library scan
POST /libraries/{id}/scan — Scan a library
GET /libraries/{id}/statistics — Retrieve library statistics
POST /libraries/{id}/validate — Validate library settings

Retrieve libraries

GET /api/libraries

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

Administrator access required.

Authentication: API key. Permission: library.read.

Parameters

Name	Where	Required	Description
`withDeleted`	query	No	Include libraries whose removal is still in progress

Parameter types, defaults and constraints

[
  {
    "name": "withDeleted",
    "required": false,
    "in": "query",
    "description": "Include libraries whose removal is still in progress",
    "schema": {
      "type": "boolean"
    }
  }
]

Responses

Field definitions: LibraryResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/LibraryResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Create a library

POST /api/libraries

Create a new external library.

Administrator access required.

Authentication: API key. Permission: library.create.

Request body

Required.

Field definitions: CreateLibraryDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/CreateLibraryDto"
    }
  }
}

Responses

Field definitions: LibraryResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LibraryResponseDto"
        }
      }
    },
    "description": ""
  }
}

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.

Administrator access required.

Authentication: API key. Permission: library.statistics.

Responses

Field definitions: ManagedUploadsStatsResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/ManagedUploadsStatsResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Delete a library

DELETE /api/libraries/{id}

Delete an external library by its ID.

Administrator access required.

Authentication: API key. Permission: library.delete.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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": ""
  }
}

Retrieve a library

GET /api/libraries/{id}

Retrieve an external library by its ID.

Administrator access required.

Authentication: API key. Permission: library.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: LibraryResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LibraryResponseDto"
        }
      }
    },
    "description": ""
  }
}

Update a library

PUT /api/libraries/{id}

Update an existing external library.

Deprecated. Avoid this operation in new integrations; use the replacement supported by your server release.

Administrator access required.

Authentication: API key. Permission: library.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: UpdateLibraryDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/UpdateLibraryDto"
    }
  }
}

Responses

Field definitions: LibraryResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LibraryResponseDto"
        }
      }
    },
    "description": ""
  }
}

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.

Administrator access required.

Authentication: API key. Permission: library.delete.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: LibraryRemovalReviewDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LibraryRemovalReviewDto"
        }
      }
    },
    "description": ""
  }
}

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.

Administrator access required.

Authentication: API key. Permission: library.delete.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: LibraryRemovalDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/LibraryRemovalDto"
    }
  }
}

Responses

{
  "204": {
    "description": ""
  }
}

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.

Administrator access required.

Authentication: API key. Permission: library.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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": ""
  }
}

Scan a library

POST /api/libraries/{id}/scan

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

Administrator access required.

Authentication: API key. Permission: library.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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": ""
  }
}

Retrieve library statistics

GET /api/libraries/{id}/statistics

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

Administrator access required.

Authentication: API key. Permission: library.statistics.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: LibraryStatsResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LibraryStatsResponseDto"
        }
      }
    },
    "description": ""
  }
}

Validate library settings

POST /api/libraries/{id}/validate

Validate the settings of an external library.

Administrator access required.

Authentication: API key. Permission: all.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: ValidateLibraryDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/ValidateLibraryDto"
    }
  }
}

Responses

Field definitions: ValidateLibraryResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ValidateLibraryResponseDto"
        }
      }
    },
    "description": ""
  }
}

Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.