Deleting safely
The API never deletes. It asks, and a human with the right role approves in the dashboard.
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
- Owners and admins with that permission get an email.
- They open API, then Deletion requests.
- Servers and sites: the usual deletion check (type
DELETE, password, a 6-digit emailed code, a warning,DELETEagain). Databases: the database name and the person's password. - They may reject with a note.
- 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
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.