openapi: 3.1.0
info:
  title: ActivityPub Actors Outbox 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: Outbox
  description: Publish activities from an actor and read their history
paths:
  /users/{username}/outbox:
    get:
      operationId: getOutbox
      summary: Read actor outbox
      description: Returns the actor's outbox as an OrderedCollection of published activities. Publicly readable (may be filtered by authentication level). Supports pagination via first, last, next, and prev collection page links.
      tags:
      - Outbox
      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: Outbox as OrderedCollection
          content:
            application/activity+json:
              schema:
                $ref: '#/components/schemas/OrderedCollection'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/OrderedCollection'
        '404':
          description: Actor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: postToOutbox
      summary: Publish activity (client-to-server)
      description: Used by authenticated clients to publish activities on behalf of an actor. The server MUST assign an id to the activity and add it to the actor's outbox. The server then federates the activity to the appropriate recipients based on addressing fields (to, cc, bcc, audience). Returns 201 Created with a Location header pointing to the new activity's IRI.
      tags:
      - Outbox
      security:
      - BearerAuth: []
      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:
        '201':
          description: Activity published successfully
          headers:
            Location:
              description: IRI of the newly created activity
              schema:
                type: string
                format: uri
        '400':
          description: Bad request or invalid activity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          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.