hosts

Edit the listing by publishing the next offer version (host owner)

The host console's listing editor. Despite the verb this is APPEND-ONLY: the next version is inserted and no existing row is ever rewritten, so a live job keeps the rate its quote snapshotted — the quote remains the only price authority. expected_version is compare-and-swapped against the CURRENT offer version (not the machine version the POST form uses); a race answers 409 with error.code = VERSION_CONFLICT and a sibling current block so the editor can show what changed instead of overwriting it. listing_expires_at has no column of its own and is FOLDED onto available_until (the earlier of the two wins — available_until already means "bookable until", which is what the catalog filters on); the response echoes the stored value. min_duration_s and max_duration_s are accepted but NOT stored, because no per-offer duration bound exists in the schema and nothing at quote time would enforce one; they are named back to the caller in ignored_fields rather than silently dropped. A publish that would retract availability a live job is already holding is refused 409 CONFLICT.

patch/api/v1/hosts/machines/{id}/offer

Request

  • Base URL: https://amplerun-api.spiry.org
  • URL: https://amplerun-api.spiry.org/api/v1/hosts/machines/{id}/offer
  • Auth: HTTP bearer

Path parameters

idstring uuid required
Example:3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40

Headers

Idempotency-Keystring uuid required
Example:3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40

UUID scoped to authenticated principal, route and canonical request hash.

Request body

expected_versionstring required

Unsigned base-10 integer as string; never a float.

rate_micro_per_hourstring required

Unsigned base-10 integer as string; never a float.

included_disk_gibinteger required
included_egress_gibinteger required
available_fromstring date-time required
available_untilstring date-time required
listing_expires_atstring date-time
min_duration_sinteger

Accepted, never stored; reported in ignored_fields.

max_duration_sinteger

Accepted, never stored; reported in ignored_fields.

availability_class'dedicated' | 'interruptible'

D-22. dedicated (the default) is never preempted. interruptible is sold only from idle or co-listed hosts: the host may take the machine back after preemption_notice_s seconds of notice, and billing stops at the notice.

preemption_notice_sinteger

D-22. Required for interruptible, refused for dedicated; omitted keeps the current value.

Example request

{
  "expected_version": "1",
  "rate_micro_per_hour": "1",
  "available_from": "2026-09-25T12:00:00Z",
  "available_until": "2026-09-25T12:00:00Z",
  "listing_expires_at": "2026-09-25T12:00:00Z"
}

Response

Next offer version published.

offer_idstring uuid required
offer_versionstring required

Unsigned base-10 integer as string; never a float.

state'listed' | 'unlisted' | 'draining' required
rate_micro_per_hourstring required

Unsigned base-10 integer as string; never a float.

included_disk_gibinteger required
included_egress_gibinteger required
available_fromstring date-time required
available_untilstring date-time required
availability_class'dedicated' | 'interruptible'

D-22. dedicated (the default) is never preempted. interruptible is sold only from idle or co-listed hosts: the host may take the machine back after preemption_notice_s seconds of notice, and billing stops at the notice.

preemption_notice_sinteger nullable
ignored_fieldsstring[] required

Request fields accepted by the schema but deliberately not stored.

Example response

{
  "offer_id": "3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40",
  "offer_version": "1",
  "rate_micro_per_hour": "1",
  "available_from": "2026-09-25T12:00:00Z",
  "available_until": "2026-09-25T12:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.