Skip to content

List requests waiting for me

GET
/account/requests/incoming

Lists pending requests about assets you own and items you deleted, oldest first. No capability is needed.

Two kinds of request appear: requests for access to live assets you own, and requests to restore items you deleted, whether an asset, post or collection. A request drops out of the list when its asset is deleted or its item is restored, even though it’s still pending. A request on one of your assets that names a capability other than content.access.request is listed too, but only an approver can decide it.

Each row has decidable_by_caller. Decide with POST /admin/requests/{id}/decide. Page with limit and offset; requests made at the same moment have no fixed order between pages, and total is counted separately, so it can differ from the rows if requests change in between.

limit
integer
default: 50 >= 1 <= 200
offset
integer
0

How many requests to skip, for paging. Defaults to 0.

Pending requests about your assets and the items you deleted.

object
items
required
Array<object>

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
total
required

How many requests are in this queue, counted separately from items.

integer format: int64

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"
}