Use the Server API

The Frameleaf Server API lets your scripts and tools upload media, organize albums, search your library and automate administration on your own server. Create a scoped API key, try the examples below, then explore the full reference.

Browse endpoints · Browse schemas · Download the OpenAPI specification

Connect to your server

Use your Frameleaf address followed by /api, for example https://photos.example.com/api. The API uses your server’s accounts and access rules. These pages cover the self-hosted endpoints for API-key integrations.

The reference shows its API version, and GET /api/server/version returns your running server version, so you can match the two.

Create an API key

1. Sign in to the Frameleaf web app.
2. Open Settings → Access & security → API keys.
3. Create a key with a descriptive name and only the permissions your script needs.
4. Copy the key when it’s shown and store it privately. Delete it when you no longer need the integration.

Send the key in the x-api-key header, and keep it out of public URLs, browser scripts and source repositories. A key has at most the access of the account that owns it, and administrative operations need administrator access.

For the examples below, set FRAMELEAF_API_URL to your server address including /api, and provide FRAMELEAF_API_KEY through your shell’s secret or environment facility.

Read your albums

Requires album.read.

curl --fail-with-body \
  --header "x-api-key: $FRAMELEAF_API_KEY" \
  "$FRAMELEAF_API_URL/albums"

See Albums for ownership filters, album creation and sharing.

Upload a photo

Requires asset.upload. Uploads use multipart form data; let your HTTP client set the boundary. Use the file’s real creation and modification timestamps in ISO 8601 format.

curl --fail-with-body \
  --header "x-api-key: $FRAMELEAF_API_KEY" \
  --form '[email protected]' \
  --form 'fileCreatedAt=2026-10-01T12:30:00.000Z' \
  --form 'fileModifiedAt=2026-10-01T12:30:00.000Z' \
  "$FRAMELEAF_API_URL/assets"

A new upload returns 201; a duplicate returns 200. Use the returned asset ID in later requests. See Assets for the complete request and response. For folders and large imports, the Frameleaf CLI is usually easier than writing an uploader.

Read requests and responses

Each endpoint page lists its HTTP method, path, authentication, API-key permission and parameter locations. Replace {id} in a path with the actual identifier. JSON requests need Content-Type: application/json; file uploads use multipart form data.

Schema links explain nested objects, allowed enum values, formats and required fields. An omitted field and a field set to null can mean different things. Keep identifiers as strings, and follow each endpoint’s pagination fields to page through large results.

Handle failures

Status	What to do
400	Check required fields, formats and allowed values.
401	Check that the key is valid and the request includes its header.
403	Check the key’s permissions and the owning account’s access.
404	Check the ID, route and server version. A resource may be unavailable to your account.
409	Refresh current state before retrying a conflicting update.
413	Check server and reverse-proxy upload limits.
429	Respect Retry-After when returned and slow your requests.
5xx	Check server health; retry reads with a delay. Check the result of a write before repeating it.

For destructive operations such as permanent deletion and database restoration, test your script on a small sample first, keep backups, and check a write’s result before retrying it.