---
title: API: instances
description: REST endpoints tagged instances — generated from the platform's OpenAPI contract (8 operations).
locale: en
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/api/instances/
---

> Documentation index: https://enterium-developer-docs.pages.dev/developers/llms.txt — every page of this portal has a Markdown twin at <route>.md; the frozen API contract is at https://enterium-developer-docs.pages.dev/developers/api/openapi.json.

:::note
Generated from the OpenAPI contract — do not edit by hand. Interactive explorer with full schemas: [https://entherium.duckdns.org:8443/reference](https://entherium.duckdns.org:8443/reference); frozen spec for this build: [openapi.json](/developers/api/openapi.json).
:::

## `GET /api/v1/instances`

List Instances

[Open as a page →](./get-instances/)

**Auth:** `Authorization: Bearer <token>` required

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `array of HugoInstanceRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |

## `POST /api/v1/instances`

Create Instance

[Open as a page →](./post-instances/)

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Request body:** `application/json` — schema `HugoInstanceCreate`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attached_sc` | `integer \| null` | no |  |
| `backend` | `"gcs" \| "local-fs" \| "wp"` | no |  |
| `base_url` | `string \| null` | no |  |
| `caption` | `string \| null` | no |  |
| `gcs_bucket` | `string \| null` | no |  |
| `hostname` | `string \| null` | no |  |
| `instance_id` | `string` | yes |  |
| `is_active` | `boolean` | no |  |
| `registry` | `object` | no |  |
| `template_dir` | `string \| null` | no |  |
| `theme_repo` | `string \| null` | no |  |
| `theme_sha` | `string \| null` | no |  |
| `tier` | `"prod" \| "dev" \| "test" \| "staging"` | no |  |
| `vps_ip` | `string \| null` | no |  |
| `vps_port` | `integer \| null` | no |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `201` | Successful Response | `HugoInstanceRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `DELETE /api/v1/instances/{instance_id}`

Delete Instance

[Open as a page →](./delete-instances-instance-id/)

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `instance_id` | path | yes | `string` |  |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `204` | Successful Response | — |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `GET /api/v1/instances/{instance_id}`

Read Instance

[Open as a page →](./get-instances-instance-id/)

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `instance_id` | path | yes | `string` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `HugoInstanceRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `PATCH /api/v1/instances/{instance_id}`

Update Instance

[Open as a page →](./patch-instances-instance-id/)

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `instance_id` | path | yes | `string` |  |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Request body:** `application/json` — schema `HugoInstanceUpdate`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attached_sc` | `integer \| null` | no |  |
| `backend` | `"gcs" \| "local-fs" \| "wp" \| null` | no |  |
| `base_url` | `string \| null` | no |  |
| `caption` | `string \| null` | no |  |
| `gcs_bucket` | `string \| null` | no |  |
| `hostname` | `string \| null` | no |  |
| `is_active` | `boolean \| null` | no |  |
| `registry` | `object \| null` | no |  |
| `template_dir` | `string \| null` | no |  |
| `theme_repo` | `string \| null` | no |  |
| `theme_sha` | `string \| null` | no |  |
| `tier` | `"prod" \| "dev" \| "test" \| "staging" \| null` | no |  |
| `vps_ip` | `string \| null` | no |  |
| `vps_port` | `integer \| null` | no |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `HugoInstanceRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `GET /api/v1/instances/{instance_id}/published`

Instance Published

[Open as a page →](./get-instances-instance-id-published/)

published-article links on an instance (from `published_url`).

Live link = `url_external` ∥ `base_url + '/' + slug`; plus source_url, title,
timestamps, index_status. Pool-scoped: an agent reaches only its instances
(`instance.attached_sc` ∈ pool) — both convenience and a read-BOLA boundary.

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `instance_id` | path | yes | `string` |  |
| `since` | query | no | `string \| null` |  |
| `active_only` | query | no | `boolean` |  |
| `limit` | query | no | `integer` |  |
| `offset` | query | no | `integer` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `array of object` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `GET /api/v1/instances/{instance_id}/summary`

Instance Summary

[Open as a page →](./get-instances-instance-id-summary/)

Public polling endpoint (1.5-3s tick on the webui).

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `instance_id` | path | yes | `string` |  |
| `refresh` | query | no | `boolean` |  |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `InstanceSummary` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

## `POST /api/v1/instances/{instance_id}/warmup`

Warmup Instance

[Open as a page →](./post-instances-instance-id-warmup/)

Mark instance as warming. Real workflow lands in Phase 5 (Hatchet).

**Auth:** `Authorization: Bearer <token>` required

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `instance_id` | path | yes | `string` |  |
| `Idempotency-Key` | header | no | `string` | Optional. |

**Responses:**

| Code | Meaning | Body |
| --- | --- | --- |
| `200` | Successful Response | `object` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |