openapi: 3.1.0
info:
  title: Proxmox VE API
  description: |
    REST-style management API for Proxmox Virtual Environment (PVE). All endpoints live
    under /api2/json on port 8006 of a PVE node. Authentication is via stateless API
    tokens (PVEAPIToken header) or ticket-based sessions issued by /access/ticket
    (cookie + CSRFPreventionToken header for write operations). Output format may be
    switched via the path (json, extjs, html, text). Tickets expire after 2 hours.
  version: "1.0.0"
  contact:
    name: Proxmox VE API
    url: https://pve.proxmox.com/wiki/Proxmox_VE_API
servers:
  - url: https://{server}:8006/api2/json
    description: Proxmox VE node API
    variables:
      server:
        default: your.server
        description: Hostname or IP of the Proxmox VE node
security:
  - apiTokenAuth: []
  - ticketAuth: []
tags:
  - name: Access
  - name: Cluster
  - name: Nodes
  - name: VMs
  - name: Containers
paths:
  /version:
    get:
      tags: [Cluster]
      summary: Get API version
      description: Return the current API version of the Proxmox VE node.
      security: []
      responses:
        '200':
          description: Version information
  /access/ticket:
    post:
      tags: [Access]
      summary: Create authentication ticket
      description: |
        Create a ticket (and CSRFPreventionToken) using username/password credentials.
        The returned ticket is used as the PVEAuthCookie for subsequent requests, and
        the CSRFPreventionToken header is required for write operations.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                  description: User name in the form `USER@REALM`.
                password:
                  type: string
                  format: password
                realm:
                  type: string
                otp:
                  type: string
      responses:
        '200':
          description: Ticket and CSRFPreventionToken
  /access/users:
    get:
      tags: [Access]
      summary: List configured users
      responses:
        '200':
          description: User list
    post:
      tags: [Access]
      summary: Create a new user
      responses:
        '200':
          description: User created
  /access/users/{userid}:
    parameters:
      - name: userid
        in: path
        required: true
        schema:
          type: string
        description: User identifier in `USER@REALM` form.
    delete:
      tags: [Access]
      summary: Delete user
      responses:
        '200':
          description: User deleted
  /nodes/{node}/status:
    parameters:
      - $ref: '#/components/parameters/Node'
    get:
      tags: [Nodes]
      summary: Get node status
      description: Return runtime status of the named Proxmox node.
      responses:
        '200':
          description: Node status
  /nodes/{node}/lxc:
    parameters:
      - $ref: '#/components/parameters/Node'
    post:
      tags: [Containers]
      summary: Create LXC container
      responses:
        '200':
          description: Container creation task identifier
  /nodes/{node}/lxc/{vmid}/status/start:
    parameters:
      - $ref: '#/components/parameters/Node'
      - name: vmid
        in: path
        required: true
        schema:
          type: integer
        description: Numeric VM/container identifier.
    post:
      tags: [Containers]
      summary: Start LXC container
      responses:
        '200':
          description: Start task identifier
components:
  securitySchemes:
    apiTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Stateless API token. Send header
        `Authorization: PVEAPIToken=USER@REALM!TOKENID=UUID`.
        No CSRFPreventionToken required.
    ticketAuth:
      type: apiKey
      in: cookie
      name: PVEAuthCookie
      description: |
        Ticket issued by POST /access/ticket. Carried as a cookie. Write
        operations also require the `CSRFPreventionToken` header returned with
        the ticket. Tickets expire after 2 hours.
  parameters:
    Node:
      name: node
      in: path
      required: true
      schema:
        type: string
      description: Name of the Proxmox VE node (cluster member).