REST API

The module registers a backups resource with Omeka's REST API at /api/backups. It uses Omeka's standard API conventions: JSON-LD responses, and authentication with an API key (key_identity and key_credential query parameters). /api/backups ignores the admin session cookie: from a browser where an administrator is signed in, use Omeka's read-only path /api-local/backups to list and read records.

Only Global Administrators can use the resource, through either path. Other roles, Supervisors included, receive a permission error (HTTP 403).

Endpoints#

Update (PUT and PATCH) is not supported.

GET /api/backups#

Returns every record. The usual page and per_page parameters are ignored; the full list is always returned and Omeka-S-Total-Results equals its length.

curl "https://example.org/api/backups?status=complete&key_identity=KEY&key_credential=SECRET"

POST /api/backups#

Creates a backup in the request itself, not as a background job. The request does not return until the archive is finished, so it can take minutes on a large site and is subject to the web server's request timeout. For large sites prefer the admin page or the CLI.

The JSON body holds the same options as the Create Backup page; every one defaults to true.

{
    "include_db": true,
    "include_files": true,
    "include_themes": true,
    "include_modules": true,
    "include_api": false
}

curl -X POST "https://example.org/api/backups?key_identity=KEY&key_credential=SECRET" \
     -H "Content-Type: application/json" \
     -d '{"include_api": false}'

The response is the finished record. The backup is credited to the API key's user, and retention cleanup runs afterwards as usual.

DELETE /api/backups/:id#

Removes the archive from disk and the record from the list, and returns the deleted record. Unknown IDs return a 404.

Representation#

{
    "@context": "https://example.org/api-context",
    "@id": "https://example.org/api/backups/12",
    "@type": "o:Backup",
    "o:id": 12,
    "o:filename": "omeka-backup-20260326-020000-3f9a1c7e5b2d8e04.zip",
    "o:path": "/var/backups/omeka/omeka-backup-20260326-020000-3f9a1c7e5b2d8e04.zip",
    "o:storage": "local",
    "o:size": 734003200,
    "o:status": "complete",
    "o:checksum": "sha256:9b2c...e41f",
    "o:created_by": 1,
    "o:created_at": "2026-03-26 02:00:00",
    "o:metadata": {
        "backup_module_version": "1.3.0",
        "created_at": "2026-03-26T02:00:00+00:00",
        "includes": { "include_db": true, "include_files": true, "include_themes": true, "include_modules": true, "include_api": true }
    }
}

o:created_by is null for backups made from the command line. o:storage is local for an archive on the server, where o:path is its absolute path, or file_store for one kept in the site's cloud file store, where o:path is its path in the store (backups/<32 random characters>/<filename>). Either way, treat responses as sensitive.

There is no download endpoint in the API. Download archives from the admin list or read them from the backup directory.

API Browser#

If the API Browser module is installed, the backups resource appears there with its query parameter, request body fields and response keys documented, since the adapter implements apiBrowserSchema().