Decommission a server that Tarsana created

Destructive · POST /v1/tenants/{tenant}/providers/{provider_name}/servers/{server_id}/decommission · MCP tool decommission-server

Removes one server that Tarsana created for you, by the ID that create-server returned. Tarsana first revokes the server's own credentials, then asks the provider to delete the server, and waits until the provider shows it is gone; a 200 answer means it is gone. If a step fails, sending the request again continues from that step. A server Tarsana did not create is refused; delete those with destroy-server.

Roles that can call it: deployer.

Parameters

Name	In	Required	Description
`tenant`	path	yes	Your tenant ID
`provider_name`	path	yes	The provider's name, for example `hetzner`
`server_id`	path	yes	The server's ID at the provider, as `create-server` returned it

Returns

A JSON object with these keys: tenant, provider_name, server_id, decommissioned, guarantee, caller_authenticated.

Example request

curl -X POST https://api.tarsana.io/v1/tenants/acme/providers/hetzner/servers/1001/decommission \
  -H "X-Tarsana-Access-Token: $ACCESS_TOKEN" \
  -H 'X-Tarsana-Tenant: acme'

Example response

{
  "tenant": "acme",
  "provider_name": "hetzner",
  "server_id": "1000",
  "decommissioned": {
    "state": "destroyed",
    "observed": "not-found",
    "action_id": "ff97f81e3825703462ecab41c1c4ffa3",
    "idempotent_replay": false,
    "requested_at": "2026-10-05T02:15:41.166635+00:00",
    "completed_at": "2026-10-05T02:15:41.169045+00:00",
    "target": {
      "id": "1000",
      "region": "fsn1"
    }
  },
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false
}

Errors

Code	HTTP	What it means
`invalid_parameter`	400	A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again.
`no_acting_tenant`	400	Your request does not say which tenant you are acting for. Send your tenant ID in the `X-Tarsana-Tenant` header, or with `--as` on the command line.
`isolation_refused`	403	This address belongs to a tenant ID you do not have access to. Check the tenant ID in the address and in your request header.
`tenant_refused`	400	This tenant ID is not allowed, or is not in the expected format. Use a different ID made of lower-case letters, digits, dots, dashes and underscores.
`decommission_not_configured`	503	Decommissioning servers is not available on this Tarsana deployment. Contact Tarsana support if you need it.
`no_such_provider`	404	Tarsana does not support a provider with this name. The response lists the providers you can use.
`servers_unavailable`	502	Your server list could not be read with your stored credential: none is stored, the provider refused it, or the provider could not be reached. Check your credential with `provider-credential`, then try again.
`no_such_server`	404	Your server list at this provider has no server with this ID. Check the ID with `servers` and try again.
`server_not_accounted_for`	409	Tarsana cannot prove it created this server, so it does not decommission it. If you want it gone, delete it with `destroy-server`.
`decommission_failed`	502	The decommission stopped at the step the response names, and that step is recorded. Send the same request again to continue from there.
`unauthenticated`	401	Your request has no credential, or one that Tarsana does not recognise. Sign in with `login`, or send a valid access token.
`forbidden`	403	Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them.
`rate_limited`	429	You sent too many requests in a short time. Wait for the number of seconds in `retry_after_seconds`, then try again.
`surface_fault`	500	Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening.

View this page as Markdown