# Deleting safely

## The rule

No API token, and no AI, can delete a server, a site or a database. A token with the scope `deletions:request` can only ask. An owner or admin then approves or rejects in the dashboard.

## Ask

| Delete | Call | Body |
| --- | --- | --- |
| A server | `POST /servers/{server}/deletion-requests` | `reason` (optional, up to 500 characters) |
| A site | `POST /sites/{site}/deletion-requests` | `reason`, `drop_database` (boolean) |
| A database | `POST /servers/{server}/databases/{database}/deletion-requests` | `reason` |

`{database}` is the database name. The answer is `202` with the request (or `200` when an identical one is already waiting):

| Field | Meaning |
| --- | --- |
| `id` | Public id of the request. |
| `subject` | `type` and `name` of what would be deleted. |
| `status` | Pending, approved, rejected, expired or cancelled. |
| `reason`, `options` | What you sent. |
| `requested_by`, `decided_by`, `decided_at`, `decision_note` | Who decided, and any note. |
| `expires_at` | Requests expire after 7 days. |

Needs the maker to have the "Delete resources" permission.

## What happens next

1. Owners and admins with that permission get an email.
2. They open **API**, then **Deletion requests**.
3. Servers and sites: the usual deletion check (type `DELETE`, password, a 6-digit emailed code, a warning, `DELETE` again). Databases: the database name and the person's password.
4. They may reject with a note.
5. Deleted servers and sites are hidden at once and kept for 30 days before purging, so support can restore them. Removing a server only forgets it: nothing is removed from the machine.

## Follow or withdraw

```bash
curl -s -H "Authorization: Bearer $TOKEN" $MYFORGE/deletion-requests
curl -s -H "Authorization: Bearer $TOKEN" "$MYFORGE/deletion-requests?status=pending"
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" $MYFORGE/deletion-requests/REQUEST_ID
```

`DELETE /deletion-requests/{id}` withdraws a pending request, and only the token that asked may do it (`403` otherwise, `409` when it is already decided).

## Other removals

Smaller removals that are not deletion of servers, sites or databases (a firewall rule, a redirect, a scheduled job, a recipe, an SSH key, a service) have normal `DELETE` endpoints under their own scopes. They can break things, so keep those scopes out of AI tokens unless you need them.

## Advice for AI

Give an AI `deletions:request` only if you want it to be able to propose deletions. Even then it only proposes. Read every request before you approve it.