Skip to content

Share a post with a user

POST
/posts/{id}/acls

Shares a post with one user by storing a grant on it. While the grant hasn’t expired, that user can read the post whatever its visibility, and its pictures keep their own access rules. 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, and other users can read it once it’s published.

You need to be signed in. Only the post’s author and holders of posts.admin or system.admin granted globally can share it; holding posts.admin only for the post’s team lets you list and remove grants but not add them (403). A post that doesn’t exist or is deleted is 404. A body that isn’t valid JSON is refused with 400 before any of these checks.

principal_type must be user: role and team are refused with 400 because they give no access on posts. principal_id is the user’s numeric ref in plain digits; a username, zero, a negative or non-numeric value is refused with 400. The account isn’t looked up, and a ref written with leading zeros or a plus sign is accepted but stored as written, so it gives no access.

read, write and admin all give the same thing here: the right to read the post. None of them lets the user edit the post or manage its grants. An unknown or missing permission isn’t refused with 400; the database rejects it and the answer is 500. Without expires_at the grant doesn’t expire. A time that has already passed is accepted and stored, but the grant gives no access.

Each user and level is one grant. Sending the same user and level again replaces its expiry (leaving expires_at out makes it permanent) and records you and the current time as its latest grant; a different level is a separate grant. When two requests change the same grant at once, the one saved last stands.

After the grant is saved, and again on each repeat, the server tries to send the user an in-app notification. None is sent when you share with yourself, when either of you has blocked the other, or when their settings don’t include in-app notices for shares, and a failure is only logged. The grant stands either way, and share notifications aren’t sent by email.

id
required
string format: uuid

The post’s id.

object
principal_type
required
string
Allowed values: user role team
principal_id
required

Who the grant is for, by reference rather than name: for user, the account’s numeric ref in plain digits; for role or team, its UUID in lowercase.

The value is stored exactly as sent and compared as written, so a ref with leading zeros or a plus sign is accepted but matches no one. Each route’s description says which principal types it accepts.

string
<= 64 characters /^([0-9]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/
permission
required
string
Allowed values: read write admin
expires_at

When the grant should stop giving access. Leave it out or send null for a grant that doesn’t expire. A time that has already passed is accepted, but the grant gives no access.

string format: date-time
nullable

The grant was saved, or an existing grant for the same user and level was updated.

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

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