Core Concepts

Before diving into implementation, you need to understand the fundamental building blocks of ActivityPub. Everything in the protocol revolves around four core concepts: Actors, Activities, Objects, and Collections.

The ActivityPub Model

Actors

An Actor is any entity that can perform activities. In social networking terms, actors are typically users, but they can also be bots, organizations, or services.

Actor Types

Type	Description	Example
Person	A human user	@alice@example.com
Organization	A company or group	@acme-corp@example.com
Application	A software application	Mastodon's server-wide "instance actor"
Service	A service of any kind	@weather-bot@example.com — Mastodon publishes bot accounts as Service
Group	A shared actor for communities	@developers@example.com

Actor Properties

Every actor has these essential properties:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1"
  ],
  "type": "Person",
  "id": "https://example.com/users/alice",
  "inbox": "https://example.com/users/alice/inbox",
  "outbox": "https://example.com/users/alice/outbox",
  "followers": "https://example.com/users/alice/followers",
  "following": "https://example.com/users/alice/following",
  "preferredUsername": "alice",
  "name": "Alice Smith",
  "summary": "Software developer and Fediverse enthusiast",
  "publicKey": {
    "id": "https://example.com/users/alice#main-key",
    "owner": "https://example.com/users/alice",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n..."
  }
}

Actor Endpoints

ActivityPub §4.1 says actors MUST have inbox and outbox, SHOULD have followers and following, and MAY have liked.

Endpoint	Requirement	Purpose
inbox	MUST	Receives incoming activities from other servers
outbox	MUST	Contains activities performed by this actor
followers	SHOULD	Collection of actors following this actor
following	SHOULD	Collection of actors this actor follows
liked	MAY	Collection of objects this actor has liked

In practice, Mastodon rejects an actor that has neither preferredUsername nor a FEP-2c59 webfinger property (fetch_remote_actor_service.rb), and it needs a public key to verify your signed requests.

Activities

An Activity represents an action. When an actor does something — posts a message, follows someone, likes a post — that action is represented as an Activity.

Common Activity Types

Activity	Description	Example
Create	Create new content	Posting a new status
Update	Modify existing content	Editing a post
Delete	Remove content	Deleting a post
Follow	Subscribe to an actor	Following a user
Accept	Accept a request	Accepting a follow request
Reject	Reject a request	Rejecting a follow request
Like	Express appreciation	Liking a post
Announce	Share content	Boosting/reblogging
Undo	Reverse an activity	Unfollowing, unliking

Activity Structure

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "id": "https://example.com/activities/1",
  "actor": "https://example.com/users/alice",
  "object": {
    "type": "Note",
    "id": "https://example.com/notes/1",
    "content": "Hello, Fediverse!"
  },
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://example.com/users/alice/followers"]
}

Activity Properties

Property	Required	Description
id	Yes, except for transient activities (AP §3.1)	Globally unique URL
type	Yes	The type of activity
actor	Yes in practice — servers reject activities without one	Who performed the activity
object	Usually	The target of the activity
to	No	Primary recipients
cc	No	Secondary recipients
bto	No	Private primary recipients
bcc	No	Private secondary recipients

Objects

An Object represents content or things that activities act upon. The most common objects are content types like notes, articles, and images.

Common Object Types

Type	Description	Use Case
Note	Short text content	Mastodon statuses, tweets
Article	Long-form content	Blog posts
Image	Image content	Photos
Video	Video content	Video posts
Audio	Audio content	Podcasts, music
Document	Generic file	Attachments
Event	Calendar event	Meetups, events
Place	Location	Check-ins

Object Structure

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Note",
  "id": "https://example.com/notes/1",
  "attributedTo": "https://example.com/users/alice",
  "content": "Hello, Fediverse!",
  "published": "2024-01-15T10:30:00Z",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://example.com/users/alice/followers"]
}

Important Object Properties

Property	Description
id	Unique identifier (URL)
type	The object type
attributedTo	The creator/author
content	The main content (HTML)
published	When it was created
updated	When it was last modified
inReplyTo	Parent object (for replies)
attachment	Media attachments
tag	Hashtags, mentions

Collections

A Collection is an ordered or unordered set of objects or activities. Collections are used for inboxes, outboxes, followers lists, and more.

Collection Types

Type	Description
Collection	Unordered set
OrderedCollection	Ordered set. ActivityPub requires inbox and outbox to be in reverse chronological order (§5.1, §5.2)
CollectionPage	A page within a collection
OrderedCollectionPage	An ordered page

Collection Structure

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "OrderedCollection",
  "id": "https://example.com/users/alice/outbox",
  "totalItems": 42,
  "first": "https://example.com/users/alice/outbox?page=1",
  "last": "https://example.com/users/alice/outbox?page=3"
}

Collection Page

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "OrderedCollectionPage",
  "id": "https://example.com/users/alice/outbox?page=1",
  "partOf": "https://example.com/users/alice/outbox",
  "next": "https://example.com/users/alice/outbox?page=2",
  "orderedItems": [
    { "type": "Create", "..." : "..." },
    { "type": "Announce", "..." : "..." }
  ]
}

Addressing and Visibility

ActivityPub uses to, cc, bto, and bcc properties to control who sees content.

Special Addresses

Address	Meaning
https://www.w3.org/ns/activitystreams#Public	Visible to everyone (also written as:Public or Public)
The actor's followers collection	Visible to followers

Only the Public collection is truly special. The followers collection is just the IRI in the actor's followers property — read it from the actor rather than assuming it's {actor}/followers.

Visibility Examples

Public post:

{
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://example.com/users/alice/followers"]
}

Followers-only post:

{
  "to": ["https://example.com/users/alice/followers"],
  "cc": []
}

Direct message:

{
  "to": ["https://other.example/users/bob"],
  "cc": [],
  "tag": [
    {
      "type": "Mention",
      "href": "https://other.example/users/bob",
      "name": "@bob@other.example"
    }
  ]
}

Include a Mention tag for every addressed actor. If Mastodon receives a non-public post addressed to someone who isn't tagged, it records a silent mention and downgrades the post from direct to limited (create.rb).

JSON-LD Context

ActivityPub uses JSON-LD for extensibility. The @context tells parsers how to interpret the JSON.

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {
      "toot": "http://joinmastodon.org/ns#",
      "sensitive": "as:sensitive"
    }
  ]
}

tip

You can extend ActivityStreams with custom properties by adding them to the context. This is how Mastodon adds features like the sensitive media flag and custom emoji. (The content-warning text itself goes in the standard summary property.)

Next Steps

Now that you understand the core concepts:

1. Your First ActivityPub Server - Put these concepts into practice
2. ActivityStreams Reference - Complete vocabulary reference
3. Object Types Reference - All object types with examples