Skip to content

Ask for access to an asset

POST
/assets/{id}/request-access

Files a request about an asset. It’s listed in the pending queue at GET /admin/requests, and if the asset exists and isn’t deleted, its owner also sees it in GET /account/requests/incoming.

Leave out capability, as the web app does, and the request names content.access.request. Approving that records that your request was accepted; it doesn’t unlock the asset, because nothing can yet grant access to a single item. Name any other capability instead and an approval grants it to you across the whole instance; only holders of share.grant or system.admin can decide those.

The asset isn’t checked: any id is accepted, whether or not the asset exists, is visible to you, or is already yours. An unknown capability gets a 400, and so does content.restore.request; to ask for a deleted item back, use POST /account/trash/{kind}/{id}/request-restore.

If you already have the same request pending, you get 200 with it unchanged, and a new reason isn’t saved. Otherwise you get 201. Once a request has been decided you can ask again. Your reason is shown to whoever reviews the request and kept in the audit log. The asset’s owner and the approvers are notified without it; notifications and the audit entry are best effort.

id
required
string format: uuid
object
capability

What you’re asking for. Leave it out to ask about this asset with content.access.request, which unlocks nothing on its own.

Any other capability code is a request for that capability across the whole instance. The asset’s owner can’t decide it; only holders of share.grant or system.admin can.

string
reason

Why you’re asking. Optional. Whoever reviews the request sees it, and it’s kept in the audit log.

string
<= 1000 characters

You already had this request pending. It’s 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

Request filed.

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