Ask for a deleted item back
POST /account/trash/{kind}/{id}/request-restore
Asks for one of your deleted items to be restored, when someone else deleted it and you can’t restore it yourself.
You need to be signed in; no capability is needed. Without a session
cookie or bearer token that identifies you, the answer is 401,
whether or not public mode is on. An id that isn’t a valid UUID
gets a plain-text 400 before sign-in is checked, and so does a body
that can’t be decoded: one that isn’t valid JSON, a JSON value other
than an object or null, or a reason that is neither text nor null.
An empty body, {} and null are all fine. After sign-in, a kind
other than asset, post or collection gets 400. If the item
doesn’t exist, isn’t deleted, isn’t yours or has no owner, the
answer is the same 404, so the call reveals nothing about other
people’s items. If you can restore it yourself, because you deleted
it or hold system.admin granted globally, you get 409.
The request is always for content.restore.request, and nothing in
the body changes that; other keys are ignored. reason is saved as
sent, without trimming, and the length limit shown isn’t checked.
If you already have a pending request for the item, you get 200 with
it unchanged, and a new reason isn’t saved. Otherwise you get 201
with a new pending request, even if earlier ones were granted or
denied. The checks above run every time, so once the item is
restored, permanently deleted or no longer yours, asking again gets
404 or 409 even while your request is pending. Two identical
requests at the same moment usually both get back the same request;
rarely, one of them gets a plain-text 500. The checks and the save
are separate steps, so a request can be saved for an item that was
restored or changed at that moment.
A new request is sent as an in-app notification to whoever deleted
the item, if that was recorded, and to holders of system.admin
granted globally. A block between you, their notification settings
or a failure can stop it, and no email is sent. The notification
doesn’t include your reason, which is saved with the request for
whoever reviews it. Recording the request in the audit log is
attempted too, and can fail without affecting the request.
Filing a request doesn’t restore the item or keep it: the cleanup
can still delete it permanently (see purge_after in
listMyTrash). The person who deleted it, or a holder of
system.admin granted globally, decides with decideAdminRequest,
and granting it restores the item. Server errors get a plain-text
500.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”What id refers to: asset, post or collection. Any other value gets 400.
The deleted item’s id.
Request Body
Section titled “Request Body ”object
Why you want it back, for whoever reviews the request. Saved as sent; the length limit shown isn’t checked.
Responses
Section titled “ Responses ”You already had a pending request for this item. It is returned unchanged, and nobody is notified again.
A request and where it stands.
object
What target_id refers to. Access requests are always for an
asset; a restoration request can name an asset, post or
collection.
The id of the item the request is about. It isn’t checked when an access request is filed, so it may not exist.
What the request is for, which also decides who can answer it:
content.access.request: a request to see an asset. The asset’s owner can decide it, as can holders ofshare.grantorsystem.admin. Granting it unlocks nothing.content.restore.request: a request to get a deleted item back. Only whoever deleted the item, or a holder ofsystem.admin, can decide it. Granting it restores the item and grants no capability.- Any other code: a request for that capability across the whole
instance. Only holders of
share.grantorsystem.admincan decide it, and granting it gives the requester that capability.
On the two queues, whether you can decide this request, checked when the list was built. It can change before you act, and the decide call checks again. Left out on other responses.
The requester’s reason, if they gave one.
pending until someone decides it, then granted or denied. When the periodic cleanup removes an expired grant, the server tries to mark its request expired; a request can stay granted if that doesn’t happen. Pending requests don’t expire.
The reason recorded with the decision, if any. When a restoration request is granted for an item that was already back, a note says so here.
The expiry given when the request was granted; left out when there
was none. It describes the grant made at that time: approving a
later request for the same capability replaces that instance-wide
grant and its link to this request, so a request can show granted
after its grant has changed or gone.
The new pending request.
A request and where it stands.
object
What target_id refers to. Access requests are always for an
asset; a restoration request can name an asset, post or
collection.
The id of the item the request is about. It isn’t checked when an access request is filed, so it may not exist.
What the request is for, which also decides who can answer it:
content.access.request: a request to see an asset. The asset’s owner can decide it, as can holders ofshare.grantorsystem.admin. Granting it unlocks nothing.content.restore.request: a request to get a deleted item back. Only whoever deleted the item, or a holder ofsystem.admin, can decide it. Granting it restores the item and grants no capability.- Any other code: a request for that capability across the whole
instance. Only holders of
share.grantorsystem.admincan decide it, and granting it gives the requester that capability.
On the two queues, whether you can decide this request, checked when the list was built. It can change before you act, and the decide call checks again. Left out on other responses.
The requester’s reason, if they gave one.
pending until someone decides it, then granted or denied. When the periodic cleanup removes an expired grant, the server tries to mark its request expired; a request can stay granted if that doesn’t happen. Pending requests don’t expire.
The reason recorded with the decision, if any. When a restoration request is granted for an item that was already back, a note says so here.
The expiry given when the request was granted; left out when there
was none. It describes the grant made at that time: approving a
later request for the same capability replaces that instance-wide
grant and its link to this request, so a request can show granted
after its grant has changed or gone.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}The item doesn’t exist, isn’t deleted, isn’t yours or has no owner. The answer is the same in every case.
object
Human-readable error summary
Example
the request could not be completedYou can restore this item yourself, because you deleted it or hold
system.admin granted globally.
object
Human-readable error summary
Example
the request could not be completed