> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafftechnologies.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create VM

> Create a new virtual machine with a chosen OS template, compute plan, and region. The VM is automatically assigned to a VPC for private networking.

## Authentication

How your VM is accessed depends on the OS:

- **Linux** — provide `ssh_keys`, `password`, or both. At least one is required.
- **Windows** — `password` is required. SSH keys are not supported.

## Extra Storage

Set `extra_storage` (GB) to attach an additional block volume. On Linux, choose the filesystem with `extra_storage_type` (defaults to `ext4`). Windows volumes are automatically formatted as NTFS.

## Backups

- **Daily** — set `backup_type` to `daily`. Runs every day at `backup_time` (defaults to `8am`).
- **Weekly** — set `backup_type` to `weekly` with a `backup_date` (e.g. `Saturday`). Runs at `backup_time`.

Omit `backup_type` or set it to `none` to skip backups.

## VPC Network

Each VM is attached to a VPC for private networking:

1. **Use existing** — set `vpc_id` to join an existing VPC.
2. **Create new** — set `vpc_name` and `vpc_cidr` to create a custom VPC.
3. **Auto-create** (default) — leave all VPC fields empty. A VPC named `vpc-{vm-name}` is created automatically.

## Billing Checks

Before provisioning, the API validates:

- Account billing status (not banned, no failed payments)
- Active payment method exists


<sub>Updated May 8, 2026</sub>


## OpenAPI

````yaml POST /api/v1/vms
openapi: 3.0.3
info:
  title: Raff API
  description: >
    REST API for managing cloud infrastructure on Raff.


    ## Authentication

    Most endpoints require authentication via API key. Catalog endpoints under
    `/api/v1/public/` are open and require no authentication.


    ### API Key Authentication

    Include your API key in the `X-API-Key` header:
      ```
      curl -H "X-API-Key: YOUR_API_KEY" https://api.rafftechnologies.com/api/v1/vms
      ```

    ## Catalog

    Use the public catalog endpoints to discover available regions, OS
    templates, and pricing plans before creating resources:

    - `GET /api/v1/public/regions` — list available regions

    - `GET /api/v1/public/templates` — list OS templates (use the `id` as
    `template_id` when creating a VM)

    - `GET /api/v1/public/pricing/vm` — list VM pricing plans (use the `id` as
    `pricing_id` when creating a VM)

    - `GET /api/v1/public/pricing/volume` — volume storage pricing

    - `GET /api/v1/public/pricing/snapshot` — snapshot storage pricing

    - `GET /api/v1/public/pricing/backup` — backup storage pricing

    - `GET /api/v1/public/pricing/ip` — IP address pricing
  version: 1.0.0
  contact:
    name: Raff Technologies
    url: https://rafftechnologies.com
servers:
  - url: https://api.rafftechnologies.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Catalog
    description: >-
      Discover available regions, OS templates, and pricing plans. No
      authentication required.
  - name: Health
    description: Health check endpoints
  - name: Projects
    description: Organize resources into projects for billing and access control
  - name: Virtual Machines
    description: Create, manage, and control virtual machines
  - name: Networking
    description: >-
      Attach and detach VPCs, floating IPs, and security groups to VM network
      interfaces
  - name: Snapshots
    description: Point-in-time copies of VMs and volumes for quick rollback or cloning
  - name: Backups
    description: Scheduled and on-demand VM backups with restore capability
  - name: Backup Schedules
    description: Recurring daily or weekly backup schedules attached to a VM
  - name: SSH Keys
    description: Manage account-level SSH keys for VM provisioning
  - name: Members
    description: Account-level members — invite, list, update role, remove
  - name: Project Members
    description: Members of a specific project — same model as Members but project-scoped
  - name: Roles
    description: Custom roles bundling account or project permissions
  - name: Permissions
    description: List the catalog of permission strings used by roles
  - name: API Keys
    description: Create and manage API keys for programmatic access
  - name: Invitations
    description: Create and cancel email-based invitations to join the account or a project
