Skip to content

Share an object with a peer

POST
/admin/federation/shares

Shares a post, asset or collection on your instance with a paired peer, or with one user on that peer. The share is recorded locally and the object itself isn’t sent.

You can share objects you own; with system.admin you can share any object, and the server doesn’t check that it exists. The share is in your name either way, which decides who can revoke it. The peer must be enabled and connected.

The share, an aa:Share activity and a federation.share.granted audit event are saved in one transaction. The activity reaches the outbox only when the object is a post with explicit-share visibility, and is then queued for the peers that post is shared with (see GET /admin/federation/outbox). As shipped, the outbox keeps each post’s recipients in memory and doesn’t update them when shares change, so a new share may not reach the outbox until the app restarts.

Remote instances do not act on shares yet: today only likes and comments take effect between paired instances (see the ArchivePub overview, “What works today”).

You can’t grant the same object to the same peer and user twice while your earlier share is unrevoked, even if it has expired: you get 409. The 409 body shows an unexpired share of this object for that peer, but it may not be yours or the one that caused the conflict: it can be someone else’s share, including their notes. If the server finds none, for example because your share has expired, every field is empty or zero.

object
object_kind
required

The kind of object to share. Ownership is checked only for post, asset and collection, so the other kinds can be shared only by an admin.

string
Allowed values: asset post collection workspace brand_kit
object_id
required
string format: uuid
peer_id
required
string format: uuid
target_user_url

The actor URL of one user on the peer, to share with only that user. Leave it out, or send an empty string, to share with the whole peer. It’s optional for every object, including restricted and embargoed ones. Only deliveries to a named user can be encrypted, and only if the peer supports encryption and that user’s key is known.

string
scope
required

How much the peer may do with the object, from view up to remix. It’s stored with the share; remote instances don’t act on it yet.

string
Allowed values: view comment annotate remix
expires_at

When the share should end. The expiry job revokes it after that time, checking when the app starts and then every hour. Leave it out for a share that doesn’t expire.

string format: date-time
nullable
notes

A note about the share for your admins. As shipped, it’s also copied into the aa:Share activity, so it reaches the peer if that activity is delivered. Don’t put anything here you wouldn’t show the peer.

string
<= 2000 characters

The saved share.

One share: an object on your instance shared with a paired peer, or with one user on it. Pairing alone shares nothing; each share covers one object. Remote instances don’t act on shares yet.

object
id
required
string format: uuid
grantor_user_ref
required

The user who granted the share. Only they, or someone with system.admin, can revoke it.

integer format: int64
object_kind
required
string
Allowed values: asset post collection workspace brand_kit user
object_id
required
string format: uuid
peer_id
required
string format: uuid
target_user_url

The one user on the peer this share is for. Left out when it’s for the whole peer.

string
nullable
scope
required
string
Allowed values: view comment annotate remix
expires_at

When the share is set to end. It stays unrevoked after this until the expiry job revokes it.

string format: date-time
nullable
notes
required
string
granted_activity_id
required

The aa:Share activity recorded with the grant.

string format: uuid
granted_at
required
string format: date-time
revoked_at

When the share was revoked, by a user or by the expiry job. Left out until then.

string format: date-time
nullable
revoked_activity_id

The aa:Unshare activity recorded when it was revoked.

string format: uuid
nullable
created_at
required
string format: date-time
updated_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"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

No peer with that peer_id.

object
error
required

Human-readable error summary

string
Example
the request could not be completed

You already have an unrevoked share of this object for this peer and user.

One share: an object on your instance shared with a paired peer, or with one user on it. Pairing alone shares nothing; each share covers one object. Remote instances don’t act on shares yet.

object
id
required
string format: uuid
grantor_user_ref
required

The user who granted the share. Only they, or someone with system.admin, can revoke it.

integer format: int64
object_kind
required
string
Allowed values: asset post collection workspace brand_kit user
object_id
required
string format: uuid
peer_id
required
string format: uuid
target_user_url

The one user on the peer this share is for. Left out when it’s for the whole peer.

string
nullable
scope
required
string
Allowed values: view comment annotate remix
expires_at

When the share is set to end. It stays unrevoked after this until the expiry job revokes it.

string format: date-time
nullable
notes
required
string
granted_activity_id
required

The aa:Share activity recorded with the grant.

string format: uuid
granted_at
required
string format: date-time
revoked_at

When the share was revoked, by a user or by the expiry job. Left out until then.

string format: date-time
nullable
revoked_activity_id

The aa:Unshare activity recorded when it was revoked.

string format: uuid
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time