Skip to content

Remove one sharing grant from a post

DELETE
/posts/{id}/acls/{principal_type}/{principal_id}/{permission}

Removes one grant from a post: the one with exactly this principal type, principal id and level. Other grants, including other levels for the same user, stay.

You need to be signed in. The post’s author, holders of posts.admin or system.admin granted globally, and holders of posts.admin for the post’s team can remove grants. Others get 403; a post that doesn’t exist or is deleted is 404. When no grant matches exactly, the answer is 404, including on a second request.

The path values are matched as stored rather than checked, so an expired grant or an old role or team grant can be removed this way, and a user ref must be written as it was stored: 1 doesn’t remove a grant stored as 001.

Removing a grant takes away only what that grant gave. The user can still read the post if its visibility or another rule lets them, and anything they already downloaded stays with them. They aren’t notified.

id
required
string format: uuid

The post’s id.

principal_type
required
string
Allowed values: user role team

The principal type of the grant to remove, as listed.

principal_id
required
string
<= 64 characters

The principal id of the grant to remove, exactly as listed.

permission
required
string
Allowed values: read write admin

The level of the grant to remove, as listed.

The grant was removed.

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

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed