API: instances

Note

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

GET /api/v1/instances

List Instances

Open as a page →

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 →

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 →

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 →

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 →

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 →

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 →

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 →

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