Skip to content

List who a post is shared with

GET
/posts/{id}/acls

Lists every sharing grant stored on a post: who it names, the level, when it was last granted and by whom, and when it expires.

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 see the list. Being able to read the post, or having it shared with you, isn’t enough. Others get 403; a post that doesn’t exist or is deleted is 404.

Every stored grant is listed, including expired ones and old role or team grants, which give no access, most recently granted first, with no paging. Only a user grant that hasn’t expired lets someone read the post, and the level makes no difference. Sharing doesn’t publish a draft: while the post is a draft, a grant can let in only a holder of posts.admin or system.admin granted globally.

id
required
string format: uuid

The post’s id.

The grants stored on the post.

Array<object>
object
principal_type
required
string
Allowed values: user role team
principal_id
required

Who the grant is for, as stored: a user’s numeric ref, or a role’s or team’s UUID.

string
<= 64 characters
permission
required
string
Allowed values: read write admin
granted_at
required

When the grant was last written. Granting the same principal and level again resets it.

string format: date-time
granted_by_user_ref

The ref of the account that last wrote the grant, or null if none is recorded.

integer format: int64
nullable
expires_at

When the grant stops giving access, or null if it doesn’t expire. A grant whose time has been reached is still stored and listed, but gives no access.

string format: date-time
nullable

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