--- title: ActivityPub description: A decentralized social networking protocol based upon the ActivityStreams 2.0 data format and JSON-LD. menu: docs: weight: 10 parent: spec --- {{< hint style="warning" >}} Sample payloads will be added at a future date. {{< /hint >}} ## Status federation {#status} {{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/activitypub/activity.rb" caption="app/lib/activitypub/activity.rb" >}} ### Supported activities for statuses Create : Transformed into a status and saved into database Delete : Removes a status from the database Like : Transformed into a favourite on a status Announce : Transformed into a boost on a status Flag : Transformed into a report to the moderation team. Update : Refresh vote count on polls. As of Mastodon 3.5.0, can be used to edit statuses when the `updated` timestamp is present. Undo : Undo a previous Like or Announce. ### Payloads The first-class Object types supported by Mastodon are `Note` and `Question`. - Notes are transformed into regular statuses. - Questions are transformed into a poll status. Some other Object types are converted as best as possible: - Article - Page - Image - Audio - Video - Event The transformer uses `content` if available, or `name` if not, in order to generate status text. The `url` will be appended. The `summary` property will be used as the CW text. The `icon` will be used as a thumbnail. ### Properties used content : Used as status text name : Used as status text, if `content` is not provided on a transformed Object type summary : Used as CW text sensitive : Used to determine whether status media or text should be hidden by default inReplyTo : Used for threading a status as a reply to another status published : Used as status date url : Used for status permalinks, and also appended to status text for transformed Objects attributedTo : Used to determine the profile which authored the status updated : Used to display the "last edited at" timestamp in the UI to indicate to the user that a status has been edited. Required before an Update activity will be processed. To prevent against race conditions, Mastodon will only process Update payloads with an `updated` timestamp greater than the currently known last `updated` time. to/cc : Used to determine audience and visibility of a status. - Public statuses have the `as:Public` magic collection in `to` - Unlisted statuses have the `as:Public` magic collection in `cc` - Followers-only statuses have an actor's follower collection in `to` or `cc`, but do not include the `as:Public` magic collection - Private statuses have actors in `to` or `cc`, at least one of which is not `Mention`ed in `tag` - Direct statuses have actors in `to` or `cc`, all of which are `Mention`ed in `tag` tag : Used to mark up mentions and hashtags. tag[].type : Either `Mention` or `Hashtag` is currently supported tag[].name : The plain-text Webfinger address of a profile Mention (`@user` or `@user@domain`), or the plain-text Hashtag (`#tag`) tag[].href : The URL of the actor or tag attachment : Used to include attached images, videos, or audio. attachment[].url : Used to fetch the media attachment attachment[].summary : Used as media description attachment[].blurhash : Used to generate a blurred preview image corresponding to the colors used within the image. See [Blurhash](#blurhash) for more details. replies : A Collection of statuses that are in reply to the current status. Up to 5 replies from the same server will be fetched upon discovery of a remote status, in order to resolve threads more fully. On Mastodon's side, the first page contains self-replies, and additional pages contain replies from other people. #### Poll-specific properties endTime : The timestamp for when voting will close on the poll closed : The timestamp for when voting closed on the poll. The timestamp will likely match the `endTime` timestamp. If this property is present, the poll is assumed to be closed. votersCount : How many people have voted in the poll. Distinct from how many votes have been cast (in the case of multiple-choice polls) oneOf : Single-choice poll options anyOf : Multiple-choice poll options oneOf/anyOf[].name : The poll option's text oneOf/anyOf[].replies.totalItems : The poll option's vote count ## Profile federation {#profile} ### Supported activities for profiles Follow : Indicate interest in receiving status updates from a profile. Accept/Reject : Used to approve or deny Follow activities. Unlocked accounts will automatically reply with an Accept, while locked accounts can manually choose whether to approve or deny a follow request. Add/Remove : Manage pinned posts and featured collections. Block : Signal to a remote server that they should hide your profile from that user. Not guaranteed. Flag : Report user Update : Refresh account details Move : Migrate followers from one account to another. Requires alsoKnownAs to be set in both directions. Delete : Remove an account from the database, as well as all of their statuses. Undo : Undo a previous Follow, Accept Follow, or Block. ### Properties used preferredUsername : Used for Webfinger lookup. Must be unique on the domain, and must correspond to a Webfinger `acct:` URI. name : Used as profile display name. summary : Used as profile bio. type : Assumed to be Person. If type is Application or Service, it will be interpreted as a bot flag. url : Used as profile link. icon : Used as profile avatar. image : Used as profile header. manuallyApprovesFollowers : Will be shown as a locked account. discoverable : Will be shown in the profile directory. See [Discoverability flag](#discoverable). publicKey : Required for signatures. See [Public key](#publicKey). featured : Pinned posts. See [Featured collection](#featured). attachment : Used for profile fields. See [Profile metadata](#PropertyValue) and [Identity proofs](#IdentityProof). alsoKnownAs : Required for Move activity. published : When the profile was created. ## HTML sanitization {#sanitization} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/sanitize_ext/sanitize_config.rb" caption="lib/sanitize_ext/sanitize_config.rb" >}} Mastodon sanitizes incoming HTML in order to not break assumptions for API client developers. Supported elements include `
`, ``, ` `.The sanitizer will keep classes if they begin with microformats prefixes or are semantic classes:
- h-*
- p-*
- u-*
- dt-*
- e-*
- mention
- hashtag
- ellipsis
- invisible
## JSON-LD Namespacing {#namespaces}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/app/lib/activitypub/adapter.rb" caption="app/lib/activitypub/adapter.rb" >}}
### Mastodon extensions (`toot:`) {#toot}
Contains definitions for Mastodon features.
- toot:Emoji
- toot:IdentityProof
- toot:blurhash
- toot:focalPoint
- toot:featured
- toot:featuredTags
- toot:discoverable
- toot:suspended
- toot:votersCount
### ActivityStreams extensions (`as:`) {#as}
Contains ActivityStreams extended properties that have been proposed but not officially adopted yet.
- as:Hashtag
- as:alsoKnownAs
- as:manuallyApprovesFollowers
- as:movedTo
- as:sensitive
### W3ID Security Vocabulary (`sec:`) {#sec}
Contains properties used for HTTPS Signatures and Linked Data Signatures. Also used for identity proofs. See [Security]({{< relref "spec/security" >}}) for more information.
- sec:publicKey
- sec:publicKeyPem
- sec:owner
- sec:signature
- sec:signatureValue
#### W3ID Identity
Contains a collection of terms from various namespaces, used for Linked Data Signatures.
- dc:creator
- dc:created
- sec:signature
- sec:signatureValue
### schema.org extensions (`schema:`) {#schema}
Contains properties used for profile metadata.
- schema:PropertyValue
- schema:value
## Extensions
### Public key {#publicKey}
Public keys are used for HTTPS Signatures and Linked Data Signatures. This is implemented using an extra property `publicKey` on actor objects. See [Security]({{< relref "spec/security" >}}) for more information. Example:
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://w3id.org/security/v1"
],
"id": "https://mastodon.social/users/Gargron",
"type": "Person",
"publicKey": {
"id": "https://mastodon.social/users/Gargron#main-key",
"owner": "https://mastodon.social/users/Gargron",
"publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvXc4vkECU2/CeuSo1wtn\nFoim94Ne1jBMYxTZ9wm2YTdJq1oiZKif06I2fOqDzY/4q/S9uccrE9Bkajv1dnkO\nVm31QjWlhVpSKynVxEWjVBO5Ienue8gND0xvHIuXf87o61poqjEoepvsQFElA5ym\novljWGSA/jpj7ozygUZhCXtaS2W5AD5tnBQUpcO0lhItYPYTjnmzcc4y2NbJV8hz\n2s2G8qKv8fyimE23gY1XrPJg+cRF+g4PqFXujjlJ7MihD9oqtLGxbu7o1cifTn3x\nBfIdPythWu5b4cujNsB3m3awJjVmx+MHQ9SugkSIYXV0Ina77cTNS0M2PYiH1PFR\nTwIDAQAB\n-----END PUBLIC KEY-----\n"
}
}
```
### Featured collection {#featured}
What is known in Mastodon as “pinned statuses”, or statuses that are always featured at the top of people’s profiles, is implemented using an extra property `featured` on the actor object that points to a `Collection` of objects. Example:
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"toot": "http://joinmastodon.org/ns#",
"featured": {
"@id": "toot:featured",
"@type": "@id"
}
}
],
"id": "https://example.com/@alice",
"type": "Person",
"featured": "https://example.com/@alice/collections/featured"
}
```
### Featured tags {#featuredTags}
Mastodon allows users to feature specific hashtags on their profile for easy browsing, as a discoverability mechanism. This is implemented using an extra property `featuredTags` on the actor object that points to a `Collection` of `Hashtag` objects specifically.
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"toot": "http://joinmastodon.org/ns#",
"featuredTags": {
"@id": "toot:featuredTags",
"@type": "@id"
}
}
],
"id": "https://example.com/@alice",
"type": "Person",
"featuredTags": "https://example.com/@alice/collections/tags"
}
```
### Custom emojis {#emoji}
Mastodon supports arbitrary emojis, that is, small images uploaded by admins and invokable via shortcodes. For this, an `Emoji` type is used. These emojis are listed in the `tag` property just like `Mention` and `Hashtag` objects, since they are entities that affect how the text is rendered. Example:
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"toot": "http://joinmastodon.org/ns#",
"Emoji": "toot:Emoji"
}
],
"id": "https://example.com/@alice/hello-world",
"type": "Note",
"content": "Hello world :kappa:",
"tag": [
{
"id": "https://example.com/emoji/123",
"type": "Emoji",
"name": ":kappa:",
"icon": {
"type": "Image",
"mediaType": "image/png",
"url": "https://example.com/files/kappa.png"
}
}
]
}
```
### Focal points {#focalPoint}
Mastodon supports setting a focal point on uploaded images, so that wherever that image is displayed, the focal point stays in view. This is implemented using an extra property `focalPoint` on `Image` objects. The property is an array of two floating points between -1.0 and 1.0, with 0,0 being the center of the image, the first value being x (-1.0 is the left edge, +1.0 is the right edge) and the second value being y (-1.0 is the bottom edge, +1.0 is the top edge). See [API Guidelines > Focal points]({{< relref "api/guidelines#focal-points" >}}) for more information. Example:
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"toot": "http://joinmastodon.org/ns#",
"focalPoint": {
"@container": "@list",
"@id": "toot:focalPoint"
}
}
],
"id": "https://example.com/@alice/hello-world",
"type": "Note",
"content": "A picture attached!",
"attachment": [
{
"type": "Image",
"mediaType": "image/png",
"url": "https://example.com/files/cats.png",
"focalPoint": [
-0.55,
0.43
]
}
]
}
```
{{< figure src="assets/focal-points.jpg" caption="A demonstration of various focal points and their coordinates." >}}
The focal point of (-0.55, 0.43) in the example above corresponds to a point 55% to the left of center and 43% above center. This focal point should remain visible within the cropped thumbnail, if any cropping is done.
### Blurhash {#blurhash}
Mastodon generates colorful preview thumbnails for attachments. This is implemented using an extra property `blurhash` on `Image` objects. The property is a string generated by the [BlurHash algorithm](https://blurha.sh). Example:
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"toot": "http://joinmastodon.org/ns#",
"blurhash": "toot:blurhash"
}
],
"id": "https://example.com/@alice/hello-world",
"type": "Note",
"content": "A picture attached!",
"attachment": [
{
"type": "Image",
"mediaType": "image/png",
"url": "https://example.com/files/cats.png",
"blurhash": "UBL_:rOpGG-oBUNG,qRj2so|=eE1w^n4S5NH"
}
]
}
```
### Profile metadata {#PropertyValue}
Mastodon supports arbitrary profile fields containing name-value pairs. This is implemented using the `attachment` property on actor objects, with objects in the array having a type of `PropertyValue` and a `value` property, both from the schema.org namespace. Example:
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"PropertyValue": "schema:PropertyValue",
"value": "schema:value"
}
],
"id": "https://mastodon.social/users/Gargron",
"type": "Person",
"attachment": [
{
"type": "PropertyValue",
"name": "Patreon",
"value": "https://www.patreon.com/mastodonhttps://zeonfederated.com}}
This property is currently unused/deprecated due to the removal of Keybase support in Mastodon 3.5:
`, and ``. Unsupported elements will be converted to `