API Specification¶

openapi: 3.0.3
info:
  title: Machineuse API
  description: Distributed container management for browser automation
  version: 2.0.0
  contact:
    name: Machineuse
    url: https://github.com/dotcommoners/machineuse
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8000
    description: Local development
  - url: https://api.example.com
    description: Production

paths:
  /health:
    get:
      summary: Health check
      operationId: healthCheck
      tags: [Health]
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /v2/instances:
    post:
      summary: Create instance
      operationId: createInstance
      tags: [Instances]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInstanceRequest'
      responses:
        '201':
          description: Instance created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '400':
          $ref: '#/components/responses/BadRequest'
        '503':
          $ref: '#/components/responses/InsufficientResources'

    get:
      summary: List instances
      operationId: listInstances
      tags: [Instances]
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [creating, running, idle, dormant, failed]
        - name: node_id
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of instances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceList'

  /v2/instances/{instance_id}:
    get:
      summary: Get instance
      operationId: getInstance
      tags: [Instances]
      parameters:
        - $ref: '#/components/parameters/InstanceId'
      responses:
        '200':
          description: Instance details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete instance
      operationId: deleteInstance
      tags: [Instances]
      parameters:
        - $ref: '#/components/parameters/InstanceId'
        - name: force
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Instance deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /v2/instances/{instance_id}/dormant:
    post:
      summary: Make instance dormant
      operationId: makeInstanceDormant
      tags: [Instances]
      parameters:
        - $ref: '#/components/parameters/InstanceId'
      responses:
        '200':
          description: Instance made dormant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'

  /v2/instances/{instance_id}/revive:
    post:
      summary: Revive dormant instance
      operationId: reviveInstance
      tags: [Instances]
      parameters:
        - $ref: '#/components/parameters/InstanceId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviveRequest'
      responses:
        '200':
          description: Instance reviving
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'

  /v2/nodes:
    get:
      summary: List nodes
      operationId: listNodes
      tags: [Nodes]
      responses:
        '200':
          description: List of nodes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeList'

  /v2/nodes/{node_id}:
    get:
      summary: Get node
      operationId: getNode
      tags: [Nodes]
      parameters:
        - $ref: '#/components/parameters/NodeId'
      responses:
        '200':
          description: Node details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
        '404':
          $ref: '#/components/responses/NotFound'

  /v2/metrics:
    get:
      summary: Get metrics
      operationId: getMetrics
      tags: [Metrics]
      parameters:
        - name: node_id
          in: query
          schema:
            type: string
        - name: period
          in: query
          schema:
            type: string
            enum: [1h, 24h, 7d]
            default: 24h
      responses:
        '200':
          description: Metrics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'

components:
  parameters:
    InstanceId:
      name: instance_id
      in: path
      required: true
      schema:
        type: string
    NodeId:
      name: node_id
      in: path
      required: true
      schema:
        type: string

  schemas:
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: healthy
        instances_count:
          type: integer
          example: 15
        running_instances:
          type: integer
          example: 12

    CreateInstanceRequest:
      type: object
      properties:
        image:
          type: string
          default: ubuntu:22.04
        config:
          $ref: '#/components/schemas/InstanceConfig'
        node_preference:
          type: string

    InstanceConfig:
      type: object
      properties:
        memory_gb:
          type: number
          default: 2
        cpu_cores:
          type: integer
          default: 2
        disk_gb:
          type: number
          default: 10
        idle_timeout_minutes:
          type: integer
          default: 30
        auto_snapshot:
          type: boolean
          default: true

    Instance:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [creating, running, idle, dormant, failed]
        node_id:
          type: string
        subdomain:
          type: string
        debug_port:
          type: integer
        stream_port:
          type: integer
        created_at:
          type: string
          format: date-time
        config:
          $ref: '#/components/schemas/InstanceConfig'
        resources:
          $ref: '#/components/schemas/ResourceUsage'
        urls:
          type: object
          properties:
            debug:
              type: string
            stream:
              type: string

    InstanceList:
      type: object
      properties:
        instances:
          type: array
          items:
            $ref: '#/components/schemas/Instance'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    ReviveRequest:
      type: object
      properties:
        method:
          type: string
          enum: [quick_start, full_restore]
          default: quick_start

    Node:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [online, offline]
        address:
          type: string
        instances_count:
          type: integer
        max_instances:
          type: integer
        resources:
          $ref: '#/components/schemas/ResourceUsage'
        last_heartbeat:
          type: string
          format: date-time

    NodeList:
      type: object
      properties:
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/Node'

    ResourceUsage:
      type: object
      properties:
        cpu_percent:
          type: number
        memory_percent:
          type: number
        disk_percent:
          type: number

    MetricsResponse:
      type: object
      properties:
        cluster:
          type: object
          properties:
            total_instances:
              type: integer
            running_instances:
              type: integer
            avg_cpu_percent:
              type: number
            avg_memory_percent:
              type: number
        timeseries:
          type: object
          properties:
            timestamps:
              type: array
              items:
                type: string
            cpu:
              type: array
              items:
                type: number
            memory:
              type: array
              items:
                type: number

    MessageResponse:
      type: object
      properties:
        message:
          type: string

    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
        code:
          type: string

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Resource state conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientResources:
      description: Insufficient resources
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

security:
  - bearerAuth: []

tags:
  - name: Health
    description: Health check endpoints
  - name: Instances
    description: Instance management
  - name: Nodes
    description: Node management
  - name: Metrics
    description: Metrics and monitoring