> ## Documentation Index > Fetch the complete documentation index at: https://vastai-80aa3a82-ltxv2-serverless.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # create instance > Creates a new instance by accepting an "ask" contract from a provider. - Use the search offers endpoint to discover available machines. - If `template_id` or `template_hash_id` is provided, those template defaults are either merged or overridden by parameters specified in the request body. CLI Usage: `vastai create instance [options]` ## OpenAPI ````yaml /api-reference/openapi.json put /api/v0/asks/{id}/ openapi: 3.1.0 info: title: Vast.ai API description: >- Welcome to Vast.ai 's API documentation. Our API allows you to programmatically manage GPU instances, handle machine operations, and automate your AI/ML workflow. Whether you're running individual GPU instances or managing a fleet of machines, our API provides comprehensive control over all Vast.ai platform features. version: 1.0.0 contact: name: Vast.ai Support url: https://discord.gg/vast servers: - url: https://console.vast.ai description: Production server security: - BearerAuth: [] paths: /api/v0/asks/{id}/: put: tags: - Instances 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` or `template_hash_id` is provided, those template defaults are either merged or overridden by parameters specified in the request body. CLI Usage: `vastai create instance [options]` 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_id: type: integer description: > ID of an existing template to use for instance configuration. Alternative to providing template_hash_id. Example : `62897` template_hash_id: type: string description: | Hash ID of a template. Alternative to providing template_id 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 env: type: object description: | Environment variables Example : ` { "HF_TOKEN": "hf_xxx123456789", "MODEL_ID": "TheBloke/Llama-2-7B-Chat-GPTQ", }` 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: Whether to create a new volume volume_id: type: integer description: >- ID of existing volume to link or volume offer ID for new volume size: type: integer description: Size of the volume in GB (for new volumes) mount_path: type: string description: Mount path for the volume inside the container 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 security: - BearerAuth: [] components: schemas: Error: type: object properties: success: type: boolean example: false error: type: string msg: type: string securitySchemes: BearerAuth: type: http scheme: bearer description: API key must be provided in the Authorization header ````