paths:
  /api/v1/vms:
    post:
      tags:
        - Virtual Machines
      summary: Create VM
      description: >
        Create a new virtual machine with a chosen OS template, compute plan,
        and region. The VM is automatically assigned to a VPC for private
        networking.


        ## Authentication


        How your VM is accessed depends on the OS:


        - **Linux** — provide `ssh_keys`, `password`, or both. At least one is
        required.

        - **Windows** — `password` is required. SSH keys are not supported.


        ## Extra Storage


        Set `extra_storage` (GB) to attach an additional block volume. On Linux,
        choose the filesystem with `extra_storage_type` (defaults to `ext4`).
        Windows volumes are automatically formatted as NTFS.


        ## Backups


        - **Daily** — set `backup_type` to `daily`. Runs every day at
        `backup_time` (defaults to `8am`).

        - **Weekly** — set `backup_type` to `weekly` with a `backup_date` (e.g.
        `Saturday`). Runs at `backup_time`.


        Omit `backup_type` or set it to `none` to skip backups.


        ## VPC Network


        Each VM is attached to a VPC for private networking:


        1. **Use existing** — set `vpc_id` to join an existing VPC.

        2. **Create new** — set `vpc_name` and `vpc_cidr` to create a custom
        VPC.

        3. **Auto-create** (default) — leave all VPC fields empty. A VPC named
        `vpc-{vm-name}` is created automatically.


        ## Billing Checks


        Before provisioning, the API validates:


        - Account billing status (not banned, no failed payments)

        - Active payment method exists
      operationId: createVM
      parameters:
        - $ref: '#/components/parameters/ProjectIDHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVMRequest'
      responses:
        '201':
          description: VM created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/VM'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientBalance'
        '403':
          $ref: '#/components/responses/BillingValidationFailed'
