Skip to content
/
Delete a server
Last updated

Delete a server

Deletes a server and everything Forge created for it at the provider: the server, its kept disks and snapshots, its SSH key and its firewall. The answer is 202 Accepted with the server in deleting; poll Get a server until it is deleted. The record stays, in deleted, and is listed for seven days.

Works from every state except revoking (wait until it is revoked, then delete it); asking again while the server is deleting or deleted returns it unchanged. Use it for failed_clean and failed_billing servers too. If the provider does not confirm the deletion, the server ends in failed_billing — a server may still exist — and deleting it again retries.

Billing. An Aitronos server is charged for every started hour until the provider confirms it is gone; a parked server's snapshot charge ends with it. For a server in your own account, anything the provider still holds after a delete is listed in reconcile_flags.

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. It works while Forge cloud compute is switched off, so switching the feature off never strands a server that costs money.

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

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.

This endpoint takes no body.

Returns

202 Accepted with the server object in deleting.

{
  "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": "deleting",
  "state_label": "Deleting the server",
  "transient": true,
  "step": null,
  "step_started_at": null,
  "state_changed_at": "2026-09-29T17:30:08.771045Z",
  "failure": null,
  "ipv4": "203.0.113.24",
  "ipv6": "2001:db8:4f2a::1",
  "ssh_port": 22,
  "ssh_user": "forge",
  "bootstrap_host_key_pub": null,
  "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000",
  "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": "7.47",
  "notice": null,
  "idle_reminder": null,
  "reconcile_flags": null,
  "actions": [],
  "created_at": "2026-09-28T09:00:00.184066Z",
  "ready_at": "2026-09-28T09:03:41.502318Z",
  "parked_at": null,
  "parked_expires_at": null,
  "deleted_at": null,
  "revoked_at": null,
  "revoke_reason": null,
  "last_activity_at": "2026-09-28T09:25:00Z"
}

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.
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 being revoked. details.action is delete.
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/delete" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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": "deleting",
  "state_label": "Deleting the server",
  "transient": true,
  "step": null,
  "step_started_at": null,
  "state_changed_at": "2026-09-29T17:30:08.771045Z",
  "failure": null,
  "ipv4": "203.0.113.24",
  "ipv6": "2001:db8:4f2a::1",
  "ssh_port": 22,
  "ssh_user": "forge",
  "bootstrap_host_key_pub": null,
  "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000",
  "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": "7.47",
  "notice": null,
  "idle_reminder": null,
  "reconcile_flags": null,
  "actions": [],
  "created_at": "2026-09-28T09:00:00.184066Z",
  "ready_at": "2026-09-28T09:03:41.502318Z",
  "parked_at": null,
  "parked_expires_at": null,
  "deleted_at": null,
  "revoked_at": null,
  "revoke_reason": null,
  "last_activity_at": "2026-09-28T09:25:00Z"
}
Previous page
Next page