openapi: 3.1.0
info:
  title: Actor Model Actors Supervisors API
  description: Reference API for actor model systems covering actor lifecycle management, message passing, supervision, clustering, and distributed state. Applicable to frameworks including Akka, Erlang/OTP, Microsoft Orleans, Pony, and Proto.Actor.
  version: 1.0.0
  contact:
    name: Actor Model Reference
    url: https://en.wikipedia.org/wiki/Actor_model
servers:
- url: https://api.example.com/actor-system/v1
  description: Actor system management API
security:
- BearerAuth: []
tags:
- name: Supervisors
  description: Supervision hierarchy
paths:
  /supervisors:
    get:
      operationId: listSupervisors
      summary: Actor Model List Supervisors
      description: List all supervisor actors with their child counts and supervision strategies.
      tags:
      - Supervisors
      parameters:
      - name: limit
        in: query
        description: Maximum number of supervisors to return
        schema:
          type: integer
          default: 50
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      responses:
        '200':
          description: List of supervisors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupervisorList'
        '401':
          description: Unauthorized
  /supervisors/{supervisorId}:
    get:
      operationId: getSupervisor
      summary: Actor Model Get Supervisor
      description: Retrieve the supervision tree and strategy for a specific supervisor actor.
      tags:
      - Supervisors
      parameters:
      - name: supervisorId
        in: path
        required: true
        description: Supervisor actor identifier
        schema:
          type: string
      responses:
        '200':
          description: Supervisor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Supervisor'
        '401':
          description: Unauthorized
        '404':
          description: Supervisor not found
  /supervisors/{supervisorId}/children:
    get:
      operationId: listChildren
      summary: Actor Model List Supervisor Children
      description: List all child actors currently under a supervisor's watch.
      tags:
      - Supervisors
      parameters:
      - name: supervisorId
        in: path
        required: true
        description: Supervisor actor identifier
        schema:
          type: string
      responses:
        '200':
          description: List of child actors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActorList'
        '401':
          description: Unauthorized
        '404':
          description: Supervisor not found
components:
  schemas:
    SupervisorList:
      type: object
      description: Paginated list of supervisors
      properties:
        supervisors:
          type: array
          items:
            $ref: '#/components/schemas/Supervisor'
        total:
          type: integer
          description: Total supervisor count
          example: 12
        cursor:
          type: string
          description: Cursor for next page
    Supervisor:
      type: object
      description: A supervisor actor managing a set of child actors
      properties:
        id:
          type: string
          description: Supervisor actor ID
          example: session-supervisor
        path:
          type: string
          description: Actor path
          example: /system/supervisor/session-supervisor
        strategy:
          type: string
          enum:
          - one-for-one
          - one-for-all
          - rest-for-one
          - all-for-one
          description: Supervision strategy
          example: one-for-one
        maxRestarts:
          type: integer
          description: Maximum restart attempts within window
          example: 10
        restartWindow:
          type: integer
          description: Restart window in seconds
          example: 60
        childCount:
          type: integer
          description: Current number of supervised children
          example: 42
        status:
          type: string
          description: Supervisor status
          example: active
    Actor:
      type: object
      description: An actor in the system with its current state and mailbox info
      properties:
        id:
          type: string
          description: Unique actor identifier
          example: user-123
        path:
          type: string
          description: Hierarchical actor path
          example: /user/supervisor/worker-1
        behavior:
          type: string
          description: Current behavior class or name
          example: UserSessionBehavior
        status:
          type: string
          enum:
          - active
          - idle
          - stopping
          - stopped
          description: Current actor status
          example: active
        mailboxSize:
          type: integer
          description: Number of pending messages in mailbox
          example: 3
        supervisorId:
          type: string
          description: Parent supervisor actor ID
          example: supervisor-pool-1
        spawnedAt:
          type: string
          format: date-time
          description: When the actor was spawned
        lastMessageAt:
          type: string
          format: date-time
          description: Timestamp of last processed message
        messageCount:
          type: integer
          description: Total messages processed since spawn
          example: 1024
        restartCount:
          type: integer
          description: Number of times this actor has been restarted
          example: 0
    ActorList:
      type: object
      description: Paginated list of actors
      properties:
        actors:
          type: array
          items:
            $ref: '#/components/schemas/Actor'
        total:
          type: integer
          description: Total actor count
          example: 500
        cursor:
          type: string
          description: Cursor for next page
          example: eyJwYWdlIjoxfQ==
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for actor system management API access