components:
  parameters:
    ProjectIDHeader:
      name: X-Project-ID
      in: header
      required: true
      description: >-
        Project ID. Required for all mutating operations (create, delete, power
        actions, resize).
      schema:
        type: string
        format: uuid
  schemas:
    CreateVMRequest:
      type: object
      required:
        - name
        - template_id
        - pricing_id
        - region
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          description: VM display name
          example: my-ubuntu-server
        template_id:
          type: string
          format: uuid
          description: >-
            OS template ID. Use `GET /api/v1/public/templates` to list available
            templates.
          example: 5ac21891-32e6-41ce-8a93-b5d6ab708b0d
        pricing_id:
          type: integer
          minimum: 1
          maximum: 13
          description: >-
            Pricing plan ID that determines vCPU, RAM, storage, and bandwidth.
            Use `GET /api/v1/public/pricing/vm` to list available plans.
          example: 3
        region:
          type: string
          enum:
            - us-east
          description: Data center region
          example: us-east
        ssh_keys:
          type: array
          items:
            type: string
          description: >-
            SSH public keys for VM access. Required for Linux VMs if no password
            is provided. Ignored for Windows VMs.
        password:
          type: string
          minLength: 12
          description: >-
            Root password for the VM. Required for Windows VMs. For Linux VMs,
            required if no SSH keys are provided. Both SSH keys and password can
            be set on Linux. Must be at least 12 characters with: 2+ uppercase
            letters, 2+ digits, 1+ special character (@+-_.,!). Only
            alphanumeric characters and @+-_.,! are allowed.
        extra_storage:
          type: integer
          minimum: 0
          description: >-
            Additional block storage volume in GB (0–10,000). Attached as a
            separate disk to the VM.
          example: 100
        extra_storage_type:
          type: string
          enum:
            - ext4
            - xfs
            - btrfs
          description: >-
            Filesystem type for extra storage. Required for Linux VMs with extra
            storage (defaults to ext4 if omitted). For Windows VMs, storage is
            automatically formatted as NTFS — this field is ignored.
          example: ext4
        backup_type:
          type: string
          enum:
            - none
            - daily
            - weekly
          description: >-
            Set `daily` for daily backups or `weekly` for weekly backups. Use
            `none` or omit for no backups.
          example: weekly
        backup_time:
          type: string
          description: >-
            Time of day to run backups (e.g. `8am`). Defaults to `8am` if not
            specified.
          example: 8am
        backup_date:
          type: string
          description: >-
            Day of the week for weekly backups (e.g. `Saturday`). Required when
            `backup_type` is `weekly`, ignored for daily backups. Valid values:
            Monday–Sunday.
          example: Saturday
        tags:
          type: array
          items:
            type: string
          description: Custom tags for the VM
        vpc_id:
          type: string
          format: uuid
          description: >-
            Attach VM to an existing VPC by its ID. If omitted along with
            `vpc_name`, a VPC is auto-created.
        vpc_name:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            Create a new VPC with this name. Must be used together with
            `vpc_cidr`.
          example: my-custom-vpc
        vpc_cidr:
          type: string
          description: >-
            CIDR block for the new VPC (e.g. `10.0.1.0/24`). Must be used
            together with `vpc_name`.
          pattern: ^([0-9]{1,3}\.){3}[0-9]{1,3}/[0-9]{1,2}$
          example: 10.0.1.0/24
        skip_public_ip:
          type: boolean
          default: false
          description: >
            When `true`, the VM is created without a public IPv4 address. It
            will only be reachable on its VPC private IP, so a VPC is required —
            pass `vpc_id` (existing) or `vpc_name` + `vpc_cidr` (new), or leave
            VPC fields empty to auto-create one. Combining `skip_public_ip=true`
            with `skip_vpc=true` is rejected because the VM would have no
            network at all.
        skip_vpc:
          type: boolean
          default: false
          description: >
            When `true`, no VPC is created or attached. The VM will only have
            its public IP — no private networking. Cannot be combined with
            `skip_public_ip=true`.
    VM:
      type: object
      required:
        - id
        - name
        - status
        - cpu
        - ram
        - storage
        - added_storage
        - total_storage
        - template_id
        - template_name
        - template_version
        - price_per_hour
        - pricing_id
        - region
        - active
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique VM identifier
        name:
          type: string
          description: VM display name
          example: my-ubuntu-server
        status:
          type: string
          enum:
            - active
            - passive
            - provisioning
            - booting
            - initiating
            - finalizing
            - failure
          description: |
            Current VM status. Lifecycle transitions:
            - Creation: `initiating` → `provisioning` → `booting` → `active`
            - Stop: `active` → `finalizing` → `passive`
            - Start: `passive` → `booting` → `active`
            - Reboot: `active` → `booting` → `active`

            | Status | Meaning | Billable |
            |--------|---------|----------|
            | `initiating` | Queued, initial setup before provisioning | Yes |
            | `provisioning` | VM being created in the hypervisor | Yes |
            | `booting` | VM starting up | Yes |
            | `active` | Running and accessible | Yes |
            | `passive` | Stopped, resources still reserved | Yes |
            | `finalizing` | Shutting down | Yes |
            | `failure` | Creation or operation failed | No |
        cpu:
          type: integer
          description: Number of vCPU cores
          example: 2
        ram:
          type: integer
          description: RAM in GB
          example: 4
        storage:
          type: integer
          description: Base storage in GB
          example: 80
        added_storage:
          type: integer
          description: Additional storage in GB
          example: 0
        total_storage:
          type: integer
          description: Total storage (base + added) in GB
          example: 80
        template_id:
          type: string
          format: uuid
          description: OS template ID used to create this VM
        template_name:
          type: string
          description: OS template name
          example: Ubuntu
        template_version:
          type: string
          description: OS template version
          example: 24.10x64
        version:
          type: string
          description: VM version
        price_per_hour:
          type: string
          description: Hourly billing rate in USD
          example: '0.027764'
        pricing_id:
          type: integer
          description: Pricing plan ID
          example: 3
        created_by:
          type: string
          description: User ID who created this VM
        billing_type:
          type: string
          description: Billing type for this VM
          enum:
            - payg
            - subscription
          example: payg
        subscription_id:
          type: string
          format: uuid
          description: Subscription ID if billing_type is subscription
        backup_type:
          type: string
          description: Backup schedule type
          nullable: true
          example: weekly
        region:
          type: string
          enum:
            - us-east
          description: Data center region
          example: us-east
        project_id:
          type: string
          format: uuid
          description: Project this VM belongs to
        public_ipv4_address:
          type: string
          description: Public IPv4 address
          example: 15.204.178.3
        public_ipv6_address:
          type: string
          description: Public IPv6 address
          nullable: true
        private_ipv4_address:
          type: string
          description: Private IPv4 address (VPC)
          example: 10.10.0.96
        private_ipv6_address:
          type: string
          description: Private IPv6 address
          nullable: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/VMTag'
          description: Custom tags
        active:
          type: boolean
          description: Whether the VM is active
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    VMTag:
      type: object
      description: Custom tag attached to a VM.
      required:
        - id
        - name
        - priority
        - created_at
      properties:
        id:
          type: string
          description: Unique tag identifier
        name:
          type: string
          description: Tag name
        priority:
          type: integer
          description: Tag priority (ordering)
        created_at:
          type: string
          format: date-time
          description: When the tag was created
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    BillingError:
      type: object
      description: >-
        Billing validation error response. Returned when the account is not in
        good standing for paid operations.
      required:
        - error
        - reason
      properties:
        error:
          type: string
          example: Billing validation failed
        message:
          type: string
          example: Payment failed. Please update your payment method.
        reason:
          type: string
          description: >
            Machine-readable reason code:

            - `banned` — account has been suspended

            - `failed` — last payment failed; balance top-up needed

            - `no_billing_customer` — billing has not been set up for this
            account
          enum:
            - banned
            - failed
            - no_billing_customer
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientBalance:
      description: >
        Account balance is insufficient for this operation. Top up the balance
        and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Payment Required
            message: Insufficient balance for subscription
    BillingValidationFailed:
      description: |
        Billing validation failed. The account is not in good standing.
        Check the `reason` field:
        - `banned` — account suspended
        - `failed` — last payment failed; top up the account balance
        - `no_billing_customer` — billing not set up
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication. Each key is bound to a specific account.

````