openapi: 3.0.3
info:
  title: Jagacloud Node Agent API
  version: 0.1.0
  description: Minimal single-node hypervisor API for VMs (libvirt), LXC containers, and Podman-in-LXC.
servers:
  - url: http://{host}:{port}
    variables:
      host:
        default: 127.0.0.1
      port:
        default: "8000"
components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
    NodeInfo:
      type: object
      properties:
        hostname: { type: string }
        version: { type: string }
        cpu: { type: object, properties: { cores: {type: integer}, model: {type: string}, load: {type: number} } }
        memory: { type: object, properties: { total_mb: {type: integer}, used_mb: {type: integer} } }
        storage_pools:
          type: array
          items: { $ref: '#/components/schemas/StoragePool' }
        bridges:
          type: array
          items: { $ref: '#/components/schemas/Bridge' }
    StoragePool:
      type: object
      properties:
        name: { type: string }
        type: { type: string, enum: [dir, lvm, zfs] }
        path: { type: string }
        free_gb: { type: number }
        total_gb: { type: number }
    Bridge:
      type: object
      properties:
        name: { type: string }
        vlan_aware: { type: boolean }
        mtu: { type: integer }
    VM:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        status: { type: string, enum: [running, stopped, paused, error] }
        cpus: { type: integer }
        memory_mb: { type: integer }
        disks: { type: array, items: { $ref: '#/components/schemas/VMDisk' } }
        nics: { type: array, items: { $ref: '#/components/schemas/VMNic' } }
    VMDisk:
      type: object
      properties:
        name: { type: string }
        pool: { type: string }
        size_gb: { type: integer }
        bus: { type: string, enum: [virtio, sata] }
    VMNic:
      type: object
      properties:
        bridge: { type: string }
        model: { type: string }
        vlan: { type: integer }
    VMCreate:
      allOf:
        - $ref: '#/components/schemas/VM'
        - type: object
          required: [name, cpus, memory_mb]
          properties:
            cloud_init:
              type: object
              properties:
                user: { type: string }
                ssh_keys: { type: array, items: {type: string} }
                user_data: { type: string }
    Container:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        status: { type: string, enum: [running, stopped, error] }
        unprivileged: { type: boolean }
        nics: { type: array, items: { $ref: '#/components/schemas/ContainerNic' } }
        limits: { type: object, properties: { cpus: {type: integer}, memory_mb: {type: integer} } }
    ContainerCreate:
      allOf:
        - $ref: '#/components/schemas/Container'
        - type: object
          required: [name, template]
          properties:
            template: { type: string }
            rootfs: { type: object, properties: { pool: {type: string}, size_gb: {type: integer} }, required: [pool, size_gb] }
    ContainerNic:
      type: object
      properties:
        bridge: { type: string }
        vlan: { type: integer }
    OCIContainer:
      type: object
      properties:
        id: { type: string }
        image: { type: string }
        status: { type: string }
    OCICreate:
      type: object
      required: [image]
      properties:
        image: { type: string }
        cmd: { type: array, items: {type: string} }
        env: { type: object, additionalProperties: {type: string} }
        ports: { type: array, items: { type: object, properties: { host_port: {type: integer}, container_port: {type: integer} } } }
        volumes: { type: array, items: { type: string } }
        restart: { type: string }
security:
  - bearerToken: []
paths:
  /api/v1/node:
    get:
      summary: Node information
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/NodeInfo' } } } }
        default: { description: Error, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
  /api/v1/vms:
    get:
      summary: List VMs
      responses:
        '200': { description: OK, content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/VM' } } } } }
    post:
      summary: Create VM
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/VMCreate' } } }
      responses:
        '202': { description: Accepted, content: { application/json: { schema: { $ref: '#/components/schemas/VM' } } } }
  /api/v1/vms/{id}:
    get:
      summary: Get VM
      parameters: [{ name: id, in: path, required: true, schema: {type: string} }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/VM' } } } }
    post:
      summary: Update VM (reserved for future)
      responses:
        '501': { description: Not implemented }
  /api/v1/vms/{id}/{action}:
    post:
      summary: VM lifecycle action
      parameters:
        - { name: id, in: path, required: true, schema: {type: string} }
        - { name: action, in: path, required: true, schema: { type: string, enum: [start, stop, reboot, delete] } }
      responses:
        '202': { description: Accepted }
  /api/v1/containers:
    get:
      summary: List LXC containers
      responses:
        '200': { description: OK, content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Container' } } } } }
    post:
      summary: Create container
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/ContainerCreate' } } }
      responses:
        '202': { description: Accepted, content: { application/json: { schema: { $ref: '#/components/schemas/Container' } } } }
  /api/v1/containers/{id}:
    get:
      summary: Get container
      parameters: [{ name: id, in: path, required: true, schema: {type: string} }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Container' } } } }
  /api/v1/containers/{id}/{action}:
    post:
      summary: Container lifecycle action
      parameters:
        - { name: id, in: path, required: true, schema: {type: string} }
        - { name: action, in: path, required: true, schema: { type: string, enum: [start, stop, delete] } }
      responses:
        '202': { description: Accepted }
  /api/v1/containers/{id}/oci:
    get:
      summary: List OCI containers inside CT
      parameters: [{ name: id, in: path, required: true, schema: {type: string} }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/OCIContainer' } } } } }
    post:
      summary: Create OCI container inside CT
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/OCICreate' } } }
      responses:
        '202': { description: Accepted, content: { application/json: { schema: { $ref: '#/components/schemas/OCIContainer' } } } }
  /api/v1/containers/{id}/oci/{cid}:
    get:
      summary: Get OCI container
      parameters:
        - { name: id, in: path, required: true, schema: {type: string} }
        - { name: cid, in: path, required: true, schema: {type: string} }
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/OCIContainer' } } } }
  /api/v1/containers/{id}/oci/{cid}/{action}:
    post:
      summary: OCI lifecycle action
      parameters:
        - { name: id, in: path, required: true, schema: {type: string} }
        - { name: cid, in: path, required: true, schema: {type: string} }
        - { name: action, in: path, required: true, schema: { type: string, enum: [start, stop, delete] } }
      responses:
        '202': { description: Accepted }