openapi: 3.0.0
info:
  title: Vast.ai Instance Creation API
  description: API endpoint for creating new instances by accepting provider offers
  version: 1.0.0
servers:
- url: https://console.vast.ai
  description: Production server
paths:
  /api/v0/asks/{id}/:
    put:
      summary: create instance
      description: |
        Creates a new instance by accepting an "ask" contract from a provider.

        - Use the search offers endpoint to discover available machines.
        - If `template_id` is provided, those template defaults are either merged or overridden by parameters specified in the request body.

        **Template Precedence Rules:**
        - **Scalar fields** (image, disk, runtype, etc.): Request value overrides template value
        - **`env`**: Merged by key. Request values win on key conflicts
        - **`extra_filters`**: Merged by key. Request values win on key conflicts

        For detailed template usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api).

        CLI Usage: `vastai create instance <offer_id> <image> [options]`
      security:
      - BearerAuth: []
      tags:
      - Instances
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: ID of the offer to accept (ask_id)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: 
              - image
              properties:
                image:
                  type: string
                  default: vastai/base-image:@vastai-automatic-tag
                  description: |
                    Docker image to use for the instance.
                template_hash_id:
                  type: string
                  description: |
                    Content-based hash ID of a template to use as base configuration. Template values are merged with or overridden by request parameters (see precedence rules in endpoint description). When using a template, the `image` field is optional as the template provides it.

                    Example: `4e17788f74f075dd9aab7d0d4427968f`
                label:
                  type: string
                  description: Custom name for the instance
                disk:
                  type: number
                  format: float
                  description: |
                    Size of local disk partition (in GB)
                runtype:
                  type: string
                  description: |
                    Launch mode for the instance. If omitted, defaults to 'ssh' unless `args/args_str` is provided.
                  enum:
                  - ssh
                  - jupyter
                  - args
                  - ssh_proxy
                  - ssh_direct
                  - jupyter_proxy
                  - jupyter_direct
                target_state:
                  type: string
                  description: |
                    Desired initial state of the instance
                  enum:
                  - running
                  - stopped
                price:
                  type: number
                  description: Bid price per machine (in $/hour). Only for interruptible instances
                  minimum: 0.001
                  maximum: 128.0
                env:
                  type: string
                  description: |
                    Environment variables and port mappings in Docker flag format. When using a template, request `env` is merged with template `env` - existing keys are retained, new keys are appended, conflicting keys use the request value.

                    Example: `"-e HF_TOKEN=hf_xxx123456789 -e MODEL_ID=TheBloke/Llama-2-7B-Chat-GPTQ -p 8000:8000"`
                cancel_unavail:
                  type: boolean
                  description: Whether to cancel if instance cannot start immediately. Defaults to false for interruptibles. Defaults to true for on-demand with target_state='running'
                vm:
                  type: boolean
                  description: Whether this is a VM instance
                onstart:
                  type: string
                  description: |
                    Commands to run when instance starts

                    Example : `env | grep _ >> /etc/environment; echo 'starting up'` 
                args:
                  type: array
                  items:
                    type: string
                  description: |
                    Arguments array to passed to the image entrypoint

                    Example : `["bash", "-c", "env | grep _ >> /etc/environment; echo 'starting up'"]`
                args_str:
                  type: string
                  description: |
                    Arguments string to pass to the entrypoint (alternative to args)

                    Example : `args_str: bash -c "env | grep _ >> /etc/environment; echo 'starting up'"`
                use_jupyter_lab:
                  type: boolean
                  description: Launch instance with jupyter lab instead of notebook
                jupyter_dir:
                  type: string
                  description: |
                    Directory to launch Jupyter from

                    Example : `/home/notebooks`
                python_utf8:
                  type: boolean
                  description: Set python's locale to C.UTF-8
                lang_utf8:
                  type: boolean
                  description: Set locale to C.UTF-8
                force:
                  type: boolean
                  description: Skip sanity checks when creating from an existing instance
                user:
                  type: string
                  description: User to use with docker create (breaks some images, use with caution)
                image_login:
                  type: string
                  description: Docker registry credentials if needed
                volume_info:
                  type: object
                  description: Volume creation/linking information
                  properties:
                    create_new:
                      type: boolean
                      description: Set to `true` to create a new volume, `false` to link an existing volume
                    volume_id:
                      type: integer
                      description: |
                        If `create_new` is false: existing volume ID (from `show volumes`). If `create_new` is true: volume offer ID (from `search volumes`)
                    size:
                      type: integer
                      description: Size of the volume in GB. Only used when `create_new` is true
                    mount_path:
                      type: string
                      description: Mount path for the volume inside the container (e.g., `/workspace`)
            example:
              image: vastai/base-image:@vastai-automatic-tag
      responses:
        '200':
          description: Instance created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the instance was created successfully
                    example: true
                  new_contract:
                    type: integer
                    description: ID of the newly created instance contract
                    example: 1234568
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    enum:
                    - invalid_args
                    - invalid_price
                    - no_ssh_key_for_vm
                  msg:
                    type: string
                    example: "error 400/3467: Invalid args: 'id' is required and must be a valid offer ID"
                  ask_id:
                    type: integer
                    example: 1234567
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: invalid_args
                  msg:
                    type: string
                    example: "error 403/3586: Offer 1234567 is not your own. Hosts can only rent their own machines."
                  ask_id:
                    type: integer
                    example: 1234567
        '404':
          description: Offer not found or not available
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: invalid_args
                  msg:
                    type: string
                    example: "error 404/3603: no_such_ask Instance type by id 1234567 is not available."
                  ask_id:
                    type: integer
                    example: 1234567
        '410':
          description: Offer no longer available (when cancel_unavail is true and instance cannot start)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: no_such_ask
                  msg:
                    type: string
                    example: "error 410/3907: no_such_ask Instance type 1234567 is no longer available."
                  ask_id:
                    type: integer
                    example: 1234567
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: API requests too frequent endpoint threshold=4.5
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: API key must be provided as a query parameter
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
        msg:
          type: string
x-rate-limit:
  threshold: 4.5
  penalty: 12
  per: request
  description: Maximum request frequency per IP address for this endpoint
x-input-validation:
  image:
    max_length: 1024
    description: Docker image name
  args:
    max_length: 4096
    description: Combined length of args, args_str and onstart
  label:
    max_length: 256
    description: Instance label
  env:
    max_length: 256
    max_total_length: 32768
    description: Environment variables
  price:
    min: 0.001
    max: 128.0
    description: Min/max bid price for interruptible instances
  disk:
    min: 8.0
    description: Minimum storage space in GB
x-cli-commands:
- name: create instance
  description: Create a new instance from an offer
  endpoint: /api/v0/asks/{id}/
  method: PUT
  examples:
  - vast create instance 1234567 --image tensorflow/tensorflow:latest-gpu --disk 32
  - vast create instance 1234567 --template abc123def456
  - vast create instance 1234567 --price 0.4 --disk 100 --env JUPYTER_TOKEN=abc123