---
title: "Api Submit Instance"
method: POST
path: "/instance"
tags: ["Instances"]
---

# Api Submit Instance

`POST /instance`

Submit a job to the queue or directly assign to a host.

If host_id is provided (marketplace launch), the job is assigned directly
to that host and container start is attempted immediately. Otherwise,
the job is queued and process_queue runs to find a host.

## Request body

- JobIn
  - `name` string, required
  - `vram_needed_gb` number
  - `priority` integer
  - `tier` string, nullable
  - `num_gpus` integer
  - `host_id` string, nullable
  - `gpu_model` string, nullable
  - `nfs_server` string, nullable
  - `nfs_path` string, nullable
  - `nfs_mount_point` string, nullable
  - `image` string, nullable
  - `interactive` boolean
  - `command` string, nullable
  - `ssh_port` integer
  - `max_bid` number, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-04-10** `95960849edcd` — 1 info
  - added the new optional request property `max_bid`
- **2026-04-03** `74dc97653bc3` — 1 warning, 4 info
  - the `vram_needed_gb` request property's min was set to `0.00`
  - added the new optional request property `gpu_model`
  - added the new optional request property `host_id`
  - the request property `vram_needed_gb` became optional
  - …1 more
- **2026-04-01** `526c3dd3d9d7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/aabiro/apis/xcelsior/changes/instance/post.md)

---

[API](https://skmtc.dev/aabiro/apis/xcelsior.md) · [All operations](https://skmtc.dev/aabiro/apis/xcelsior/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/aabiro/xcelsior/revisions/95960849edcd/schema)