openapi: 3.1.0
info:
  title: ActivityPub Actors Inbox API
  version: 1.0.0
  description: ActivityPub is a W3C Recommendation (https://www.w3.org/TR/activitypub/) that defines a decentralized social networking protocol. It specifies both a client-to-server API for creating and managing social content and a server-to-server federation protocol for distributing activities across instances. Built on ActivityStreams 2.0 and JSON-LD, ActivityPub powers the Fediverse — Mastodon, Pixelfed, PeerTube, and hundreds of other platforms — enabling interoperable social networking across independently operated servers.
  contact:
    name: W3C Social Web Working Group
    url: https://www.w3.org/wiki/Socialwg
  license:
    name: W3C Document License
    url: https://www.w3.org/Consortium/Legal/2015/doc-license
  externalDocs:
    description: ActivityPub W3C Recommendation
    url: https://www.w3.org/TR/activitypub/
servers:
- url: https://{domain}
  description: ActivityPub server (replace with your instance domain)
  variables:
    domain:
      default: social.example
      description: The domain of the ActivityPub server
tags:
- name: Inbox
  description: Receive and read activities delivered to an actor
paths:
  /users/{username}/inbox:
    get:
      operationId: getInbox
      summary: Read actor inbox
      description: Returns the actor's inbox as an OrderedCollection of received activities. Requires authentication. The server SHOULD filter the inbox contents based on the authenticated actor's access rights.
      tags:
      - Inbox
      security:
      - BearerAuth: []
      - HTTPSignature: []
      parameters:
      - name: username
        in: path
        required: true
        description: The local username of the actor
        schema:
          type: string
          example: alyssa
      - name: page
        in: query
        required: false
        description: Page token or number for pagination
        schema:
          type: string
      responses:
        '200':
          description: Inbox as OrderedCollection
          content:
            application/activity+json:
              schema:
                $ref: '#/components/schemas/OrderedCollection'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/OrderedCollection'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: postToInbox
      summary: Deliver activity to actor inbox (server-to-server)
      description: Used by remote servers to deliver activities to this actor's inbox as part of server-to-server federation. The posting server MUST authenticate the request using HTTP Signatures. The receiving server MUST validate the signature and deduplicate activities.
      tags:
      - Inbox
      security:
      - HTTPSignature: []
      parameters:
      - name: username
        in: path
        required: true
        description: The local username of the actor
        schema:
          type: string
          example: alyssa
      requestBody:
        required: true
        content:
          application/activity+json:
            schema:
              $ref: '#/components/schemas/Activity'
          application/ld+json:
            schema:
              $ref: '#/components/schemas/Activity'
      responses:
        '200':
          description: Activity accepted
        '201':
          description: Activity created and accepted
        '400':
          description: Bad request or invalid activity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - missing or invalid HTTP Signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Collection:
      type: object
      description: An ActivityStreams 2.0 Collection of Objects or Links
      required:
      - type
      - id
      properties:
        '@context':
          $ref: '#/components/schemas/ASContext'
        id:
          type: string
          format: uri
          description: IRI of the collection
        type:
          type: string
          enum:
          - Collection
          - OrderedCollection
          example: Collection
        totalItems:
          type: integer
          description: Total number of items in the collection
          example: 42
        current:
          type: string
          format: uri
          description: IRI of the most recent page
        first:
          type: string
          format: uri
          description: IRI of the first page
        last:
          type: string
          format: uri
          description: IRI of the last page
        items:
          type: array
          description: Items in the collection (unordered)
          items:
            oneOf:
            - type: string
              format: uri
            - $ref: '#/components/schemas/ASObject'
            - $ref: '#/components/schemas/Activity'
    Activity:
      type: object
      description: 'An ActivityStreams 2.0 Activity describing an action performed by an actor. Common activity types: Create, Update, Delete, Follow, Accept, Reject, Announce, Like, Dislike, Undo, Block, Add, Remove, Flag.'
      required:
      - '@context'
      - type
      - actor
      properties:
        '@context':
          $ref: '#/components/schemas/ASContext'
        id:
          type: string
          format: uri
          description: Globally unique IRI identifying the activity (assigned by server)
          example: https://social.example/users/alyssa/activities/12345
        type:
          type: string
          description: The activity type
          enum:
          - Accept
          - Add
          - Announce
          - Arrive
          - Block
          - Create
          - Delete
          - Dislike
          - Flag
          - Follow
          - Ignore
          - Invite
          - Join
          - Leave
          - Like
          - Listen
          - Move
          - Offer
          - Question
          - Read
          - Reject
          - Remove
          - TentativeAccept
          - TentativeReject
          - Travel
          - Undo
          - Update
          - View
          example: Create
        actor:
          description: The actor performing the activity (IRI or Actor object)
          oneOf:
          - type: string
            format: uri
          - $ref: '#/components/schemas/Actor'
        object:
          description: The object upon which the activity is performed
          oneOf:
          - type: string
            format: uri
          - $ref: '#/components/schemas/ASObject'
        target:
          description: The indirect object or target of the activity
          oneOf:
          - type: string
            format: uri
          - $ref: '#/components/schemas/ASObject'
        to:
          description: Primary audience (public, followers, specific actors)
          oneOf:
          - type: string
            format: uri
          - type: array
            items:
              type: string
              format: uri
        cc:
          description: Secondary (carbon copy) audience
          oneOf:
          - type: string
            format: uri
          - type: array
            items:
              type: string
              format: uri
        bto:
          description: Private primary audience (stripped before delivery)
          oneOf:
          - type: string
            format: uri
          - type: array
            items:
              type: string
              format: uri
        bcc:
          description: Private secondary audience (stripped before delivery)
          oneOf:
          - type: string
            format: uri
          - type: array
            items:
              type: string
              format: uri
        published:
          type: string
          format: date-time
          description: When the activity occurred
        summary:
          type: string
          description: Short summary or content warning
        result:
          description: The result or output of the activity
          oneOf:
          - type: string
            format: uri
          - $ref: '#/components/schemas/ASObject'
        origin:
          description: The source of the activity (e.g., for Move)
          oneOf:
          - type: string
            format: uri
          - $ref: '#/components/schemas/ASObject'
        instrument:
          description: Tool or instrument used to perform the activity
          oneOf:
          - type: string
            format: uri
          - $ref: '#/components/schemas/ASObject'
    Link:
      type: object
      description: An ActivityStreams 2.0 Link, a qualified reference to another resource
      required:
      - type
      - href
      properties:
        type:
          type: string
          enum:
          - Link
          - Mention
          example: Mention
        href:
          type: string
          format: uri
          description: Target IRI of the link
        name:
          type: string
          description: Display name for the link
        mediaType:
          type: string
          description: MIME type of the target resource
        hreflang:
          type: string
          description: Language of the target resource (BCP 47)
        rel:
          description: Link relation type(s)
          oneOf:
          - type: string
          - type: array
            items:
              type: string
    ImageObject:
      type: object
      description: An ActivityStreams 2.0 Image object
      properties:
        type:
          type: string
          enum:
          - Image
        url:
          type: string
          format: uri
        mediaType:
          type: string
          example: image/jpeg
        width:
          type: integer
        height:
          type: integer
    OrderedCollection:
      type: object
      description: An ActivityStreams 2.0 OrderedCollection with temporally ordered items
      required:
      - type
      - id
      properties:
        '@context':
          $ref: '#/components/schemas/ASContext'
        id:
          type: string
          format: uri
          description: IRI of the ordered collection
        type:
          type: string
          enum:
          - OrderedCollection
          example: OrderedCollection
        totalItems:
          type: integer
          description: Total number of items in the collection
          example: 15
        current:
          type: string
          format: uri
          description: IRI of the most recent page
        first:
          type: string
          format: uri
          description: IRI of the first page
        last:
          type: string
          format: uri
          description: IRI of the last page
        orderedItems:
          type: array
          description: Temporally ordered items (most recent first)
          items:
            oneOf:
            - type: string
              format: uri
            - $ref: '#/components/schemas/ASObject'
            - $ref: '#/components/schemas/Activity'
    ASContext:
      description: ActivityStreams 2.0 JSON-LD context
      oneOf:
      - type: string
        example: https://www.w3.org/ns/activitystreams
      - type: array
        items:
          oneOf:
          - type: string
          - type: object
    Actor:
      type: object
      description: An ActivityPub Actor object representing an entity capable of performing activities. Actor types include Person, Application, Group, Organization, and Service.
      required:
      - '@context'
      - id
      - type
      - inbox
      - outbox
      properties:
        '@context':
          $ref: '#/components/schemas/ASContext'
        id:
          type: string
          format: uri
          description: Globally unique IRI identifying the actor
          example: https://social.example/users/alyssa
        type:
          type: string
          enum:
          - Person
          - Application
          - Group
          - Organization
          - Service
          description: The actor type
          example: Person
        name:
          type: string
          description: Display name of the actor
          example: Alyssa P. Hacker
        preferredUsername:
          type: string
          description: Short username for the actor (used in mentions and WebFinger)
          example: alyssa
        summary:
          type: string
          description: Bio or description of the actor (may contain HTML)
          example: Lisp enthusiast and hacker extraordinaire
        url:
          type: string
          format: uri
          description: Human-readable profile URL
          example: https://social.example/@alyssa
        inbox:
          type: string
          format: uri
          description: IRI of the actor's inbox OrderedCollection
          example: https://social.example/users/alyssa/inbox
        outbox:
          type: string
          format: uri
          description: IRI of the actor's outbox OrderedCollection
          example: https://social.example/users/alyssa/outbox
        followers:
          type: string
          format: uri
          description: IRI of the actor's followers collection
          example: https://social.example/users/alyssa/followers
        following:
          type: string
          format: uri
          description: IRI of the actor's following collection
          example: https://social.example/users/alyssa/following
        liked:
          type: string
          format: uri
          description: IRI of the actor's liked collection (optional)
          example: https://social.example/users/alyssa/liked
        publicKey:
          type: object
          description: Actor's public key for HTTP Signature verification
          properties:
            id:
              type: string
              format: uri
              example: https://social.example/users/alyssa#main-key
            owner:
              type: string
              format: uri
              example: https://social.example/users/alyssa
            publicKeyPem:
              type: string
              description: PEM-encoded RSA public key
        endpoints:
          type: object
          description: Additional endpoints for the actor
          properties:
            sharedInbox:
              type: string
              format: uri
              description: Shared inbox for efficient bulk delivery of public posts
              example: https://social.example/inbox
            oauthAuthorizationEndpoint:
              type: string
              format: uri
            oauthTokenEndpoint:
              type: string
              format: uri
            proxyUrl:
              type: string
              format: uri
        icon:
          $ref: '#/components/schemas/ImageObject'
        image:
          $ref: '#/components/schemas/ImageObject'
        published:
          type: string
          format: date-time
          description: When the actor was created
        updated:
          type: string
          format: date-time
          description: When the actor was last updated
    ASObject:
      type: object
      description: Base ActivityStreams 2.0 Object type. Encompasses Note, Article, Image, Video, Audio, Document, Page, Event, Place, Profile, Relationship, Tombstone, and Question.
      properties:
        '@context':
          $ref: '#/components/schemas/ASContext'
        id:
          type: string
          format: uri
          description: Globally unique IRI identifying the object
        type:
          type: string
          description: Object type
          enum:
          - Object
          - Article
          - Audio
          - Document
          - Event
          - Image
          - Note
          - Page
          - Place
          - Profile
          - Relationship
          - Tombstone
          - Video
          example: Note
        name:
          type: string
          description: Human-readable display name
        content:
          type: string
          description: HTML or text content of the object
          example: Say, did you finish reading that book I lent you?
        contentMap:
          type: object
          additionalProperties:
            type: string
          description: Language-tagged content variants (BCP47 language codes as keys)
        summary:
          type: string
          description: Short summary or content warning
        url:
          type: string
          format: uri
          description: Canonical URL of the object
        attributedTo:
          description: Actor(s) to attribute this object to
          oneOf:
          - type: string
            format: uri
          - type: array
            items:
              type: string
              format: uri
        to:
          description: Primary audience
          oneOf:
          - type: string
            format: uri
          - type: array
            items:
              type: string
              format: uri
        cc:
          description: Secondary audience
          oneOf:
          - type: string
            format: uri
          - type: array
            items:
              type: string
              format: uri
        inReplyTo:
          description: Object this is a reply to
          oneOf:
          - type: string
            format: uri
          - type: array
            items:
              type: string
              format: uri
        replies:
          description: Collection of replies to this object
          oneOf:
          - type: string
            format: uri
          - $ref: '#/components/schemas/Collection'
        tag:
          description: Tags, hashtags, or mentions associated with this object
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Link'
            - $ref: '#/components/schemas/ASObject'
        attachment:
          description: Media or other attachments
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Link'
            - $ref: '#/components/schemas/ASObject'
        mediaType:
          type: string
          description: MIME type of the content
          example: text/html
        published:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
        sensitive:
          type: boolean
          description: Whether the content is sensitive (Mastodon extension, widely adopted)
          example: false
        formerType:
          type: string
          description: Former type before object was deleted (Tombstone only)
        deleted:
          type: string
          format: date-time
          description: When the object was deleted (Tombstone only)
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code or short description
        error_description:
          type: string
          description: Human-readable error detail
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token for client-to-server authentication
    HTTPSignature:
      type: apiKey
      in: header
      name: Signature
      description: HTTP Signatures (draft-cavage-http-signatures) for server-to-server authentication. The Signature header contains keyId, algorithm, headers, and signature fields.