Skip to content

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.

kind
required
string
Allowed values: asset post collection

What id refers to: asset, post or collection. Any other value gets 400.

id
required
string format: uuid

The deleted item’s id.

object
reason

Why you want it back, for whoever reviews the request. Saved as sent; the length limit shown isn’t checked.

string
<= 1000 characters

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
id
required
string format: uuid
requester_user_ref
required
integer format: int64
target_kind
required

What target_id refers to. Access requests are always for an asset; a restoration request can name an asset, post or collection.

string
Allowed values: asset post collection
target_id
required

The id of the item the request is about. It isn’t checked when an access request is filed, so it may not exist.

string format: uuid
requested_capability
required

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 of share.grant or system.admin. Granting it unlocks nothing.
  • content.restore.request: a request to get a deleted item back. Only whoever deleted the item, or a holder of system.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.grant or system.admin can decide it, and granting it gives the requester that capability.
string
decidable_by_caller

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.

boolean
reason

The requester’s reason, if they gave one.

string
state
required

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.

string
Allowed values: pending granted denied expired
decided_at
string format: date-time
nullable
decided_by_user_ref
integer format: int64
nullable
decision_reason

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.

string
expires_at

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.

string format: date-time
nullable
requested_at
required
string format: date-time

The new pending request.

A request and where it stands.

object
id
required
string format: uuid
requester_user_ref
required
integer format: int64
target_kind
required

What target_id refers to. Access requests are always for an asset; a restoration request can name an asset, post or collection.

string
Allowed values: asset post collection
target_id
required

The id of the item the request is about. It isn’t checked when an access request is filed, so it may not exist.

string format: uuid
requested_capability
required

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 of share.grant or system.admin. Granting it unlocks nothing.
  • content.restore.request: a request to get a deleted item back. Only whoever deleted the item, or a holder of system.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.grant or system.admin can decide it, and granting it gives the requester that capability.
string
decidable_by_caller

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.

boolean
reason

The requester’s reason, if they gave one.

string
state
required

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.

string
Allowed values: pending granted denied expired
decided_at
string format: date-time
nullable
decided_by_user_ref
integer format: int64
nullable
decision_reason

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.

string
expires_at

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.

string format: date-time
nullable
requested_at
required
string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"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
error
required

Human-readable error summary

string
Example
the request could not be completed

You can restore this item yourself, because you deleted it or hold system.admin granted globally.

object
error
required

Human-readable error summary

string
Example
the request could not be completed