---
title: "Create an instance"
method: POST
path: "/v1/instances"
tags: ["public", "instances"]
---

# Create an instance

`POST /v1/instances`

## Request

- Base URL: `https://api.vozora.io`
- URL: `https://api.vozora.io/v1/instances`
- Auth: API key in header `Authorization`

Places an order and pays for it off-session against the account's default payment method, going through exactly the gates the Portal goes through (verified email, consent, catalog/provider validation, moderation, spend cap, quota, frozen prices, and a real charge). Responds 202 once the order is placed and, for a fixed-plan product, paid; a 3DS challenge or a missing payment method is a 402 with an order_id and portal_url to finish in the Portal. Optional Idempotency-Key header: a retry with the same key and body replays the original order; a different body under the same key is 409.

## Headers

- `Idempotency-Key` string

## Request body

- ProvisioningPublicCreateInstanceRequest
  - `add_on_product_ids` string[]
  - `chosen_options` object
  - `consent_cancel_waiver` boolean
  - `consent_over_18` boolean
  - `currency` string
  - `desired_private_network_id` string
  - `display_names` string[]
  - `ipv4_enabled` boolean
  - `ipv6_enabled` boolean
  - `kind_payload` object: KindPayload is ADR 0016 §4.1's kind payload, an ALTERNATIVE SPELLING of the six VM fields above plus display_names. Supplying one key both here and at the top level is 400 kind_payload_conflict, per field. display_names is REQUIRED on this contract; supplying it only here satisfies that requirement, and it runs exactly the same hostname validation either way.
  - `network_profile` string
  - `offering` ProvisioningPublicOfferingSelection
    - `contract_token` string
    - `id` string
    - `inputs` object
  - `product_id` string
  - `ssh_authorized_keys` string[]
  - `ssh_key_ids` string[]

## Response `202`

Accepted

- ProvisioningPublicCreateInstanceResponse
  - `instance_ids` string[]
  - `order_id` string
  - `status` string

## Other responses

- `400`: bad_request, bad_id, display_names_required, or ssh_key_required — every VPS product hands the customer a machine reachable only over SSH, so the request must carry ssh_key_ids or ssh_authorized_keys, or the account must have a saved key; or kind_payload_conflict — a VM field was supplied both at the top level and inside kind_payload
- `401`: invalid or missing API key
- `402`: no_payment_method or payment_requires_action
- `403`: the key lacks instances:create, or email_not_verified
- `409`: offering_changed, or idempotency_mismatch
- `422`: held or blocked (moderation); network_not_active — the private network must reach state active before it can be ordered onto, so poll GET /v1/networks/{id} first; private_network_required, network_profile_invalid, network_profile_conflict — network_profile disagrees with an ipv4_enabled/ipv6_enabled you also sent, and the profile is authoritative, network_profile_unsupported, public_network_unavailable, ipv6_unavailable, invalid_nic_rate_cap (addressing); offering_unavailable, offering_incompatible, offering_inputs_invalid (catalog); invalid_add_on — add_on_product_id is not an add-on of this product; add_on_unpriced — the add-on has no price; add_on_requires_fixed_term — add-ons can only be ordered with a fixed-term plan
- `503`: a gated seam is temporarily unavailable; address_allocation_unavailable when a family or pool is gated off, moderation_unavailable when the moderation gate could not run — nothing was placed, retry later

---

[API](https://skmtc.dev/vozora/apis/vozora-api.md) · [All operations](https://skmtc.dev/vozora/apis/vozora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vozora/apis/vozora-api/revisions/56f15734fc5a?raw)