Skip to content
/
Report a setup step
Last updated

Report a setup step

Records the setup step the client has reached on a server it is preparing: securing (replacing the bootstrap host key), installing (installing Forge on the server) or pairing. The server moves to that state: state and step become the step and step_started_at is set, so every client showing the server sees the same progress. The order of the whole setup is in the lifecycle.

Steps only move forward. A later step may skip an earlier one (a resumed server keeps its host key, so the client goes straight to installing); repeating the current step returns the server unchanged; an earlier step is refused. Allowed while the server is awaiting_client, securing, installing or pairing.

Requires a bearer token (or API key) whose principal holds the use_forge capability in the acting organization and created the server or holds manage_forge, and Forge cloud compute switched on for the organization.

POSThttps://api.aitronos.com/v1/forge/compute/hosts/{host_id}/progress

Path Parameters

host_id string required

The server's id: the fchost_ id returned in id, or the UUID sent when the server was created (any letter case, with or without hyphens).

Query Parameters

organization_id string optional

The organization the server belongs to: send its organization.id (from List your servers in every organization). Defaults to your current organization, where a server of another organization is not found. You must be an active member of it, or the request is refused with 403 ORGANIZATION_ACCESS_DENIED.

Headers

X-Organization-Id string optional

The same as organization_id, as a header. When both are sent, the query parameter wins.

Body Parameters

step string required

The step reached: securing, installing or pairing.

detail string optional

A short note of up to 1,000 characters kept in the server's step log. It is not returned.

Unknown fields are refused.

Returns

200 OK with the server object in the reported step.

{
  "id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90",
  "offering_id": "aitronos",
  "kind": "managed",
  "name": "build-box",
  "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"},
  "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7",
  "project_group": {"id": "fpgrp_4b9e2c7a1d3f4e8a9c0b6d2e1f3a5b7c", "client_id": "grp-clients", "name": "Clients"},
  "location_id": "eu-central",
  "location_label": "Germany",
  "size_id": "std-16",
  "size_label": "16 vCPU · 64 GB",
  "state": "securing",
  "state_label": "Securing the connection",
  "transient": true,
  "step": "securing",
  "step_started_at": "2026-09-28T09:01:20.118532Z",
  "state_changed_at": "2026-09-28T09:01:20.118532Z",
  "failure": null,
  "ipv4": "203.0.113.24",
  "ipv6": "2001:db8:4f2a::1",
  "ssh_port": 22,
  "ssh_user": "forge",
  "bootstrap_host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleBootstrapHostKeyForDocumentation0000 forge-bootstrap",
  "host_key_pub": null,
  "price": {
    "hourly": "0.83",
    "monthly_cap": "520.30",
    "currency": "CHF",
    "source": "aitronos",
    "includes_vat": false,
    "catalog_version": "fc-3b8e1f0a9c42",
    "quoted_at": "2026-09-28T09:00:00.184066Z",
    "parked_per_gb_month": "0.0269",
    "price_verified": true
  },
  "month_to_date": "0.83",
  "notice": null,
  "idle_reminder": null,
  "reconcile_flags": null,
  "actions": ["park", "delete", "revoke"],
  "created_at": "2026-09-28T09:00:00.184066Z",
  "ready_at": null,
  "parked_at": null,
  "parked_expires_at": null,
  "deleted_at": null,
  "revoked_at": null,
  "revoke_reason": null,
  "last_activity_at": null
}

Errors

StatusCodeWhen
401AUTHENTICATION_REQUIREDNo valid credential.
403ORGANIZATION_ACCESS_DENIEDorganization_id or X-Organization-Id names an organization you are not an active member of.
403INSUFFICIENT_PERMISSIONSThe caller does not hold use_forge in the acting organization.
403FORGE_COMPUTE_DISABLEDForge cloud compute is not switched on for the organization.
404FORGE_COMPUTE_HOST_NOT_FOUNDNo server with this id in the acting organization, or it was created by someone else and the caller does not hold manage_forge.
409FORGE_COMPUTE_INVALID_STATEThe server is not being set up, or the step is earlier than the current one. details.state is the current state and details.action is progress:<step>.
422VALIDATION_ERRORstep is not one of the three steps, detail is longer than 1,000 characters, or the body has an unknown field.
422INVALID_ID_FORMAThost_id is neither a UUID nor fchost_<32 hex>.
cURL
curl -X POST "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90/progress" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "step": "securing"
  }'

Response:

{
  "id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90",
  "offering_id": "aitronos",
  "kind": "managed",
  "name": "build-box",
  "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"},
  "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7",
  "project_group": {"id": "fpgrp_4b9e2c7a1d3f4e8a9c0b6d2e1f3a5b7c", "client_id": "grp-clients", "name": "Clients"},
  "location_id": "eu-central",
  "location_label": "Germany",
  "size_id": "std-16",
  "size_label": "16 vCPU · 64 GB",
  "state": "securing",
  "state_label": "Securing the connection",
  "transient": true,
  "step": "securing",
  "step_started_at": "2026-09-28T09:01:20.118532Z",
  "state_changed_at": "2026-09-28T09:01:20.118532Z",
  "failure": null,
  "ipv4": "203.0.113.24",
  "ipv6": "2001:db8:4f2a::1",
  "ssh_port": 22,
  "ssh_user": "forge",
  "bootstrap_host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleBootstrapHostKeyForDocumentation0000 forge-bootstrap",
  "host_key_pub": null,
  "price": {
    "hourly": "0.83",
    "monthly_cap": "520.30",
    "currency": "CHF",
    "source": "aitronos",
    "includes_vat": false,
    "catalog_version": "fc-3b8e1f0a9c42",
    "quoted_at": "2026-09-28T09:00:00.184066Z",
    "parked_per_gb_month": "0.0269",
    "price_verified": true
  },
  "month_to_date": "0.83",
  "notice": null,
  "idle_reminder": null,
  "reconcile_flags": null,
  "actions": ["park", "delete", "revoke"],
  "created_at": "2026-09-28T09:00:00.184066Z",
  "ready_at": null,
  "parked_at": null,
  "parked_expires_at": null,
  "deleted_at": null,
  "revoked_at": null,
  "revoke_reason": null,
  "last_activity_at": null
}
Previous page
Next page