This is an old revision of the document!

Actors

Actors represent an entity that can “do something” (e.g. a person, creature, automated service, etc.) and are one of the 5 types of pushable object.

Endpoints

Actors have a set of “endpoints”, which are used as a way to “do something” to that actor. For example, sending an authenticated POST request to the follow endpoint (on behalf of another actor) will notify the remote instance that your actor is now following the remote actor, or if the remote actor has requestToFollow set, that a follow request was sent. The exceptions to this are the feed endpoints, which should be GET-requested, and will return a list of objects published by the actor.

Note about the follow endpoint: it should return a single word, active or pending, representing whether the follow was immediately accepted or if it's waiting to be approved. If for whatever reason the remote server doesn't do that, you can guess based on whether the actor has requestToFollow set (pending) or not (active), but this could lead to desynchronisation issues in certain cases

todo: document all of these different endpoints

Schema

type: “actor”
self: uri(actor) required
created: timestamp required
modified: timestamp optional
homepage: uri optional
handle: string required [can be anything at all]
displayName: string required
avatar: uri optional
bio: string optional
pronouns: string optional
automated: boolean optional default=false
requestToFollow: boolean optional default=false
endpoints: object required
- basicFeed: uri(pagination(uri(any))) required
- fullFeed: uri(pagination(any)) optional
- filteredFeed: uri(pagination(any)) optional
- follow: uri optional
- unfollow: uri optional [if follow is present, unfollow must also be present]
- acceptedFollow: uri optional
- rejectedFollow: uri optional [if acceptedFollow is present, rejectedFollow must also be present]
- block: uri optional
- unblock: uri optional [if block is present, unblock must also be present]
extensions: object optional default={}
- (uri): any many

Example

{
    "type": "actor",
    "self": "https://social.example/user/winter",
    "created": "2025-01-01T09:00:00Z",
    "homepage": "https://social.example/@winter",
    "handle": "winter",
    "displayName": "winter the eternal",
    "avatar": "https://social.example/upload/1423.png",
    "bio": "hi i'm winter!!\n\nmeow",
    "pronouns": "it/she",
    "requestToFollow": true,
    "endpoints": {
        "basicFeed": "https://social.example/user/winter/feed",
        "follow": "https://social.example/user/winter/rpc/follow",
        "unfollow": "https://social.example/user/winter/rpc/unfollow",
        "acceptedFollow": "https://social.example/user/winter/rpc/accepted",
        "rejectedFollow": "https://social.example/user/winter/rpc/rejected"
    },
    "extensions": {
        "https://example.org/extension/bloop": "bloop!"
    }
}

PawPub

Table of Contents

Actors

Endpoints

Schema

Example