# Decommission a server that Tarsana created {#top}

**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

```sh
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

```json
{
  "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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#decommission_not_configured) | 503 | Decommissioning servers is not available on this Tarsana deployment. Contact Tarsana support if you need it. |
| [`no_such_provider`](/api/errors#no_such_provider) | 404 | Tarsana does not support a provider with this name. The response lists the providers you can use. |
| [`servers_unavailable`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#surface_fault) | 500 | Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening. |