## POST /api/v2/vps/{id}/ddos-scrubbing

**Enable DDoS scrubbing**

Start DDoS scrubbing for the VPS's primary IPv4 address. Traffic to the address is then filtered before it reaches the VPS. Send `duration` in seconds for a session of 1, 3, 6, 12 or 24 hours. Send `permanent: true` for always-on scrubbing that runs until you stop it with [`DELETE /api/v2/vps/{id}/ddos-scrubbing`](/endpoints/vps-services/delete-v2-vps-id-ddos-scrubbing/). Check `available` on [`GET /api/v2/vps/{id}/ddos-scrubbing`](/endpoints/vps-services/get-v2-vps-id-ddos-scrubbing/) first. A VPS in a location without scrubbing answers 403. So does an address that is excluded from scrubbing. An address outside the ranges that can be scrubbed answers 400 `invalid_request`. When the filter cannot take the address range yet, the call answers 409 `ddos_scrubbing_unavailable_for_ip` and nothing is started. When protection is already on for the address, the call answers 409 `ddos_mitigation_active`.

### Related Endpoints

- `GET /api/v2/vps/{id}/ddos-scrubbing`: Get DDoS scrubbing status
- `DELETE /api/v2/vps/{id}/ddos-scrubbing`: Disable DDoS scrubbing
- `GET /api/v2/vps/{id}/ddos-scrubbing/traffic`: Get DDoS filtering measurements

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scope: `write:vm`
- `Content-Type`: application/json

### Parameters

- `id` (path, string, required): The VPS ID (`vps_…`). Example: `vps_01hxa3b4c5d6e7f8g9h0j1k2m3`

### Request Body

- `duration` (integer, optional): Session length in seconds: 3600, 10800, 21600, 43200 or 86400 (1, 3, 6, 12 or 24 hours). Not together with `permanent`.
  Allowed values: 3600, 10800, 21600, 43200, 86400
- `permanent` (boolean, optional): `true` for always-on scrubbing without an end time. It runs until you stop it. Not together with `duration`.
  Allowed values: true

### Request Examples

#### Enable for one hour

```bash
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/ddos-scrubbing" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "duration": 3600
  }'
```

```json
{
  "duration": 3600
}
```

#### Enable always-on scrubbing

```bash
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/ddos-scrubbing" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permanent": true
  }'
```

```json
{
  "permanent": true
}
```

### Response Schema

- `available` (boolean, required): True after a successful start.
- `reason` (string, required, nullable): Always null after a successful start.
- `ip` (string, required, nullable): The address being scrubbed.
- `active` (boolean, required): True once scrubbing has started.
- `durationSeconds` (integer, required, nullable): Session length in seconds. Null for always-on scrubbing.
- `createdAt` (string, required, nullable): Always null in this response.
- `expiresAt` (string, required, nullable): When the session ends. Null for always-on scrubbing.
- `networkMitigation` (object, required): Always `status: "unknown"` in this response. Read `GET /api/v2/vps/{id}/ddos-scrubbing` for the verified state.
- `networkMitigation.status` (string, required): `active` when protection is on. `none` when checked and clear. `unknown` when it could not be checked, which never means clear.
  Allowed values: active, none, unknown
- `networkMitigation.action` (string, required, nullable): `blackhole`: all internet traffic to the address is dropped. `scrub`: traffic is filtered before it reaches the VPS. Null unless `status` is `active`.
  Allowed values: blackhole, scrub
- `networkMitigation.automatic` (boolean, required, nullable): False for a session started from the client area or the API. True otherwise, for example the automatic response to an attack. Null when unknown.
- `networkMitigation.createdAt` (string, required, nullable): When it started. Null when unknown.
- `networkMitigation.expiresAt` (string, required, nullable): When it ends by itself. Null when it has no end or is unknown.

### Responses

#### 200 - Scrubbing started.
```json
{
  "available": true,
  "reason": null,
  "ip": "192.0.2.10",
  "active": true,
  "durationSeconds": 3600,
  "createdAt": null,
  "expiresAt": "2026-06-22T13:07:03.000Z",
  "networkMitigation": {
    "status": "unknown",
    "action": null,
    "automatic": null,
    "createdAt": null,
    "expiresAt": null
  }
}
```

#### 400 - Invalid request. The response body is an RFC 7807 Problem Details document.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request is invalid.",
  "code": "invalid_request",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 401 - Unauthorized. Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 403 - Forbidden. The caller lacks a required scope or does not own the resource.
```json
{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The caller lacks a required scope or does not own the resource.",
  "code": "forbidden",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 404 - Not found. The resource does not exist or is not owned by the caller; `code` is `vps_not_found`.
```json
{
  "type": "https://developer.hostup.se/errors/vps_not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "code": "vps_not_found",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 409 - `ddos_mitigation_active`: protection is already on for this address. `ddos_scrubbing_unavailable_for_ip`: the address range cannot be scrubbed yet. Nothing was started in either case.
```json
{
  "type": "https://developer.hostup.se/errors/ddos_mitigation_active",
  "title": "DDoS mitigation already active",
  "status": 409,
  "detail": "DDoS mitigation is already active for this IP address.",
  "code": "ddos_mitigation_active",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/ddos-scrubbing"
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Internal error. Retry later or contact support if the issue persists.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Retry later or contact support if the issue persists.",
  "code": "internal_error",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```
