Recycle Bin

Recycle Bin#

The Recycle Bin REST API provides endpoints to interact with the Plone Recycle Bin functionality.

Reading or writing recycle bin data requires the cmf.ManagePortal permission.

List recycle bin contents#

A list of all items in the recycle bin can be retrieved by sending a GET request to the @recyclebin endpoint:

http

GET /plone/@recyclebin HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET http://nohost/plone/@recyclebin -H "Accept: application/json" --user admin:secret

httpie

http http://nohost/plone/@recyclebin Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@recyclebin', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:55001/plone/@recyclebin",
    "items": [
        {
            "@id": "http://localhost:55001/plone/@recyclebin/688e63b3-26e2-463f-aa7c-537251bba80c",
            "@type": "Document",
            "actions": {
                "purge": "http://localhost:55001/plone/@recyclebin/688e63b3-26e2-463f-aa7c-537251bba80c",
                "restore": "http://localhost:55001/plone/@recyclebin/688e63b3-26e2-463f-aa7c-537251bba80c/restore"
            },
            "deleted_by": "test_user_1_",
            "deletion_date": "2026-03-21T21:34:59.994296",
            "has_children": false,
            "id": "document1",
            "language": "",
            "parent_path": "/plone",
            "path": "/plone/document1",
            "recycle_id": "688e63b3-26e2-463f-aa7c-537251bba80c",
            "review_state": "private",
            "title": "My Document"
        },
        {
            "@id": "http://localhost:55001/plone/@recyclebin/a3de7769-75dc-4f96-9235-5a642dcfe6eb",
            "@type": "Folder",
            "actions": {
                "purge": "http://localhost:55001/plone/@recyclebin/a3de7769-75dc-4f96-9235-5a642dcfe6eb",
                "restore": "http://localhost:55001/plone/@recyclebin/a3de7769-75dc-4f96-9235-5a642dcfe6eb/restore"
            },
            "deleted_by": "test_user_1_",
            "deletion_date": "2026-03-21T21:34:59.992021",
            "has_children": true,
            "id": "folder1",
            "language": "",
            "parent_path": "/plone",
            "path": "/plone/folder1",
            "recycle_id": "a3de7769-75dc-4f96-9235-5a642dcfe6eb",
            "review_state": "private",
            "title": "My Folder"
        }
    ],
    "items_total": 2
}

Filtering and Sorting Parameters#

The listing supports various query parameters for filtering and sorting:

Parameter	Description	Example
`title`	Filter by title (case-insensitive substring match)	`title=my doc`
`path`	Filter by path (case-insensitive substring match)	`path=/plone/news`
`portal_type`	Filter by content type	`portal_type=Document`
`date_from`	Filter by deletion date from (YYYY-MM-DD)	`date_from=2024-01-01`
`date_to`	Filter by deletion date to (YYYY-MM-DD)	`date_to=2024-12-31`
`deleted_by`	Filter by the user ID who deleted the item	`deleted_by=admin`
`has_subitems`	Filter items with (`true`) or without (`false`) children	`has_subitems=true`
`language`	Filter by language code	`language=it`
`review_state`	Filter by workflow state	`review_state=published`
`sort_on`	Sort field: `title`, `portal_type`, `path`, `deletion_date`, `review_state`	`sort_on=title`
`sort_order`	Sort direction: `ascending` or `descending` (default)	`sort_order=ascending`

Batching#

The API supports standard Plone REST API batching parameters (b_start, b_size).

Example with filtering and sorting#

http

GET /plone/@recyclebin?portal_type=Document&sort_on=title&sort_order=ascending HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET 'http://nohost/plone/@recyclebin?portal_type=Document&sort_on=title&sort_order=ascending' -H "Accept: application/json" --user admin:secret

httpie

http 'http://nohost/plone/@recyclebin?portal_type=Document&sort_on=title&sort_order=ascending' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@recyclebin?portal_type=Document&sort_on=title&sort_order=ascending', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:55001/plone/@recyclebin?portal_type=Document",
    "items": [
        {
            "@id": "http://localhost:55001/plone/@recyclebin/3428fff7-155a-4b53-afaa-833cba13ab4a",
            "@type": "Document",
            "actions": {
                "purge": "http://localhost:55001/plone/@recyclebin/3428fff7-155a-4b53-afaa-833cba13ab4a",
                "restore": "http://localhost:55001/plone/@recyclebin/3428fff7-155a-4b53-afaa-833cba13ab4a/restore"
            },
            "deleted_by": "test_user_1_",
            "deletion_date": "2026-03-21T21:35:00.106645",
            "has_children": false,
            "id": "document1",
            "language": "",
            "parent_path": "/plone",
            "path": "/plone/document1",
            "recycle_id": "3428fff7-155a-4b53-afaa-833cba13ab4a",
            "review_state": "private",
            "title": "My Document"
        },
        {
            "@id": "http://localhost:55001/plone/@recyclebin/54547a55-e1db-4821-afd6-b08e62694a0f",
            "@type": "Folder",
            "actions": {
                "purge": "http://localhost:55001/plone/@recyclebin/54547a55-e1db-4821-afd6-b08e62694a0f",
                "restore": "http://localhost:55001/plone/@recyclebin/54547a55-e1db-4821-afd6-b08e62694a0f/restore"
            },
            "deleted_by": "test_user_1_",
            "deletion_date": "2026-03-21T21:35:00.104531",
            "has_children": true,
            "id": "folder1",
            "language": "",
            "parent_path": "/plone",
            "path": "/plone/folder1",
            "recycle_id": "54547a55-e1db-4821-afd6-b08e62694a0f",
            "review_state": "private",
            "title": "My Folder"
        }
    ],
    "items_total": 2
}

