# Client API: Shield

> Client-facing DDoS scrubber status and attack events for your IPs.

Source: https://docs.coritan.com/api/reference/client/shield/

Client-facing DDoS scrubber status and attack events for your IPs.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Client API reference](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/shield/events`](#op-get-api-v1-client-shield-events) | Recent attack events for this account's IP services |
| GET | [`/api/v1/client/shield/status`](#op-get-api-v1-client-shield-status) | Protection view for every assigned floating IP on this account |
| GET | [`/api/v1/client/shield/subjects/{ip_service_id}/profile`](#op-get-api-v1-client-shield-subjects-ip-service-id-profile) | The profile scrubbing this IP: the platform default, or its custom one |
| PATCH | [`/api/v1/client/shield/subjects/{ip_service_id}/profile`](#op-patch-api-v1-client-shield-subjects-ip-service-id-profile) | Ensure custom profile |
| POST | [`/api/v1/client/shield/subjects/{ip_service_id}/rules`](#op-post-api-v1-client-shield-subjects-ip-service-id-rules) | Create subject rule |
| DELETE | [`/api/v1/client/shield/subjects/{ip_service_id}/rules/{rule_id}`](#op-delete-api-v1-client-shield-subjects-ip-service-id-rules-rule-id) | Delete subject rule |

### Recent attack events for this account's IP services {#op-get-api-v1-client-shield-events}

`GET /api/v1/client/shield/events`

Recent attack events for this account's IP services.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Protection view for every assigned floating IP on this account {#op-get-api-v1-client-shield-status}

`GET /api/v1/client/shield/status`

Protection view for every assigned floating IP on this account.

Unattached IPs remain scrubbed (platform default).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### The profile scrubbing this IP: the platform default, or its custom one {#op-get-api-v1-client-shield-subjects-ip-service-id-profile}

`GET /api/v1/client/shield/subjects/{ip_service_id}/profile`

The profile scrubbing this IP: the platform default, or its custom one.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Ensure custom profile {#op-patch-api-v1-client-shield-subjects-ip-service-id-profile}

`PATCH /api/v1/client/shield/subjects/{ip_service_id}/profile`

Promote the subject to a customer-editable custom profile (idempotent),
then apply any tuning in the body.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `protection_mode` | string or null | no |
| `default_action` | string or null | no |
| `established_passthrough` | boolean or null | no |
| `rate_limits` | RateLimitsPatch or null | no |
| `rate_limits.per_source_pps` | integer or null | no |
| `rate_limits.aggregate_pps` | integer or null | no |
| `rate_limits.syn_pps_per_source` | integer or null | no |
| `rate_limits.icmp_pps_per_source` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create subject rule {#op-post-api-v1-client-shield-subjects-ip-service-id-rules}

`POST /api/v1/client/shield/subjects/{ip_service_id}/rules`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | no |
| `enabled` | boolean | no |
| `action` | string | no |
| `protocol` | integer or null | no |
| `src_prefix` | string or null | no |
| `dst_prefix` | string or null | no |
| `src_port_min` | integer or null | no |
| `src_port_max` | integer or null | no |
| `dst_port_min` | integer or null | no |
| `dst_port_max` | integer or null | no |
| `tcp_flags_mask` | integer or null | no |
| `tcp_flags_value` | integer or null | no |
| `packet_len_min` | integer or null | no |
| `packet_len_max` | integer or null | no |
| `ttl_min` | integer or null | no |
| `ttl_max` | integer or null | no |
| `icmp_type` | integer or null | no |
| `icmp_code` | integer or null | no |
| `rate_limit_pps` | integer or null | no |
| `notes` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete subject rule {#op-delete-api-v1-client-shield-subjects-ip-service-id-rules-rule-id}

`DELETE /api/v1/client/shield/subjects/{ip_service_id}/rules/{rule_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |
| `rule_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |