---
title: "Create an instance (starts a checkout)"
method: POST
path: "/instances"
tags: ["instances"]
---

# Create an instance (starts a checkout)

`POST /instances`

## Request

- Base URL: `https://app.lathe.live/api/v1`
- URL: `https://app.lathe.live/api/v1/instances`
- Auth: none declared

## Request body

- InstanceCreate
  - `tier` string, required: free | mini | starter | plus | pro (see GET /plans; Free only where offered)
  - `engines` union: Engines on the box: a list of names (budgets split by default) or {name: {memory_mb}}; omit for Postgres alone. GET /plans lists what is available.
    - string[]
    - object
  - `name` string: A label shown instead of the id; free text, not unique.
  - `tags` string[]: Lowercase tokens for grouping: letters, digits, . _ : -
  - `location` string: Location code from GET /locations; empty = the default.
  - `coupon` string: A discount code for the first month.

## Response `202`

Successful Response

- CreatedOut
  - `instance_id` string, required
  - `tier` string, required
  - `status` 'awaiting_payment' | 'pending', required
  - `checkout_url` string, nullable: Open in a browser and pay (or, for a trial, verify the card). Present for paid purchases.
  - `trial` boolean: The checkout verifies the card and starts a free trial; the first month is charged when it ends.
  - `free` boolean: A free instance: no checkout, nothing to pay now or later. One per person.
  - `job_id` string, nullable
  - `url` string, required
  - `message` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/lathe/apis/lathe-customer-api.md) · [All operations](https://skmtc.dev/lathe/apis/lathe-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lathe/apis/lathe-customer-api/revisions/68cfd9bb71c1?raw)