---
title: API: instances
description: REST-эндпоинты с тегом instances — сгенерировано из OpenAPI-контракта платформы (8 операций).
locale: ru
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/ru/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
Сгенерировано из OpenAPI-контракта — не редактировать руками. Сводки операций и описания полей приводятся на английском (дословно из контракта). Интерактивный обозреватель с полными схемами: [https://entherium.duckdns.org:8443/reference](https://entherium.duckdns.org:8443/reference); замороженная спецификация этой сборки: [openapi.json](/developers/api/openapi.json).
:::

## `GET /api/v1/instances`

List Instances

[Открыть отдельной страницей →](./get-instances/)

**Авторизация:** нужен `Authorization: Bearer <token>`

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `массив HugoInstanceRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |

## `POST /api/v1/instances`

Create Instance

[Открыть отдельной страницей →](./post-instances/)

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Тело запроса:** `application/json` — схема `HugoInstanceCreate`

| Поле | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| `attached_sc` | `integer \| null` | нет |  |
| `backend` | `"gcs" \| "local-fs" \| "wp"` | нет |  |
| `base_url` | `string \| null` | нет |  |
| `caption` | `string \| null` | нет |  |
| `gcs_bucket` | `string \| null` | нет |  |
| `hostname` | `string \| null` | нет |  |
| `instance_id` | `string` | да |  |
| `is_active` | `boolean` | нет |  |
| `registry` | `object` | нет |  |
| `template_dir` | `string \| null` | нет |  |
| `theme_repo` | `string \| null` | нет |  |
| `theme_sha` | `string \| null` | нет |  |
| `tier` | `"prod" \| "dev" \| "test" \| "staging"` | нет |  |
| `vps_ip` | `string \| null` | нет |  |
| `vps_port` | `integer \| null` | нет |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `201` | Successful Response | `HugoInstanceRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Delete Instance

[Открыть отдельной страницей →](./delete-instances-instance-id/)

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `instance_id` | path | да | `string` |  |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `204` | Successful Response | — |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Read Instance

[Открыть отдельной страницей →](./get-instances-instance-id/)

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `instance_id` | path | да | `string` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `HugoInstanceRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Update Instance

[Открыть отдельной страницей →](./patch-instances-instance-id/)

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `instance_id` | path | да | `string` |  |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Тело запроса:** `application/json` — схема `HugoInstanceUpdate`

| Поле | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| `attached_sc` | `integer \| null` | нет |  |
| `backend` | `"gcs" \| "local-fs" \| "wp" \| null` | нет |  |
| `base_url` | `string \| null` | нет |  |
| `caption` | `string \| null` | нет |  |
| `gcs_bucket` | `string \| null` | нет |  |
| `hostname` | `string \| null` | нет |  |
| `is_active` | `boolean \| null` | нет |  |
| `registry` | `object \| null` | нет |  |
| `template_dir` | `string \| null` | нет |  |
| `theme_repo` | `string \| null` | нет |  |
| `theme_sha` | `string \| null` | нет |  |
| `tier` | `"prod" \| "dev" \| "test" \| "staging" \| null` | нет |  |
| `vps_ip` | `string \| null` | нет |  |
| `vps_port` | `integer \| null` | нет |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `HugoInstanceRead` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Instance Published

[Открыть отдельной страницей →](./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.

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `instance_id` | path | да | `string` |  |
| `since` | query | нет | `string \| null` |  |
| `active_only` | query | нет | `boolean` |  |
| `limit` | query | нет | `integer` |  |
| `offset` | query | нет | `integer` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `массив object` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Instance Summary

[Открыть отдельной страницей →](./get-instances-instance-id-summary/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `instance_id` | path | да | `string` |  |
| `refresh` | query | нет | `boolean` |  |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `InstanceSummary` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

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

Warmup Instance

[Открыть отдельной страницей →](./post-instances-instance-id-warmup/)

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

**Авторизация:** нужен `Authorization: Bearer <token>`

| Параметр | Где | Обязателен | Тип | Описание |
| --- | --- | --- | --- | --- |
| `instance_id` | path | да | `string` |  |
| `Idempotency-Key` | header | нет | `string` | Optional. |

**Ответы:**

| Код | Смысл | Тело |
| --- | --- | --- |
| `200` | Successful Response | `object` |
| `401` | Missing or invalid authentication credentials | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |