openapi: 3.1.0
info:
  title: ActivityPub Actors 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: Actors
  description: Retrieve actor profile objects
paths:
  /users/{username}:
    get:
      operationId: getActor
      summary: Retrieve actor profile
      description: Retrieves the ActivityPub actor object for the given username. The response is a JSON-LD document conforming to ActivityStreams 2.0, containing the actor's IRI, type, and required endpoint properties (inbox, outbox, followers, following). Servers MUST return the actor object when a valid Accept header is sent.
      tags:
      - Actors
      parameters:
      - name: username
        in: path
        required: true
        description: The local username of the actor
        schema:
          type: string
          example: alyssa
      responses:
        '200':
          description: Actor object as JSON-LD
          content:
            application/activity+json:
              schema:
                $ref: '#/components/schemas/Actor'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Actor'
        '404':
          description: Actor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access denied (or 404 for privacy)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code or short description
        error_description:
          type: string
          description: Human-readable error detail
    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
  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.