> ## Documentation Index > Fetch the complete documentation index at: https://vastai-80aa3a82-docs-screenshot-updates.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` 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 [options]` ## OpenAPI ````yaml /api-reference/openapi.yaml put /api/v0/asks/{id}/ openapi: 3.1.0 info: title: Vast.ai API description: >- Vast.ai REST API for managing GPU cloud instances, machine operations, and AI/ML workflows. ## AI Agent Quick-Start Install the CLI skill for your agent (Claude Code, Cursor, Windsurf, etc.): npx skills add vast-ai/vast-cli CLI reference: https://raw.githubusercontent.com/vast-ai/vast-cli/master/vastai/SKILL.md SDK reference: https://raw.githubusercontent.com/vast-ai/vast-cli/master/vastai_sdk/SKILL.md ## Auth All endpoints require `Authorization: Bearer $VAST_API_KEY`. Get your key at: https://cloud.vast.ai/manage-keys/ ## Key Quirks - `gpu_ram` in CLI = GB; in REST API = MB (CLI auto-converts) - SSH keys must be registered BEFORE creating an instance (VM: no recovery; Docker: can add post-create) - `onstart` field is limited to 4048 characters -- gzip+base64 for longer scripts - `POST /api/v0/asks/{id}/` (create instance) returns `new_contract` as the instance ID, not `id` - Poll trap: if `actual_status` becomes `exited`, `unknown`, or `offline` it will never reach `running` -- destroy and retry 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` 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 [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_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 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 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 ````