API reference

Storage

Storage providers and host browsing (library:manage).

Paths are relative to /api/v1 on your server.

GET/storages#

List storages

Authorisation: Bearer token or API key · Session cookie

200Success. application/json · Storage[]
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

POST/storages#

Add a storage

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

201Success. application/json · Storage
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

GET/storages/{id}#

Read a storage

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · Storage
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

PATCH/storages/{id}#

Update a storage

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · Storage
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

DELETE/storages/{id}#

Remove a storage

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

204Done; no body.
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
409CONFLICT: a library still uses it application/json · ErrorEnvelope

GET/storages/{id}/browse#

Browse inside a storage

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`
`path`	query	`string`

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

GET/storages/browse#

Browse the host filesystem

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`rootPath`	query	`string`
`path`	query	`string`

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

GET/storages/cloud#

Cloud drives this server can connect

Which vendors have an app registration on this server (P6-15), and the redirect URI each registration must name. No secrets.

Authorisation: Bearer token or API key · Session cookie

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

GET/storages/cloud/{provider}/callback#

Finish connecting a cloud drive

Where the vendor sends the browser. Redirects to the Storage page with cloud=connected&storage=<id>, or with cloud_error.

Authorisation: None

Parameter	In	Type
`provider` required	path	`"onedrive" \| "googledrive" \| "dropbox"`
`code`	query	`string`
`state`	query	`string`
`error`	query	`string`
`error_description`	query	`string`

302Success.
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

POST/storages/cloud/{provider}/start#

Start connecting a cloud drive

The vendor sign-in URL for the browser to open. The account that signs in becomes a storage of that kind when the vendor sends the browser back.

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

Parameter	In	Type	Description
`provider` required	path	`"onedrive" \| "googledrive" \| "dropbox"`

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

GET/storages/mine#

The cloud drives the caller connected

A member’s own connected drives (P6-15), for the photo library page. Empty for an account that connected none.

Authorisation: Bearer token or API key · Session cookie

200Success. application/json · Storage[]
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

DELETE/storages/mine/{id}#

Disconnect a drive the caller connected

Its folders leave every library they were in, those libraries rescan, and the storage is removed. 204.

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

204Done; no body.
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

GET/storages/mine/{id}/browse#

Browse inside a drive the caller connected

The folder picker for a member’s own cloud drive (P6-15); someone else’s drive is not found.

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`
`path`	query	`string`

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

GET/storages/roots#

List the host’s drives and mounts

Authorisation: Bearer token or API key · Session cookie

200Success. application/json · object
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

POST/storages/test#

Test a storage configuration

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope