Reference

REST API

The module exposes a JSON API under /api/asset-picker/. It is the same API the Asset Library and the CKEditor modal use.

Requests are authenticated by the normal Omeka S admin session cookie and follow the same role rules as the interface: authors and reviewers can read, editors and above can write. Every response has a status of success or error, and errors include a message.

Folders

GET /api/asset-picker/folders

Returns the whole folder tree.

{
  "status": "success",
  "folders": [
    {
      "id": 1, "title": "Photos", "slug": "photos",
      "parent_id": null, "asset_count": 12,
      "children": [
        { "id": 3, "title": "2025", "slug": "2025", "parent_id": 1, "asset_count": 5, "children": [] }
      ]
    }
  ]
}

POST /api/asset-picker/folders

Create a folder.

{ "title": "New Folder", "parent_id": null }

GET /api/asset-picker/folders/:id

Return one folder.

PUT /api/asset-picker/folders/:id

Rename a folder or move it under a different parent.

{ "title": "Renamed", "parent_id": 1 }

DELETE /api/asset-picker/folders/:id

Delete a folder. Assets in it are not deleted.

Assets

GET /api/asset-picker/assets

A paged list of assets.

Parameter Default Description
page 1 Page number
per_page 24 Results per page, maximum 100
sort_by id id or name
sort_order desc asc or desc
folder_id Only assets in this folder
search Filter by name (substring match) 
{
  "status": "success",
  "assets": [
    {
      "id": 42,
      "filename": "abc123.jpg",
      "mime_type": "image/jpeg",
      "canonical_url": "https://example.com/files/asset/abc123.jpg",
      "created_at": null,
      "metadata": { "title": "My Photo", "alt": "A mountain view" },
      "folders": [1]
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 24
}

POST /api/asset-picker/assets

Upload a new asset as multipart/form-data.

Field Description
file[0] The file
o:name Optional name; defaults to the filename
folder_id Optional folder to place the asset in

GET /api/asset-picker/assets/:id

Return one asset.

DELETE /api/asset-picker/assets/:id

Delete an asset. Its folder assignments and usage records are removed first, then the Omeka asset itself.

PATCH /api/asset-picker/assets/bulk

Update several assets at once. Only the keys present are changed.

{
  "ids": [1, 2, 3],
  "name": "Updated name",
  "alt_text": "Updated alt",
  "folder_id": 5
}

Send "folder_id": null to remove the assets from every folder.

The same endpoint deletes in bulk when action is delete:

{ "ids": [1, 2, 3], "action": "delete" }

The response lists the ids that were deleted:

{ "status": "success", "deleted": [1, 2, 3] }

PUT /api/asset-picker/assets/:id/replace

Replace the asset's file. Send multipart/form-data with a single file field. The new file must have the same extension as the original; a mismatch returns HTTP 400 with an explanation.

curl -X PUT https://example.com/api/asset-picker/assets/42/replace \
  -F "file=@/path/to/new-photo.jpg" \
  -b "PHPSESSID=..."

Usage

GET /api/asset-picker/assets/:id/usage

The most recent 100 usage records for an asset.

POST /api/asset-picker/assets/:id/usage

Record a usage. The CKEditor plugin calls this on every insertion; you can call it from your own integrations too.

{ "context_type": "ckeditor", "context_id": null }
Log in for Support