====== Actor ======

**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 [[:objects|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 ([[:x-pawpub-actor|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.

<WRAP center round info 60%>
**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
</WRAP>


<WRAP center round todo 60%>
todo: document all of these different endpoints
</WRAP>


===== 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 =====

<code javascript>
{
    "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!"
    }
}
</code>