Get individual item from recycle bin#

To retrieve detailed information about a specific item in the recycle bin, including its sub-items, send a GET request to @recyclebin/{item_id}. The response includes a paginated items list with all flattened descendants. Standard batching parameters (b_start, b_size) are supported.

http

GET /plone/@recyclebin/9543ec39-054a-48b3-967b-b9578f8b2b0d HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET http://nohost/plone/@recyclebin/9543ec39-054a-48b3-967b-b9578f8b2b0d -H "Accept: application/json" --user admin:secret

httpie

http http://nohost/plone/@recyclebin/9543ec39-054a-48b3-967b-b9578f8b2b0d Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@recyclebin/9543ec39-054a-48b3-967b-b9578f8b2b0d', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:55001/plone/@recyclebin/9543ec39-054a-48b3-967b-b9578f8b2b0d",
    "@type": "Document",
    "actions": {
        "purge": "http://localhost:55001/plone/@recyclebin/9543ec39-054a-48b3-967b-b9578f8b2b0d",
        "restore": "http://localhost:55001/plone/@recyclebin/9543ec39-054a-48b3-967b-b9578f8b2b0d/restore"
    },
    "deleted_by": "test_user_1_",
    "deletion_date": "2026-03-21T21:35:00.215868",
    "has_children": false,
    "id": "document1",
    "items": [],
    "items_total": 0,
    "language": "",
    "parent_path": "/plone",
    "path": "/plone/document1",
    "recycle_id": "9543ec39-054a-48b3-967b-b9578f8b2b0d",
    "review_state": "private",
    "title": "My Document"
}

Restore an item from the recycle bin#

An item can be restored to its original location by issuing a POST to @recyclebin/{item_id}/restore:

http

POST /plone/@recyclebin/e981c08f-4a37-4238-a843-10665ad7479a/restore HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X POST http://nohost/plone/@recyclebin/e981c08f-4a37-4238-a843-10665ad7479a/restore -H "Accept: application/json" --user admin:secret

httpie

http POST http://nohost/plone/@recyclebin/e981c08f-4a37-4238-a843-10665ad7479a/restore Accept:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@recyclebin/e981c08f-4a37-4238-a843-10665ad7479a/restore', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Item document1 restored successfully",
    "restored_item": {
        "@id": "http://localhost:55001/plone/document1",
        "@type": "Document",
        "id": "document1",
        "title": "My Document"
    },
    "status": "success"
}

Restore to a specific location#

Pass a target_path in the request body to restore the item to a different folder:

http

POST /plone/@recyclebin/3c44d4b8-a431-4bbf-b6fe-875a7ce8b0b9/restore HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "target_path": "/plone/target_folder"
}

curl

curl -i -X POST http://nohost/plone/@recyclebin/3c44d4b8-a431-4bbf-b6fe-875a7ce8b0b9/restore -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"target_path": "/plone/target_folder"}' --user admin:secret

httpie

echo '{
  "target_path": "/plone/target_folder"
}' | http POST http://nohost/plone/@recyclebin/3c44d4b8-a431-4bbf-b6fe-875a7ce8b0b9/restore Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@recyclebin/3c44d4b8-a431-4bbf-b6fe-875a7ce8b0b9/restore', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'target_path': '/plone/target_folder'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Item document2 restored successfully",
    "restored_item": {
        "@id": "http://localhost:55001/plone/target_folder/document2",
        "@type": "Document",
        "id": "document2",
        "title": "Another Document"
    },
    "status": "success"
}

Purge a specific item from the recycle bin#

To permanently delete a specific item, send a DELETE request to @recyclebin/{item_id}:

http

DELETE /plone/@recyclebin/661060b1-7410-4069-a359-b674f4addbd6 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X DELETE http://nohost/plone/@recyclebin/661060b1-7410-4069-a359-b674f4addbd6 -H "Accept: application/json" --user admin:secret

httpie

http DELETE http://nohost/plone/@recyclebin/661060b1-7410-4069-a359-b674f4addbd6 Accept:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/@recyclebin/661060b1-7410-4069-a359-b674f4addbd6', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 204 No Content

Empty the entire recycle bin#

To permanently delete all items, send a DELETE request to @recyclebin:

http

DELETE /plone/@recyclebin HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X DELETE http://nohost/plone/@recyclebin -H "Accept: application/json" --user admin:secret

httpie

http DELETE http://nohost/plone/@recyclebin Accept:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/@recyclebin', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 204 No Content

Recycle Bin

Contents

Recycle Bin#

List recycle bin contents#

Filtering and Sorting Parameters#

Batching#

Example with filtering and sorting#

Get individual item from recycle bin#

Restore an item from the recycle bin#

Restore to a specific location#

Purge a specific item from the recycle bin#

Empty the entire recycle bin#